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

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

perl v5.42.2                      2026-06-18               Crypt::Mac::KMAC(3)