.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Crypt::Mac::HMAC 3"
.TH Crypt::Mac::HMAC 3 2026-08-10 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Crypt::Mac::HMAC \- Message authentication code HMAC
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&   ### Functional interface:
\&   use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u );
\&
\&   # calculate MAC from string/buffer
\&   my $hmac_raw  = hmac(\*(AqSHA256\*(Aq, $key, \*(Aqdata buffer\*(Aq);
\&   my $hmac_hex  = hmac_hex(\*(AqSHA256\*(Aq, $key, \*(Aqdata buffer\*(Aq);
\&   my $hmac_b64  = hmac_b64(\*(AqSHA256\*(Aq, $key, \*(Aqdata buffer\*(Aq);
\&   my $hmac_b64u = hmac_b64u(\*(AqSHA256\*(Aq, $key, \*(Aqdata buffer\*(Aq);
\&
\&   ### OO interface:
\&   use Crypt::Mac::HMAC;
\&
\&   my $d = Crypt::Mac::HMAC\->new(\*(AqSHA256\*(Aq, $key);
\&   $d\->add(\*(Aqany data\*(Aq);
\&   my $result_hex = $d\->hexmac;   # finalizes the object
\&
\&   # for another output encoding use a fresh object (or clone before finalizing)
\&   my $result_b64u = Crypt::Mac::HMAC\->new(\*(AqSHA256\*(Aq, $key)\->add(\*(Aqany data\*(Aq)\->b64umac;
\&
\&   # or MAC a file instead
\&   my $file_result_raw = Crypt::Mac::HMAC\->new(\*(AqSHA256\*(Aq, $key)\->addfile(\*(Aqfilename.dat\*(Aq)\->mac;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides an interface to the HMAC message authentication code (MAC) algorithm.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::Mac::HMAC qw( hmac hmac_hex hmac_b64 hmac_b64u );
.Ve
.PP
Or all of them at once:
.PP
.Vb 1
\&  use Crypt::Mac::HMAC \*(Aq:all\*(Aq;
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS hmac
.IX Subsection "hmac"
Joins all arguments into a single string and returns its HMAC message authentication code encoded as a binary string.
.PP
Data arguments for the functional helpers are converted to byte strings using
Perl\*(Aqs usual scalar stringification. Defined scalars, including numbers and
string\-overloaded objects, are accepted. \f(CW\*(C`undef\*(C'\fR is treated as an empty
string and may emit Perl\*(Aqs usual "uninitialized value" warning. The same
rules apply to \f(CW\*(C`hmac_hex\*(C'\fR, \f(CW\*(C`hmac_b64\*(C'\fR, and
\&\f(CW\*(C`hmac_b64u\*(C'\fR.
.PP
.Vb 3
\& my $hmac_raw = hmac($hash_name, $key, \*(Aqdata buffer\*(Aq);
\& #or
\& my $hmac_raw = hmac($hash_name, $key, \*(Aqany data\*(Aq, \*(Aqmore data\*(Aq, \*(Aqeven more data\*(Aq);
\&
\& # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
\& # $key ......... [binary string] the key (octets/bytes)
.Ve
.SS hmac_hex
.IX Subsection "hmac_hex"
Joins all arguments into a single string and returns its HMAC message authentication code encoded as a hexadecimal string.
.PP
.Vb 3
\& my $hmac_hex = hmac_hex($hash_name, $key, \*(Aqdata buffer\*(Aq);
\& #or
\& my $hmac_hex = hmac_hex($hash_name, $key, \*(Aqany data\*(Aq, \*(Aqmore data\*(Aq, \*(Aqeven more data\*(Aq);
\&
\& # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
\& # $key ......... [binary string] the key (not hex!)
.Ve
.SS hmac_b64
.IX Subsection "hmac_b64"
Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 string.
.PP
.Vb 3
\& my $hmac_b64 = hmac_b64($hash_name, $key, \*(Aqdata buffer\*(Aq);
\& #or
\& my $hmac_b64 = hmac_b64($hash_name, $key, \*(Aqany data\*(Aq, \*(Aqmore data\*(Aq, \*(Aqeven more data\*(Aq);
\&
\& # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
\& # $key ......... [binary string] the key (not Base64!)
.Ve
.SS hmac_b64u
.IX Subsection "hmac_b64u"
Joins all arguments into a single string and returns its HMAC message authentication code encoded as a Base64 URL\-safe string (see RFC 4648 section 5).
.PP
.Vb 3
\& my $hmac_b64url = hmac_b64u($hash_name, $key, \*(Aqdata buffer\*(Aq);
\& #or
\& my $hmac_b64url = hmac_b64u($hash_name, $key, \*(Aqany data\*(Aq, \*(Aqmore data\*(Aq, \*(Aqeven more data\*(Aq);
\&
\& # $hash_name ... [string] any <NAME> for which there is a Crypt::Digest::<NAME> module
\& # $key ......... [binary string] the key (not Base64url!)
.Ve
.SH METHODS
.IX Header "METHODS"
Unless noted otherwise, assume \f(CW$d\fR is an existing MAC object created via
\&\f(CW\*(C`new\*(C'\fR, for example:
.PP
.Vb 1
\& my $d = Crypt::Mac::HMAC\->new(\*(AqSHA256\*(Aq, $key);
.Ve
.SS new
.IX Subsection "new"
.Vb 1
\& my $d = Crypt::Mac::HMAC\->new($hash_name, $key);
\&
\& # $hash_name ... [string] one of \*(AqSHA256\*(Aq, \*(AqSHA384\*(Aq, \*(AqSHA512\*(Aq, \*(AqSHA1\*(Aq, \*(AqSHA3_256\*(Aq, \*(AqBLAKE2b_256\*(Aq,
\& #                \*(AqRIPEMD160\*(Aq, etc. \- any <NAME> for which there is a Crypt::Digest::<NAME> module
\& # $key ......... [binary string] the key (any length \- internally padded/hashed as per RFC 2104)
.Ve
.SS clone
.IX Subsection "clone"
.Vb 1
\& $d\->clone();
.Ve
.SS add
.IX Subsection "add"
Appends data to the message. Returns the object itself (for chaining).
Croaks if the object has already been finalized by \f(CW\*(C`mac\*(C'\fR, \f(CW\*(C`hexmac\*(C'\fR,
\&\f(CW\*(C`b64mac\*(C'\fR, or \f(CW\*(C`b64umac\*(C'\fR.
.PP
Each argument is converted to bytes using Perl\*(Aqs usual scalar stringification.
Defined scalars, including numbers and string\-overloaded objects, are
accepted. \f(CW\*(C`undef\*(C'\fR is treated as an empty string and may emit Perl\*(Aqs usual
"uninitialized value" warning.
.PP
.Vb 3
\& $d\->add(\*(Aqany data\*(Aq);
\& #or
\& $d\->add(\*(Aqany data\*(Aq, \*(Aqmore data\*(Aq, \*(Aqeven more data\*(Aq);
.Ve
.SS addfile
.IX Subsection "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 by \f(CW\*(C`mac\*(C'\fR,
\&\f(CW\*(C`hexmac\*(C'\fR, \f(CW\*(C`b64mac\*(C'\fR, or \f(CW\*(C`b64umac\*(C'\fR.
.PP
.Vb 4
\& $d\->addfile(\*(Aqfilename.dat\*(Aq);
\& #or
\& my $filehandle = ...; # existing binary\-mode filehandle
\& $d\->addfile($filehandle);
.Ve
.SS mac
.IX Subsection "mac"
Returns the binary MAC (raw bytes) and finalizes the object. After the first
call to \f(CW\*(C`mac\*(C'\fR, \f(CW\*(C`hexmac\*(C'\fR, \f(CW\*(C`b64mac\*(C'\fR, or \f(CW\*(C`b64umac\*(C'\fR, later calls to \f(CW\*(C`add\*(C'\fR,
\&\f(CW\*(C`addfile\*(C'\fR, or any MAC getter croak.
.PP
.Vb 1
\& my $result_raw = $d\->mac();
.Ve
.SS hexmac
.IX Subsection "hexmac"
Returns the MAC encoded as a lowercase hexadecimal string and finalizes the
object. After the first call to \f(CW\*(C`mac\*(C'\fR, \f(CW\*(C`hexmac\*(C'\fR, \f(CW\*(C`b64mac\*(C'\fR, or \f(CW\*(C`b64umac\*(C'\fR,
later calls to \f(CW\*(C`add\*(C'\fR, \f(CW\*(C`addfile\*(C'\fR, or any MAC getter croak.
.PP
.Vb 1
\& my $result_hex = $d\->hexmac();
.Ve
.SS b64mac
.IX Subsection "b64mac"
Returns the MAC encoded as a Base64 string with trailing \f(CW\*(C`=\*(C'\fR padding and
finalizes the object. After the first call to \f(CW\*(C`mac\*(C'\fR, \f(CW\*(C`hexmac\*(C'\fR, \f(CW\*(C`b64mac\*(C'\fR, or
\&\f(CW\*(C`b64umac\*(C'\fR, later calls to \f(CW\*(C`add\*(C'\fR, \f(CW\*(C`addfile\*(C'\fR, or any MAC getter croak.
.PP
.Vb 1
\& my $result_b64 = $d\->b64mac();
.Ve
.SS b64umac
.IX Subsection "b64umac"
Returns the MAC encoded as a Base64 URL\-safe string (no trailing \f(CW\*(C`=\*(C'\fR) and
finalizes the object. After the first call to \f(CW\*(C`mac\*(C'\fR, \f(CW\*(C`hexmac\*(C'\fR, \f(CW\*(C`b64mac\*(C'\fR, or
\&\f(CW\*(C`b64umac\*(C'\fR, later calls to \f(CW\*(C`add\*(C'\fR, \f(CW\*(C`addfile\*(C'\fR, or any MAC getter croak.
.PP
.Vb 1
\& my $result_b64url = $d\->b64umac();
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CryptX
.IP \(bu 4
<https://en.wikipedia.org/wiki/Hmac>
.IP \(bu 4
<https://www.rfc\-editor.org/rfc/rfc2104>