1ECB(3)                User Contributed Perl Documentation               ECB(3)
2
3
4

NAME

6       Crypt::ECB - Use block ciphers using ECB mode
7

SYNOPSIS

9       Use Crypt::ECB OO style
10
11         use Crypt::ECB;
12
13         $ecb = Crypt::ECB->new;
14         $ecb->cipher('Blowfish');
15         $ecb->key('some_key');
16
17         $enc = $ecb->encrypt("Some data.");
18         print $ecb->decrypt($enc);
19
20       or use the function style interface
21
22         use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
23
24         $ciphertext = encrypt($key, 'Blowfish', "Some data");
25         $plaintext  = decrypt($key, 'Blowfish', $ciphertext);
26
27         $hexcode = encrypt_hex($key, $cipher, $plaintext);
28         $plain   = decrypt_hex($key, $cipher, $hexcode);
29

DESCRIPTION

31       This module is a Perl-only implementation of the ECB mode. In
32       combination with a block cipher such as Blowfish, DES, IDEA or
33       Rijndael, you can encrypt and decrypt messages of arbitrarily long
34       length. Though for security reasons other modes than ECB such as CBC
35       should be preferred. See textbooks on cryptography if you want to know
36       why.
37
38       The functionality of the module can be accessed via OO methods or via
39       standard function calls. Remember that some block cipher module like
40       for example Crypt::Blowfish has to be installed. The syntax of
41       Crypt::ECB follows that of Crypt::CBC.
42

METHODS

44   new()
45         $ecb = Crypt::ECB->new(
46               -cipher    => $cipher,
47               -key       => $key,
48               -padding   => 'oneandzeroes',
49               -keysize   => 8,  # use to override cipher's default
50               -blocksize => 8,  # use to override cipher's default
51         );
52
53       or
54
55         $ecb = Crypt::ECB->new({
56               cipher    => $cipher,
57               key       => $key,
58               padding   => 'oneandzeroes',
59               keysize   => 8,  # use to override cipher's default
60               blocksize => 8,  # use to override cipher's default
61         });
62
63       or (only key and cipher can be passed this way)
64
65         $ecb = Crypt::ECB->new($key, 'Blowfish');
66         $ecb = Crypt::ECB->new($key); # DES is assumed
67
68       The following options are recognized: cipher, key, keysize, blocksize
69       and padding. Options can be passed like in Crypt::CBC. All options can
70       be read and also be changed via corresponding methods afterwards.
71
72       If called without parameters you have to call at least key() and
73       cipher() before you can start crypting.
74
75   cipher(), module(), key()
76         $ecb = Crypt::ECB->new;
77         $ecb->cipher('Blowfish');
78         $ecb->key('some_key');
79
80         print $ecb->cipher;   # Blowfish
81         print $ecb->module;   # Crypt::Blowfish
82         print $ecb->key;      # some_key
83
84       or
85
86         my $ecb  = Crypt::ECB->new;
87         my $xtea = Crypt::XTEA->new($key, 32, little_endian => 1);
88         $ecb->cipher($xtea);
89
90       cipher() sets the block cipher to be used. It tries to load the
91       corresponding module. If an error occurs, it dies with some errmessage.
92       Otherwise it returns the cipher name. Free packages available for Perl
93       are for example Blowfish, DES, IDEA or Rijndael. If called without
94       parameter it just returns the name of the cipher.
95
96       cipher() also accepts a pre-existing object from a suitable block
97       cipher module. This is useful e.g. for cipher modules such as
98       Crypt::XTEA which need additional parameters.
99
100       module() returns the perl package containing the block cipher which has
101       been specified using cipher().
102
103       key() sets the key if given a parameter. It always returns the key.
104       Note that most block ciphers require keys of definite length.  For
105       example DES expects an eight byte key.
106
107   keysize(), blocksize()
108         $ecb = Crypt::ECB->new;
109         $ecb->cipher('Blowfish');
110
111         $keysize   = $ecb->keysize;
112         $blocksize = $ecb->blocksize;
113
114       These methods can be used to retrieve keysize and blocksize as reported
115       from the block cipher chosen.
116
117       They can be used as well to override the values that are reported from
118       the cipher module. Of course that doesn't make sense unless the block
119       cipher used supports the new values. E.g. Crypt::Rijndael works with
120       16, 24 and 32 byte keys.
121
122   padding()
123         $ecb->padding('oneandzeroes');
124
125         my $custom_padding = sub { ... };
126         $ecb->padding($custom_padding);
127
128       padding() sets the way how data is padded up to a multiple of the
129       cipher's blocksize. Until now the following methods are implemented:
130       'standard', 'zeroes', 'oneandzeroes', 'rijndael_compat', 'space',
131       'null' and 'none'. If the padding style is not set explicitly,
132       'standard' is used.
133
134         'standard' (default) (binary safe)
135         The PKCS#5 / PKCS#7 method (RFC 5652): Pads with the number of bytes
136         that should be truncated. So, if blocksize is 8, then "0A0B0C" will
137         be padded with five "05"s, resulting in "0A0B0C0505050505". If the
138         message is already a multiple of the cipher's block size, then another
139         whole block is appended.
140
141         'zeroes' (binary safe)
142         This is a variant of the standard method. It pads with null bytes, except
143         the last byte equals the number of padding bytes. So, if the blocksize is
144         8, then "0A0B0C" will be padded to "0A0B0C0000000005". If the message is
145         already a multiple of the cipher's block size, then another whole block
146         is appended.
147
148         'oneandzeroes' (binary safe)
149         Pads with "80" followed by as many "00"s as necessary to fill the block,
150         in other words a 1 bit followed by 0s. If the message already is a
151         multiple of the cipher's block size, then another whole block is
152         appended.
153
154         'rijndael_compat' (binary safe)
155         Similar to oneandzeroes, except that no padding is performed if the
156         message already is already a multiple of the cipher's block size. This is
157         provided for compatibility with Crypt::Rijndael.
158
159         'null'
160         Pads with as many null bytes as necessary to fill the block. If the
161         message is already a multiple of the cipher's block size, then another
162         whole block is appended.
163         ATTENTION: Can truncate more characters than it should (if the original
164         message ended with one or more null bytes).
165
166         'space'
167         Pads with as many space characters as necessary to fill the block.
168         If the message is already a multiple of the cipher's block size, unlike
169         the other methods NO block is appended.
170         ATTENTION: Can truncate more characters than it should (if the original
171         message ended with one or more space characters).
172
173         'none'
174         No padding added by Crypt::ECB. You then have to take care of correct
175         padding and truncating yourself.
176
177       You can also use a custom padding function. To do this, create a
178       function that is called like:
179
180         $padded_block = function($block, $blocksize, $direction);
181
182       and tell Crypt::ECB to use your function:
183
184         $ecb->padding(\&function);
185
186       $block is the current block of data, $blocksize is the size to pad to,
187       $direction is "e" for encrypting and "d" for decrypting, and
188       $padded_block is the result after padding or truncation. When
189       encrypting, the function should always return a string of $blocksize
190       length, and when decrypting, it can expect the string coming in to be
191       of that length.
192
193   start(), mode(), crypt(), finish()
194         $ecb->start('encrypt');
195         $enc .= $ecb->crypt($_) foreach (@lines);
196         $enc .= $ecb->finish;
197
198         $ecb->start('decrypt');
199         print $ecb->mode;
200
201       start() sets the crypting mode, checks if all required variables like
202       key and cipher are set, then initializes the block cipher specified.
203       Allowed parameters are any words starting either with 'e' or 'd'. The
204       method returns the current mode.
205
206       mode() is called without parameters and just returns the current mode.
207
208       crypt() processes the data given as argument. If called without
209       argument $_ is processed. The method returns the processed data.
210       Cipher and key have to be set in order to be able to process data.  If
211       some of these are missing or start() was not called before, the method
212       dies.
213
214       After having sent all data to be processed to crypt() you have to call
215       finish() in order to flush data that's left in the buffer.
216
217   encrypt(), decrypt(), encrypt_hex(), decrypt_hex()
218         $enc = $ecb->encrypt($data);
219         print $ecb->decrypt($enc);
220
221         $hexenc = $ecb->encrypt_hex($data);
222         print $ecb->decrypt_hex($hexenc);
223
224       encrypt() and decrypt() are convenience methods which call start(),
225       crypt() and finish() for you.
226
227       encrypt_hex() and decrypt_hex() are convenience functions that operate
228       on ciphertext in a hexadecimal representation.  These functions can be
229       useful if, for example, you wish to place the encrypted information
230       into an e-mail message, web page or URL.
231

