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

Comparing Crypt-Spritz/README (file contents):
Revision 1.2 by root, Sat Jan 10 07:48:29 2015 UTC vs.
Revision 1.3 by root, Sat Jan 10 09:56:40 2015 UTC

1NAME 1NAME
2 Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module 2 Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
3 3
4SYNOPSIS 4SYNOPSIS
5 use Crypt::Spritz; 5 use Crypt::Spritz;
6 6
7 # see the commented examples in their respective classes, 7 # see the commented examples in their respective classes,
8 # but basically 8 # but basically
9 9
10 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; 10 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
11 $ciphertext = $cipher->crypt ($cleartext); 11 $ciphertext = $cipher->crypt ($cleartext);
12
13 my $cipher = new Crypt::Spritz::Cipher $key, $iv;
14 $ciphertext = $cipher->encrypt ($cleartext);
15 # $cleartext = $cipher->decrypt ($ciphertext);
12 16
13 my $hasher = new Crypt::Spritz::Hash; 17 my $hasher = new Crypt::Spritz::Hash;
14 $hasher->add ($data); 18 $hasher->add ($data);
15 $digest = $hasher->finish; 19 $digest = $hasher->finish;
16 20
17 my $hasher = new Crypt::Spritz::MAC $key; 21 my $hasher = new Crypt::Spritz::MAC $key;
18 $hasher->add ($data); 22 $hasher->add ($data);
19 $mac = $hasher->finish; 23 $mac = $hasher->finish;
24
25 my $prng = new Crypt::Spritz::PRNG $entropy;
26 $prng->add ($additional_entropy);
27 $keydata = $prng->get (32);
20 28
21 my $aead = new Crypt::Spritz::AEAD::XOR $key; 29 my $aead = new Crypt::Spritz::AEAD::XOR $key;
22 $aead->nonce ($counter); 30 $aead->nonce ($counter);
23 $aead->associated_data ($header); 31 $aead->associated_data ($header);
24 $ciphertext = $aead->crypt ($cleartext); 32 $ciphertext = $aead->crypt ($cleartext);
25 $mac = $aead->mac; 33 $mac = $aead->mac;
26 34
27 my $prng = new Crypt::Spritz::PRNG $entropy; 35 my $aead = new Crypt::Spritz::AEAD $key;
28 $prng->add ($additional_entropy); 36 $aead->nonce ($counter);
29 $keydata = $prng->get (32); 37 $aead->associated_data ($header);
38 $ciphertext = $aead->encrypt ($cleartext);
39 # $cleartext = $aead->decrypt ($ciphertext);
40 $mac = $aead->mac;
30 41
31DESCRIPTION 42DESCRIPTION
32 This module implements the Spritz spongelike function (with N=256), the 43 This module implements the Spritz spongelike function (with N=256), the
33 spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. 44 spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
34 45
52 63
53 The Spritz base class is not meant for end users. To make usage simpler 64 The Spritz base class is not meant for end users. To make usage simpler
54 and safer, a number of convenience classes are provided for typical 65 and safer, a number of convenience classes are provided for typical
55 end-user tasks: 66 end-user tasks:
56 67
57 encryption - Crypt::Spritz::Cipher::XOR 68 random number generation - Crypt::Spritz::PRNG
58 hashing - Crypt::Spritz::Hash 69 hashing - Crypt::Spritz::Hash
59 message authentication - Crypt::Spritz::MAC 70 message authentication - Crypt::Spritz::MAC
71 encryption - Crypt::Spritz::Cipher::XOR
72 encryption - Crypt::Spritz::Cipher
60 authenticated encryption - Crypt::Spritz::AEAD::XOR 73 authenticated encryption - Crypt::Spritz::AEAD::XOR
61 random number generation - Crypt::Spritz::PRNG 74 authenticated encryption - Crypt::Spritz::AEAD
62 75
63 THE Crypt::Spritz CLASS 76 THE Crypt::Spritz CLASS
64 This class implements most of the Spritz primitives. To use it 77 This class implements most of the Spritz primitives. To use it
65 effectively you should understand them, for example, by reading the 78 effectively you should understand them, for example, by reading the
66 "http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper, 79 "http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper,
73 Creates and returns a new, initialised Spritz state. 86 Creates and returns a new, initialised Spritz state.
74 87
75 $spritz->init # InitializeState 88 $spritz->init # InitializeState
76 Initialises the Spritz state again, throwing away the previous 89 Initialises the Spritz state again, throwing away the previous
77 state. 90 state.
91
92 $another_spritz = $spritz->clone
93 Make an exact copy of the spritz state. This method can be called on
94 all of the objects in this module, but is documented separately to
95 give some cool usage examples.
78 96
79 $spritz->update # Update 97 $spritz->update # Update
80 $spritz->whip ($r) # Whip 98 $spritz->whip ($r) # Whip
81 $spritz->crush # Crush 99 $spritz->crush # Crush
82 $spritz->shuffle # Shuffle 100 $spritz->shuffle # Shuffle
102 120
103 $octets = $spritz->squeeze ($len) # Squeeze 121 $octets = $spritz->squeeze ($len) # Squeeze
104 Squeezes out the requested number of bytes from the state - this is 122 Squeezes out the requested number of bytes from the state - this is
105 usually 123 usually
106 124
125 THE Crypt::Spritz::PRNG CLASS
126 This class implements a Pseudorandom Number Generatore (PRNG), sometimes
127 also called a Deterministic Random Bit Generator (DRBG). In fact, it is
128 even cryptographically secure, making it a CSPRNG.
129
130 Typical usage as a random number generator involves creating a PRNG
131 object with a seed of your choice, and then fetching randomness via
132 "get":
133
134 # create a PRNG object, use a seed string of your choice
135 my $prng = new Crypt::Spritz::PRNG $seed;
136
137 # now call get as many times as you wish to get binary randomness
138 my $some_randomness = $prng->get (17);
139 my moree_randomness = $prng->get (5000);
140 ...
141
142 Typical usage as a cryptographically secure random number generator is
143 to feed in some secret entropy (32 octets/256 bits are commonly
144 considered enough), for example from "/dev/random" or "/dev/urandom",
145 and then generate some key material.
146
147 # create a PRNG object
148 my $prng = new Crypt::Spritz::PRNG;
149
150 # seed some entropy (either via ->add or in the constructor)
151 $prng->add ($some_secret_highly_entropic_string);
152
153 # now call get as many times as you wish to get
154 # hard to guess binary randomness
155 my $key1 = $prng->get (32);
156 my $key2 = $prng->get (16);
157 ...
158
159 # for long running programs, it is advisable to
160 # reseed the PRNG from time to time with new entropy
161 $prng->add ($some_more_entropy);
162
163 $prng = new Crypt::Spritz::PRNG [$seed]
164 Creates a new random number generator object. If $seed is given,
165 then the $seed is added to the internal state as if by a call to
166 "add".
167
168 $prng->add ($entropy)
169 Adds entropy to the internal state, thereby hopefully making it
170 harder to guess. Good sources for entropy are irregular hardware
171 events, or randomness provided by "/dev/urandom" or "/dev/random".
172
173 The design of the Spritz PRNG should make it strong against attacks
174 where the attacker controls all the entropy, so it should be safe to
175 add entropy from untrusted sources - more is better than less if you
176 need a CSPRNG.
177
178 For use as PRNG, of course, this matters very little.
179
180 $octets = $prng->get ($length)
181 Generates and returns $length random octets as a string.
182
183 THE Crypt::Spritz::Hash CLASS
184 This implements the Spritz digest/hash algorithm. It works very similar
185 to other digest modules on CPAN, such as Digest::SHA3.
186
187 Typical use for hashing:
188
189 # create hasher object
190 my $hasher = new Crypt::Spritz::Hash;
191
192 # now feed data to be hashed into $hasher
193 # in as few or many calls as required
194 $hasher->add ("Some data");
195 $hasher->add ("Some more");
196
197 # extract the hash - the object is not usable afterwards
198 my $digest = $hasher->finish (32);
199
200 $hasher = new Crypt::Spritz::Hash
201 Creates a new hasher object.
202
203 $hasher->add ($data)
204 Adds data to be hashed into the hasher state. It doesn't matter
205 whether you pass your data in in one go or split it up, the hash
206 will be the same.
207
208 $digest = $hasher->finish ($length)
209 Calculates a hash digest of the given length and return it. The
210 object cannot sensibly be used for further hashing afterwards.
211
212 Typical digest lengths are 16 and 32, corresponding to 128 and 256
213 bit digests, respectively.
214
215 $another_hasher = $hasher->clone
216 Make an exact copy of the hasher state. This can be useful to
217 generate incremental hashes, for example.
218
219 Example: generate a hash for the data already fed into the hasher,
220 by keeping the original hasher for further "add" calls and calling
221 "finish" on a "clone".
222
223 my $intermediate_hash = $hasher->clone->finish;
224
225 Example: hash 64KiB of data, and generate a hash after every
226 kilobyte that is over the full data.
227
228 my $hasher = new Crypt::Spritz::Hash;
229
230 for (0..63) {
231 my $kib = "x" x 1024; # whatever data
232
233 $hasher->add ($kib);
234
235 my $intermediate_hash = $hasher->clone->finish;
236 ...
237 }
238
239 These kind of intermediate hashes are sometimes used in
240 communications protocols to protect the integrity of the data
241 incrementally, e.g. to detect errors early, while still having a
242 complete hash at the end of a transfer.
243
244 THE Crypt::Spritz::MAC CLASS
245 This implements the Spritz Message Authentication Code algorithm. It
246 works very similar to other digest modules on CPAN, such as
247 Digest::SHA3, but implements an authenticated digest (like
248 Digest::HMAC).
249
250 *Authenticated* means that, unlike Crypt::Spritz::Hash, where everybody
251 can verify and recreate the hash value for some data, with a MAC,
252 knowledge of the (hopefully) secret key is required both to create and
253 to verify the digest.
254
255 Typical use for hashing is almost the same as with Crypt::Spritz::MAC,
256 except a key (typically 16 or 32 octets) is provided to the constructor:
257
258 # create hasher object
259 my $hasher = new Crypt::Spritz::Mac $key;
260
261 # now feed data to be hashed into $hasher
262 # in as few or many calls as required
263 $hasher->add ("Some data");
264 $hasher->add ("Some more");
265
266 # extract the mac - the object is not usable afterwards
267 my $mac = $hasher->finish (32);
268
269 $hasher = new Crypt::Spritz::MAC $key
270 Creates a new hasher object. The $key can be of any length, but 16
271 and 32 (128 and 256 bit) are customary.
272
273 $hasher->add ($data)
274 Adds data to be hashed into the hasher state. It doesn't matter
275 whether you pass your data in in one go or split it up, the hash
276 will be the same.
277
278 $mac = $hasher->finish ($length)
279 Calculates a message code of the given length and return it. The
280 object cannot sensibly be used for further hashing afterwards.
281
282 Typical digest lengths are 16 and 32, corresponding to 128 and 256
283 bit digests, respectively.
284
285 $another_hasher = $hasher->clone
286 Make an exact copy of the hasher state. This can be useful to
287 generate incremental macs, for example.
288
289 See the description for the "Crypt::Spritz::Hash::clone" method for
290 some examples.
291
107 THE Crypt::Spritz::Cipher::XOR CLASS 292 THE Crypt::Spritz::Cipher::XOR CLASS
108 This class implements stream encryption/decryption. It doesn't implement 293 This class implements stream encryption/decryption. It doesn't implement
109 the standard Spritz encryption but the XOR variant (called spritz-xor in 294 the standard Spritz encryption but the XOR variant (called spritz-xor in
110 the paper). 295 the paper).
111 296
144 are 16 (128 bit) or 32 (256 bit), while the $IV simply needs to be 329 are 16 (128 bit) or 32 (256 bit), while the $IV simply needs to be
145 long enough to distinguish repeated uses of tghe same key. 330 long enough to distinguish repeated uses of tghe same key.
146 331
147 $encrypted = $cipher->crypt ($cleartext) 332 $encrypted = $cipher->crypt ($cleartext)
148 $cleartext = $cipher->crypt ($encrypted) 333 $cleartext = $cipher->crypt ($encrypted)
149 Encrypt or decrypt a piece of a message. This cna be called as many 334 Encrypt or decrypt a piece of a message. This can be called as many
150 times as you want, and the message can be split into as few or many 335 times as you want, and the message can be split into as few or many
151 pieces as required without affecting the results. 336 pieces as required without affecting the results.
152 337
153 $cipher->crypt_inplace ($cleartext_or_ciphertext) 338 $cipher->crypt_inplace ($cleartext_or_ciphertext)
154 Same as "crypt", except it *modifies the argument in-place*. 339 Same as "crypt", except it *modifies the argument in-place*.
340
341 $another_cipher = $cipher->clone
342 Make an exact copy of the cipher state. This can be useful to cache
343 states for reuse later, for example, to avoid expensive key setups.
344
345 While there might be use cases for this feature, it makes a lot more
346 sense for "Crypt::Spritz::AEAD" and "Crypt::Spritz::AEAD::XOR", as
347 they allow you to specify the IV/nonce separately.
155 348
156 $constant_32 = $cipher->keysize 349 $constant_32 = $cipher->keysize
157 $constant_64 = $cipher->blocksize 350 $constant_64 = $cipher->blocksize
158 These methods are provided for Crypt::CBC compatibility and simply 351 These methods are provided for Crypt::CBC compatibility and simply
159 return 32 and 64, respectively. 352 return 32 and 64, respectively.
160 353
161 Note that it is pointless to use Spritz with Crypt::CBC, as Spritz 354 Note that it is pointless to use Spritz with Crypt::CBC, as Spritz
162 is not a block cipher and already provides an appropriate mode. 355 is not a block cipher and already provides an appropriate mode.
163 356
164 THE Crypt::Spritz::Hash CLASS
165 This implements the Spritz digest/hash algorithm. It works very similar
166 to other digest modules on CPAN, such as Digest::SHA3.
167
168 Typical use for hashing:
169
170 # create hasher object
171 my $hasher = new Crypt::Spritz::Hash;
172
173 # now feed data to be hashed into $hasher
174 # in as few or many calls as required
175 $hasher->add ("Some data");
176 $hasher->add ("Some more");
177
178 # extract the hash - the object is not usable afterwards
179 my $digest = $hasher->finish (32);
180
181 $hasher = new Crypt::Spritz::Hash
182 Creates a new hasher object.
183
184 $hasher->add ($data)
185 Adds data to be hashed into the hasher state. It doesn't matter
186 whether you pass your data in in one go or split it up, the hash
187 will be the same.
188
189 $digest = $hasher->finish ($length)
190 Calculates a hash digest of the given length and return it. The
191 object cannot sensibly be used for further hashing afterwards.
192
193 Typical digest lengths are 16 and 32, corresponding to 128 and 256
194 bit digests, respectively.
195
196 THE Crypt::Spritz::MAC CLASS 357 THE Crypt::Spritz::Cipher CLASS
197 This implements the Spritz Message Authentication Code algorithm. It 358 This class is pretty much the same as the "Crypt::Spritz::Cipher::XOR"
198 works very similar to other digest modules on CPAN, such as 359 class, with two differences: first, it implements the "standard" Spritz
199 Digest::SHA3, but implements an authenticated digest (like 360 encryption algorithm, and second, while this variant is easier to
200 Digest::HMAC). 361 analyze mathematically, there is little else to recommend it for, as it
362 is slower, and requires lots of code duplication code.
201 363
202 *Authenticated* means that, unlike Crypt::Spritz::Hash, where everybody 364 So unless you need to be compatible with another implementation that
203 can verify and recreate the hash value for some data, with a MAC, 365 does not offer the XOR variant, stick to "Crypt::Spritz::Cipher::XOR".
204 knowledge of the (hopefully) secret key is required both to create and
205 to verify the digest.
206 366
207 Typical use for hashing is almost the same as with Crypt::Spritz::MAC, 367 All the methods from "Crypt::Spritz::Cipher::XOR" are available, except
208 except a key (typically 16 or 32 octets) is provided to the constructor: 368 "crypt", which has been replaced by separate "encrypt" and "decrypt"
369 methods:
209 370
210 # create hasher object 371 $encrypted = $cipher->encrypt ($cleartext)
211 my $hasher = new Crypt::Spritz::Mac $key; 372 $cleartext = $cipher->decrypt ($encrypted)
212 373 Really the same as "Crypt::Spritz::Cipher::XOR", except you need
213 # now feed data to be hashed into $hasher 374 separate calls and code for encryption and decryption.
214 # in as few or many calls as required
215 $hasher->add ("Some data");
216 $hasher->add ("Some more");
217
218 # extract the mac - the object is not usable afterwards
219 my $mac = $hasher->finish (32);
220
221 $hasher = new Crypt::Spritz::MAC $key
222 Creates a new hasher object. The $key can be of any length, but 16
223 and 32 (128 and 256 bit) are customary.
224
225 $hasher->add ($data)
226 Adds data to be hashed into the hasher state. It doesn't matter
227 whether you pass your data in in one go or split it up, the hash
228 will be the same.
229
230 $mac = $hasher->finish ($length)
231 Calculates a message code of the given length and return it. The
232 object cannot sensibly be used for further hashing afterwards.
233
234 Typical digest lengths are 16 and 32, corresponding to 128 and 256
235 bit digests, respectively.
236 375
237 THE Crypt::Spritz::AEAD::XOR CLASS 376 THE Crypt::Spritz::AEAD::XOR CLASS
238 This is the most complicated class - it combines encryption and message 377 This is the most complicated class - it combines encryption and message
239 authentication into a single "authenticated encryption mode". It is 378 authentication into a single "authenticated encryption mode". It is
240 similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC, 379 similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC,
310 increments, and thus reuse the same sequence number. The problem 449 increments, and thus reuse the same sequence number. The problem
311 with random strings i that your random number generator might be 450 with random strings i that your random number generator might be
312 hosed and generate the same randomness multiple times (randomness 451 hosed and generate the same randomness multiple times (randomness
313 can be very hard to get especially on embedded devices). 452 can be very hard to get especially on embedded devices).
314 453
315 $aead->associated_data ($data)( 454 $aead->associated_data ($data)
316 Provide the associated data (cleartext data to be authenticated but 455 Provide the associated data (cleartext data to be authenticated but
317 not encrypted). This method *must* be called *after* "nonce" and 456 not encrypted). This method *must* be called *after* "nonce" and
318 *before* "crypt". 457 *before* "crypt".
319 458
320 If you don't have any associated data, you can provide an empty 459 If you don't have any associated data, you can provide an empty
327 message or in general how to interpret the encrypted part of a 466 message or in general how to interpret the encrypted part of a
328 message. 467 message.
329 468
330 $encrypted = $cipher->crypt ($cleartext) 469 $encrypted = $cipher->crypt ($cleartext)
331 $cleartext = $cipher->crypt ($encrypted) 470 $cleartext = $cipher->crypt ($encrypted)
332 Encrypt or decrypt a piece of a message. This cna be called as many 471 Encrypt or decrypt a piece of a message. This can be called as many
333 times as you want, and the message can be split into as few or many 472 times as you want, and the message can be split into as few or many
334 pieces as required without affecting the results, with one 473 pieces as required without affecting the results, with one
335 exception: All except the last call to "crypt" needs to pass in a 474 exception: All except the last call to "crypt" needs to pass in a
336 multiple of 64 octets. The last call to "crypt" does not have this 475 multiple of 64 octets. The last call to "crypt" does not have this
337 limitation. 476 limitation.
338 477
339 $cipher->crypt_inplace ($cleartext_or_ciphertext) 478 $cipher->crypt_inplace ($cleartext_or_ciphertext)
340 Same as "crypt", except it *modifies the argument in-place*. 479 Same as "crypt", except it *modifies the argument in-place*.
341 480
481 $another_cipher = $cipher->clone
482 Make an exact copy of the cipher state. This can be useful to cache
483 states for reuse later, for example, to avoid expensive key setups.
484
485 Example: set up a cipher state with a key, then clone and use it to
486 encrypt messages with different nonces.
487
488 my $cipher = new Crypt::Spritz::AEAD::XOR $key;
489
490 my $message_counter;
491
492 for my $message ("a", "b", "c") {
493 my $clone = $cipher->clone;
494 $clone->nonce (pack "N", ++$message_counter);
495 $clone->associated_data ("");
496 my $encrypted = $clone->crypt ($message);
497 ...
498 }
499
342 THE Crypt::Spritz::PRNG CLASS 500 THE Crypt::Spritz::AEAD CLASS
343 This class implements a Pseudorandom Number Generatore (PRNG), sometimes 501 This class is pretty much the same as the "Crypt::Spritz::AEAD::XOR"
344 also called a Deterministic Random Bit Generator (DRBG). In fact, it is 502 class, with two differences: first, it implements the "standard" Spritz
345 even cryptographically secure, making it a CSPRNG. 503 encryption algorithm, and second, while this variant is easier to
504 analyze mathematically, there is little else to recommend it for, as it
505 is slower, and requires lots of code duplication code.
346 506
347 Typical usage as a random number generator involves creating a PRNG 507 So unless you need to be compatible with another implementation that
348 object with a seed of your choice, and then fetching randomness via 508 does not offer the XOR variant, stick to "Crypt::Spritz::AEAD::XOR".
349 "get":
350 509
351 # create a PRNG object, use a seed string of your choice 510 All the methods from "Crypt::Spritz::AEAD::XOR" are available, except
352 my $prng = new Crypt::Spritz::PRNG $seed; 511 "crypt", which has been replaced by separate "encrypt" and "decrypt"
512 methods:
353 513
354 # now call get as many times as you wish to get binary randomness 514 $encrypted = $cipher->encrypt ($cleartext)
355 my $some_randomness = $prng->get (17); 515 $cleartext = $cipher->decrypt ($encrypted)
356 my moree_randomness = $prng->get (5000); 516 Really the same as "Crypt::Spritz::AEAD::XOR", except you need
357 ... 517 separate calls and code for encryption and decryption, but you have
358 518 the same limitations on usage.
359 Typical usage as a cryptographically secure random number generator is
360 to feed in some secret entropy (32 octets/256 bits are commonly
361 considered enough), for example from "/dev/random" or "/dev/urandom",
362 and then generate some key material.
363
364 # create a PRNG object
365 my $prng = new Crypt::Spritz::PRNG;
366
367 # seed some entropy (either via ->add or in the constructor)
368 $prng->add ($some_secret_highly_entropic_string);
369
370 # now call get as many times as you wish to get
371 # hard to guess binary randomness
372 my $key1 = $prng->get (32);
373 my $key2 = $prng->get (16);
374 ...
375
376 # for long running programs, it is advisable to
377 # reseed the PRNG from time to time with new entropy
378 $prng->add ($some_more_entropy);
379
380 $prng = new Crypt::Spritz::PRNG [$seed]
381 Creates a new random number generator object. If $seed is given,
382 then the $seed is added to the internal state as if by a call to
383 "add".
384
385 $prng->add ($entropy)
386 Adds entropy to the internal state, thereby hopefully making it
387 harder to guess. Good sources for entropy are irregular hardware
388 events, or randomness provided by "/dev/urandom" or "/dev/random".
389
390 The design of the Spritz PRNG should make it strong against attacks
391 where the attacker controls all the entropy, so it should be safe to
392 add entropy from untrusted sources - more is better than less if you
393 need a CSPRNG.
394
395 For use as PRNG, of course, this matters very little.
396
397 $octets = $prng->get ($length)
398 Generates and returns $length random octets as a string.
399 519
400SEE ALSO 520SEE ALSO
401 <http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. 521 <http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
402 522
403SECURITY CONSIDERATIONS 523SECURITY CONSIDERATIONS

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines