---
name: "Crypt::Mac::KMAC"
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::KMAC"
---

# Crypt::Mac::KMAC(3pm)

Message authentication code KMAC (NIST SP 800-185)

## 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)