… | |
… | |
15 | # - OR - |
15 | # - OR - |
16 | $plaintext = $cipher->decrypt($crypted); |
16 | $plaintext = $cipher->decrypt($crypted); |
17 | |
17 | |
18 | =head1 DESCRIPTION |
18 | =head1 DESCRIPTION |
19 | |
19 | |
20 | This module implements the spritz spongelike function. |
20 | This module implements the Spritz spongelike function (with N=256), the |
|
|
21 | spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. |
21 | |
22 | |
22 | Although it is C<Crypt::CBC> compliant you usually gain nothing by using |
23 | Its strength is extreme versatility (you get a stream cipher, a hash, a |
23 | that module (except generality, which is often a good thing), since |
24 | MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and |
24 | C<Crypt::Twofish2> can work in either ECB or CBC mode itself. |
25 | more) and extremely simple and small code (encryption and authentication |
|
|
26 | can be had in 1KB of compiled code on amd64, which isn't an issue for most |
|
|
27 | uses in Perl, but is useful in embedded situations, or e.g. when doing |
|
|
28 | crypto using javascript in a browser and communicating with Perl). |
25 | |
29 | |
26 | =over 4 |
30 | Its weakness is its relatively slow speed (encryption is a few times |
|
|
31 | slower than RC4 or AES, hashing many times slower than SHA-3, although |
|
|
32 | this might be reversed on an 8-bit-cpu) and the fact that it is totally |
|
|
33 | unproven in the field (as of this writing, the cipher was just a few |
|
|
34 | months old), so it can't be called production-ready. |
|
|
35 | |
|
|
36 | All the usual caveats regarding stream ciphers apply - never repeat |
|
|
37 | your key, never repeat your nonce etc. - you should have some basic |
|
|
38 | understanding of cryptography before using this cipher in your own |
|
|
39 | designs. |
|
|
40 | |
|
|
41 | The Spritz base class is not meant for end users. To make usage simpler |
|
|
42 | and safer, a number of convenience classes are provided for typical |
|
|
43 | end-user tasks: |
|
|
44 | |
|
|
45 | encryption - Crypt::Spritz::Cipher::XOR |
|
|
46 | hashing - Crypt::Spritz::Hash |
|
|
47 | message authentication - Crypt::Spritz::MAC |
|
|
48 | authenticated encryption - Crypt::Spritz::AEAD::XOR |
|
|
49 | random number generation - Crypt::Spritz::PRNG |
27 | |
50 | |
28 | =cut |
51 | =cut |
29 | |
52 | |
30 | package Crypt::Spritz; |
53 | package Crypt::Spritz; |
31 | |
54 | |
… | |
… | |
33 | |
56 | |
34 | $VERSION = '0.0'; |
57 | $VERSION = '0.0'; |
35 | |
58 | |
36 | XSLoader::load __PACKAGE__, $VERSION; |
59 | XSLoader::load __PACKAGE__, $VERSION; |
37 | |
60 | |
38 | @Crypt::Spritz::CipherBase::ISA = |
61 | @Crypt::Spritz::ISA = Crypt::Spritz::Base::; |
|
|
62 | |
39 | @Crypt::Spritz::Hash::ISA = |
63 | @Crypt::Spritz::Hash::ISA = |
|
|
64 | @Crypt::Spritz::PRNG::ISA = |
|
|
65 | @Crypt::Spritz::Cipher::ISA = |
40 | @Crypt::Spritz::PRNG::ISA = Crypt::Spritz::; |
66 | @Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::; |
41 | |
67 | |
42 | @Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::; |
68 | @Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::; |
43 | |
69 | |
44 | @Crypt::Spritz::Cipher::XOR::ISA = |
70 | @Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::; |
45 | @Crypt::Spritz::Cipher::ISA = |
|
|
46 | @Crypt::Spritz::AEAD::ISA = |
|
|
47 | @Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::CipherBase::; |
71 | @Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::; |
48 | |
72 | |
49 | sub Crypt::Spritz::CipherBase::keysize () { 32 } |
73 | sub Crypt::Spritz::Cipher::keysize () { 32 } |
50 | sub Crypt::Spritz::CipherBase::blocksize () { 64 } |
74 | sub Crypt::Spritz::Cipher::blocksize () { 64 } |
|
|
75 | |
|
|
76 | *Crypt::Spritz::Hash::new = \&Crypt::Spritz::new; |
51 | |
77 | |
52 | *Crypt::Spritz::Hash::add = |
78 | *Crypt::Spritz::Hash::add = |
53 | *Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb; |
79 | *Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb; |
54 | |
80 | |
55 | *Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze; |
81 | *Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze; |
56 | |
82 | |
57 | *Crypt::Spritz::AEAD::XOR::new = |
|
|
58 | *Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new; |
83 | *Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new; |
59 | |
|
|
60 | *Crypt::Spritz::AEAD::XOR::finish = |
|
|
61 | *Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish; |
84 | *Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish; |
62 | |
85 | |
63 | *Crypt::Spritz::AEAD::XOR::associated_data = |
86 | *Crypt::Spritz::AEAD::associated_data = |
64 | *Crypt::Spritz::AEAD::associated_data = |
|
|
65 | *Crypt::Spritz::AEAD::XOR::nonce = |
|
|
66 | *Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absborb_and_stop; |
87 | *Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop; |
67 | |
88 | |
68 | =item keysize |
|
|
69 | |
89 | |
70 | Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually |
90 | =head2 THE Crypt::Spritz CLASS |
71 | supports keylengths of 16, 24 or 32 bytes, but there is no way to |
|
|
72 | communicate this to C<Crypt::CBC>. |
|
|
73 | |
91 | |
74 | =item blocksize |
92 | This class implements most of the Spritz primitives. To use it effectively |
|
|
93 | you should understand them, for example, by reading the L<Spritz |
|
|
94 | paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially |
|
|
95 | pp. 5-6. |
75 | |
96 | |
76 | The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat |
97 | The Spritz primitive corresponding to the Perl method is given as |
77 | unique. It is also the reason I need this module myself ;) |
98 | comment. |
78 | |
99 | |
79 | =item $cipher = new $key [, $mode] |
100 | =over 4 |
80 | |
101 | |
81 | Create a new C<Crypt::Twofish2> cipher object with the given key (which |
102 | =item $spritz = new Crypt::Spritz # InitializeState |
82 | must be 128, 192 or 256 bits long). The additional C<$mode> argument is |
|
|
83 | the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the |
|
|
84 | default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC> |
|
|
85 | does) or C<MODE_CFB1> (1-bit cipher feedback mode). |
|
|
86 | |
103 | |
87 | ECB mode is very insecure (read a book on cryptography if you don't know |
104 | Creates and returns a new, initialised Spritz state. |
88 | why!), so you should probably use CBC mode. CFB1 mode is not tested and is |
|
|
89 | most probably broken, so do not try to use it. |
|
|
90 | |
105 | |
91 | In ECB mode you can use the same cipher object to encrypt and decrypt |
106 | =item $spritz->init # InitializeState |
92 | data. However, every change of "direction" causes an internal reordering |
|
|
93 | of key data, which is quite slow, so if you want ECB mode and |
|
|
94 | encryption/decryption at the same time you should create two seperate |
|
|
95 | C<Crypt::Twofish2> objects with the same key. |
|
|
96 | |
107 | |
97 | In CBC mode you have to use seperate objects for encryption/decryption in |
108 | Initialises the Spritz state again, throwing away the previous state. |
98 | any case. |
|
|
99 | |
109 | |
100 | The C<MODE_*>-constants are not exported by this module, so you must |
110 | =item $spritz->update # Update |
101 | specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that). |
|
|
102 | |
111 | |
103 | =item $cipher->encrypt($data) |
112 | =item $spritz->whip ($r) # Whip |
104 | |
113 | |
105 | Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16 |
114 | =item $spritz->crush # Crush |
106 | bytes), otherwise this function will croak. Apart from that, it can be of |
|
|
107 | (almost) any length. |
|
|
108 | |
115 | |
109 | =item $cipher->decrypt($data) |
116 | =item $spritz->shuffle # Shuffle |
110 | |
117 | |
111 | The pendant to C<encrypt> in that it I<de>crypts data again. |
118 | =item $spritz->output # Output |
|
|
119 | |
|
|
120 | Calls the Spritz primitive ovf the same name - these are not normally |
|
|
121 | called manually. |
|
|
122 | |
|
|
123 | =item $spritz->absorb ($I) # Absorb |
|
|
124 | |
|
|
125 | Absorbs the given data into the state (usually used for key material, nonces, IVs |
|
|
126 | messages to be hashed and so on). |
|
|
127 | |
|
|
128 | =item $spritz->absorb_stop # AbsorbStop |
|
|
129 | |
|
|
130 | Absorbs a special stop symbol - this is usually used as delimiter between |
|
|
131 | multiple strings to be absorbed, to thwart extension attacks. |
|
|
132 | |
|
|
133 | =item $spritz->absorb_and_stop ($I) |
|
|
134 | |
|
|
135 | This is a convenience function that simply calls C<absorb> followed by |
|
|
136 | C<absorb_stop>. |
|
|
137 | |
|
|
138 | =item $octet = $spritz->drip # Drip |
|
|
139 | |
|
|
140 | Squeezes out a single byte from the state. |
|
|
141 | |
|
|
142 | =item $octets = $spritz->squeeze ($len) # Squeeze |
|
|
143 | |
|
|
144 | Squeezes out the requested number of bytes from the state - this is usually |
112 | |
145 | |
113 | =back |
146 | =back |
114 | |
147 | |
|
|
148 | |
|
|
149 | =head2 THE Crypt::Spritz::Cipher::XOR CLASS |
|
|
150 | |
|
|
151 | This class implements stream encryption/decryption. It doesn't implement |
|
|
152 | the standard Spritz encryption but the XOR variant (called B<spritz-xor> |
|
|
153 | in the paper). |
|
|
154 | |
|
|
155 | The XOR variant should be as secure as the standard variant, but |
|
|
156 | doesn't have separate encryption and decryaption functions, which saves |
|
|
157 | codesize. IT is not compatible with standard Spritz encryption, however - |
|
|
158 | drop me a note if you want that implemented as well. |
|
|
159 | |
|
|
160 | Typical use for encryption I<and> decryption (code is identical for |
|
|
161 | decryption, you simply pass the encrypted data to C<crypt>): |
|
|
162 | |
|
|
163 | # create a cipher - $salt can be a random string you send |
|
|
164 | # with your message, in clear, a counter (best), or empty if |
|
|
165 | # you only want to encrypt one message with the given key. |
|
|
166 | # 16 or 32 octets are typical sizes for the key, for the salt, |
|
|
167 | # use whatever you need to give a unique salt for every |
|
|
168 | # message you encrypt with the same key. |
|
|
169 | |
|
|
170 | my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt; |
|
|
171 | |
|
|
172 | # encrypt a message in one or more calls to crypt |
|
|
173 | |
|
|
174 | my $encrypted; |
|
|
175 | |
|
|
176 | $encrypted .= $cipher->crypt ("This is"); |
|
|
177 | $encrypted .= $cipher->crypt ("all very"); |
|
|
178 | $encrypted .= $cipher->crypt ("secret"); |
|
|
179 | |
|
|
180 | # that's all |
|
|
181 | |
|
|
182 | =over 4 |
|
|
183 | |
|
|
184 | =item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv] |
|
|
185 | |
|
|
186 | Creates a new cipher object usable for encryption and decryption. The |
|
|
187 | C<$key> must be provided, the initial vector C<$IV> is optional. |
|
|
188 | |
|
|
189 | Both C<$key> and C<$IV> can be of any length. Typical lengths for the |
|
|
190 | C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to |
|
|
191 | be long enough to distinguish repeated uses of tghe same key. |
|
|
192 | |
|
|
193 | =item $encrypted = $cipher->crypt ($cleartext) |
|
|
194 | |
|
|
195 | =item $cleartext = $cipher->crypt ($encrypted) |
|
|
196 | |
|
|
197 | Encrypt or decrypt a piece of a message. This cna be called as many times |
|
|
198 | as you want, and the message can be split into as few or many pieces as |
|
|
199 | required without affecting the results. |
|
|
200 | |
|
|
201 | =item $cipher->crypt_inplace ($cleartext_or_ciphertext) |
|
|
202 | |
|
|
203 | Same as C<crypt>, except it I<modifies the argument in-place>. |
|
|
204 | |
|
|
205 | =item $constant_32 = $cipher->keysize |
|
|
206 | |
|
|
207 | =item $constant_64 = $cipher->blocksize |
|
|
208 | |
|
|
209 | These methods are provided for L<Crypt::CBC> compatibility and simply |
|
|
210 | return C<32> and C<64>, respectively. |
|
|
211 | |
|
|
212 | Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is |
|
|
213 | not a block cipher and already provides an appropriate mode. |
|
|
214 | |
|
|
215 | =back |
|
|
216 | |
|
|
217 | |
|
|
218 | =head2 THE Crypt::Spritz::Hash CLASS |
|
|
219 | |
|
|
220 | This implements the Spritz digest/hash algorithm. It works very similar to |
|
|
221 | other digest modules on CPAN, such as L<Digest::SHA3>. |
|
|
222 | |
|
|
223 | Typical use for hashing: |
|
|
224 | |
|
|
225 | # create hasher object |
|
|
226 | my $hasher = new Crypt::Spritz::Hash; |
|
|
227 | |
|
|
228 | # now feed data to be hashed into $hasher |
|
|
229 | # in as few or many calls as required |
|
|
230 | $hasher->add ("Some data"); |
|
|
231 | $hasher->add ("Some more"); |
|
|
232 | |
|
|
233 | # extract the hash - the object is not usable afterwards |
|
|
234 | my $digest = $hasher->finish (32); |
|
|
235 | |
|
|
236 | =over 4 |
|
|
237 | |
|
|
238 | =item $hasher = new Crypt::Spritz::Hash |
|
|
239 | |
|
|
240 | Creates a new hasher object. |
|
|
241 | |
|
|
242 | =item $hasher->add ($data) |
|
|
243 | |
|
|
244 | Adds data to be hashed into the hasher state. It doesn't matter whether |
|
|
245 | you pass your data in in one go or split it up, the hash will be the same. |
|
|
246 | |
|
|
247 | =item $digest = $hasher->finish ($length) |
|
|
248 | |
|
|
249 | Calculates a hash digest of the given length and return it. The object |
|
|
250 | cannot sensibly be used for further hashing afterwards. |
|
|
251 | |
|
|
252 | Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit |
|
|
253 | digests, respectively. |
|
|
254 | |
|
|
255 | =back |
|
|
256 | |
|
|
257 | |
|
|
258 | =head2 THE Crypt::Spritz::MAC CLASS |
|
|
259 | |
|
|
260 | This implements the Spritz Message Authentication Code algorithm. It works |
|
|
261 | very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but |
|
|
262 | implements an authenticated digest (like L<Digest::HMAC>). |
|
|
263 | |
|
|
264 | I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where |
|
|
265 | everybody can verify and recreate the hash value for some data, with a |
|
|
266 | MAC, knowledge of the (hopefully) secret key is required both to create |
|
|
267 | and to verify the digest. |
|
|
268 | |
|
|
269 | Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>, |
|
|
270 | except a key (typically 16 or 32 octets) is provided to the constructor: |
|
|
271 | |
|
|
272 | # create hasher object |
|
|
273 | my $hasher = new Crypt::Spritz::Mac $key; |
|
|
274 | |
|
|
275 | # now feed data to be hashed into $hasher |
|
|
276 | # in as few or many calls as required |
|
|
277 | $hasher->add ("Some data"); |
|
|
278 | $hasher->add ("Some more"); |
|
|
279 | |
|
|
280 | # extract the mac - the object is not usable afterwards |
|
|
281 | my $mac = $hasher->finish (32); |
|
|
282 | |
|
|
283 | =over 4 |
|
|
284 | |
|
|
285 | =item $hasher = new Crypt::Spritz::MAC $key |
|
|
286 | |
|
|
287 | Creates a new hasher object. The C<$key> can be of any length, but 16 and |
|
|
288 | 32 (128 and 256 bit) are customary. |
|
|
289 | |
|
|
290 | =item $hasher->add ($data) |
|
|
291 | |
|
|
292 | Adds data to be hashed into the hasher state. It doesn't matter whether |
|
|
293 | you pass your data in in one go or split it up, the hash will be the same. |
|
|
294 | |
|
|
295 | =item $mac = $hasher->finish ($length) |
|
|
296 | |
|
|
297 | Calculates a message code of the given length and return it. The object |
|
|
298 | cannot sensibly be used for further hashing afterwards. |
|
|
299 | |
|
|
300 | Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit |
|
|
301 | digests, respectively. |
|
|
302 | |
|
|
303 | =back |
|
|
304 | |
|
|
305 | |
|
|
306 | =head2 THE Crypt::Spritz::AEAD::XOR CLASS |
|
|
307 | |
|
|
308 | This is the most complicated class - it combines encryption and |
|
|
309 | message authentication into a single "authenticated encryption |
|
|
310 | mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and |
|
|
311 | L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining |
|
|
312 | them. |
|
|
313 | |
|
|
314 | You can additionally provide cleartext data that will not be encrypted or |
|
|
315 | decrypted, but that is nevertheless authenticated using the MAC, which |
|
|
316 | is why this mode is called I<AEAD>, I<Authenticated Encryption with |
|
|
317 | Associated Data>. Associated data is usually used to any header data that |
|
|
318 | is in cleartext, but should nevertheless be authenticated. |
|
|
319 | |
|
|
320 | This implementation implements the XOR variant. Just as with |
|
|
321 | L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with |
|
|
322 | the standard mode, but uses less code and doesn't distinguish between |
|
|
323 | encryption and decryption. |
|
|
324 | |
|
|
325 | Typical usage is as follows: |
|
|
326 | |
|
|
327 | # create a new aead object |
|
|
328 | # you use one object per message |
|
|
329 | # key length customarily is 16 or 32 |
|
|
330 | my $aead = new Crypt::Spritz::AEAD::XOR $key; |
|
|
331 | |
|
|
332 | # now you must feed the nonce. if you do not need a nonce, |
|
|
333 | # you can provide the empty string, but you have to call it |
|
|
334 | # after creating the object, before calling associated_data. |
|
|
335 | # the nonce must be different for each usage of the $key. |
|
|
336 | # a counter of some kind is good enough. |
|
|
337 | # reusing a nonce with the same key completely |
|
|
338 | # destroys security! |
|
|
339 | $aead->nonce ($counter); |
|
|
340 | |
|
|
341 | # then you must feed any associated data you have. if you |
|
|
342 | # do not have associated cleartext data, you can provide the empty |
|
|
343 | # string, but you have to call it after nonce and before crypt. |
|
|
344 | $aead->associated_data ($header); |
|
|
345 | |
|
|
346 | # next, you call crypt one or more times with your data |
|
|
347 | # to be encrypted (opr decrypted). |
|
|
348 | # all except the last call must use a length that is a |
|
|
349 | # multiple of 64. |
|
|
350 | # the last block can have any length. |
|
|
351 | my $encrypted; |
|
|
352 | |
|
|
353 | $encrypted .= $aead->crypt ("1" x 64); |
|
|
354 | $encrypted .= $aead->crypt ("2" x 64); |
|
|
355 | $encrypted .= $aead->crypt ("3456"); |
|
|
356 | |
|
|
357 | # finally you can calculate the MAC for all of the above |
|
|
358 | my $mac = $aead->finish; |
|
|
359 | |
|
|
360 | =over 4 |
|
|
361 | |
|
|
362 | =item $aead = new Crypt::Spritz::AEAD::XOR $key |
|
|
363 | |
|
|
364 | Creates a new cipher object usable for encryption and decryption. |
|
|
365 | |
|
|
366 | The C<$key> can be of any length. Typical lengths for the C<$key> are 16 |
|
|
367 | (128 bit) or 32 (256 bit). |
|
|
368 | |
|
|
369 | After creation, you have to call C<nonce> next. |
|
|
370 | |
|
|
371 | =item $aead->nonce ($nonce) |
|
|
372 | |
|
|
373 | Provide the nonce value (nonce means "value used once"), a value the is |
|
|
374 | unique between all uses with the same key. This method I<must> be called |
|
|
375 | I<after> C<new> and I<before> C<associated_data>. |
|
|
376 | |
|
|
377 | If you only ever use a given key once, you can provide an empty nonce - |
|
|
378 | but you still have to call the method. |
|
|
379 | |
|
|
380 | Common strategies to provide a nonce are to implement a persistent counter |
|
|
381 | or to generate a random string of sufficient length to guarantee that it |
|
|
382 | differs each time. |
|
|
383 | |
|
|
384 | The problem with counters is that you might get confused and forget |
|
|
385 | increments, and thus reuse the same sequence number. The problem with |
|
|
386 | random strings i that your random number generator might be hosed and |
|
|
387 | generate the same randomness multiple times (randomness can be very hard |
|
|
388 | to get especially on embedded devices). |
|
|
389 | |
|
|
390 | =item $aead->associated_data ($data)( |
|
|
391 | |
|
|
392 | Provide the associated data (cleartext data to be authenticated but not |
|
|
393 | encrypted). This method I<must> be called I<after> C<nonce> and I<before> |
|
|
394 | C<crypt>. |
|
|
395 | |
|
|
396 | If you don't have any associated data, you can provide an empty string - |
|
|
397 | but you still have to call the method. |
|
|
398 | |
|
|
399 | Associated data is typically header data - data anybody is allowed to |
|
|
400 | see in cleartext, but that should nevertheless be protected with an |
|
|
401 | authentication code. Typically such data is used to identify where to |
|
|
402 | forward a message to, how to find the key to decrypt the message or in |
|
|
403 | general how to interpret the encrypted part of a message. |
|
|
404 | |
|
|
405 | =item $encrypted = $cipher->crypt ($cleartext) |
|
|
406 | |
|
|
407 | =item $cleartext = $cipher->crypt ($encrypted) |
|
|
408 | |
|
|
409 | Encrypt or decrypt a piece of a message. This cna be called as many times |
|
|
410 | as you want, and the message can be split into as few or many pieces as |
|
|
411 | required without affecting the results, with one exception: All except the |
|
|
412 | last call to C<crypt> needs to pass in a multiple of C<64> octets. The |
|
|
413 | last call to C<crypt> does not have this limitation. |
|
|
414 | |
|
|
415 | =item $cipher->crypt_inplace ($cleartext_or_ciphertext) |
|
|
416 | |
|
|
417 | Same as C<crypt>, except it I<modifies the argument in-place>. |
|
|
418 | |
|
|
419 | =back |
|
|
420 | |
|
|
421 | |
|
|
422 | =head2 THE Crypt::Spritz::PRNG CLASS |
|
|
423 | |
|
|
424 | This class implements a Pseudorandom Number Generatore (B<PRNG>), |
|
|
425 | sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In |
|
|
426 | fact, it is even cryptographically secure, making it a B<CSPRNG>. |
|
|
427 | |
|
|
428 | Typical usage as a random number generator involves creating a PRNG |
|
|
429 | object with a seed of your choice, and then fetching randomness via |
|
|
430 | C<get>: |
|
|
431 | |
|
|
432 | # create a PRNG object, use a seed string of your choice |
|
|
433 | my $prng = new Crypt::Spritz::PRNG $seed; |
|
|
434 | |
|
|
435 | # now call get as many times as you wish to get binary randomness |
|
|
436 | my $some_randomness = $prng->get (17); |
|
|
437 | my moree_randomness = $prng->get (5000); |
|
|
438 | ... |
|
|
439 | |
|
|
440 | Typical usage as a cryptographically secure random number generator is to |
|
|
441 | feed in some secret entropy (32 octets/256 bits are commonly considered |
|
|
442 | enough), for example from C</dev/random> or C</dev/urandom>, and then |
|
|
443 | generate some key material. |
|
|
444 | |
|
|
445 | # create a PRNG object |
|
|
446 | my $prng = new Crypt::Spritz::PRNG; |
|
|
447 | |
|
|
448 | # seed some entropy (either via ->add or in the constructor) |
|
|
449 | $prng->add ($some_secret_highly_entropic_string); |
|
|
450 | |
|
|
451 | # now call get as many times as you wish to get |
|
|
452 | # hard to guess binary randomness |
|
|
453 | my $key1 = $prng->get (32); |
|
|
454 | my $key2 = $prng->get (16); |
|
|
455 | ... |
|
|
456 | |
|
|
457 | # for long running programs, it is advisable to |
|
|
458 | # reseed the PRNG from time to time with new entropy |
|
|
459 | $prng->add ($some_more_entropy); |
|
|
460 | |
|
|
461 | =over 4 |
|
|
462 | |
|
|
463 | =item $prng = new Crypt::Spritz::PRNG [$seed] |
|
|
464 | |
|
|
465 | Creates a new random number generator object. If C<$seed> is given, then |
|
|
466 | the C<$seed> is added to the internal state as if by a call to C<add>. |
|
|
467 | |
|
|
468 | =item $prng->add ($entropy) |
|
|
469 | |
|
|
470 | Adds entropy to the internal state, thereby hopefully making it harder |
|
|
471 | to guess. Good sources for entropy are irregular hardware events, or |
|
|
472 | randomness provided by C</dev/urandom> or C</dev/random>. |
|
|
473 | |
|
|
474 | The design of the Spritz PRNG should make it strong against attacks where |
|
|
475 | the attacker controls all the entropy, so it should be safe to add entropy |
|
|
476 | from untrusted sources - more is better than less if you need a CSPRNG. |
|
|
477 | |
|
|
478 | For use as PRNG, of course, this matters very little. |
|
|
479 | |
|
|
480 | =item $octets = $prng->get ($length) |
|
|
481 | |
|
|
482 | Generates and returns C<$length> random octets as a string. |
|
|
483 | |
|
|
484 | =back |
|
|
485 | |
|
|
486 | |
115 | =head1 SEE ALSO |
487 | =head1 SEE ALSO |
116 | |
488 | |
117 | L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. |
489 | L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. |
118 | |
490 | |
119 | =head1 SECURITY CONSIDERATIONS |
491 | =head1 SECURITY CONSIDERATIONS |
120 | |
492 | |
121 | I also cannot guarantee for security. |
493 | I also cannot give any guarantees for security, Spritz is a very new |
|
|
494 | cryptographic algorithm, and when this module was written, almost |
|
|
495 | completely unproven. |
122 | |
496 | |
123 | =head1 AUTHOR |
497 | =head1 AUTHOR |
124 | |
498 | |
125 | Marc Lehmann <schmorp@schmorp.de> |
499 | Marc Lehmann <schmorp@schmorp.de> |
126 | http://home.schmorp.de/ |
500 | http://home.schmorp.de/ |
127 | |
501 | |
128 | The actual twofish encryption is written in horribly microsoft'ish looking |
|
|
129 | almost ansi-c by Doug Whiting. |
|
|
130 | |
|
|
131 | =cut |
502 | =cut |
132 | |
503 | |
133 | 1; |
504 | 1; |
134 | |
505 | |