blib/lib/Crypt/AuthEnc/GCMSIV.pm

filter: Statementstmt 100% 21 / 21 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 100% 25 / 25 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/lib/Crypt/AuthEnc.pm ↑ Summary blib/lib/Crypt/AuthEnc/SIV.pm »
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
« blib/lib/Crypt/AuthEnc.pm ↑ Summary blib/lib/Crypt/AuthEnc/SIV.pm »