.\" -*- 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::CCM 3"
.TH Crypt::AuthEnc::CCM 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::CCM \- Authenticated encryption in CCM mode
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& ### OO interface
\& use Crypt::AuthEnc::CCM;
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $adata = \*(Aq...\*(Aq;
\& my $tag_len = 16;
\& my $pt_len = 15;
\& my $expected_tag = \*(Aq...\*(Aq;
\&
\& # encrypt and authenticate
\& my $ae_enc = Crypt::AuthEnc::CCM\->new("AES", $key, $nonce, $adata, $tag_len, $pt_len);
\& 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::CCM\->new("AES", $key, $nonce, $adata, $tag_len, $pt_len);
\& 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::CCM qw(ccm_encrypt_authenticate ccm_decrypt_verify);
\&
\& my $key = \*(Aq...\*(Aq;
\& my $nonce = \*(Aq...\*(Aq;
\& my $adata = \*(Aq...\*(Aq;
\& my $plaintext = \*(Aq...\*(Aq;
\& my $tag_len = 16;
\&
\& my ($ciphertext, $tag) = ccm_encrypt_authenticate(\*(AqAES\*(Aq, $key, $nonce, $adata, $tag_len, $plaintext);
\& my $decrypted = ccm_decrypt_verify(\*(AqAES\*(Aq, $key, $nonce, $adata, $ciphertext, $tag);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
CCM is an encrypt+authenticate mode that is built around using AES (or any 16\-byte cipher) as a primitive.
Unlike EAX and OCB mode, it is only meant for packet mode where the length of the input is known in advance.
.PP
Use a fresh object per message. The OO constructor requires all per\-message parameters
up front: key, nonce, associated data, tag length, and the exact total plaintext/ciphertext
length that will be processed by \f(CW\*(C`encrypt_add\*(C'\fR / \f(CW\*(C`decrypt_add\*(C'\fR. If you have no associated
data in OO mode, pass \f(CW\*(Aq\*(Aq\fR.
.PP
When verifying, \f(CWdecrypt_done($expected_tag)\fR is the safer form. The no\-argument form of
\&\f(CW\*(C`decrypt_done\*(C'\fR only returns the computed 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`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::CCM qw(ccm_encrypt_authenticate ccm_decrypt_verify);
.Ve
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.SS ccm_encrypt_authenticate
.IX Subsection "ccm_encrypt_authenticate"
.Vb 1
\& my ($ciphertext, $tag) = ccm_encrypt_authenticate($cipher, $key, $nonce, $adata, $tag_len, $plaintext);
\&
\& # $cipher .. [string] \*(AqAES\*(Aq or name of any other cipher with 16\-byte block len
\& # $key ..... [binary string] key of proper length (e.g. 128/192/256 bits for AES)
\& # $nonce ... [binary string] unique nonce/salt (no need to keep it secret)
\& # $adata ... [binary string] additional authenticated data (C<undef> is treated the same as C<\*(Aq\*(Aq>)
\& # $tag_len . [integer] required length of output tag
.Ve
.PP
CCM parameters should follow
<https://csrc.nist.gov/pubs/sp/800/38/c/final>
.PP
.Vb 3
\& # tag length:   4, 6, 8, 10, 12, 14, 16 (reasonable minimum is 8)
\& # nonce length: 7, 8, 9, 10, 11, 12, 13 (if you are not sure, use 11)
\& # BEWARE nonce length determines max. enc/dec data size: max_data_size = 2^(8*(15\-nonce_len))
.Ve
.PP
The functional helper normalizes out\-of\-range \f(CW$tag_len\fR values to \f(CW16\fR.
.SS ccm_decrypt_verify
.IX Subsection "ccm_decrypt_verify"
.Vb 2
\& my $plaintext = ccm_decrypt_verify($cipher, $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::CCM\->new($cipher, $key, $nonce, $adata, $pt_len);
.Ve
.SS new
.IX Subsection "new"
.Vb 1
\& my $ae = Crypt::AuthEnc::CCM\->new($cipher, $key, $nonce, $adata, $tag_len, $pt_len);
\&
\& # $cipher .. [string] \*(AqAES\*(Aq or name of any other cipher with 16\-byte block len
\& # $key ..... [binary string] key of proper length (e.g. 128/192/256 bits for AES)
\& # $nonce ... [binary string] unique nonce/salt (no need to keep it secret)
\& # $adata ... [binary string] additional authenticated data; must be a defined string scalar, use C<\*(Aq\*(Aq> if none
\& # $tag_len . [integer] tag length in bytes, validated as 1..16
\& # $pt_len .. [integer] exact total plaintext/ciphertext length to encrypt/decrypt; must be >= 0
.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
.PP
Use the \f(CWdecrypt_done($tag)\fR form for authentication checks. The no\-argument form only
returns the computed tag.
.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::EAX, Crypt::AuthEnc::GCM, Crypt::AuthEnc::OCB
.IP \(bu 4
<https://en.wikipedia.org/wiki/CCM_mode>