blib/lib/Crypt/AuthEnc/XChaCha20Poly1305.pm

filter: Statementstmt 98.0% 51 / 52 Branchbran 75.0% 12 / 16 Conditioncond 55.5% 5 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 92.3% 12 / 13 Podpod 100% 5 / 5 totaltotal 84.1% 85 / 101 CC 12 SCAR 11.6
CC
12
Cov
88%
_check_nonce
5.3
_check_key
5.3
new
3.0
CRAP 3.2
« blib/lib/CryptX.pm ↑ Summary blib/lib/Crypt/PK.pm »
1 package Crypt::AuthEnc::XChaCha20Poly1305;
2  
3 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 our $VERSION = '0.091';
6  
7 2 require Exporter; our @ISA = qw(Exporter Crypt::AuthEnc::ChaCha20Poly1305); ### use Exporter 5.57 'import';
8 2 our %EXPORT_TAGS = ( all => [qw( xchacha20poly1305_encrypt_authenticate xchacha20poly1305_decrypt_verify )] );
9 2 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10 2 our @EXPORT = qw();
11  
12 2 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 2 $Carp::Internal{(__PACKAGE__)}++;
14 2 ▶use Crypt::AuthEnc::ChaCha20Poly1305 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
15 2 ▶use overload ();
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 18 ▶sub _check_nonce {
Subroutine _check_nonce: called CC=5 SCAR=16.7
18 18 my ($nonce) = @_;
19 18 ▶ croak "FATAL: undefined nonce" unless defined $nonce;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $nonce 0 18 18
20 18 ▶ croak "FATAL: nonce must be string/buffer scalar"
Branch: 1 branch
BranchTrueFalseTotal
if ref $nonce and not overload::Method($nonce, "\"\"") 0 18 18
Condition66%2/3
ref $nonce and not overload::Method($nonce, "\"\"")
!ll&&!rl&&r
1620
MC/DC0%0/2
ref $nonce and not overload::Method($nonce, "\"\"")
ref $nonce not overload::Method($nonce, "\"\"")
Truth table66%2/3
A and not(B)
A= ref $nonceB= not overload::Method($nonce, "\"\"")
ABresult
0X0
100
111
21 if ref($nonce) && !overload::Method($nonce, q{""});
22 18 ▶ croak "FATAL: XChaCha20Poly1305 nonce length must be 24 bytes" unless length($nonce) == 24;
Branch: 1 branch
BranchTrueFalseTotal
unless length $nonce == 24 3 15 18
23 }
24  
25 19 ▶sub _check_key {
Subroutine _check_key: called CC=5 SCAR=16.7
26 19 my ($key) = @_;
27 19 ▶ croak "FATAL: undefined key" unless defined $key;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 0 19 19
28 19 ▶ croak "FATAL: key must be string/buffer scalar"
Branch: 1 branch
BranchTrueFalseTotal
if ref $key and not overload::Method($key, "\"\"") 0 19 19
Condition66%2/3
ref $key and not overload::Method($key, "\"\"")
!ll&&!rl&&r
1720
MC/DC0%0/2
ref $key and not overload::Method($key, "\"\"")
ref $key not overload::Method($key, "\"\"")
Truth table66%2/3
A and not(B)
A= ref $keyB= not overload::Method($key, "\"\"")
ABresult
0X0
100
111
29 if ref($key) && !overload::Method($key, q{""});
30 19 ▶ croak "FATAL: XChaCha20Poly1305 key length must be 32 bytes" unless length($key) == 32;
Branch: 1 branch
BranchTrueFalseTotal
unless length $key == 32 1 18 19
31 }
32  
33 6 ▶sub new {
Subroutine new: called CC=3 SCAR=11.0
Pod documented
34 6 my ($class, $key, $nonce) = @_;
35 6 _check_key($key);
36 5 ▶ _check_nonce($nonce) if @_ > 2;
Branch: 1 branch
BranchTrueFalseTotal
if @_ > 2 4 1 5
37 4 ▶ my $self = @_ > 2
Branch: 1 branch
BranchTrueFalseTotal
@_ > 2 ? : 3 1 4
38 ? Crypt::AuthEnc::ChaCha20Poly1305->new($key, $nonce)
39 : Crypt::AuthEnc::ChaCha20Poly1305->new($key);
40 4 return bless $self, $class;
41 }
42  
43 1 ▶sub clone {
Subroutine clone: called CC=2 SCAR=8.1
Pod documented
44 1 my ($self) = @_;
45 1 ▶ return bless Crypt::AuthEnc::ChaCha20Poly1305::clone($self), ref($self) || $self;
Condition33%1/3
ref $self || $self
l!l&&r!l&&!r
100
MC/DC0%0/2
ref $self || $self
ref $self $self
Truth table33%1/3
A || B
A= ref $selfB= $self
ABresult
1X1
011
000
46 }
47  
48 1 ▶sub set_iv {
Subroutine set_iv: called CC=1 SCAR=0.0
Pod documented
49 1 my ($self, $nonce) = @_;
50 1 _check_nonce($nonce);
51 1 Crypt::AuthEnc::ChaCha20Poly1305::set_iv($self, $nonce);
52 1 return $self;
53 }
54  
55 6 ▶sub xchacha20poly1305_encrypt_authenticate {
Subroutine xchacha20poly1305_encrypt_authenticate: called CC=1 SCAR=0.0
Pod documented
56 6 my ($key, $nonce, $adata, $plaintext) = @_;
57 6 _check_key($key);
58 6 _check_nonce($nonce);
59 4 return Crypt::AuthEnc::ChaCha20Poly1305::chacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
60 }
61  
62 7 ▶sub xchacha20poly1305_decrypt_verify {
Subroutine xchacha20poly1305_decrypt_verify: called CC=1 SCAR=0.0
Pod documented
63 7 my ($key, $nonce, $adata, $ciphertext, $tag) = @_;
64 7 _check_key($key);
65 7 _check_nonce($nonce);
66 7 return Crypt::AuthEnc::ChaCha20Poly1305::chacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
67 }
68  
69 0 ▶sub CLONE_SKIP { 1 } # prevent cloning
Subroutine CLONE_SKIP: not called CC=1 SCAR=6.9
70  
71 2 1;
72  
73 =pod
74  
75 =head1 NAME
76  
77 Crypt::AuthEnc::XChaCha20Poly1305 - Authenticated encryption in XChaCha20-Poly1305 mode
78  
79 =head1 SYNOPSIS
80  
81 ### OO interface
82 use Crypt::AuthEnc::XChaCha20Poly1305;
83  
84 my $key = '...';
85 my $nonce = '...';
86 my $expected_tag = '...';
87  
88 # encrypt and authenticate
89 my $ae_enc = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
90 $ae_enc->adata_add('additional_authenticated_data1');
91 $ae_enc->adata_add('additional_authenticated_data2');
92 my $ct = $ae_enc->encrypt_add('data1');
93 $ct .= $ae_enc->encrypt_add('data2');
94 my $tag = $ae_enc->encrypt_done();
95  
96 # decrypt and verify
97 my $ae_dec = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
98 $ae_dec->adata_add('additional_authenticated_data1');
99 my $pt = $ae_dec->decrypt_add($ct);
100 die "decrypt failed" unless $ae_dec->decrypt_done($tag);
101  
102 ### functional interface
103 use Crypt::AuthEnc::XChaCha20Poly1305 qw(
104 xchacha20poly1305_encrypt_authenticate
105 xchacha20poly1305_decrypt_verify
106 );
107  
108 my $key = '...';
109 my $nonce = '...';
110 my $adata = '...';
111 my $plaintext = '...';
112  
113 my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
114 my $decrypted = xchacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
115  
116 =head1 DESCRIPTION
117  
118 I<Since: CryptX-0.089>
119  
120 Provides encryption and authentication based on XChaCha20 + Poly1305 using
121 the extended 192-bit (24-byte) nonce variant of ChaCha20-Poly1305.
122  
123 This is a stateful API. Build one message by calling, in order:
124 C<new> or C<set_iv>, optional C<adata_add>, zero or more C<encrypt_add> or
125 C<decrypt_add> calls, then C<encrypt_done> or C<decrypt_done>.
126  
127 Use a fresh object per message. If you construct with C<new($key)> you must
128 call C<set_iv($nonce)> before adding AAD or processing plaintext/ciphertext.
129 When verifying, C<decrypt_done($expected_tag)> is the safer one-step form;
130 C<decrypt_done()> without arguments only returns the calculated tag.
131 The first C<encrypt_done> / C<decrypt_done> call finalizes the object. After that,
132 further C<set_iv>, C<adata_add>, C<encrypt_add>, C<decrypt_add>,
133 C<encrypt_done>, and C<decrypt_done> calls croak.
134  
135 =head1 EXPORT
136  
137 Nothing is exported by default.
138  
139 You can export selected functions:
140  
141 use Crypt::AuthEnc::XChaCha20Poly1305 qw(
142 xchacha20poly1305_encrypt_authenticate
143 xchacha20poly1305_decrypt_verify
144 );
145  
146 =head1 FUNCTIONS
147  
148 =head2 xchacha20poly1305_encrypt_authenticate
149  
150 my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
151  
152 # $key ..... [binary string] encryption key (256 bits / 32 bytes)
153 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
154 # $adata ... [binary string] additional authenticated data (optional)
155  
156 Invalid key or nonce lengths croak.
157 String-overloaded objects are accepted for C<$key> and C<$nonce>.
158  
159 =head2 xchacha20poly1305_decrypt_verify
160  
161 my $plaintext = xchacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
162 # on error returns undef
163  
164 Invalid key or nonce lengths croak.
165 String-overloaded objects are accepted for C<$key> and C<$nonce>.
166  
167 =head1 METHODS
168  
169 Unless noted otherwise, assume C<$ae> is an existing AEAD object created via
170 C<new>, for example:
171  
172 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
173  
174 =head2 new
175  
176 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key, $nonce);
177 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key);
178  
179 # $key ..... [binary string] encryption key (256 bits / 32 bytes)
180 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
181  
182 =head2 adata_add
183  
184 Add B<additional authenticated data>.
185 Can be called only before the first C<encrypt_add> or C<decrypt_add>.
186 Returns the object itself (for chaining).
187  
188 $ae->adata_add($aad_data); # can be called multiple times
189  
190 =head2 encrypt_add
191  
192 Returns a binary string of ciphertext (raw bytes).
193  
194 my $ciphertext = $ae->encrypt_add($data); # can be called multiple times
195  
196 =head2 encrypt_done
197  
198 Returns the authentication tag as a binary string (raw bytes).
199 This call finalizes the current message.
200  
201 my $tag = $ae->encrypt_done(); # returns $tag value
202  
203 =head2 decrypt_add
204  
205 Returns a binary string of plaintext (raw bytes).
206  
207 my $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
208  
209 =head2 decrypt_done
210  
211 Without argument returns the computed tag as a binary string. With C<$tag> argument returns C<1> (success) or C<0> (failure).
212 This call finalizes the current message.
213  
214 my $tag = $ae->decrypt_done; # returns $tag value
215 #or
216 my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
217  
218 =head2 set_iv
219  
220 my $ae = Crypt::AuthEnc::XChaCha20Poly1305->new($key)->set_iv($nonce);
221 # $nonce ... [binary string] extended nonce (192 bits / 24 bytes)
222  
223 Call C<set_iv> before the first C<adata_add>, C<encrypt_add>, or C<decrypt_add>
224 for a message.
225  
226 =head2 clone
227  
228 Returns a copy of the AEAD object in its current state.
229  
230 my $ae_new = $ae->clone;
231  
232 =head1 SEE ALSO
233  
234 =over
235  
236 =item * L<Crypt::AuthEnc::ChaCha20Poly1305>, L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::CCM>
237  
238 =item * L<https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha>
239  
240 =back
241  
242 =cut
« blib/lib/CryptX.pm ↑ Summary blib/lib/Crypt/PK.pm »