.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Crypt::AuthEnc::ChaCha20Poly1305 3"
.TH Crypt::AuthEnc::ChaCha20Poly1305 3 2026-08-10 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Crypt::AuthEnc::ChaCha20Poly1305 \- Authenticated encryption in ChaCha20\-Poly1305 mode
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& ### OO interface
\& use Crypt::AuthEnc::ChaCha20Poly1305;
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $expected_tag = \*(Aq...\*(Aq;
\&
\& # encrypt and authenticate
\& my $ae_enc = Crypt::AuthEnc::ChaCha20Poly1305\->new($key, $nonce);
\& $ae_enc\->adata_add(\*(Aqadditional_authenticated_data1\*(Aq);
\& $ae_enc\->adata_add(\*(Aqadditional_authenticated_data2\*(Aq);
\& my $ct = $ae_enc\->encrypt_add(\*(Aqdata1\*(Aq);
\& $ct .= $ae_enc\->encrypt_add(\*(Aqdata2\*(Aq);
\& $ct .= $ae_enc\->encrypt_add(\*(Aqdata3\*(Aq);
\& my $tag = $ae_enc\->encrypt_done();
\&
\& # decrypt and verify
\& my $ae_dec = Crypt::AuthEnc::ChaCha20Poly1305\->new($key, $nonce);
\& $ae_dec\->adata_add(\*(Aqadditional_authenticated_data1\*(Aq);
\& $ae_dec\->adata_add(\*(Aqadditional_authenticated_data2\*(Aq);
\& my $pt = $ae_dec\->decrypt_add(\*(Aqciphertext1\*(Aq);
\& $pt .= $ae_dec\->decrypt_add(\*(Aqciphertext2\*(Aq);
\& $pt .= $ae_dec\->decrypt_add(\*(Aqciphertext3\*(Aq);
\& $ae_dec\->decrypt_done($expected_tag) or die "decrypt failed"; # constant\-time tag check
\&
\& #or, if you need the computed tag, compare it with slow_eq from Crypt::Misc
\& #(Perl\*(Aqs \*(Aqeq\*(Aq is not constant\-time and leaks timing information)
\& my $computed_tag = $ae_dec\->decrypt_done();
\& die "decrypt failed" unless Crypt::Misc::slow_eq($computed_tag, $expected_tag);
\&
\& ### functional interface
\& use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $adata = \*(Aq...\*(Aq;
\& my $plaintext = \*(Aq...\*(Aq;
\&
\& my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
\& my $decrypted = chacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides authenticated encryption with ChaCha20\-Poly1305 as defined in
RFC 7539 <https://www.rfc-editor.org/rfc/rfc7539>.
.PP
This is a stateful API. Build one message by calling, in order:
\&\f(CW\*(C`new\*(C'\fR or \f(CW\*(C`set_iv\*(C'\fR, optional \f(CW\*(C`adata_add\*(C'\fR, zero or more \f(CW\*(C`encrypt_add\*(C'\fR or
\&\f(CW\*(C`decrypt_add\*(C'\fR calls, then \f(CW\*(C`encrypt_done\*(C'\fR or \f(CW\*(C`decrypt_done\*(C'\fR.
.PP
Use a fresh object per message. If you construct with \f(CWnew($key)\fR you must
call \f(CWset_iv($iv)\fR before adding AAD or processing plaintext/ciphertext.
When verifying, \f(CWdecrypt_done($expected_tag)\fR is the safer one\-step form;
\&\f(CWdecrypt_done()\fR without arguments only returns the calculated tag.
The first \f(CW\*(C`encrypt_done\*(C'\fR / \f(CW\*(C`decrypt_done\*(C'\fR call finalizes the object. After that,
further \f(CW\*(C`set_iv\*(C'\fR, \f(CW\*(C`set_iv_rfc7905\*(C'\fR, \f(CW\*(C`adata_add\*(C'\fR, \f(CW\*(C`encrypt_add\*(C'\fR,
\&\f(CW\*(C`decrypt_add\*(C'\fR, \f(CW\*(C`encrypt_done\*(C'\fR, and \f(CW\*(C`decrypt_done\*(C'\fR calls croak.
.SH EXPORT
.IX Header "EXPORT"
Nothing is exported by default.
.PP
You can export selected functions:
.PP
.Vb 1
\&  use Crypt::AuthEnc::ChaCha20Poly1305 qw(chacha20poly1305_encrypt_authenticate chacha20poly1305_decrypt_verify);
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS chacha20poly1305_encrypt_authenticate
.IX Subsection "chacha20poly1305_encrypt_authenticate"
.Vb 1
\& my ($ciphertext, $tag) = chacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext);
\&
\& # $key ..... [binary string] key of proper length (128 or 256 bits / 16 or 32 bytes)
\& # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
\& # $adata ... [binary string] additional authenticated data (optional)
.Ve
.SS chacha20poly1305_decrypt_verify
.IX Subsection "chacha20poly1305_decrypt_verify"
.Vb 2
\& my $plaintext = chacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag);
\& # on error returns undef
.Ve
.SH METHODS
.IX Header "METHODS"
Unless noted otherwise, assume \f(CW$ae\fR is an existing AEAD object created via
\&\f(CW\*(C`new\*(C'\fR, for example:
.PP
.Vb 1
\& my $ae = Crypt::AuthEnc::ChaCha20Poly1305\->new($key, $nonce);
.Ve
.SS new
.IX Subsection "new"
.Vb 3
\& my $ae = Crypt::AuthEnc::ChaCha20Poly1305\->new($key, $nonce);
\& #or
\& my $ae = Crypt::AuthEnc::ChaCha20Poly1305\->new($key);
\&
\& # $key ..... [binary string] encryption key of proper length (128 or 256 bits / 16 or 32 bytes)
\& # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
.Ve
.SS adata_add
.IX Subsection "adata_add"
Add \fBadditional authenticated data\fR.
Can be called only before the first \f(CW\*(C`encrypt_add\*(C'\fR or \f(CW\*(C`decrypt_add\*(C'\fR.
Returns the object itself (for chaining).
.PP
.Vb 1
\& $ae\->adata_add($aad_data);                     # can be called multiple times
.Ve
.SS encrypt_add
.IX Subsection "encrypt_add"
Returns a binary string of ciphertext (raw bytes).
.PP
.Vb 1
\& my $ciphertext = $ae\->encrypt_add($data);      # can be called multiple times
.Ve
.SS encrypt_done
.IX Subsection "encrypt_done"
Returns the authentication tag as a binary string (raw bytes).
This call finalizes the current message.
.PP
.Vb 1
\& my $tag = $ae\->encrypt_done();                 # returns $tag value
.Ve
.SS decrypt_add
.IX Subsection "decrypt_add"
Returns a binary string of plaintext (raw bytes).
.PP
.Vb 1
\& my $plaintext = $ae\->decrypt_add($ciphertext); # can be called multiple times
.Ve
.SS decrypt_done
.IX Subsection "decrypt_done"
Without argument returns the computed tag as a binary string. With \f(CW$tag\fR argument returns \f(CW1\fR (success) or \f(CW0\fR (failure).
This call finalizes the current message.
.PP
.Vb 3
\& my $tag = $ae\->decrypt_done;           # returns $tag value
\& #or
\& my $result = $ae\->decrypt_done($tag);  # returns 1 (success) or 0 (failure)
.Ve
.SS set_iv
.IX Subsection "set_iv"
.Vb 2
\& my $ae = Crypt::AuthEnc::ChaCha20Poly1305\->new($key)\->set_iv($nonce);
\& # $nonce ... [binary string] nonce (64 or 96 bits / 8 or 12 bytes)
.Ve
.PP
Call \f(CW\*(C`set_iv\*(C'\fR before the first \f(CW\*(C`adata_add\*(C'\fR, \f(CW\*(C`encrypt_add\*(C'\fR, or \f(CW\*(C`decrypt_add\*(C'\fR
for a message.
.SS set_iv_rfc7905
.IX Subsection "set_iv_rfc7905"
See RFC 7905 <https://www.rfc-editor.org/rfc/rfc7905>.
.PP
.Vb 3
\& my $ae = Crypt::AuthEnc::ChaCha20Poly1305\->new($key)\->set_iv_rfc7905($nonce, $seqnum);
\& # $nonce ... [binary string] nonce (96 bits / 12 bytes)
\& # $seqnum .. [integer] 64\-bit integer (sequence number)
.Ve
.SS clone
.IX Subsection "clone"
Returns a copy of the AEAD object in its current state.
.PP
.Vb 1
\& my $ae_new = $ae\->clone;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP \(bu 4
CryptX, Crypt::AuthEnc::XChaCha20Poly1305, Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM, Crypt::AuthEnc::EAX, Crypt::AuthEnc::OCB
.IP \(bu 4
<https://www.rfc\-editor.org/rfc/rfc7539>