--- name: "Crypt::Mac::HMAC" section: "3pm" platform: "linux" package: "perl-cryptx" version: "0.091-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/Crypt::Mac::HMAC" --- # Crypt::Mac::HMAC(3pm) Message authentication code HMAC ## NAME Crypt::Mac::HMAC - Message authentication code HMAC ## SYNOPSIS ``` ### Functional interface: use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u ); # calculate MAC from string/buffer my $hmac_raw = hmac('SHA256', $key, 'data buffer'); my $hmac_hex = hmac_hex('SHA256', $key, 'data buffer'); my $hmac_b64 = hmac_b64('SHA256', $key, 'data buffer'); my $hmac_b64u = hmac_b64u('SHA256', $key, 'data buffer'); ### OO interface: use Crypt::Mac::HMAC; my $d = Crypt::Mac::HMAC->new('SHA256', $key); $d->add('any data'); my $result_hex = $d->hexmac; # finalizes the object # for another output encoding use a fresh object (or clone before finalizing) my $result_b64u = Crypt::Mac::HMAC->new('SHA256', $key)->add('any data')->b64umac; # or MAC a file instead my $file_result_raw = Crypt::Mac::HMAC->new('SHA256', $key)->addfile('filename.dat')->mac; ``` ## DESCRIPTION Provides an interface to the HMAC message authentication code (MAC) algorithm. ## EXPORT Nothing is exported by default. You can export selected functions: ``` use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u ); ``` Or all of them at once: ``` use Crypt::Mac::HMAC ':all'; ``` ## FUNCTIONS ### hmac Joins all arguments into a single string and returns its HMAC message authentication code encoded as a binary string. Data arguments for the functional helpers are converted to byte strings using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. `"undef"` is treated as an empty string and may emit Perl's usual "uninitialized value" warning. The same rules apply to `"hmac_hex"`, `"hmac_b64"`, and `"hmac_b64u"`. ``` my $hmac_raw = hmac($hash_name, $key, 'data buffer'); #or my $hmac_raw = hmac($hash_name, $key, 'any data', 'more data', 'even more data'); # $hash_name ... [string] any for which there is a Crypt::Digest:: module # $key ......... [binary string] the key (octets/bytes) ``` ### hmac\_hex Joins all arguments into a single string and returns its HMAC message authentication code encoded as a hexadecimal string. ``` my $hmac_hex = hmac_hex($hash_name, $key, 'data buffer'); #or my $hmac_hex = hmac_hex($hash_name, $key, 'any data', 'more data', 'even more data'); # $hash_name ... [string] any for which there is a Crypt::Digest:: module # $key ......... [binary string] the key (not hex!) ``` ### hmac\_b64 Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 string. ``` my $hmac_b64 = hmac_b64($hash_name, $key, 'data buffer'); #or my $hmac_b64 = hmac_b64($hash_name, $key, 'any data', 'more data', 'even more data'); # $hash_name ... [string] any for which there is a Crypt::Digest:: module # $key ......... [binary string] the key (not Base64!) ``` ### hmac\_b64u 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). ``` my $hmac_b64url = hmac_b64u($hash_name, $key, 'data buffer'); #or my $hmac_b64url = hmac_b64u($hash_name, $key, 'any data', 'more data', 'even more data'); # $hash_name ... [string] any for which there is a Crypt::Digest:: module # $key ......... [binary string] the key (not Base64url!) ``` ## METHODS Unless noted otherwise, assume `$d` is an existing MAC object created via `"new"`, for example: ``` my $d = Crypt::Mac::HMAC->new('SHA256', $key); ``` ### new ``` my $d = Crypt::Mac::HMAC->new($hash_name, $key); # $hash_name ... [string] one of 'SHA256', 'SHA384', 'SHA512', 'SHA1', 'SHA3_256', 'BLAKE2b_256', # 'RIPEMD160', etc. - any for which there is a Crypt::Digest:: module # $key ......... [binary string] the key (any length - internally padded/hashed as per RFC 2104) ``` ### clone ``` $d->clone(); ``` ### add Appends data to the message. Returns the object itself (for chaining). Croaks if the object has already been finalized by `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`. Each argument is converted to bytes using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. `"undef"` is treated as an empty string and may emit Perl's usual "uninitialized value" warning. ``` $d->add('any data'); #or $d->add('any data', 'more data', 'even more data'); ``` ### addfile Reads the file content and appends it to the message. Returns the object itself (for chaining). Croaks if the object has already been finalized by `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`. ``` $d->addfile('filename.dat'); #or my $filehandle = ...; # existing binary-mode filehandle $d->addfile($filehandle); ``` ### mac Returns the binary MAC (raw bytes) and finalizes the object. After the first call to `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`, later calls to `"add"`, `"addfile"`, or any MAC getter croak. ``` my $result_raw = $d->mac(); ``` ### hexmac Returns the MAC encoded as a lowercase hexadecimal string and finalizes the object. After the first call to `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`, later calls to `"add"`, `"addfile"`, or any MAC getter croak. ``` my $result_hex = $d->hexmac(); ``` ### b64mac Returns the MAC encoded as a Base64 string with trailing `"="` padding and finalizes the object. After the first call to `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`, later calls to `"add"`, `"addfile"`, or any MAC getter croak. ``` my $result_b64 = $d->b64mac(); ``` ### b64umac Returns the MAC encoded as a Base64 URL-safe string (no trailing `"="`) and finalizes the object. After the first call to `"mac"`, `"hexmac"`, `"b64mac"`, or `"b64umac"`, later calls to `"add"`, `"addfile"`, or any MAC getter croak. ``` my $result_b64url = $d->b64umac(); ``` ## SEE ALSO - • CryptX - • \ - • \