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:

"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);