.\" -*- 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::AuthEnc::EAX 3"
.TH Crypt::AuthEnc::EAX 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::AuthEnc::EAX \- Authenticated encryption in EAX mode
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& ### OO interface
\& use Crypt::AuthEnc::EAX;
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $expected_tag = \*(Aq...\*(Aq;
\&
\& # encrypt and authenticate
\& my $ae_enc = Crypt::AuthEnc::EAX\->new("AES", $key, $nonce);
\& $ae_enc\->adata_add(\*(Aqadditional_authenticated_data1\*(Aq);
\& $ae_enc\->adata_add(\*(Aqadditional_authenticated_data2\*(Aq);
\& my $ct = $ae_enc\->encrypt_add(\*(Aqdata1\*(Aq);
\& $ct .= $ae_enc\->encrypt_add(\*(Aqdata2\*(Aq);
\& $ct .= $ae_enc\->encrypt_add(\*(Aqdata3\*(Aq);
\& my $tag = $ae_enc\->encrypt_done();
\&
\& # decrypt and verify
\& my $ae_dec = Crypt::AuthEnc::EAX\->new("AES", $key, $nonce);
\& $ae_dec\->adata_add(\*(Aqadditional_authenticated_data1\*(Aq);
\& $ae_dec\->adata_add(\*(Aqadditional_authenticated_data2\*(Aq);
\& my $pt = $ae_dec\->decrypt_add(\*(Aqciphertext1\*(Aq);
\& $pt .= $ae_dec\->decrypt_add(\*(Aqciphertext2\*(Aq);
\& $pt .= $ae_dec\->decrypt_add(\*(Aqciphertext3\*(Aq);
\& $ae_dec\->decrypt_done($expected_tag) or die "decrypt failed"; # constant\-time tag check
\&
\& #or, if you need the computed tag, compare it with slow_eq from Crypt::Misc
\& #(Perl\*(Aqs \*(Aqeq\*(Aq is not constant\-time and leaks timing information)
\& my $computed_tag = $ae_dec\->decrypt_done();
\& die "decrypt failed" unless Crypt::Misc::slow_eq($computed_tag, $expected_tag);
\&
\& ### functional interface
\& use Crypt::AuthEnc::EAX qw(eax_encrypt_authenticate eax_decrypt_verify);
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $adata = \*(Aq...\*(Aq;
\& my $plaintext = \*(Aq...\*(Aq;
\&
\& my ($ciphertext, $tag) = eax_encrypt_authenticate(\*(AqAES\*(Aq, $key, $nonce, $adata, $plaintext);
\& my $decrypted = eax_decrypt_verify(\*(AqAES\*(Aq, $key, $nonce, $adata, $ciphertext, $tag);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
EAX is a mode that requires a cipher, CTR and OMAC support and provides encryption and authentication.
It is initialized with a random IV that can be shared publicly, additional authenticated data which can
be fixed and public, and a random secret symmetric key.
.PP
This is a stateful API. Build one message by calling, in order:
\&\f(CW\*(C`new\*(C'\fR, optional extra \f(CW\*(C`adata_add\*(C'\fR, zero or more \f(CW\*(C`encrypt_add\*(C'\fR or
\&\f(CW\*(C`decrypt_add\*(C'\fR calls, then \f(CW\*(C`encrypt_done\*(C'\fR or \f(CW\*(C`decrypt_done\*(C'\fR.
.PP
Use a fresh object per message. The optional \f(CW$adata\fR argument to \f(CW\*(C`new\*(C'\fR is
equivalent to adding initial AAD before processing any payload. When verifying,
\&\f(CWdecrypt_done($expected_tag)\fR is the safer one\-step form; \f(CWdecrypt_done()\fR
without arguments only returns the calculated tag.
The first \f(CW\*(C`encrypt_done\*(C'\fR / \f(CW\*(C`decrypt_done\*(C'\fR call finalizes the object. After that,
further \f(CW\*(C`adata_add\*(C'\fR, \f(CW\*(C`encrypt_add\*(C'\fR, \f(CW\*(C`decrypt_add\*(C'\fR, \f(CW\*(C`encrypt_done\*(C'\fR, and
\&\f(CW\*(C`decrypt_done\*(C'\fR calls croak.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::AuthEnc::EAX qw(eax_encrypt_authenticate eax_decrypt_verify);
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS eax_encrypt_authenticate
.IX Subsection "eax_encrypt_authenticate"
.Vb 1
\& my ($ciphertext, $tag) = eax_encrypt_authenticate($cipher, $key, $nonce, $adata, $plaintext);
\&
\& # $cipher .. [string] \*(AqAES\*(Aq or name of any other cipher with 16\-byte block len
\& # $key ..... [binary string] AES key of proper length (128/192/256 bits)
\& # $nonce ... [binary string] unique nonce (no need to keep it secret)
\& # $adata ... [binary string] additional authenticated data
.Ve
.SS eax_decrypt_verify
.IX Subsection "eax_decrypt_verify"
.Vb 2
\& my $plaintext = eax_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext, $tag);
\& # on error returns undef
.Ve
.SH METHODS
.IX Header "METHODS"
Unless noted otherwise, assume \f(CW$ae\fR is an existing AEAD object created via
\&\f(CW\*(C`new\*(C'\fR, for example:
.PP
.Vb 1
\& my $ae = Crypt::AuthEnc::EAX\->new($cipher, $key, $nonce);
.Ve
.SS new
.IX Subsection "new"
.Vb 3
\& my $ae = Crypt::AuthEnc::EAX\->new($cipher, $key, $nonce);
\& #or
\& my $ae = Crypt::AuthEnc::EAX\->new($cipher, $key, $nonce, $adata);
\&
\& # $cipher .. [string] \*(AqAES\*(Aq or name of any other cipher with 16\-byte block len
\& # $key ..... [binary string] AES key of proper length (128/192/256 bits)
\& # $nonce ... [binary string] unique nonce (no need to keep it secret)
\& # $adata ... [binary string] additional authenticated data (optional)
.Ve
.SS adata_add
.IX Subsection "adata_add"
Can be called only before the first \f(CW\*(C`encrypt_add\*(C'\fR or \f(CW\*(C`decrypt_add\*(C'\fR.
Returns the object itself (for chaining).
.PP
.Vb 1
\& $ae\->adata_add($adata);                        # can be called multiple times
.Ve
.SS encrypt_add
.IX Subsection "encrypt_add"
Returns a binary string of ciphertext (raw bytes).
.PP
.Vb 1
\& my $ciphertext = $ae\->encrypt_add($data);      # can be called multiple times
.Ve
.SS encrypt_done
.IX Subsection "encrypt_done"
Returns the authentication tag as a binary string (raw bytes).
This call finalizes the current message.
.PP
.Vb 1
\& my $tag = $ae\->encrypt_done();                 # returns $tag value
.Ve
.PP
\&\fBIMPORTANT:\fR The length of the tag is a security parameter and a zero\-length
tag is legal (it simply provides no authenticity), which is the caller\*(Aqs choice.
.SS decrypt_add
.IX Subsection "decrypt_add"
Returns a binary string of plaintext (raw bytes).
.PP
.Vb 1
\& my $plaintext = $ae\->decrypt_add($ciphertext); # can be called multiple times
.Ve
.SS decrypt_done
.IX Subsection "decrypt_done"
Without argument returns the computed tag as a binary string. With \f(CW$tag\fR argument returns \f(CW1\fR (success) or \f(CW0\fR (failure).
This call finalizes the current message.
.PP
.Vb 3
\& my $tag = $ae\->decrypt_done;           # returns $tag value
\& #or
\& my $result = $ae\->decrypt_done($tag);  # returns 1 (success) or 0 (failure)
.Ve
.SS clone
.IX Subsection "clone"
Returns a copy of the AEAD object in its current state.
.PP
.Vb 1
\& my $ae_new = $ae\->clone;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CryptX, Crypt::AuthEnc::CCM, Crypt::AuthEnc::GCM, Crypt::AuthEnc::OCB
.IP \(bu 4
<https://en.wikipedia.org/wiki/EAX_mode>
.IP \(bu 4
<https://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf>