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.5 by root, Sat Jan 10 07:19:24 2015 UTC vs.
Revision 1.6 by root, Sat Jan 10 07:48:29 2015 UTC

1=head1 NAME 1=head1 NAME
2 2
3Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG 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
… …
46slower than RC4 or AES, hashing many times slower than SHA-3, although 46slower than RC4 or AES, hashing many times slower than SHA-3, although
47this might be reversed on an 8-bit-cpu) and the fact that it is totally 47this might be reversed on an 8-bit-cpu) and the fact that it is totally
48unproven in the field (as of this writing, the cipher was just a few 48unproven in the field (as of this writing, the cipher was just a few
49months old), so it can't be called production-ready. 49months old), so it can't be called production-ready.
50 50
51All the usual caveats regarding stream ciphers apply - never repeat 51All the usual caveats regarding stream ciphers apply - never repeat your
52your key, never repeat your nonce and so on - you should have some basic 52key, never repeat your nonce and so on - you should have some basic
53understanding of cryptography before using this cipher in your own 53understanding of cryptography before using this cipher in your own
54designs. 54designs.
55 55
56The Spritz base class is not meant for end users. To make usage simpler 56The Spritz base class is not meant for end users. To make usage simpler
57and safer, a number of convenience classes are provided for typical 57and safer, a number of convenience classes are provided for typical
… …
67 67
68package Crypt::Spritz; 68package Crypt::Spritz;
69 69
70use XSLoader; 70use XSLoader;
71 71
72$VERSION = '0.0'; 72$VERSION = '0.1';
73 73
74XSLoader::load __PACKAGE__, $VERSION; 74XSLoader::load __PACKAGE__, $VERSION;
75 75
76@Crypt::Spritz::ISA = Crypt::Spritz::Base::; 76@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
77 77
… …
120 120
121=item $spritz->init # InitializeState 121=item $spritz->init # InitializeState
122 122
123Initialises the Spritz state again, throwing away the previous state. 123Initialises the Spritz state again, throwing away the previous state.
124 124
125=item $another_spritz = $spritz->clone
126
127Make an exact copy of the spritz state. This method can be called on all
128of the objects in this module, but is documented separately to give some
129cool usage examples.
130
125=item $spritz->update # Update 131=item $spritz->update # Update
126 132
127=item $spritz->whip ($r) # Whip 133=item $spritz->whip ($r) # Whip
128 134
129=item $spritz->crush # Crush 135=item $spritz->crush # Crush
… …
135Calls the Spritz primitive ovf the same name - these are not normally 141Calls the Spritz primitive ovf the same name - these are not normally
136called manually. 142called manually.
137 143
138=item $spritz->absorb ($I) # Absorb 144=item $spritz->absorb ($I) # Absorb
139 145
140Absorbs the given data into the state (usually used for key material, nonces, IVs 146Absorbs the given data into the state (usually used for key material,
141messages to be hashed and so on). 147nonces, IVs messages to be hashed and so on).
142 148
143=item $spritz->absorb_stop # AbsorbStop 149=item $spritz->absorb_stop # AbsorbStop
144 150
145Absorbs a special stop symbol - this is usually used as delimiter between 151Absorbs a special stop symbol - this is usually used as delimiter between
146multiple strings to be absorbed, to thwart extension attacks. 152multiple strings to be absorbed, to thwart extension attacks.
… …
207 213
208=item $encrypted = $cipher->crypt ($cleartext) 214=item $encrypted = $cipher->crypt ($cleartext)
209 215
210=item $cleartext = $cipher->crypt ($encrypted) 216=item $cleartext = $cipher->crypt ($encrypted)
211 217
212Encrypt or decrypt a piece of a message. This cna be called as many times 218Encrypt or decrypt a piece of a message. This can be called as many times
213as you want, and the message can be split into as few or many pieces as 219as you want, and the message can be split into as few or many pieces as
214required without affecting the results. 220required without affecting the results.
215 221
216=item $cipher->crypt_inplace ($cleartext_or_ciphertext) 222=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
217 223
218Same as C<crypt>, except it I<modifies the argument in-place>. 224Same as C<crypt>, except it I<modifies the argument in-place>.
225
226=item $another_cipher = $cipher->clone
227
228Make an exact copy of the cipher state. This can be useful to cache states
229for reuse later, for example, to avoid expensive key setups.
230
231While there might be use cases for this feature, it makes a lot more sense
232for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
233you to specify the IV/nonce separately.
219 234
220=item $constant_32 = $cipher->keysize 235=item $constant_32 = $cipher->keysize
221 236
222=item $constant_64 = $cipher->blocksize 237=item $constant_64 = $cipher->blocksize
223 238
… …
265cannot sensibly be used for further hashing afterwards. 280cannot sensibly be used for further hashing afterwards.
266 281
267Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit 282Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
268digests, respectively. 283digests, respectively.
269 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
270=back 314=back
271 315
272 316
273=head2 THE Crypt::Spritz::MAC CLASS 317=head2 THE Crypt::Spritz::MAC CLASS
274 318
… …
312Calculates a message code of the given length and return it. The object 356Calculates a message code of the given length and return it. The object
313cannot sensibly be used for further hashing afterwards. 357cannot sensibly be used for further hashing afterwards.
314 358
315Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit 359Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
316digests, respectively. 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.
317 369
318=back 370=back
319 371
320 372
321=head2 THE Crypt::Spritz::AEAD::XOR CLASS 373=head2 THE Crypt::Spritz::AEAD::XOR CLASS
… …
400increments, and thus reuse the same sequence number. The problem with 452increments, and thus reuse the same sequence number. The problem with
401random strings i that your random number generator might be hosed and 453random strings i that your random number generator might be hosed and
402generate the same randomness multiple times (randomness can be very hard 454generate the same randomness multiple times (randomness can be very hard
403to get especially on embedded devices). 455to get especially on embedded devices).
404 456
405=item $aead->associated_data ($data)( 457=item $aead->associated_data ($data)
406 458
407Provide the associated data (cleartext data to be authenticated but not 459Provide the associated data (cleartext data to be authenticated but not
408encrypted). This method I<must> be called I<after> C<nonce> and I<before> 460encrypted). This method I<must> be called I<after> C<nonce> and I<before>
409C<crypt>. 461C<crypt>.
410 462
… …
419 471
420=item $encrypted = $cipher->crypt ($cleartext) 472=item $encrypted = $cipher->crypt ($cleartext)
421 473
422=item $cleartext = $cipher->crypt ($encrypted) 474=item $cleartext = $cipher->crypt ($encrypted)
423 475
424Encrypt or decrypt a piece of a message. This cna be called as many times 476Encrypt or decrypt a piece of a message. This can be called as many times
425as you want, and the message can be split into as few or many pieces as 477as you want, and the message can be split into as few or many pieces as
426required without affecting the results, with one exception: All except the 478required without affecting the results, with one exception: All except the
427last call to C<crypt> needs to pass in a multiple of C<64> octets. The 479last call to C<crypt> needs to pass in a multiple of C<64> octets. The
428last call to C<crypt> does not have this limitation. 480last call to C<crypt> does not have this limitation.
429 481
430=item $cipher->crypt_inplace ($cleartext_or_ciphertext) 482=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
431 483
432Same as C<crypt>, except it I<modifies the argument in-place>. 484Same as C<crypt>, except it I<modifies the argument in-place>.
485
486=item $another_cipher = $cipher->clone
487
488Make an exact copy of the cipher state. This can be useful to cache states
489for reuse later, for example, to avoid expensive key setups.
490
491Example: set up a cipher state with a key, then clone and use it to
492encrypt messages with different nonces.
493
494 my $cipher = new Crypt::Spritz::AEAD::XOR $key;
495
496 my $message_counter;
497
498 for my $message ("a", "b", "c") {
499 my $clone = $cipher->clone;
500 $clone->nonce (pack "N", ++$message_counter);
501 $clone->associated_data ("");
502 my $encrypted = $clone->crypt ($message);
503 ...
504 }
433 505
434=back 506=back
435 507
436 508
437=head2 THE Crypt::Spritz::PRNG CLASS 509=head2 THE Crypt::Spritz::PRNG CLASS

Diff Legend

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