blib/lib/Crypt/AuthEnc/ChaCha20Poly1305.pm

filter: Statementstmt 95.4% 21 / 22 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 80.0% 4 / 5 Podpod n/a totaltotal 92.5% 25 / 27 CC 1 SCAR 1.8
CC
1
Cov
95%
CLONE_SKIP
2.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.2
« blib/lib/Crypt/AuthEnc/CCM.pm ↑ Summary blib/lib/Crypt/AuthEnc/GCM.pm »
1 package Crypt::AuthEnc::ChaCha20Poly1305;
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( chacha20poly1305_encrypt_authenticate chacha20poly1305_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 0 ▶sub CLONE_SKIP { 1 } # prevent cloning
Subroutine CLONE_SKIP: not called CC=1 SCAR=6.9
17  
18 5 1;
19  
20 =pod
21  
22 =head1 NAME
23  
24 Crypt::AuthEnc::ChaCha20Poly1305 - Authenticated encryption in ChaCha20-Poly1305 mode
25  
26 =head1 SYNOPSIS
27  
28 ### OO interface
29 use Crypt::AuthEnc::ChaCha20Poly1305;
30  
31 my $key = '...';
32 my $nonce = '...';
33 my $expected_tag = '...';
34  
35 # encrypt and authenticate
36 my $ae_enc = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $nonce);
37 $ae_enc->adata_add('additional_authenticated_data1');
38 $ae_enc->adata_add('additional_authenticated_data2');
39 my $ct = $ae_enc->encrypt_add('data1');
40 $ct .= $ae_enc->encrypt_add('data2');
41 $ct .= $ae_enc->encrypt_add('data3');
42 my $tag = $ae_enc->encrypt_done();
43  
44 # decrypt and verify
45 my $ae_dec = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $nonce);
46 $ae_dec->adata_add('additional_authenticated_data1');
47 $ae_dec->adata_add('additional_authenticated_data2');
48 my $pt = $ae_dec->decrypt_add('ciphertext1');
49 $pt .= $ae_dec->decrypt_add('ciphertext2');
50 $pt .= $ae_dec->decrypt_add('ciphertext3');
51 $ae_dec->decrypt_done($expected_tag) or die "decrypt failed"; # constant-time tag check
52  
53 #or, if you need the computed tag, compare it with slow_eq from Crypt::Misc
54 #(Perl's 'eq' is not constant-time and leaks timing information)
55 my $computed_tag = $ae_dec->decrypt_done();
56 die "decrypt failed" unless Crypt::Misc::slow_eq($computed_tag, $expected_tag);
57  
58 ### functional interface
59 use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
60  
61 my $key = '...';
62 my $nonce = '...';
63 my $adata = '...';
64 my $plaintext = '...';
65  
66 my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
67 my $decrypted = chacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
68  
69 =head1 DESCRIPTION
70  
71 Provides authenticated encryption with ChaCha20-Poly1305 as defined in
72 L<RFC 7539|https://www.rfc-editor.org/rfc/rfc7539>.
73  
74 This is a stateful API. Build one message by calling, in order:
75 C<new> or C<set_iv>, optional C<adata_add>, zero or more C<encrypt_add> or
76 C<decrypt_add> calls, then C<encrypt_done> or C<decrypt_done>.
77  
78 Use a fresh object per message. If you construct with C<new($key)> you must
79 call C<set_iv($iv)> before adding AAD or processing plaintext/ciphertext.
80 When verifying, C<decrypt_done($expected_tag)> is the safer one-step form;
81 C<decrypt_done()> without arguments only returns the calculated tag.
82 The first C<encrypt_done> / C<decrypt_done> call finalizes the object. After that,
83 further C<set_iv>, C<set_iv_rfc7905>, C<adata_add>, C<encrypt_add>,
84 C<decrypt_add>, C<encrypt_done>, and C<decrypt_done> calls croak.
85  
86 =head1 EXPORT
87  
88 Nothing is exported by default.
89  
90 You can export selected functions:
91  
92 use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
93  
94 =head1 FUNCTIONS
95  
96 =head2 chacha20poly1305_encrypt_authenticate
97  
98 my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
99  
100 # $key ..... [binary string] key of proper length (128 or 256 bits / 16 or 32 bytes)
101 # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
102 # $adata ... [binary string] additional authenticated data (optional)
103  
104 =head2 chacha20poly1305_decrypt_verify
105  
106 my $plaintext = chacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
107 # on error returns undef
108  
109 =head1 METHODS
110  
111 Unless noted otherwise, assume C<$ae> is an existing AEAD object created via
112 C<new>, for example:
113  
114 my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $nonce);
115  
116 =head2 new
117  
118 my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $nonce);
119 #or
120 my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key);
121  
122 # $key ..... [binary string] encryption key of proper length (128 or 256 bits / 16 or 32 bytes)
123 # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
124  
125 =head2 adata_add
126  
127 Add B<additional authenticated data>.
128 Can be called only before the first C<encrypt_add> or C<decrypt_add>.
129 Returns the object itself (for chaining).
130  
131 $ae->adata_add($aad_data); # can be called multiple times
132  
133 =head2 encrypt_add
134  
135 Returns a binary string of ciphertext (raw bytes).
136  
137 my $ciphertext = $ae->encrypt_add($data); # can be called multiple times
138  
139 =head2 encrypt_done
140  
141 Returns the authentication tag as a binary string (raw bytes).
142 This call finalizes the current message.
143  
144 my $tag = $ae->encrypt_done(); # returns $tag value
145  
146 =head2 decrypt_add
147  
148 Returns a binary string of plaintext (raw bytes).
149  
150 my $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
151  
152 =head2 decrypt_done
153  
154 Without argument returns the computed tag as a binary string. With C<$tag> argument returns C<1> (success) or C<0> (failure).
155 This call finalizes the current message.
156  
157 my $tag = $ae->decrypt_done; # returns $tag value
158 #or
159 my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
160  
161 =head2 set_iv
162  
163 my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv($nonce);
164 # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
165  
166 Call C<set_iv> before the first C<adata_add>, C<encrypt_add>, or C<decrypt_add>
167 for a message.
168  
169 =head2 set_iv_rfc7905
170  
171 See L<RFC 7905|https://www.rfc-editor.org/rfc/rfc7905>.
172  
173 my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv_rfc7905($nonce, $seqnum);
174 # $nonce ... [binary string] nonce (96 bits / 12 bytes)
175 # $seqnum .. [integer] 64-bit integer (sequence number)
176  
177 =head2 clone
178  
179 Returns a copy of the AEAD object in its current state.
180  
181 my $ae_new = $ae->clone;
182  
183 =head1 SEE ALSO
184  
185 =over
186  
187 =item * L<CryptX>, L<Crypt::AuthEnc::XChaCha20Poly1305>, L<Crypt::AuthEnc::GCM>, L<Crypt::AuthEnc::CCM>, L<Crypt::AuthEnc::EAX>, L<Crypt::AuthEnc::OCB>
188  
189 =item * L<https://www.rfc-editor.org/rfc/rfc7539>
190  
191 =back
192  
193 =cut
« blib/lib/Crypt/AuthEnc/CCM.pm ↑ Summary blib/lib/Crypt/AuthEnc/GCM.pm »