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


NAME
       Crypt::AuthEnc::GCMSIV - Authenticated encryption in AES-GCM-SIV mode
       (RFC 8452)

SYNOPSIS
         use Crypt::AuthEnc::GCMSIV qw( gcm_siv_encrypt_authenticate gcm_siv_decrypt_verify );

         my $ciphertext = gcm_siv_encrypt_authenticate('AES', $key, $nonce, $adata, $plaintext);
         my $plaintext  = gcm_siv_decrypt_verify('AES', $key, $nonce, $adata, $ciphertext); # undef on failure

DESCRIPTION
       Since: CryptX-0.090

       AES-GCM-SIV is a nonce-misuse-resistant authenticated encryption scheme
       defined in RFC 8452 <https://www.rfc-editor.org/rfc/rfc8452>. Reusing a
       nonce with the same key no longer reveals the plaintext or the
       authentication key; it only reveals whether the same (plaintext, AAD)
       pair was encrypted twice.

       The output of "gcm_siv_encrypt_authenticate" is the ciphertext with a
       16-byte authentication tag appended (total output length is
       "length($plaintext) + 16").

       GCM-SIV is defined only for 128-bit block ciphers (i.e. AES); the nonce
       must be exactly 12 bytes long and the key must be 16 or 32 bytes
       (AES-128 / AES-256).

EXPORT
       Nothing is exported by default.

       You can export selected functions:

         use Crypt::AuthEnc::GCMSIV qw( gcm_siv_encrypt_authenticate gcm_siv_decrypt_verify );

FUNCTIONS
   gcm_siv_encrypt_authenticate
         my $ciphertext = gcm_siv_encrypt_authenticate($cipher, $key, $nonce, $adata, $plaintext);

         # $cipher    ... [string] cipher name (must be 'AES')
         # $key       ... [binary string] 16- or 32-byte key
         # $nonce     ... [binary string] 12-byte nonce
         # $adata     ... [binary string | undef] optional associated data
         # $plaintext ... [binary string] plaintext to encrypt

       Returns a string of "length($plaintext) + 16" bytes: ciphertext
       followed by the 16-byte authentication tag.

       The required string/buffer arguments must be plain scalars; $adata may
       be "undef" to indicate no associated data. String-overloaded objects
       are accepted.

   gcm_siv_decrypt_verify
         my $plaintext = gcm_siv_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext);

         # $cipher     ... [string] cipher name (must be 'AES')
         # $key        ... [binary string] 16- or 32-byte key
         # $nonce      ... [binary string] 12-byte nonce
         # $adata      ... [binary string | undef] optional associated data (must match the value used during encryption)
         # $ciphertext ... [binary string] ciphertext with 16-byte tag appended

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

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

       o   RFC 8452 <https://www.rfc-editor.org/rfc/rfc8452>

perl v5.42.2                      2026-06-18         Crypt::AuthEnc::GCMSIV(3)