.\" -*- 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::SIV 3"
.TH Crypt::AuthEnc::SIV 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::SIV \- Authenticated encryption in SIV mode
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );
\&
\&  my $ciphertext = siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $plaintext);
\&  my $ciphertext = siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $plaintext, $adata);
\&  my $ciphertext = siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $plaintext, [$ad1, $ad2, ...]);
\&
\&  my $plaintext = siv_decrypt_verify(\*(AqAES\*(Aq, $key, $ciphertext);
\&  my $plaintext = siv_decrypt_verify(\*(AqAES\*(Aq, $key, $ciphertext, $adata);
\&  my $plaintext = siv_decrypt_verify(\*(AqAES\*(Aq, $key, $ciphertext, [$ad1, $ad2, ...]); # undef on failure
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fISince: CryptX\-0.089\fR
.PP
SIV (Synthetic IV) is a deterministic authenticated encryption scheme defined in
RFC 5297 <https://www.rfc-editor.org/rfc/rfc5297>. Unlike nonce\-based modes, SIV derives
the authentication tag (the IV) synthetically from the key, associated data, and plaintext,
making it nonce\-misuse resistant.
.PP
The output of \f(CW\*(C`siv_encrypt_authenticate\*(C'\fR is the 16\-byte SIV tag prepended to the ciphertext
(total output length is \f(CW\*(C`length($plaintext) + 16\*(C'\fR).
.PP
\&\fBBEWARE:\fR SIV requires a key that is twice the length of the underlying cipher key
(e.g. 256 bits for AES\-128\-SIV, 512 bits for AES\-256\-SIV).
.PP
If you pass associated data as an arrayref, at most 126 components are accepted.
.SS "No associated data vs. empty associated data"
.IX Subsection "No associated data vs. empty associated data"
RFC 5297 feeds \f(CW\*(C`S2V\*(C'\fR a \fIlist\fR of strings (\f(CW\*(C`AD1..ADm\*(C'\fR, then the plaintext), and the
number of components changes the result. Passing \fBno\fR associated data is therefore
not the same as passing \fBone empty\fR associated data string:
.PP
.Vb 3
\&  siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $pt);         # zero AD components
\&  siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $pt, undef);  # zero AD components
\&  siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $pt, []);     # zero AD components
\&
\&  siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $pt, "");     # ONE empty AD component
\&  siv_encrypt_authenticate(\*(AqAES\*(Aq, $key, $pt, [""]);   # ONE empty AD component
.Ve
.PP
The two groups produce different tags, and ciphertext produced by one does not
verify under the other.
.PP
Beware that some other libraries expose only a single associated data argument and
so cannot express the zero\-component case at all; when interoperating with those,
an "empty" associated data string usually corresponds to the \f(CW""\fR form above.
.PP
\&\f(CW\*(C`undef\*(C'\fR elements inside an arrayref are skipped rather than folded as empty
components, so \f(CW\*(C`[$ad1, undef, $ad2]\*(C'\fR is equivalent to \f(CW\*(C`[$ad1, $ad2]\*(C'\fR.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS siv_encrypt_authenticate
.IX Subsection "siv_encrypt_authenticate"
.Vb 5
\&  my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext);
\&  #or
\&  my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, $adata);
\&  #or
\&  my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, [$ad1, $ad2, ...]);
\&
\&  # $cipher    ... [string] cipher name (e.g. \*(AqAES\*(Aq)
\&  # $key       ... [binary string] key (must be double the cipher\*(Aqs standard key length)
\&  # $plaintext ... [binary string] plaintext to encrypt
\&  # $adata     ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars
.Ve
.PP
Returns a string of \f(CW\*(C`length($plaintext) + 16\*(C'\fR bytes (16\-byte SIV tag prepended to ciphertext).
.PP
The required \f(CW$key\fR and \f(CW$plaintext\fR arguments must be string/buffer scalars.
If \f(CW$adata\fR is given as a scalar, it must also be a string/buffer scalar. If
it is given as an arrayref, each defined element must be a string/buffer scalar.
String\-overloaded objects are accepted.
.SS siv_decrypt_verify
.IX Subsection "siv_decrypt_verify"
.Vb 5
\&  my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext);
\&  #or
\&  my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, $adata);
\&  #or
\&  my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, [$ad1, $ad2, ...]);
\&
\&  # $cipher     ... [string] cipher name (e.g. \*(AqAES\*(Aq)
\&  # $key        ... [binary string] key (must be double the cipher\*(Aqs standard key length)
\&  # $ciphertext ... [binary string] ciphertext with 16\-byte SIV tag prepended
\&  # $adata      ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars
.Ve
.PP
Returns the plaintext on success, or \f(CW\*(C`undef\*(C'\fR if authentication fails.
Malformed ciphertext shorter than 16 bytes croaks because it cannot contain the required
prepended SIV tag.
.PP
The required \f(CW$key\fR and \f(CW$ciphertext\fR arguments must be string/buffer
scalars. If \f(CW$adata\fR is given as a scalar, it must also be a
string/buffer scalar. If it is given as an arrayref, each defined element
must be a string/buffer scalar. String\-overloaded objects are accepted.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CryptX, Crypt::AuthEnc::EAX, Crypt::AuthEnc::GCM
.IP \(bu 4
RFC 5297 <https://www.rfc-editor.org/rfc/rfc5297>