blib/lib/Crypt/AuthEnc/SIV.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/GCMSIV.pm ↑ Summary blib/lib/Crypt/Checksum/Adler32.pm »
1 package Crypt::AuthEnc::SIV;
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( siv_encrypt_authenticate 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::SIV - Authenticated encryption in SIV mode
23  
24 =head1 SYNOPSIS
25  
26 use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );
27  
28 my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext);
29 my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, $adata);
30 my $ciphertext = siv_encrypt_authenticate('AES', $key, $plaintext, [$ad1, $ad2, ...]);
31  
32 my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext);
33 my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, $adata);
34 my $plaintext = siv_decrypt_verify('AES', $key, $ciphertext, [$ad1, $ad2, ...]); # undef on failure
35  
36 =head1 DESCRIPTION
37  
38 I<Since: CryptX-0.089>
39  
40 SIV (Synthetic IV) is a deterministic authenticated encryption scheme defined in
41 L<RFC 5297|https://www.rfc-editor.org/rfc/rfc5297>. Unlike nonce-based modes, SIV derives
42 the authentication tag (the IV) synthetically from the key, associated data, and plaintext,
43 making it nonce-misuse resistant.
44  
45 The output of C<siv_encrypt_authenticate> is the 16-byte SIV tag prepended to the ciphertext
46 (total output length is C<length($plaintext) + 16>).
47  
48 B<BEWARE:> SIV requires a key that is twice the length of the underlying cipher key
49 (e.g. 256 bits for AES-128-SIV, 512 bits for AES-256-SIV).
50  
51 If you pass associated data as an arrayref, at most 126 components are accepted.
52  
53 =head2 No associated data vs. empty associated data
54  
55 RFC 5297 feeds C<S2V> a I<list> of strings (C<AD1..ADm>, then the plaintext), and the
56 number of components changes the result. Passing B<no> associated data is therefore
57 not the same as passing B<one empty> associated data string:
58  
59 siv_encrypt_authenticate('AES', $key, $pt); # zero AD components
60 siv_encrypt_authenticate('AES', $key, $pt, undef); # zero AD components
61 siv_encrypt_authenticate('AES', $key, $pt, []); # zero AD components
62  
63 siv_encrypt_authenticate('AES', $key, $pt, ""); # ONE empty AD component
64 siv_encrypt_authenticate('AES', $key, $pt, [""]); # ONE empty AD component
65  
66 The two groups produce different tags, and ciphertext produced by one does not
67 verify under the other.
68  
69 Beware that some other libraries expose only a single associated data argument and
70 so cannot express the zero-component case at all; when interoperating with those,
71 an "empty" associated data string usually corresponds to the C<""> form above.
72  
73 C<undef> elements inside an arrayref are skipped rather than folded as empty
74 components, so C<[$ad1, undef, $ad2]> is equivalent to C<[$ad1, $ad2]>.
75  
76 =head1 EXPORT
77  
78 Nothing is exported by default.
79  
80 You can export selected functions:
81  
82 use Crypt::AuthEnc::SIV qw( siv_encrypt_authenticate siv_decrypt_verify );
83  
84 =head1 FUNCTIONS
85  
86 =head2 siv_encrypt_authenticate
87  
88 my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext);
89 #or
90 my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, $adata);
91 #or
92 my $ciphertext = siv_encrypt_authenticate($cipher, $key, $plaintext, [$ad1, $ad2, ...]);
93  
94 # $cipher ... [string] cipher name (e.g. 'AES')
95 # $key ... [binary string] key (must be double the cipher's standard key length)
96 # $plaintext ... [binary string] plaintext to encrypt
97 # $adata ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars
98  
99 Returns a string of C<length($plaintext) + 16> bytes (16-byte SIV tag prepended to ciphertext).
100  
101 The required C<$key> and C<$plaintext> arguments must be string/buffer scalars.
102 If C<$adata> is given as a scalar, it must also be a string/buffer scalar. If
103 it is given as an arrayref, each defined element must be a string/buffer scalar.
104 String-overloaded objects are accepted.
105  
106 =head2 siv_decrypt_verify
107  
108 my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext);
109 #or
110 my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, $adata);
111 #or
112 my $plaintext = siv_decrypt_verify($cipher, $key, $ciphertext, [$ad1, $ad2, ...]);
113  
114 # $cipher ... [string] cipher name (e.g. 'AES')
115 # $key ... [binary string] key (must be double the cipher's standard key length)
116 # $ciphertext ... [binary string] ciphertext with 16-byte SIV tag prepended
117 # $adata ... [binary string | arrayref] optional associated data: a scalar string or an arrayref of up to 126 string/buffer scalars
118  
119 Returns the plaintext on success, or C<undef> if authentication fails.
120 Malformed ciphertext shorter than 16 bytes croaks because it cannot contain the required
121 prepended SIV tag.
122  
123 The required C<$key> and C<$ciphertext> arguments must be string/buffer
124 scalars. If C<$adata> is given as a scalar, it must also be a
125 string/buffer scalar. If it is given as an arrayref, each defined element
126 must be a string/buffer scalar. String-overloaded objects are accepted.
127  
128 =head1 SEE ALSO
129  
130 =over
131  
132 =item * L<CryptX>, L<Crypt::AuthEnc::EAX>, L<Crypt::AuthEnc::GCM>
133  
134 =item * L<RFC 5297|https://www.rfc-editor.org/rfc/rfc5297>
135  
136 =back
137  
138 =cut
« blib/lib/Crypt/AuthEnc/GCMSIV.pm ↑ Summary blib/lib/Crypt/Checksum/Adler32.pm »