ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Crypt-Spritz/Spritz.pm
(Generate patch)

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.4 by root, Sat Jan 10 07:10:46 2015 UTC vs.
Revision 1.7 by root, Sat Jan 10 09:20:24 2015 UTC

1=head1 NAME 1=head1 NAME
2 2
3Crypt::Spritz - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng module 3Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Crypt::Spritz; 7 use Crypt::Spritz;
8 8
9 # keysize() is 32, but spritz accepts any key size 9 # see the commented examples in their respective classes,
10 # blocksize() is 16, but cna be anything 10 # but basically
11 11
12 $cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC; 12 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
13 $ciphertext = $cipher->crypt ($cleartext);
13 14
15 my $cipher = new Crypt::Spritz::Cipher $key, $iv;
14 $crypted = $cipher->encrypt($plaintext); 16 $ciphertext = $cipher->encrypt ($cleartext);
15 # - OR -
16 $plaintext = $cipher->decrypt($crypted); 17 # $cleartext = $cipher->decrypt ($ciphertext);
18
19 my $hasher = new Crypt::Spritz::Hash;
20 $hasher->add ($data);
21 $digest = $hasher->finish;
22
23 my $hasher = new Crypt::Spritz::MAC $key;
24 $hasher->add ($data);
25 $mac = $hasher->finish;
26
27 my $prng = new Crypt::Spritz::PRNG $entropy;
28 $prng->add ($additional_entropy);
29 $keydata = $prng->get (32);
30
31 my $aead = new Crypt::Spritz::AEAD::XOR $key;
32 $aead->nonce ($counter);
33 $aead->associated_data ($header);
34 $ciphertext = $aead->crypt ($cleartext);
35 $mac = $aead->mac;
36
37 my $aead = new Crypt::Spritz::AEAD $key;
38 $aead->nonce ($counter);
39 $aead->associated_data ($header);
40 $ciphertext = $aead->encrypt ($cleartext);
41 # $cleartext = $aead->decrypt ($ciphertext);
42 $mac = $aead->mac;
17 43
18=head1 DESCRIPTION 44=head1 DESCRIPTION
19 45
20This module implements the Spritz spongelike function (with N=256), the 46This module implements the Spritz spongelike function (with N=256), the
21spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. 47spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
31slower than RC4 or AES, hashing many times slower than SHA-3, although 57slower than RC4 or AES, hashing many times slower than SHA-3, although
32this might be reversed on an 8-bit-cpu) and the fact that it is totally 58this might be reversed on an 8-bit-cpu) and the fact that it is totally
33unproven in the field (as of this writing, the cipher was just a few 59unproven in the field (as of this writing, the cipher was just a few
34months old), so it can't be called production-ready. 60months old), so it can't be called production-ready.
35 61
36All the usual caveats regarding stream ciphers apply - never repeat 62All the usual caveats regarding stream ciphers apply - never repeat your
37your key, never repeat your nonce etc. - you should have some basic 63key, never repeat your nonce and so on - you should have some basic
38understanding of cryptography before using this cipher in your own 64understanding of cryptography before using this cipher in your own
39designs. 65designs.
40 66
41The Spritz base class is not meant for end users. To make usage simpler 67The Spritz base class is not meant for end users. To make usage simpler
42and safer, a number of convenience classes are provided for typical 68and safer, a number of convenience classes are provided for typical
43end-user tasks: 69end-user tasks:
44 70
45 encryption - Crypt::Spritz::Cipher::XOR 71 random number generation - Crypt::Spritz::PRNG
46 hashing - Crypt::Spritz::Hash 72 hashing - Crypt::Spritz::Hash
47 message authentication - Crypt::Spritz::MAC 73 message authentication - Crypt::Spritz::MAC
74 encryption - Crypt::Spritz::Cipher::XOR
75 encryption - Crypt::Spritz::Cipher
48 authenticated encryption - Crypt::Spritz::AEAD::XOR 76 authenticated encryption - Crypt::Spritz::AEAD::XOR
49 random number generation - Crypt::Spritz::PRNG 77 authenticated encryption - Crypt::Spritz::AEAD
50 78
51=cut 79=cut
52 80
53package Crypt::Spritz; 81package Crypt::Spritz;
54 82
55use XSLoader; 83use XSLoader;
56 84
57$VERSION = '0.0'; 85$VERSION = '0.1';
58 86
59XSLoader::load __PACKAGE__, $VERSION; 87XSLoader::load __PACKAGE__, $VERSION;
60 88
61@Crypt::Spritz::ISA = Crypt::Spritz::Base::; 89@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
62 90
105 133
106=item $spritz->init # InitializeState 134=item $spritz->init # InitializeState
107 135
108Initialises the Spritz state again, throwing away the previous state. 136Initialises the Spritz state again, throwing away the previous state.
109 137
138=item $another_spritz = $spritz->clone
139
140Make an exact copy of the spritz state. This method can be called on all
141of the objects in this module, but is documented separately to give some
142cool usage examples.
143
110=item $spritz->update # Update 144=item $spritz->update # Update
111 145
112=item $spritz->whip ($r) # Whip 146=item $spritz->whip ($r) # Whip
113 147
114=item $spritz->crush # Crush 148=item $spritz->crush # Crush
120Calls the Spritz primitive ovf the same name - these are not normally 154Calls the Spritz primitive ovf the same name - these are not normally
121called manually. 155called manually.
122 156
123=item $spritz->absorb ($I) # Absorb 157=item $spritz->absorb ($I) # Absorb
124 158
125Absorbs the given data into the state (usually used for key material, nonces, IVs 159Absorbs the given data into the state (usually used for key material,
126messages to be hashed and so on). 160nonces, IVs messages to be hashed and so on).
127 161
128=item $spritz->absorb_stop # AbsorbStop 162=item $spritz->absorb_stop # AbsorbStop
129 163
130Absorbs a special stop symbol - this is usually used as delimiter between 164Absorbs a special stop symbol - this is usually used as delimiter between
131multiple strings to be absorbed, to thwart extension attacks. 165multiple strings to be absorbed, to thwart extension attacks.
140Squeezes out a single byte from the state. 174Squeezes out a single byte from the state.
141 175
142=item $octets = $spritz->squeeze ($len) # Squeeze 176=item $octets = $spritz->squeeze ($len) # Squeeze
143 177
144Squeezes out the requested number of bytes from the state - this is usually 178Squeezes out the requested number of bytes from the state - this is usually
179
180=back
181
182
183=head2 THE Crypt::Spritz::PRNG CLASS
184
185This class implements a Pseudorandom Number Generatore (B<PRNG>),
186sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
187fact, it is even cryptographically secure, making it a B<CSPRNG>.
188
189Typical usage as a random number generator involves creating a PRNG
190object with a seed of your choice, and then fetching randomness via
191C<get>:
192
193 # create a PRNG object, use a seed string of your choice
194 my $prng = new Crypt::Spritz::PRNG $seed;
195
196 # now call get as many times as you wish to get binary randomness
197 my $some_randomness = $prng->get (17);
198 my moree_randomness = $prng->get (5000);
199 ...
200
201Typical usage as a cryptographically secure random number generator is to
202feed in some secret entropy (32 octets/256 bits are commonly considered
203enough), for example from C</dev/random> or C</dev/urandom>, and then
204generate some key material.
205
206 # create a PRNG object
207 my $prng = new Crypt::Spritz::PRNG;
208
209 # seed some entropy (either via ->add or in the constructor)
210 $prng->add ($some_secret_highly_entropic_string);
211
212 # now call get as many times as you wish to get
213 # hard to guess binary randomness
214 my $key1 = $prng->get (32);
215 my $key2 = $prng->get (16);
216 ...
217
218 # for long running programs, it is advisable to
219 # reseed the PRNG from time to time with new entropy
220 $prng->add ($some_more_entropy);
221
222=over 4
223
224=item $prng = new Crypt::Spritz::PRNG [$seed]
225
226Creates a new random number generator object. If C<$seed> is given, then
227the C<$seed> is added to the internal state as if by a call to C<add>.
228
229=item $prng->add ($entropy)
230
231Adds entropy to the internal state, thereby hopefully making it harder
232to guess. Good sources for entropy are irregular hardware events, or
233randomness provided by C</dev/urandom> or C</dev/random>.
234
235The design of the Spritz PRNG should make it strong against attacks where
236the attacker controls all the entropy, so it should be safe to add entropy
237from untrusted sources - more is better than less if you need a CSPRNG.
238
239For use as PRNG, of course, this matters very little.
240
241=item $octets = $prng->get ($length)
242
243Generates and returns C<$length> random octets as a string.
244
245=back
246
247
248=head2 THE Crypt::Spritz::Hash CLASS
249
250This implements the Spritz digest/hash algorithm. It works very similar to
251other digest modules on CPAN, such as L<Digest::SHA3>.
252
253Typical use for hashing:
254
255 # create hasher object
256 my $hasher = new Crypt::Spritz::Hash;
257
258 # now feed data to be hashed into $hasher
259 # in as few or many calls as required
260 $hasher->add ("Some data");
261 $hasher->add ("Some more");
262
263 # extract the hash - the object is not usable afterwards
264 my $digest = $hasher->finish (32);
265
266=over 4
267
268=item $hasher = new Crypt::Spritz::Hash
269
270Creates a new hasher object.
271
272=item $hasher->add ($data)
273
274Adds data to be hashed into the hasher state. It doesn't matter whether
275you pass your data in in one go or split it up, the hash will be the same.
276
277=item $digest = $hasher->finish ($length)
278
279Calculates a hash digest of the given length and return it. The object
280cannot sensibly be used for further hashing afterwards.
281
282Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
283digests, respectively.
284
285=item $another_hasher = $hasher->clone
286
287Make an exact copy of the hasher state. This can be useful to generate
288incremental hashes, for example.
289
290Example: generate a hash for the data already fed into the hasher, by keeping
291the original hasher for further C<add> calls and calling C<finish> on a C<clone>.
292
293 my $intermediate_hash = $hasher->clone->finish;
294
295Example: hash 64KiB of data, and generate a hash after every kilobyte that
296is over the full data.
297
298 my $hasher = new Crypt::Spritz::Hash;
299
300 for (0..63) {
301 my $kib = "x" x 1024; # whatever data
302
303 $hasher->add ($kib);
304
305 my $intermediate_hash = $hasher->clone->finish;
306 ...
307 }
308
309These kind of intermediate hashes are sometimes used in communications
310protocols to protect the integrity of the data incrementally, e.g. to
311detect errors early, while still having a complete hash at the end of a
312transfer.
313
314=back
315
316
317=head2 THE Crypt::Spritz::MAC CLASS
318
319This implements the Spritz Message Authentication Code algorithm. It works
320very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
321implements an authenticated digest (like L<Digest::HMAC>).
322
323I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
324everybody can verify and recreate the hash value for some data, with a
325MAC, knowledge of the (hopefully) secret key is required both to create
326and to verify the digest.
327
328Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
329except a key (typically 16 or 32 octets) is provided to the constructor:
330
331 # create hasher object
332 my $hasher = new Crypt::Spritz::Mac $key;
333
334 # now feed data to be hashed into $hasher
335 # in as few or many calls as required
336 $hasher->add ("Some data");
337 $hasher->add ("Some more");
338
339 # extract the mac - the object is not usable afterwards
340 my $mac = $hasher->finish (32);
341
342=over 4
343
344=item $hasher = new Crypt::Spritz::MAC $key
345
346Creates a new hasher object. The C<$key> can be of any length, but 16 and
34732 (128 and 256 bit) are customary.
348
349=item $hasher->add ($data)
350
351Adds data to be hashed into the hasher state. It doesn't matter whether
352you pass your data in in one go or split it up, the hash will be the same.
353
354=item $mac = $hasher->finish ($length)
355
356Calculates a message code of the given length and return it. The object
357cannot sensibly be used for further hashing afterwards.
358
359Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
360digests, respectively.
361
362=item $another_hasher = $hasher->clone
363
364Make an exact copy of the hasher state. This can be useful to
365generate incremental macs, for example.
366
367See the description for the C<Crypt::Spritz::Hash::clone> method for some
368examples.
145 369
146=back 370=back
147 371
148 372
149=head2 THE Crypt::Spritz::Cipher::XOR CLASS 373=head2 THE Crypt::Spritz::Cipher::XOR CLASS
192 416
193=item $encrypted = $cipher->crypt ($cleartext) 417=item $encrypted = $cipher->crypt ($cleartext)
194 418
195=item $cleartext = $cipher->crypt ($encrypted) 419=item $cleartext = $cipher->crypt ($encrypted)
196 420
197Encrypt or decrypt a piece of a message. This cna be called as many times 421Encrypt or decrypt a piece of a message. This can be called as many times
198as you want, and the message can be split into as few or many pieces as 422as you want, and the message can be split into as few or many pieces as
199required without affecting the results. 423required without affecting the results.
200 424
201=item $cipher->crypt_inplace ($cleartext_or_ciphertext) 425=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
202 426
203Same as C<crypt>, except it I<modifies the argument in-place>. 427Same as C<crypt>, except it I<modifies the argument in-place>.
204 428
429=item $another_cipher = $cipher->clone
430
431Make an exact copy of the cipher state. This can be useful to cache states
432for reuse later, for example, to avoid expensive key setups.
433
434While there might be use cases for this feature, it makes a lot more sense
435for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
436you to specify the IV/nonce separately.
437
205=item $constant_32 = $cipher->keysize 438=item $constant_32 = $cipher->keysize
206 439
207=item $constant_64 = $cipher->blocksize 440=item $constant_64 = $cipher->blocksize
208 441
209These methods are provided for L<Crypt::CBC> compatibility and simply 442These methods are provided for L<Crypt::CBC> compatibility and simply
210return C<32> and C<64>, respectively. 443return C<32> and C<64>, respectively.
211 444
212Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is 445Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
213not a block cipher and already provides an appropriate mode. 446not a block cipher and already provides an appropriate mode.
214
215=back
216
217
218=head2 THE Crypt::Spritz::Hash CLASS
219
220This implements the Spritz digest/hash algorithm. It works very similar to
221other digest modules on CPAN, such as L<Digest::SHA3>.
222
223Typical 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
240Creates a new hasher object.
241
242=item $hasher->add ($data)
243
244Adds data to be hashed into the hasher state. It doesn't matter whether
245you 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
249Calculates a hash digest of the given length and return it. The object
250cannot sensibly be used for further hashing afterwards.
251
252Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
253digests, respectively.
254
255=back
256
257
258=head2 THE Crypt::Spritz::MAC CLASS
259
260This implements the Spritz Message Authentication Code algorithm. It works
261very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
262implements an authenticated digest (like L<Digest::HMAC>).
263
264I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
265everybody can verify and recreate the hash value for some data, with a
266MAC, knowledge of the (hopefully) secret key is required both to create
267and to verify the digest.
268
269Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
270except 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
287Creates a new hasher object. The C<$key> can be of any length, but 16 and
28832 (128 and 256 bit) are customary.
289
290=item $hasher->add ($data)
291
292Adds data to be hashed into the hasher state. It doesn't matter whether
293you 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
297Calculates a message code of the given length and return it. The object
298cannot sensibly be used for further hashing afterwards.
299
300Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
301digests, respectively.
302 447
303=back 448=back
304 449
305 450
306=head2 THE Crypt::Spritz::AEAD::XOR CLASS 451=head2 THE Crypt::Spritz::AEAD::XOR CLASS
385increments, and thus reuse the same sequence number. The problem with 530increments, and thus reuse the same sequence number. The problem with
386random strings i that your random number generator might be hosed and 531random strings i that your random number generator might be hosed and
387generate the same randomness multiple times (randomness can be very hard 532generate the same randomness multiple times (randomness can be very hard
388to get especially on embedded devices). 533to get especially on embedded devices).
389 534
390=item $aead->associated_data ($data)( 535=item $aead->associated_data ($data)
391 536
392Provide the associated data (cleartext data to be authenticated but not 537Provide the associated data (cleartext data to be authenticated but not
393encrypted). This method I<must> be called I<after> C<nonce> and I<before> 538encrypted). This method I<must> be called I<after> C<nonce> and I<before>
394C<crypt>. 539C<crypt>.
395 540
404 549
405=item $encrypted = $cipher->crypt ($cleartext) 550=item $encrypted = $cipher->crypt ($cleartext)
406 551
407=item $cleartext = $cipher->crypt ($encrypted) 552=item $cleartext = $cipher->crypt ($encrypted)
408 553
409Encrypt or decrypt a piece of a message. This cna be called as many times 554Encrypt or decrypt a piece of a message. This can be called as many times
410as you want, and the message can be split into as few or many pieces as 555as you want, and the message can be split into as few or many pieces as
411required without affecting the results, with one exception: All except the 556required without affecting the results, with one exception: All except the
412last call to C<crypt> needs to pass in a multiple of C<64> octets. The 557last call to C<crypt> needs to pass in a multiple of C<64> octets. The
413last call to C<crypt> does not have this limitation. 558last call to C<crypt> does not have this limitation.
414 559
415=item $cipher->crypt_inplace ($cleartext_or_ciphertext) 560=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
416 561
417Same as C<crypt>, except it I<modifies the argument in-place>. 562Same as C<crypt>, except it I<modifies the argument in-place>.
418 563
419=back 564=item $another_cipher = $cipher->clone
420 565
566Make an exact copy of the cipher state. This can be useful to cache states
567for reuse later, for example, to avoid expensive key setups.
421 568
422=head2 THE Crypt::Spritz::PRNG CLASS 569Example: set up a cipher state with a key, then clone and use it to
570encrypt messages with different nonces.
423 571
424This class implements a Pseudorandom Number Generatore (B<PRNG>),
425sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
426fact, it is even cryptographically secure, making it a B<CSPRNG>.
427
428Typical usage as a random number generator involves creating a PRNG
429object with a seed of your choice, and then fetching randomness via
430C<get>:
431
432 # create a PRNG object, use a seed string of your choice
433 my $prng = new Crypt::Spritz::PRNG $seed; 572 my $cipher = new Crypt::Spritz::AEAD::XOR $key;
434 573
435 # now call get as many times as you wish to get binary randomness 574 my $message_counter;
436 my $some_randomness = $prng->get (17); 575
437 my moree_randomness = $prng->get (5000); 576 for my $message ("a", "b", "c") {
577 my $clone = $cipher->clone;
578 $clone->nonce (pack "N", ++$message_counter);
579 $clone->associated_data ("");
580 my $encrypted = $clone->crypt ($message);
438 ... 581 ...
439 582 }
440Typical usage as a cryptographically secure random number generator is to
441feed in some secret entropy (32 octets/256 bits are commonly considered
442enough), for example from C</dev/random> or C</dev/urandom>, and then
443generate 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
465Creates a new random number generator object. If C<$seed> is given, then
466the C<$seed> is added to the internal state as if by a call to C<add>.
467
468=item $prng->add ($entropy)
469
470Adds entropy to the internal state, thereby hopefully making it harder
471to guess. Good sources for entropy are irregular hardware events, or
472randomness provided by C</dev/urandom> or C</dev/random>.
473
474The design of the Spritz PRNG should make it strong against attacks where
475the attacker controls all the entropy, so it should be safe to add entropy
476from untrusted sources - more is better than less if you need a CSPRNG.
477
478For use as PRNG, of course, this matters very little.
479
480=item $octets = $prng->get ($length)
481
482Generates and returns C<$length> random octets as a string.
483 583
484=back 584=back
485 585
486 586
487=head1 SEE ALSO 587=head1 SEE ALSO
495completely unproven. 595completely unproven.
496 596
497=head1 AUTHOR 597=head1 AUTHOR
498 598
499 Marc Lehmann <schmorp@schmorp.de> 599 Marc Lehmann <schmorp@schmorp.de>
500 http://home.schmorp.de/ 600 http://software.schmorp.de/pkg/Crypt-Spritz
501 601
502=cut 602=cut
503 603
5041; 6041;
505 605

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines