.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (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 .\" ======================================================================== .\" .IX Title "Crypt::Mode::CTR 3pm" .TH Crypt::Mode::CTR 3pm 2026-07-04 "perl v5.40.1" "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::Mode::CTR \- Block cipher mode CTR [Counter mode] .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 7 \& use Crypt::Mode::CTR; \& my $m = Crypt::Mode::CTR\->new(\*(AqAES\*(Aq); \& my $key = \*(Aq1234567890123456\*(Aq; \& my $iv = \*(Aq1234567890123456\*(Aq; \& my $plaintext = \*(Aqexample plaintext\*(Aq; \& my $chunk1 = \*(Aqexample \*(Aq; \& my $chunk2 = \*(Aqplaintext\*(Aq; \& \& # encrypt or decrypt in one call \& my $single_ciphertext = $m\->encrypt($plaintext, $key, $iv); \& my $single_plaintext = $m\->decrypt($single_ciphertext, $key, $iv); \& \& # encrypt more chunks \& $m\->start_encrypt($key, $iv); \& my $chunked_ciphertext = \*(Aq\*(Aq; \& $chunked_ciphertext .= $m\->add($chunk1); \& $chunked_ciphertext .= $m\->add($chunk2); \& \& # decrypt more chunks \& $m\->start_decrypt($key, $iv); \& my $chunked_plaintext = \*(Aq\*(Aq; \& $chunked_plaintext .= $m\->add($chunked_ciphertext); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" This module implements CTR cipher mode. \fBNote:\fR It works only with ciphers from CryptX (Crypt::Cipher::NNNN). .SH METHODS .IX Header "METHODS" Unless noted otherwise, assume \f(CW$m\fR is an existing mode object created via \&\f(CW\*(C`new\*(C'\fR, for example: .PP .Vb 1 \& my $m = Crypt::Mode::CTR\->new(\*(AqAES\*(Aq); .Ve .SS new .IX Subsection "new" .Vb 5 \& my $m = Crypt::Mode::CTR\->new($cipher_name); \& #or \& my $m = Crypt::Mode::CTR\->new($cipher_name, $ctr_mode, $ctr_width); \& #or \& my $m = Crypt::Mode::CTR\->new($cipher_name, $ctr_mode, $ctr_width, $cipher_rounds); \& \& # $cipher_name .. [string] one of \*(AqAES\*(Aq, \*(AqAnubis\*(Aq, \*(AqBlowfish\*(Aq, \*(AqCAST5\*(Aq, \*(AqCamellia\*(Aq, \*(AqDES\*(Aq, \*(AqDES_EDE\*(Aq, \& # \*(AqKASUMI\*(Aq, \*(AqKhazad\*(Aq, \*(AqMULTI2\*(Aq, \*(AqNoekeon\*(Aq, \*(AqRC2\*(Aq, \*(AqRC5\*(Aq, \*(AqRC6\*(Aq, \& # \*(AqSAFERP\*(Aq, \*(AqSAFER_K128\*(Aq, \*(AqSAFER_K64\*(Aq, \*(AqSAFER_SK128\*(Aq, \*(AqSAFER_SK64\*(Aq, \& # \*(AqSEED\*(Aq, \*(AqSkipjack\*(Aq, \*(AqTwofish\*(Aq, \*(AqXTEA\*(Aq, \*(AqIDEA\*(Aq, \*(AqSerpent\*(Aq \& # or any for which there is a Crypt::Cipher:: module \& # $ctr_mode ..... [integer] CTR_COUNTER_LITTLE_ENDIAN (0) \- little\-endian counter (DEFAULT) \& # CTR_COUNTER_BIG_ENDIAN (1) \- big\-endian counter \& # CTR_COUNTER_LITTLE_ENDIAN | 2 (2) \- little\-endian + RFC 3686 initial\-counter\-incrementing \& # CTR_COUNTER_BIG_ENDIAN | 2 (3) \- big\-endian + RFC 3686 initial\-counter\-incrementing \& # $ctr_width .... [integer] counter width in bytes (DEFAULT = full block width, e.g. 16 for AES) \& # $cipher_rounds ... [integer] optional, number of rounds for given cipher .Ve .SS encrypt .IX Subsection "encrypt" Encrypts the plaintext in a single call. Returns the ciphertext as a binary string. The plaintext scalar is converted to bytes using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. \f(CW\*(C`undef\*(C'\fR is treated as an empty string and may emit Perl's usual "uninitialized value" warning. .PP .Vb 1 \& my $ciphertext = $m\->encrypt($plaintext, $key, $iv); .Ve .SS decrypt .IX Subsection "decrypt" Decrypts the ciphertext in a single call. Returns the plaintext as a binary string. The ciphertext scalar is converted to bytes using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. \f(CW\*(C`undef\*(C'\fR is treated as an empty string and may emit Perl's usual "uninitialized value" warning. .PP .Vb 1 \& my $plaintext = $m\->decrypt($ciphertext, $key, $iv); .Ve .SS start_encrypt .IX Subsection "start_encrypt" Initializes encryption mode. Returns the object itself. .PP .Vb 1 \& $m\->start_encrypt($key, $iv); .Ve .SS start_decrypt .IX Subsection "start_decrypt" Initializes decryption mode. Returns the object itself. .PP .Vb 1 \& $m\->start_decrypt($key, $iv); .Ve .SS add .IX Subsection "add" Feeds data to the encryption or decryption stream. Returns a binary string. .PP Each argument is converted to bytes using Perl's usual scalar stringification. Defined scalars, including numbers and string-overloaded objects, are accepted. \f(CW\*(C`undef\*(C'\fR is treated as an empty string and may emit Perl's usual "uninitialized value" warning. .PP .Vb 2 \& # in encrypt mode \& my $ciphertext = $m\->add($plaintext); \& \& # in decrypt mode \& my $plaintext = $m\->add($ciphertext); .Ve .SS finish .IX Subsection "finish" CTR is a streaming mode and does not use padding, so \f(CW\*(C`finish\*(C'\fR returns an empty string. It exists for API consistency with Crypt::Mode::CBC and Crypt::Mode::ECB and may be safely called or omitted. .PP .Vb 5 \& $m\->start_encrypt($key, $iv); \& my $ciphertext = \*(Aq\*(Aq; \& $ciphertext .= $m\->add($chunk1); \& $ciphertext .= $m\->add($chunk2); \& $ciphertext .= $m\->finish; # returns \*(Aq\*(Aq .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .IP \(bu 4 CryptX, Crypt::Cipher .IP \(bu 4 Crypt::Cipher::AES, Crypt::Cipher::Blowfish, ... .IP \(bu 4