.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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 "ECB 3pm"
.TH ECB 3pm 2024-01-20 "perl v5.38.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::ECB \- Use block ciphers using ECB mode
.SH SYNOPSIS
.IX Header "SYNOPSIS"
Use Crypt::ECB OO style
.PP
.Vb 1
\&  use Crypt::ECB;
\&
\&  $ecb = Crypt::ECB\->new;
\&  $ecb\->cipher(\*(AqBlowfish\*(Aq);
\&  $ecb\->key(\*(Aqsome_key\*(Aq); 
\&
\&  $enc = $ecb\->encrypt("Some data.");
\&  print $ecb\->decrypt($enc);
.Ve
.PP
or use the function style interface
.PP
.Vb 1
\&  use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
\&
\&  $ciphertext = encrypt($key, \*(AqBlowfish\*(Aq, "Some data");
\&  $plaintext  = decrypt($key, \*(AqBlowfish\*(Aq, $ciphertext);
\&
\&  $hexcode = encrypt_hex($key, $cipher, $plaintext);
\&  $plain   = decrypt_hex($key, $cipher, $hexcode);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module is a Perl-only implementation of the ECB mode. In
combination with a block cipher such as Blowfish, DES, IDEA or Rijndael,
you can encrypt and decrypt messages of arbitrarily long length. Though
for security reasons other modes than ECB such as CBC should be
preferred. See textbooks on cryptography if you want to know why.
.PP
The functionality of the module can be accessed via OO methods or via
standard function calls. Remember that some block cipher module like for
example Crypt::Blowfish has to be installed. The syntax of Crypt::ECB
follows that of Crypt::CBC.
.SH METHODS
.IX Header "METHODS"
.SS \fBnew()\fP
.IX Subsection "new()"
.Vb 7
\&  $ecb = Crypt::ECB\->new(
\&        \-cipher    => $cipher,
\&        \-key       => $key,
\&        \-padding   => \*(Aqoneandzeroes\*(Aq,
\&        \-keysize   => 8,  # use to override cipher\*(Aqs default
\&        \-blocksize => 8,  # use to override cipher\*(Aqs default
\&  );
.Ve
.PP
or
.PP
.Vb 7
\&  $ecb = Crypt::ECB\->new({
\&        cipher    => $cipher,
\&        key       => $key,
\&        padding   => \*(Aqoneandzeroes\*(Aq,
\&        keysize   => 8,  # use to override cipher\*(Aqs default
\&        blocksize => 8,  # use to override cipher\*(Aqs default
\&  });
.Ve
.PP
or (only key and cipher can be passed this way)
.PP
.Vb 2
\&  $ecb = Crypt::ECB\->new($key, \*(AqBlowfish\*(Aq);
\&  $ecb = Crypt::ECB\->new($key); # DES is assumed
.Ve
.PP
The following options are recognized: cipher, key, keysize, blocksize 
and padding. Options can be passed like in Crypt::CBC. All options
can be read and also be changed via corresponding methods afterwards.
.PP
If called without parameters you have to call at least \fBkey()\fR and
\&\fBcipher()\fR before you can start crypting.
.SS "\fBcipher()\fP, \fBmodule()\fP, \fBkey()\fP"
.IX Subsection "cipher(), module(), key()"
.Vb 3
\&  $ecb = Crypt::ECB\->new;
\&  $ecb\->cipher(\*(AqBlowfish\*(Aq);
\&  $ecb\->key(\*(Aqsome_key\*(Aq);
\&
\&  print $ecb\->cipher;   # Blowfish
\&  print $ecb\->module;   # Crypt::Blowfish
\&  print $ecb\->key;      # some_key
.Ve
.PP
or
.PP
.Vb 3
\&  my $ecb  = Crypt::ECB\->new;
\&  my $xtea = Crypt::XTEA\->new($key, 32, little_endian => 1);
\&  $ecb\->cipher($xtea);
.Ve
.PP
\&\fBcipher()\fR sets the block cipher to be used. It tries to load the
corresponding module. If an error occurs, it dies with some errmessage.
Otherwise it returns the cipher name. Free packages available for Perl
are for example Blowfish, DES, IDEA or Rijndael. If called without
parameter it just returns the name of the cipher.
.PP
\&\fBcipher()\fR also accepts a pre-existing object from a suitable block
cipher module. This is useful e.g. for cipher modules such as
Crypt::XTEA which need additional parameters.
.PP
\&\fBmodule()\fR returns the perl package containing the block cipher which
has been specified using \fBcipher()\fR.
.PP
\&\fBkey()\fR sets the key if given a parameter. It always returns the
key. Note that most block ciphers require keys of definite length.
For example DES expects an eight byte key.
.SS "\fBkeysize()\fP, \fBblocksize()\fP"
.IX Subsection "keysize(), blocksize()"
.Vb 2
\&  $ecb = Crypt::ECB\->new;
\&  $ecb\->cipher(\*(AqBlowfish\*(Aq);
\&
\&  $keysize   = $ecb\->keysize;
\&  $blocksize = $ecb\->blocksize;
.Ve
.PP
These methods can be used to retrieve keysize and blocksize as
reported from the block cipher chosen.
.PP
They can be used as well to override the values that are reported from
the cipher module. Of course that doesn't make sense unless the block
cipher used supports the new values. E.g. Crypt::Rijndael works with
16, 24 and 32 byte keys.
.SS \fBpadding()\fP
.IX Subsection "padding()"
.Vb 1
\&  $ecb\->padding(\*(Aqoneandzeroes\*(Aq);
\&
\&  my $custom_padding = sub { ... };
\&  $ecb\->padding($custom_padding);
.Ve
.PP
\&\fBpadding()\fR sets the way how data is padded up to a multiple of the
cipher's blocksize. Until now the following methods are implemented:
\&'standard', 'zeroes', 'oneandzeroes', 'rijndael_compat', 'space', 'null'
and 'none'. If the padding style is not set explicitly, 'standard' is used.
.PP
.Vb 6
\&  \*(Aqstandard\*(Aq (default) (binary safe)
\&  The PKCS#5 / PKCS#7 method (RFC 5652): Pads with the number of bytes
\&  that should be truncated. So, if blocksize is 8, then "0A0B0C" will
\&  be padded with five "05"s, resulting in "0A0B0C0505050505". If the
\&  message is already a multiple of the cipher\*(Aqs block size, then another
\&  whole block is appended.
\&
\&  \*(Aqzeroes\*(Aq (binary safe)
\&  This is a variant of the standard method. It pads with null bytes, except
\&  the last byte equals the number of padding bytes. So, if the blocksize is
\&  8, then "0A0B0C" will be padded to "0A0B0C0000000005". If the message is
\&  already a multiple of the cipher\*(Aqs block size, then another whole block
\&  is appended.
\&
\&  \*(Aqoneandzeroes\*(Aq (binary safe)
\&  Pads with "80" followed by as many "00"s as necessary to fill the block,
\&  in other words a 1 bit followed by 0s. If the message already is a
\&  multiple of the cipher\*(Aqs block size, then another whole block is
\&  appended.
\&
\&  \*(Aqrijndael_compat\*(Aq (binary safe)
\&  Similar to oneandzeroes, except that no padding is performed if the
\&  message already is already a multiple of the cipher\*(Aqs block size. This is
\&  provided for compatibility with Crypt::Rijndael.
\&
\&  \*(Aqnull\*(Aq
\&  Pads with as many null bytes as necessary to fill the block. If the
\&  message is already a multiple of the cipher\*(Aqs block size, then another
\&  whole block is appended.
\&  ATTENTION: Can truncate more characters than it should (if the original
\&  message ended with one or more null bytes).
\&
\&  \*(Aqspace\*(Aq
\&  Pads with as many space characters as necessary to fill the block.
\&  If the message is already a multiple of the cipher\*(Aqs block size, unlike
\&  the other methods NO block is appended.
\&  ATTENTION: Can truncate more characters than it should (if the original
\&  message ended with one or more space characters).
\&
\&  \*(Aqnone\*(Aq
\&  No padding added by Crypt::ECB. You then have to take care of correct
\&  padding and truncating yourself.
.Ve
.PP
You can also use a custom padding function. To do this, create a function
that is called like:
.PP
.Vb 1
\&  $padded_block = function($block, $blocksize, $direction);
.Ve
.PP
and tell Crypt::ECB to use your function:
.PP
.Vb 1
\&  $ecb\->padding(\e&function);
.Ve
.PP
\&\f(CW$block\fR is the current block of data, \f(CW$blocksize\fR is the size to pad to,
\&\f(CW$direction\fR is "e" for encrypting and "d" for decrypting, and \f(CW$padded_block\fR
is the result after padding or truncation. When encrypting, the function
should always return a string of \f(CW$blocksize\fR length, and when decrypting,
it can expect the string coming in to be of that length.
.SS "\fBstart()\fP, \fBmode()\fP, \fBcrypt()\fP, \fBfinish()\fP"
.IX Subsection "start(), mode(), crypt(), finish()"
.Vb 3
\&  $ecb\->start(\*(Aqencrypt\*(Aq);
\&  $enc .= $ecb\->crypt($_) foreach (@lines);
\&  $enc .= $ecb\->finish;
\&
\&  $ecb\->start(\*(Aqdecrypt\*(Aq);
\&  print $ecb\->mode;
.Ve
.PP
\&\fBstart()\fR sets the crypting mode, checks if all required variables
like key and cipher are set, then initializes the block cipher
specified. Allowed parameters are any words starting either with 'e'
or 'd'. The method returns the current mode.
.PP
\&\fBmode()\fR is called without parameters and just returns the current
mode.
.PP
\&\fBcrypt()\fR processes the data given as argument. If called without
argument \f(CW$_\fR is processed. The method returns the processed data.
Cipher and key have to be set in order to be able to process data.
If some of these are missing or \fBstart()\fR was not called before,
the method dies.
.PP
After having sent all data to be processed to \fBcrypt()\fR you have to
call \fBfinish()\fR in order to flush data that's left in the buffer.
.SS "\fBencrypt()\fP, \fBdecrypt()\fP, \fBencrypt_hex()\fP, \fBdecrypt_hex()\fP"
.IX Subsection "encrypt(), decrypt(), encrypt_hex(), decrypt_hex()"
.Vb 2
\&  $enc = $ecb\->encrypt($data);
\&  print $ecb\->decrypt($enc);
\&
\&  $hexenc = $ecb\->encrypt_hex($data);
\&  print $ecb\->decrypt_hex($hexenc);
.Ve
.PP
\&\fBencrypt()\fR and \fBdecrypt()\fR are convenience methods which call
\&\fBstart()\fR, \fBcrypt()\fR and \fBfinish()\fR for you.
.PP
\&\fBencrypt_hex()\fR and \fBdecrypt_hex()\fR are convenience functions
that operate on ciphertext in a hexadecimal representation.
These functions can be useful if, for example, you wish to place
the encrypted information into an e\-mail message, web page or URL.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
For convenience en\- or decrypting can also be done by calling ordinary
functions. The functions are: \fBencrypt()\fR, \fBdecrypt()\fR,
\&\fBencrypt_hex()\fR, \fBdecrypt_hex()\fR.
.SS "\fBencrypt()\fP, \fBdecrypt()\fP, \fBencrypt_hex()\fP, \fBdecrypt_hex()\fP"
.IX Subsection "encrypt(), decrypt(), encrypt_hex(), decrypt_hex()"
.Vb 1
\&  use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
\&
\&  $ciphertext = encrypt($key, $cipher, $plaintext, $padstyle);
\&  $plaintext  = decrypt($key, $cipher, $ciphertext, $padstyle);
\&
\&  $ciphertext = encrypt_hex($key, $cipher, $plaintext, $padstyle);
\&  $plaintext  = decrypt_hex($key, $cipher, $ciphertext, $padstyle);
.Ve
.PP
\&\fBencrypt()\fR and \fBdecrypt()\fR process the provided text and return either
the corresponding ciphertext (encrypt) or plaintext (decrypt). Data
and padstyle are optional. If the padding style is omitted, 'standard'
is assumed. If data is omitted, \f(CW$_\fR is used.
.PP
\&\fBencrypt_hex()\fR and \fBdecrypt_hex()\fR operate on ciphertext in a
hexadecimal representation, just like the methods with the same name,
see above. Otherwise usage is the same as for \fBencrypt()\fR and
\&\fBdecrypt()\fR.
.SH BUGS
.IX Header "BUGS"
None that I know of. Please report if you find any.
.SH TODO
.IX Header "TODO"
Implement 'random' padding, see http://www.di\-mgt.com.au/cryptopad.html.
.PP
A taint check on the key like Crypt::CBC does could be added.
.SH LICENSE
.IX Header "LICENSE"
Crypt-ECB is Copyright (C) 2000, 2005, 2008, 2016 by Christoph Appel.
.PP
This module is distributed using the same terms as Perl itself. It is free
software; you can redistribute it and/or modify it under the terms of either:
.PP
a) the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version, or
.PP
b) the "Artistic License".
.SH AUTHOR
.IX Header "AUTHOR"
Christoph Appel (see ECB.pm for email address)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), \fBCrypt::DES\fR\|(3), \fBCrypt::IDEA\fR\|(3), \fBCrypt::CBC\fR\|(3)