| 1 | package Crypt::AuthEnc::GCMSIV; | ||
| 2 | |||
| 3 | 3 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 3 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | 3 | our $VERSION = '0.091'; | |
| 6 | |||
| 7 | 3 | require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import'; | |
| 8 | 3 | our %EXPORT_TAGS = ( all => [qw( gcm_siv_encrypt_authenticate gcm_siv_decrypt_verify )] ); | |
| 9 | 3 | our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); | |
| 10 | 3 | our @EXPORT = qw(); | |
| 11 | |||
| 12 | 3 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | 3 | $Carp::Internal{(__PACKAGE__)}++; | |
| 14 | 3 | ▶ | use CryptX; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 15 | |||
| 16 | 3 | 1; | |
| 17 | |||
| 18 | =pod | ||
| 19 | |||
| 20 | =head1 NAME | ||
| 21 | |||
| 22 | Crypt::AuthEnc::GCMSIV - Authenticated encryption in AES-GCM-SIV mode (RFC 8452) | ||
| 23 | |||
| 24 | =head1 SYNOPSIS | ||
| 25 | |||
| 26 | use Crypt::AuthEnc::GCMSIV qw( gcm_siv_encrypt_authenticate gcm_siv_decrypt_verify ); | ||
| 27 | |||
| 28 | my $ciphertext = gcm_siv_encrypt_authenticate('AES', $key, $nonce, $adata, $plaintext); | ||
| 29 | my $plaintext = gcm_siv_decrypt_verify('AES', $key, $nonce, $adata, $ciphertext); # undef on failure | ||
| 30 | |||
| 31 | =head1 DESCRIPTION | ||
| 32 | |||
| 33 | I<Since: CryptX-0.090> | ||
| 34 | |||
| 35 | AES-GCM-SIV is a nonce-misuse-resistant authenticated encryption scheme defined in | ||
| 36 | L<RFC 8452|https://www.rfc-editor.org/rfc/rfc8452>. Reusing a nonce with the same key | ||
| 37 | no longer reveals the plaintext or the authentication key; it only reveals whether | ||
| 38 | the same (plaintext, AAD) pair was encrypted twice. | ||
| 39 | |||
| 40 | The output of C<gcm_siv_encrypt_authenticate> is the ciphertext with a 16-byte | ||
| 41 | authentication tag appended (total output length is C<length($plaintext) + 16>). | ||
| 42 | |||
| 43 | GCM-SIV is defined only for 128-bit block ciphers (i.e. AES); the nonce must be | ||
| 44 | exactly 12 bytes long and the key must be 16 or 32 bytes (AES-128 / AES-256). | ||
| 45 | |||
| 46 | =head1 EXPORT | ||
| 47 | |||
| 48 | Nothing is exported by default. | ||
| 49 | |||
| 50 | You can export selected functions: | ||
| 51 | |||
| 52 | use Crypt::AuthEnc::GCMSIV qw( gcm_siv_encrypt_authenticate gcm_siv_decrypt_verify ); | ||
| 53 | |||
| 54 | =head1 FUNCTIONS | ||
| 55 | |||
| 56 | =head2 gcm_siv_encrypt_authenticate | ||
| 57 | |||
| 58 | my $ciphertext = gcm_siv_encrypt_authenticate($cipher, $key, $nonce, $adata, $plaintext); | ||
| 59 | |||
| 60 | # $cipher ... [string] cipher name (must be 'AES') | ||
| 61 | # $key ... [binary string] 16- or 32-byte key | ||
| 62 | # $nonce ... [binary string] 12-byte nonce | ||
| 63 | # $adata ... [binary string | undef] optional associated data | ||
| 64 | # $plaintext ... [binary string] plaintext to encrypt | ||
| 65 | |||
| 66 | Returns a string of C<length($plaintext) + 16> bytes: ciphertext followed by the | ||
| 67 | 16-byte authentication tag. | ||
| 68 | |||
| 69 | The required string/buffer arguments must be plain scalars; C<$adata> may be | ||
| 70 | C<undef> to indicate no associated data. String-overloaded objects are accepted. | ||
| 71 | |||
| 72 | =head2 gcm_siv_decrypt_verify | ||
| 73 | |||
| 74 | my $plaintext = gcm_siv_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext); | ||
| 75 | |||
| 76 | # $cipher ... [string] cipher name (must be 'AES') | ||
| 77 | # $key ... [binary string] 16- or 32-byte key | ||
| 78 | # $nonce ... [binary string] 12-byte nonce | ||
| 79 | # $adata ... [binary string | undef] optional associated data (must match the value used during encryption) | ||
| 80 | # $ciphertext ... [binary string] ciphertext with 16-byte tag appended | ||
| 81 | |||
| 82 | Returns the plaintext on success, or C<undef> if authentication fails. | ||
| 83 | Malformed input shorter than 16 bytes croaks because it cannot contain the | ||
| 84 | required appended tag. | ||
| 85 | |||
| 86 | =head1 SEE ALSO | ||
| 87 | |||
| 88 | =over | ||
| 89 | |||
| 90 | =item * L<CryptX>, L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::SIV> | ||
| 91 | |||
| 92 | =item * L<RFC 8452|https://www.rfc-editor.org/rfc/rfc8452> | ||
| 93 | |||
| 94 | =back | ||
| 95 | |||
| 96 | =cut | ||