Crypt::Mac::KMAC(3) User Contributed Perl Documentation Crypt::Mac::KMAC(3)
NAME
Crypt::Mac::KMAC - Message authentication code KMAC (NIST SP 800-185)
SYNOPSIS
### Functional interface:
use Crypt::Mac::KMAC qw( kmac kmac_hex kmac_b64 kmac_b64u );
# KMAC128 / KMAC256 - fixed-length output committed in advance
my $mac_raw = kmac('KMAC128', 32, $key, '', 'data buffer');
my $mac_hex = kmac_hex('KMAC256', 64, $key, $custom, 'data buffer');
# KMACXOF128 / KMACXOF256 - extendable-output variant
my $bytes = kmac('KMACXOF128', 100, $key, '', 'data buffer');
### OO interface:
use Crypt::Mac::KMAC;
my $d = Crypt::Mac::KMAC->new('KMAC256', $key, $custom);
$d->add('any data');
my $result_hex = $d->hexmac(64); # finalizes the object
# XOF mode - same API, just a different variant
my $d = Crypt::Mac::KMAC->new('KMACXOF128', $key);
$d->add('any data');
my $result_b64 = $d->b64mac(100);
DESCRIPTION
Since: CryptX-0.090
Provides an interface to KMAC, the keyed message authentication code
based on cSHAKE (NIST SP 800-185 section4). Four variants are exposed:
o "KMAC128" / "KMAC256" - fixed-output KMAC. The requested output
length "L" is encoded into the input, so re-running KMAC with a
different output length produces an unrelated MAC, even with
identical key, customization, and message.
o "KMACXOF128" / "KMACXOF256" - extendable-output KMAC (KMACXOF in SP
800-185). The encoded length is set to 0, so any prefix of the
squeezed output is a valid KMAC of the same
key/customization/message; you can request arbitrarily many bytes.
The customization string "S" is optional and is used for domain
separation. When unused it is encoded as an empty string.
EXPORT
Nothing is exported by default.
You can export selected functions:
use Crypt::Mac::KMAC qw( kmac kmac_hex kmac_b64 kmac_b64u );
Or all of them at once:
use Crypt::Mac::KMAC ':all';
FUNCTIONS
kmac
Joins all data arguments into a single string and returns its KMAC
encoded as a binary string.
my $mac = kmac($variant, $size, $key, $cust, 'data buffer');
#or
my $mac = kmac($variant, $size, $key, $cust, 'data', 'more data', 'even more');
# $variant .. [string] 'KMAC128', 'KMAC256', 'KMACXOF128' or 'KMACXOF256'
# $size .... [integer] requested output length in bytes (>0)
# $key ..... [binary string] secret key (any length, including empty)
# $cust .... [binary string] customization string (may be empty); undef is treated as empty
kmac_hex
Like "kmac" but returns the MAC encoded as a lowercase hexadecimal
string.
my $mac_hex = kmac_hex($variant, $size, $key, $cust, 'data buffer');
kmac_b64
Like "kmac" but returns the MAC encoded as a Base64 string.
my $mac_b64 = kmac_b64($variant, $size, $key, $cust, 'data buffer');
kmac_b64u
Like "kmac" but returns the MAC encoded as a Base64 URL-safe string
(see RFC 4648 section 5).
my $mac_b64u = kmac_b64u($variant, $size, $key, $cust, 'data buffer');
METHODS
Unless noted otherwise, assume $d is an existing MAC object created via
"new", for example:
my $d = Crypt::Mac::KMAC->new('KMAC256', $key, $cust);
new
my $d = Crypt::Mac::KMAC->new($variant, $key);
#or
my $d = Crypt::Mac::KMAC->new($variant, $key, $cust);
# $variant .. [string] 'KMAC128', 'KMAC256', 'KMACXOF128' or 'KMACXOF256'
# $key ..... [binary string] secret key (any length, including empty)
# $cust .... [binary string] customization string (optional, defaults to empty)
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".
$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.
$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($size);
# $size .. [integer] requested output length in bytes (>0)
For "KMAC128" / "KMAC256" the requested length is committed via
right_encode into the cSHAKE input as defined in SP 800-185
section4.3.1; for "KMACXOF128" / "KMACXOF256" the encoded length is 0
and the same $size bytes are squeezed from the XOF (section4.3.2).
hexmac
Like "mac" but returns the MAC encoded as a lowercase hexadecimal
string.
my $result_hex = $d->hexmac($size);
b64mac
Like "mac" but returns the MAC encoded as a Base64 string with trailing
"=" padding.
my $result_b64 = $d->b64mac($size);
b64umac
Like "mac" but returns the MAC encoded as a Base64 URL-safe string (no
trailing "=").
my $result_b64url = $d->b64umac($size);
SEE ALSO
o CryptX(3)
o <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf>
- NIST SP 800-185 (KMAC, cSHAKE, TupleHash, ParallelHash)
perl v5.34.3 2026-06-18 Crypt::Mac::KMAC(3)
cryptx 0.90.0 - Generated Sun Jun 21 16:13:33 CDT 2026