File Coverage

blib/lib/Crypt/AuthEnc/ChaCha20Poly1305.pm
Criterion Covered Total %
statement 12 13 92.3
branch n/a
condition n/a
subroutine 4 5 80.0
pod n/a
total 16 18 88.8


line stmt bran cond sub pod time code
1             package Crypt::AuthEnc::ChaCha20Poly1305;
2              
3 2     2   51533 use strict;
  2         9  
  2         51  
4 2     2   9 use warnings;
  2         8  
  2         177  
5             our $VERSION = '0.079_007';
6              
7             require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8             our %EXPORT_TAGS = ( all => [qw( chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify )] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 2     2   11 use Carp;
  2         3  
  2         112  
13             $Carp::Internal{(__PACKAGE__)}++;
14 2     2   293 use CryptX;
  2         4  
  2         123  
15              
16 0     0     sub CLONE_SKIP { 1 } # prevent cloning
17              
18             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             # encrypt and authenticate
32             my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
33             $ae->adata_add('additional_authenticated_data1');
34             $ae->adata_add('additional_authenticated_data2');
35             my $ct = $ae->encrypt_add('data1');
36             $ct .= $ae->encrypt_add('data2');
37             $ct .= $ae->encrypt_add('data3');
38             my $tag = $ae->encrypt_done();
39              
40             # decrypt and verify
41             my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
42             $ae->adata_add('additional_authenticated_data1');
43             $ae->adata_add('additional_authenticated_data2');
44             my $pt = $ae->decrypt_add('ciphertext1');
45             $pt .= $ae->decrypt_add('ciphertext2');
46             $pt .= $ae->decrypt_add('ciphertext3');
47             my $tag = $ae->decrypt_done();
48             die "decrypt failed" unless $tag eq $expected_tag;
49              
50             #or
51             my $result = $ae->decrypt_done($expected_tag); # 0 or 1
52              
53             ### functional interface
54             use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
55              
56             my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $iv, $adata, $plaintext);
57             my $plaintext = chacha20poly1305_decrypt_verify($key, $iv, $adata, $ciphertext, $tag);
58              
59             =head1 DESCRIPTION
60              
61             Provides encryption and authentication based on ChaCha20 + Poly1305 as defined in RFC 7539 - L
62              
63             =head1 EXPORT
64              
65             Nothing is exported by default.
66              
67             You can export selected functions:
68              
69             use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
70              
71             =head1 FUNCTIONS
72              
73             =head2 chacha20poly1305_encrypt_authenticate
74              
75             my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $iv, $adata, $plaintext);
76              
77             # $key ..... key of proper length (128 or 256 bits / 16 or 32 bytes)
78             # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
79             # $adata ... additional authenticated data (optional)
80              
81             =head2 chacha20poly1305_decrypt_verify
82              
83             my $plaintext = chacha20poly1305_decrypt_verify($key, $iv, $adata, $ciphertext, $tag);
84             # on error returns undef
85              
86             =head1 METHODS
87              
88             =head2 new
89              
90             my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
91              
92             # $key ..... encryption key of proper length (128 or 256 bits / 16 or 32 bytes)
93             # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
94              
95             =head2 adata_add
96              
97             Add B.
98             Can be called before the first C or C;
99              
100             $ae->adata_add($aad_data); # can be called multiple times
101              
102             =head2 encrypt_add
103              
104             $ciphertext = $ae->encrypt_add($data); # can be called multiple times
105              
106             =head2 encrypt_done
107              
108             $tag = $ae->encrypt_done(); # returns $tag value
109              
110             =head2 decrypt_add
111              
112             $plaintext = $ae->decrypt_add($ciphertext); # can be called multiple times
113              
114             =head2 decrypt_done
115              
116             my $tag = $ae->decrypt_done; # returns $tag value
117             #or
118             my $result = $ae->decrypt_done($tag); # returns 1 (success) or 0 (failure)
119              
120             =head2 set_iv
121              
122             my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv($iv);
123             # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
124              
125             =head2 set_iv_rfc7905
126              
127             See L
128              
129             my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv_rfc7905($iv, $seqnum);
130             # $iv ...... initialization vector (96 bits / 12 bytes)
131             # $seqnum .. 64bit integer (sequence number)
132              
133             =head2 clone
134              
135             my $ae_new = $ae->clone;
136              
137             =head1 SEE ALSO
138              
139             =over
140              
141             =item * L, L, L, L, L
142              
143             =item * L
144              
145             =back
146              
147             =cut