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.