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.6 by root, Sat Jan 10 07:48:29 2015 UTC vs.
Revision 1.7 by root, Sat Jan 10 09:20:24 2015 UTC

… …
9 # see the commented examples in their respective classes, 9 # see the commented examples in their respective classes,
10 # but basically 10 # but basically
11 11
12 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; 12 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
13 $ciphertext = $cipher->crypt ($cleartext); 13 $ciphertext = $cipher->crypt ($cleartext);
14
15 my $cipher = new Crypt::Spritz::Cipher $key, $iv;
16 $ciphertext = $cipher->encrypt ($cleartext);
17 # $cleartext = $cipher->decrypt ($ciphertext);
14 18
15 my $hasher = new Crypt::Spritz::Hash; 19 my $hasher = new Crypt::Spritz::Hash;
16 $hasher->add ($data); 20 $hasher->add ($data);
17 $digest = $hasher->finish; 21 $digest = $hasher->finish;
18 22
19 my $hasher = new Crypt::Spritz::MAC $key; 23 my $hasher = new Crypt::Spritz::MAC $key;
20 $hasher->add ($data); 24 $hasher->add ($data);
21 $mac = $hasher->finish; 25 $mac = $hasher->finish;
26
27 my $prng = new Crypt::Spritz::PRNG $entropy;
28 $prng->add ($additional_entropy);
29 $keydata = $prng->get (32);
22 30
23 my $aead = new Crypt::Spritz::AEAD::XOR $key; 31 my $aead = new Crypt::Spritz::AEAD::XOR $key;
24 $aead->nonce ($counter); 32 $aead->nonce ($counter);
25 $aead->associated_data ($header); 33 $aead->associated_data ($header);
26 $ciphertext = $aead->crypt ($cleartext); 34 $ciphertext = $aead->crypt ($cleartext);
27 $mac = $aead->mac; 35 $mac = $aead->mac;
28 36
29 my $prng = new Crypt::Spritz::PRNG $entropy; 37 my $aead = new Crypt::Spritz::AEAD $key;
30 $prng->add ($additional_entropy); 38 $aead->nonce ($counter);
31 $keydata = $prng->get (32); 39 $aead->associated_data ($header);
40 $ciphertext = $aead->encrypt ($cleartext);
41 # $cleartext = $aead->decrypt ($ciphertext);
42 $mac = $aead->mac;
32 43
33=head1 DESCRIPTION 44=head1 DESCRIPTION
34 45
35This module implements the Spritz spongelike function (with N=256), the 46This module implements the Spritz spongelike function (with N=256), the
36spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. 47spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
… …
55 66
56The 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
57and safer, a number of convenience classes are provided for typical 68and safer, a number of convenience classes are provided for typical
58end-user tasks: 69end-user tasks:
59 70
60 encryption - Crypt::Spritz::Cipher::XOR 71 random number generation - Crypt::Spritz::PRNG
61 hashing - Crypt::Spritz::Hash 72 hashing - Crypt::Spritz::Hash
62 message authentication - Crypt::Spritz::MAC 73 message authentication - Crypt::Spritz::MAC
74 encryption - Crypt::Spritz::Cipher::XOR
75 encryption - Crypt::Spritz::Cipher
63 authenticated encryption - Crypt::Spritz::AEAD::XOR 76 authenticated encryption - Crypt::Spritz::AEAD::XOR
64 random number generation - Crypt::Spritz::PRNG 77 authenticated encryption - Crypt::Spritz::AEAD
65 78
66=cut 79=cut
67 80
68package Crypt::Spritz; 81package Crypt::Spritz;
69 82
… …
161Squeezes out a single byte from the state. 174Squeezes out a single byte from the state.
162 175
163=item $octets = $spritz->squeeze ($len) # Squeeze 176=item $octets = $spritz->squeeze ($len) # Squeeze
164 177
165Squeezes 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.
166 369
167=back 370=back
168 371
169 372
170=head2 THE Crypt::Spritz::Cipher::XOR CLASS 373=head2 THE Crypt::Spritz::Cipher::XOR CLASS
… …
239These methods are provided for L<Crypt::CBC> compatibility and simply 442These methods are provided for L<Crypt::CBC> compatibility and simply
240return C<32> and C<64>, respectively. 443return C<32> and C<64>, respectively.
241 444
242Note 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
243not a block cipher and already provides an appropriate mode. 446not a block cipher and already provides an appropriate mode.
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.
369 447
370=back 448=back
371 449
372 450
373=head2 THE Crypt::Spritz::AEAD::XOR CLASS 451=head2 THE Crypt::Spritz::AEAD::XOR CLASS
… …
504 } 582 }
505 583
506=back 584=back
507 585
508 586
509=head2 THE Crypt::Spritz::PRNG CLASS
510
511This class implements a Pseudorandom Number Generatore (B<PRNG>),
512sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
513fact, it is even cryptographically secure, making it a B<CSPRNG>.
514
515Typical usage as a random number generator involves creating a PRNG
516object with a seed of your choice, and then fetching randomness via
517C<get>:
518
519 # create a PRNG object, use a seed string of your choice
520 my $prng = new Crypt::Spritz::PRNG $seed;
521
522 # now call get as many times as you wish to get binary randomness
523 my $some_randomness = $prng->get (17);
524 my moree_randomness = $prng->get (5000);
525 ...
526
527Typical usage as a cryptographically secure random number generator is to
528feed in some secret entropy (32 octets/256 bits are commonly considered
529enough), for example from C</dev/random> or C</dev/urandom>, and then
530generate some key material.
531
532 # create a PRNG object
533 my $prng = new Crypt::Spritz::PRNG;
534
535 # seed some entropy (either via ->add or in the constructor)
536 $prng->add ($some_secret_highly_entropic_string);
537
538 # now call get as many times as you wish to get
539 # hard to guess binary randomness
540 my $key1 = $prng->get (32);
541 my $key2 = $prng->get (16);
542 ...
543
544 # for long running programs, it is advisable to
545 # reseed the PRNG from time to time with new entropy
546 $prng->add ($some_more_entropy);
547
548=over 4
549
550=item $prng = new Crypt::Spritz::PRNG [$seed]
551
552Creates a new random number generator object. If C<$seed> is given, then
553the C<$seed> is added to the internal state as if by a call to C<add>.
554
555=item $prng->add ($entropy)
556
557Adds entropy to the internal state, thereby hopefully making it harder
558to guess. Good sources for entropy are irregular hardware events, or
559randomness provided by C</dev/urandom> or C</dev/random>.
560
561The design of the Spritz PRNG should make it strong against attacks where
562the attacker controls all the entropy, so it should be safe to add entropy
563from untrusted sources - more is better than less if you need a CSPRNG.
564
565For use as PRNG, of course, this matters very little.
566
567=item $octets = $prng->get ($length)
568
569Generates and returns C<$length> random octets as a string.
570
571=back
572
573
574=head1 SEE ALSO 587=head1 SEE ALSO
575 588
576L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. 589L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
577 590
578=head1 SECURITY CONSIDERATIONS 591=head1 SECURITY CONSIDERATIONS

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines