Crypt::AuthEnc::SIV(3)                     User Contributed Perl Documentation


NAME
       Crypt::AuthEnc::SIV - Authenticated encryption in SIV mode

SYNOPSIS
         use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );

         my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext);
         my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, $adata);
         my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, [$ad1, $ad2, ...]);

         my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext);
         my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, $adata);
         my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, [$ad1, $ad2, ...]); # undef on failure

DESCRIPTION
       Since: CryptX-0.089

       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.

       The output of "siv_encrypt_authenticate" is the 16-byte SIV tag
       prepended to the ciphertext (total output length is "length($plaintext)
       + 16").

       BEWARE: 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).

       If you pass associated data as an arrayref, at most 126 components are
       accepted.

EXPORT
       Nothing is exported by default.

       You can export selected functions:

         use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );

FUNCTIONS
   siv_encrypt_authenticate
         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. 'AES')
         # $key       ... [binary string] key (must be double the cipher's 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

       Returns a string of "length($plaintext) + 16" bytes (16-byte SIV tag
       prepended to ciphertext).

       The required $key and $plaintext arguments must be string/buffer
       scalars.  If $adata 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.

   siv_decrypt_verify
         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. 'AES')
         # $key        ... [binary string] key (must be double the cipher's 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

       Returns the plaintext on success, or "undef" if authentication fails.
       Malformed ciphertext shorter than 16 bytes croaks because it cannot
       contain the required prepended SIV tag.

       The required $key and $ciphertext arguments must be string/buffer
       scalars. If $adata 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.

SEE ALSO
       o   CryptX, Crypt::AuthEnc::EAX, Crypt::AuthEnc::GCM

       o   RFC 5297 <https://www.rfc-editor.org/rfc/rfc5297>

perl v5.42.2                      2026-05-12            Crypt::AuthEnc::SIV(3)