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:

•   "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.

•   "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

•   CryptX

•   <https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-185.pdf> - NIST SP 800-185 (KMAC, cSHAKE, TupleHash, ParallelHash)