.\" -*- 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::XChaCha20Poly1305 3" .TH Crypt::AuthEnc::XChaCha20Poly1305 3 2026-05-12 "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::XChaCha20Poly1305 \- Authenticated encryption in XChaCha20\-Poly1305 mode .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 2 \& ### OO interface \& use Crypt::AuthEnc::XChaCha20Poly1305; \& \& my $key = \*(Aq...\*(Aq; \& my $nonce = \*(Aq...\*(Aq; \& my $expected_tag = \*(Aq...\*(Aq; \& \& # encrypt and authenticate \& my $ae_enc = Crypt::AuthEnc::XChaCha20Poly1305\->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); \& my $tag = $ae_enc\->encrypt_done(); \& \& # decrypt and verify \& my $ae_dec = Crypt::AuthEnc::XChaCha20Poly1305\->new($key, $nonce); \& $ae_dec\->adata_add(\*(Aqadditional_authenticated_data1\*(Aq); \& my $pt = $ae_dec\->decrypt_add($ct); \& die "decrypt failed" unless $ae_dec\->decrypt_done($tag); \& \& ### functional interface \& use Crypt::AuthEnc::XChaCha20Poly1305 qw( \& xchacha20poly1305_encrypt_authenticate \& xchacha20poly1305_decrypt_verify \& ); \& \& my $key = \*(Aq...\*(Aq; \& my $nonce = \*(Aq...\*(Aq; \& my $adata = \*(Aq...\*(Aq; \& my $plaintext = \*(Aq...\*(Aq; \& \& my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext); \& my $decrypted = xchacha20poly1305_decrypt_verify($key, $nonce, $adata, $ciphertext, $tag); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fISince: CryptX\-0.089\fR .PP Provides encryption and authentication based on XChaCha20 + Poly1305 using the extended 192\-bit (24\-byte) nonce variant of ChaCha20\-Poly1305. .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($nonce)\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`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 4 \& use Crypt::AuthEnc::XChaCha20Poly1305 qw( \& xchacha20poly1305_encrypt_authenticate \& xchacha20poly1305_decrypt_verify \& ); .Ve .SH FUNCTIONS .IX Header "FUNCTIONS" .SS xchacha20poly1305_encrypt_authenticate .IX Subsection "xchacha20poly1305_encrypt_authenticate" .Vb 1 \& my ($ciphertext, $tag) = xchacha20poly1305_encrypt_authenticate($key, $nonce, $adata, $plaintext); \& \& # $key ..... [binary string] encryption key (256 bits / 32 bytes) \& # $nonce ... [binary string] extended nonce (192 bits / 24 bytes) \& # $adata ... [binary string] additional authenticated data (optional) .Ve .PP Invalid key or nonce lengths croak. String\-overloaded objects are accepted for \f(CW$key\fR and \f(CW$nonce\fR. .SS xchacha20poly1305_decrypt_verify .IX Subsection "xchacha20poly1305_decrypt_verify" my \f(CW$plaintext\fR = xchacha20poly1305_decrypt_verify($key, \f(CW$nonce\fR, \f(CW$adata\fR, \f(CW$ciphertext\fR, \f(CW$tag\fR); # on error returns undef .PP Invalid key or nonce lengths croak. String\-overloaded objects are accepted for \f(CW$key\fR and \f(CW$nonce\fR. .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::XChaCha20Poly1305\->new($key, $nonce); .Ve .SS new .IX Subsection "new" .Vb 2 \& my $ae = Crypt::AuthEnc::XChaCha20Poly1305\->new($key, $nonce); \& my $ae = Crypt::AuthEnc::XChaCha20Poly1305\->new($key); \& \& # $key ..... [binary string] encryption key (256 bits / 32 bytes) \& # $nonce ... [binary string] extended nonce (192 bits / 24 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::XChaCha20Poly1305\->new($key)\->set_iv($nonce); \& # $nonce ... [binary string] extended nonce (192 bits / 24 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 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 Crypt::AuthEnc::ChaCha20Poly1305, Crypt::AuthEnc::GCM, Crypt::AuthEnc::CCM .IP \(bu 4