| 1 | package Crypt::Mac::HMAC; | ||
| 2 | |||
| 3 | ### BEWARE - GENERATED FILE, DO NOT EDIT MANUALLY! | ||
| 4 | |||
| 5 | 5 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 5 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | 5 | our $VERSION = '0.091'; | |
| 8 | |||
| 9 | 5 | ▶ | use base qw(Crypt::Mac Exporter); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | 5 | our %EXPORT_TAGS = ( all => [qw( hmac hmac_hex hmac_b64 hmac_b64u )] ); | |
| 11 | 5 | our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); | |
| 12 | 5 | our @EXPORT = qw(); | |
| 13 | |||
| 14 | 5 | 1; | |
| 15 | |||
| 16 | =pod | ||
| 17 | |||
| 18 | =head1 NAME | ||
| 19 | |||
| 20 | Crypt::Mac::HMAC - Message authentication code HMAC | ||
| 21 | |||
| 22 | =head1 SYNOPSIS | ||
| 23 | |||
| 24 | ### Functional interface: | ||
| 25 | use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u ); | ||
| 26 | |||
| 27 | # calculate MAC from string/buffer | ||
| 28 | my $hmac_raw = hmac('SHA256', $key, 'data buffer'); | ||
| 29 | my $hmac_hex = hmac_hex('SHA256', $key, 'data buffer'); | ||
| 30 | my $hmac_b64 = hmac_b64('SHA256', $key, 'data buffer'); | ||
| 31 | my $hmac_b64u = hmac_b64u('SHA256', $key, 'data buffer'); | ||
| 32 | |||
| 33 | ### OO interface: | ||
| 34 | use Crypt::Mac::HMAC; | ||
| 35 | |||
| 36 | my $d = Crypt::Mac::HMAC->new('SHA256', $key); | ||
| 37 | $d->add('any data'); | ||
| 38 | my $result_hex = $d->hexmac; # finalizes the object | ||
| 39 | |||
| 40 | # for another output encoding use a fresh object (or clone before finalizing) | ||
| 41 | my $result_b64u = Crypt::Mac::HMAC->new('SHA256', $key)->add('any data')->b64umac; | ||
| 42 | |||
| 43 | # or MAC a file instead | ||
| 44 | my $file_result_raw = Crypt::Mac::HMAC->new('SHA256', $key)->addfile('filename.dat')->mac; | ||
| 45 | |||
| 46 | =head1 DESCRIPTION | ||
| 47 | |||
| 48 | Provides an interface to the HMAC message authentication code (MAC) algorithm. | ||
| 49 | |||
| 50 | =head1 EXPORT | ||
| 51 | |||
| 52 | Nothing is exported by default. | ||
| 53 | |||
| 54 | You can export selected functions: | ||
| 55 | |||
| 56 | use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u ); | ||
| 57 | |||
| 58 | Or all of them at once: | ||
| 59 | |||
| 60 | use Crypt::Mac::HMAC ':all'; | ||
| 61 | |||
| 62 | =head1 FUNCTIONS | ||
| 63 | |||
| 64 | =head2 hmac | ||
| 65 | |||
| 66 | Joins all arguments into a single string and returns its HMAC message authentication code encoded as a binary string. | ||
| 67 | |||
| 68 | Data arguments for the functional helpers are converted to byte strings using | ||
| 69 | Perl's usual scalar stringification. Defined scalars, including numbers and | ||
| 70 | string-overloaded objects, are accepted. C<undef> is treated as an empty | ||
| 71 | string and may emit Perl's usual "uninitialized value" warning. The same | ||
| 72 | rules apply to C<hmac_hex>, C<hmac_b64>, and | ||
| 73 | C<hmac_b64u>. | ||
| 74 | |||
| 75 | my $hmac_raw = hmac($hash_name, $key, 'data buffer'); | ||
| 76 | #or | ||
| 77 | my $hmac_raw = hmac($hash_name, $key, 'any data', 'more data', 'even more data'); | ||
| 78 | |||
| 79 | # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module | ||
| 80 | # $key ......... [binary string] the key (octets/bytes) | ||
| 81 | |||
| 82 | =head2 hmac_hex | ||
| 83 | |||
| 84 | Joins all arguments into a single string and returns its HMAC message authentication code encoded as a hexadecimal string. | ||
| 85 | |||
| 86 | my $hmac_hex = hmac_hex($hash_name, $key, 'data buffer'); | ||
| 87 | #or | ||
| 88 | my $hmac_hex = hmac_hex($hash_name, $key, 'any data', 'more data', 'even more data'); | ||
| 89 | |||
| 90 | # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module | ||
| 91 | # $key ......... [binary string] the key (not hex!) | ||
| 92 | |||
| 93 | =head2 hmac_b64 | ||
| 94 | |||
| 95 | Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 string. | ||
| 96 | |||
| 97 | my $hmac_b64 = hmac_b64($hash_name, $key, 'data buffer'); | ||
| 98 | #or | ||
| 99 | my $hmac_b64 = hmac_b64($hash_name, $key, 'any data', 'more data', 'even more data'); | ||
| 100 | |||
| 101 | # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module | ||
| 102 | # $key ......... [binary string] the key (not Base64!) | ||
| 103 | |||
| 104 | =head2 hmac_b64u | ||
| 105 | |||
| 106 | Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 URL-safe string (see RFC 4648 section 5). | ||
| 107 | |||
| 108 | my $hmac_b64url = hmac_b64u($hash_name, $key, 'data buffer'); | ||
| 109 | #or | ||
| 110 | my $hmac_b64url = hmac_b64u($hash_name, $key, 'any data', 'more data', 'even more data'); | ||
| 111 | |||
| 112 | # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module | ||
| 113 | # $key ......... [binary string] the key (not Base64url!) | ||
| 114 | |||
| 115 | =head1 METHODS | ||
| 116 | |||
| 117 | Unless noted otherwise, assume C<$d> is an existing MAC object created via | ||
| 118 | C<new>, for example: | ||
| 119 | |||
| 120 | my $d = Crypt::Mac::HMAC->new('SHA256', $key); | ||
| 121 | |||
| 122 | =head2 new | ||
| 123 | |||
| 124 | my $d = Crypt::Mac::HMAC->new($hash_name, $key); | ||
| 125 | |||
| 126 | # $hash_name ... [string] one of 'SHA256', 'SHA384', 'SHA512', 'SHA1', 'SHA3_256', 'BLAKE2b_256', | ||
| 127 | # 'RIPEMD160', etc. - any <NAME> for which there is a Crypt::Digest::<NAME> module | ||
| 128 | # $key ......... [binary string] the key (any length - internally padded/hashed as per RFC 2104) | ||
| 129 | |||
| 130 | =head2 clone | ||
| 131 | |||
| 132 | $d->clone(); | ||
| 133 | |||
| 134 | =head2 add | ||
| 135 | |||
| 136 | Appends data to the message. Returns the object itself (for chaining). | ||
| 137 | Croaks if the object has already been finalized by C<mac>, C<hexmac>, | ||
| 138 | C<b64mac>, or C<b64umac>. | ||
| 139 | |||
| 140 | Each argument is converted to bytes using Perl's usual scalar stringification. | ||
| 141 | Defined scalars, including numbers and string-overloaded objects, are | ||
| 142 | accepted. C<undef> is treated as an empty string and may emit Perl's usual | ||
| 143 | "uninitialized value" warning. | ||
| 144 | |||
| 145 | $d->add('any data'); | ||
| 146 | #or | ||
| 147 | $d->add('any data', 'more data', 'even more data'); | ||
| 148 | |||
| 149 | =head2 addfile | ||
| 150 | |||
| 151 | Reads the file content and appends it to the message. Returns the object itself | ||
| 152 | (for chaining). Croaks if the object has already been finalized by C<mac>, | ||
| 153 | C<hexmac>, C<b64mac>, or C<b64umac>. | ||
| 154 | |||
| 155 | $d->addfile('filename.dat'); | ||
| 156 | #or | ||
| 157 | my $filehandle = ...; # existing binary-mode filehandle | ||
| 158 | $d->addfile($filehandle); | ||
| 159 | |||
| 160 | =head2 mac | ||
| 161 | |||
| 162 | Returns the binary MAC (raw bytes) and finalizes the object. After the first | ||
| 163 | call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, later calls to C<add>, | ||
| 164 | C<addfile>, or any MAC getter croak. | ||
| 165 | |||
| 166 | my $result_raw = $d->mac(); | ||
| 167 | |||
| 168 | =head2 hexmac | ||
| 169 | |||
| 170 | Returns the MAC encoded as a lowercase hexadecimal string and finalizes the | ||
| 171 | object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or C<b64umac>, | ||
| 172 | later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 173 | |||
| 174 | my $result_hex = $d->hexmac(); | ||
| 175 | |||
| 176 | =head2 b64mac | ||
| 177 | |||
| 178 | Returns the MAC encoded as a Base64 string with trailing C<=> padding and | ||
| 179 | finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or | ||
| 180 | C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 181 | |||
| 182 | my $result_b64 = $d->b64mac(); | ||
| 183 | |||
| 184 | =head2 b64umac | ||
| 185 | |||
| 186 | Returns the MAC encoded as a Base64 URL-safe string (no trailing C<=>) and | ||
| 187 | finalizes the object. After the first call to C<mac>, C<hexmac>, C<b64mac>, or | ||
| 188 | C<b64umac>, later calls to C<add>, C<addfile>, or any MAC getter croak. | ||
| 189 | |||
| 190 | my $result_b64url = $d->b64umac(); | ||
| 191 | |||
| 192 | =head1 SEE ALSO | ||
| 193 | |||
| 194 | =over | ||
| 195 | |||
| 196 | =item * L<CryptX> | ||
| 197 | |||
| 198 | =item * L<https://en.wikipedia.org/wiki/Hmac> | ||
| 199 | |||
| 200 | =item * L<https://www.rfc-editor.org/rfc/rfc2104> | ||
| 201 | |||
| 202 | =back | ||
| 203 | |||
| 204 | =cut | ||