FUNCTIONS

233       For convenience en- or decrypting can also be done by calling ordinary
234       functions. The functions are: encrypt(), decrypt(), encrypt_hex(),
235       decrypt_hex().
236
237   encrypt(), decrypt(), encrypt_hex(), decrypt_hex()
238         use Crypt::ECB qw(encrypt decrypt encrypt_hex decrypt_hex);
239
240         $ciphertext = encrypt($key, $cipher, $plaintext, $padstyle);
241         $plaintext  = decrypt($key, $cipher, $ciphertext, $padstyle);
242
243         $ciphertext = encrypt_hex($key, $cipher, $plaintext, $padstyle);
244         $plaintext  = decrypt_hex($key, $cipher, $ciphertext, $padstyle);
245
246       encrypt() and decrypt() process the provided text and return either the
247       corresponding ciphertext (encrypt) or plaintext (decrypt). Data and
248       padstyle are optional. If the padding style is omitted, 'standard' is
249       assumed. If data is omitted, $_ is used.
250
251       encrypt_hex() and decrypt_hex() operate on ciphertext in a hexadecimal
252       representation, just like the methods with the same name, see above.
253       Otherwise usage is the same as for encrypt() and decrypt().
254

BUGS

256       None that I know of. Please report if you find any.
257

TODO

259       Implement 'random' padding, see
260       http://www.di-mgt.com.au/cryptopad.html.
261
262       A taint check on the key like Crypt::CBC does could be added.
263

LICENSE

265       Crypt-ECB is Copyright (C) 2000, 2005, 2008, 2016 by Christoph Appel.
266
267       This module is distributed using the same terms as Perl itself. It is
268       free software; you can redistribute it and/or modify it under the terms
269       of either:
270
271       a) the GNU General Public License as published by the Free Software
272       Foundation; either version 1, or (at your option) any later version, or
273
274       b) the "Artistic License".
275

AUTHOR

277       Christoph Appel (see ECB.pm for email address)
278

SEE ALSO

280       perl(1), Crypt::DES(3), Crypt::IDEA(3), Crypt::CBC(3)
281
282
283
284perl v5.34.0                      2022-01-21                            ECB(3)
Impressum