ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Crypt-Spritz/Spritz.pm
Revision: 1.5
Committed: Sat Jan 10 07:19:24 2015 UTC (9 years, 5 months ago) by root
Branch: MAIN
Changes since 1.4: +24 -9 lines
Log Message:
*** empty log message ***

File Contents

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