blib/lib/Crypt/AuthEnc/EAX.pm

filter: Statementstmt 91.6% 22 / 24 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 71.4% 5 / 7 Podpod 0.0% 0 / 2 totaltotal 81.8% 27 / 33 CC 1 SCAR 2.5
CC
1
Cov
92%
aad_add
2.0
CLONE_SKIP
2.0
BEGIN
1.0
CRAP 1.3
« blib/lib/Crypt/PRNG/Yarrow.pm ↑ Summary blib/lib/Crypt/Mode/XTS.pm »
1 package Crypt::AuthEnc::EAX;
2  
3 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 5 our $VERSION = '0.091';
6  
7 5 require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8 5 our %EXPORT_TAGS = ( all => [qw( eax_encrypt_authenticate eax_decrypt_verify )] );
9 5 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10 5 our @EXPORT = qw();
11  
12 5 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 5 $Carp::Internal{(__PACKAGE__)}++;
14 5 ▶use CryptX;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 # obsolete, only for backwards compatibility
17 23 ▶sub header_add { goto &adata_add }
Subroutine header_add: called CC=1 SCAR=0.0
Pod undocumented
18 0 ▶sub aad_add { goto &adata_add }
Subroutine aad_add: not called CC=1 SCAR=6.9
Pod undocumented
19  
20 0 ▶sub CLONE_SKIP { 1 } # prevent cloning
Subroutine CLONE_SKIP: not called CC=1 SCAR=6.9
21  
22 5 1;
23  
24 =pod
25  
26 =head1 NAME
27  
28 Crypt::AuthEnc::EAX - Authenticated encryption in EAX mode
29  
30 =head1 SYNOPSIS
31  
32 ### OO interface
33 use Crypt::AuthEnc::EAX;
34  
35 my $key = '...';
36 my $nonce = '...';
37 my $expected_tag = '...';
38  
39 # encrypt and authenticate
40 my $ae_enc = Crypt::AuthEnc::EAX->new("AES", $key, $nonce);
41 $ae_enc->adata_add('additional_authenticated_data1');
42 $ae_enc->adata_add('additional_authenticated_data2');
43 my $ct = $ae_enc->encrypt_add('data1');
44 $ct .= $ae_enc->encrypt_add('data2');
45 $ct .= $ae_enc->encrypt_add('data3');
46 my $tag = $ae_enc->encrypt_done();
47  
48 # decrypt and verify
49 my $ae_dec = Crypt::AuthEnc::EAX->new("AES", $key, $nonce);
50 $ae_dec->adata_add('additional_authenticated_data1');
51 $ae_dec->adata_add('additional_authenticated_data2');
52 my $pt = $ae_dec->decrypt_add('ciphertext1');
53 $pt .= $ae_dec->decrypt_add('ciphertext2');
54 $pt .= $ae_dec->decrypt_add('ciphertext3');
55 $ae_dec->decrypt_done($expected_tag) or die "decrypt failed"; # constant-time tag check
56  
57 #or, if you need the computed tag, compare it with slow_eq from Crypt::Misc
58 #(Perl's 'eq' is not constant-time and leaks timing information)
59 my $computed_tag = $ae_dec->decrypt_done();
60 die "decrypt failed" unless Crypt::Misc::slow_eq($computed_tag, $expected_tag);
61  
62 ### functional interface
63 use Crypt::AuthEnc::EAX qw(eax_encrypt_authenticate eax_decrypt_verify);
64  
65 my $key = '...';
66 my $nonce = '...';
67 my $adata = '...';
68 my $plaintext = '...';
69  
70 my ($ciphertext, $tag) = eax_encrypt_authenticate('AES', $key, $nonce, $adata, $plaintext);
71 my $decrypted = eax_decrypt_verify('AES', $key, $nonce, $adata, $ciphertext, $tag);
72  
73 =head1 DESCRIPTION
74  
75 EAX is a mode that requires a cipher, CTR and OMAC support and provides encryption and authentication.
76 It is initialized with a random IV that can be shared publicly, additional authenticated data which can
77 be fixed and public, and a random secret symmetric key.
78  
79 This is a stateful API. Build one message by calling, in order:
80 C<new>, optional extra C<adata_add>, zero or more C<encrypt_add> or
81 C<decrypt_add> calls, then C<encrypt_done> or C<decrypt_done>.
82  
83 Use a fresh object per message. The optional C<$adata> argument to C<new> is
84 equivalent to adding initial AAD before processing any payload. When verifying,
85 C<decrypt_done($expected_tag)> is the safer one-step form; C<decrypt_done()>
86 without arguments only returns the calculated tag.
87 The first C<encrypt_done> / C<decrypt_done> call finalizes the object. After that,
88 further C<adata_add>, C<encrypt_add>, C<decrypt_add>, C<encrypt_done>, and
89 C<decrypt_done> calls croak.
90  
91 =head1 EXPORT
92  
93 Nothing is exported by default.
94  
95 You can export selected functions:
96  
97 use Crypt::AuthEnc::EAX qw(eax_encrypt_authenticate eax_decrypt_verify);
98  
99 =head1 FUNCTIONS
100  
101 =head2 eax_encrypt_authenticate
102  
103 my ($ciphertext, $tag) = eax_encrypt_authenticate($cipher, $key, $nonce, $adata, $plaintext);
104  
105 # $cipher .. [string] 'AES' or name of any other cipher with 16-byte block len
106 # $key ..... [binary string] AES key of proper length (128/192/256 bits)
107 # $nonce ... [binary string] unique nonce (no need to keep it secret)
108 # $adata ... [binary string] additional authenticated data
109  
110 =head2 eax_decrypt_verify
111  
112 my $plaintext = eax_decrypt_verify($cipher, $key, $nonce, $adata, $ciphertext, $tag);
113 # on error returns undef
114  
115 =head1 METHODS
116  
117 Unless noted otherwise, assume C<$ae> is an existing AEAD object created via
118 C<new>, for example:
119  
120 my $ae = Crypt::AuthEnc::EAX->new($cipher, $key, $nonce);
121  
122 =head2 new
123  
124 my $ae = Crypt::AuthEnc::EAX->new($cipher, $key, $nonce);
125 #or
126 my $ae = Crypt::AuthEnc::EAX->new($cipher, $key, $nonce, $adata);
127  
128 # $cipher .. [string] 'AES' or name of any other cipher with 16-byte block len
129 # $key ..... [binary string] AES key of proper length (128/192/256 bits)
130 # $nonce ... [binary string] unique nonce (no need to keep it secret)
131 # $adata ... [binary string] additional authenticated data (optional)
132  
133 =head2 adata_add
134  
135 Can be called only before the first C<encrypt_add> or C<decrypt_add>.
136 Returns the object itself (for chaining).
137  
138 $ae->adata_add($adata); # can be called multiple times
139  
140 =head2 encrypt_add
141  
142 Returns a binary string of ciphertext (raw bytes).
143  
144 my $ciphertext = $ae->encrypt_add($data); # can be called multiple times
145  
146 =head2 encrypt_done
147  
148 Returns the authentication tag as a binary string (raw bytes).
149 This call finalizes the current message.
150  
151 my $tag = $ae->encrypt_done(); # returns $tag value
152  
153 B<IMPORTANT:> The length of the tag is a security parameter and a zero-length
154 tag is legal (it simply provides no authenticity), which is the caller's choice.
155  
156 =head2 decrypt_add
157  
158 Returns a binary string of plaintext (raw bytes).
159  
160 my $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
161  
162 =head2 decrypt_done
163  
164 Without argument returns the computed tag as a binary string. With C<$tag> argument returns C<1> (success) or C<0> (failure).
165 This call finalizes the current message.
166  
167 my $tag = $ae->decrypt_done; # returns $tag value
168 #or
169 my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
170  
171 =head2 clone
172  
173 Returns a copy of the AEAD object in its current state.
174  
175 my $ae_new = $ae->clone;
176  
177 =head1 SEE ALSO
178  
179 =over
180  
181 =item * L<CryptX>, L<Crypt::AuthEnc::CCM>, L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::OCB>
182  
183 =item * L<https://en.wikipedia.org/wiki/EAX_mode>
184  
185 =item * L<https://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf>
186  
187 =back
188  
189 =cut
« blib/lib/Crypt/PRNG/Yarrow.pm ↑ Summary blib/lib/Crypt/Mode/XTS.pm »