1Crypt::AuthEnc::ChaCha2U0sPeorlyC1o3n0t5r(i3b)uted PerlCDroycputm:e:nAtuatthiEonnc::ChaCha20Poly1305(3)
2
3
4

NAME

6       Crypt::AuthEnc::ChaCha20Poly1305 - Authenticated encryption in
7       ChaCha20-Poly1305 mode
8

SYNOPSIS

10        ### OO interface
11        use Crypt::AuthEnc::ChaCha20Poly1305;
12
13        # encrypt and authenticate
14        my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
15        $ae->adata_add('additional_authenticated_data1');
16        $ae->adata_add('additional_authenticated_data2');
17        my $ct = $ae->encrypt_add('data1');
18        $ct .= $ae->encrypt_add('data2');
19        $ct .= $ae->encrypt_add('data3');
20        my $tag = $ae->encrypt_done();
21
22        # decrypt and verify
23        my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
24        $ae->adata_add('additional_authenticated_data1');
25        $ae->adata_add('additional_authenticated_data2');
26        my $pt = $ae->decrypt_add('ciphertext1');
27        $pt .= $ae->decrypt_add('ciphertext2');
28        $pt .= $ae->decrypt_add('ciphertext3');
29        my $tag = $ae->decrypt_done();
30        die "decrypt failed" unless $tag eq $expected_tag;
31
32        #or
33        my $result = $ae->decrypt_done($expected_tag); # 0 or 1
34
35        ### functional interface
36        use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
37
38        my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $iv, $adata, $plaintext);
39        my $plaintext = chacha20poly1305_decrypt_verify($key, $iv, $adata, $ciphertext, $tag);
40

DESCRIPTION

42       Provides encryption and authentication based on ChaCha20 + Poly1305 as
43       defined in RFC 7539 - <https://tools.ietf.org/html/rfc7539>
44

EXPORT

46       Nothing is exported by default.
47
48       You can export selected functions:
49
50         use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
51

FUNCTIONS

53   chacha20poly1305_encrypt_authenticate
54        my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $iv, $adata, $plaintext);
55
56        # $key ..... key of proper length (128 or 256 bits / 16 or 32 bytes)
57        # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
58        # $adata ... additional authenticated data (optional)
59
60   chacha20poly1305_decrypt_verify
61        my $plaintext = chacha20poly1305_decrypt_verify($key, $iv, $adata, $ciphertext, $tag);
62        # on error returns undef
63

METHODS

65   new
66        my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key, $iv);
67
68        # $key ..... encryption key of proper length (128 or 256 bits / 16 or 32 bytes)
69        # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
70
71   adata_add
72       Add additional authenticated data.  Can be called before the first
73       "encrypt_add" or "decrypt_add";
74
75        $ae->adata_add($aad_data);                     # can be called multiple times
76
77   encrypt_add
78        $ciphertext = $ae->encrypt_add($data);         # can be called multiple times
79
80   encrypt_done
81        $tag = $ae->encrypt_done();                    # returns $tag value
82
83   decrypt_add
84        $plaintext = $ae->decrypt_add($ciphertext);    # can be called multiple times
85
86   decrypt_done
87        my $tag = $ae->decrypt_done;           # returns $tag value
88        #or
89        my $result = $ae->decrypt_done($tag);  # returns 1 (success) or 0 (failure)
90
91   set_iv
92        my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv($iv);
93        # $iv ...... initialization vector (64 or 96 bits / 8 or 12 bytes)
94
95   set_iv_rfc7905
96       See <https://tools.ietf.org/html/rfc7905>
97
98        my $ae = Crypt::AuthEnc::ChaCha20Poly1305->new($key)->set_iv_rfc7905($iv, $seqnum);
99        # $iv ...... initialization vector (96 bits / 12 bytes)
100        # $seqnum .. 64bit integer (sequence number)
101
102   clone
103        my $ae_new = $ae->clone;
104

SEE ALSO

106       •   CryptX, Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM,
107           Crypt::AuthEnc::EAX, Crypt::AuthEnc::OCB
108
109       •   <https://tools.ietf.org/html/rfc7539>
110
111
112
113perl v5.36.1                      2023-10-04Crypt::AuthEnc::ChaCha20Poly1305(3)
Impressum