Scroll to navigation

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

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

2026-07-04 perl v5.40.1