File Coverage

blib/lib/Crypt/Spritz.pm
Criterion Covered Total %
statement 3 3 100.0
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 4 4 100.0


line stmt bran cond sub pod time code
1             =head1 NAME
2              
3             Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
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 $cipher = new Crypt::Spritz::Cipher $key, $iv;
16             $ciphertext = $cipher->encrypt ($cleartext);
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;
43              
44             =head1 DESCRIPTION
45              
46             This module implements the Spritz spongelike function (with N=256), the
47             spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
48              
49             Its strength is extreme versatility (you get a stream cipher, a hash, a
50             MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
51             more) and extremely simple and small code (encryption and authentication
52             can be had in 1KB of compiled code on amd64, which isn't an issue for most
53             uses in Perl, but is useful in embedded situations, or e.g. when doing
54             crypto using javascript in a browser and communicating with Perl).
55              
56             Its weakness is its relatively slow speed (encryption is a few times
57             slower than RC4 or AES, hashing many times slower than SHA-3, although
58             this might be reversed on an 8-bit-cpu) and the fact that it is totally
59             unproven in the field (as of this writing, the cipher was just a few
60             months old), so it can't be called production-ready.
61              
62             All the usual caveats regarding stream ciphers apply - never repeat your
63             key, never repeat your nonce and so on - you should have some basic
64             understanding of cryptography before using this cipher in your own
65             designs.
66              
67             The Spritz base class is not meant for end users. To make usage simpler
68             and safer, a number of convenience classes are provided for typical
69             end-user tasks:
70              
71             random number generation - Crypt::Spritz::PRNG
72             hashing - Crypt::Spritz::Hash
73             message authentication - Crypt::Spritz::MAC
74             encryption - Crypt::Spritz::Cipher::XOR
75             encryption - Crypt::Spritz::Cipher
76             authenticated encryption - Crypt::Spritz::AEAD::XOR
77             authenticated encryption - Crypt::Spritz::AEAD
78              
79             =cut
80              
81             package Crypt::Spritz;
82              
83 1     1   1181 use XSLoader;
  1         3  
  1         437  
84              
85             $VERSION = 0.2;
86              
87             XSLoader::load __PACKAGE__, $VERSION;
88              
89             @Crypt::Spritz::ISA = Crypt::Spritz::Base::;
90              
91             @Crypt::Spritz::Hash::ISA =
92             @Crypt::Spritz::PRNG::ISA =
93             @Crypt::Spritz::Cipher::ISA =
94             @Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
95              
96             @Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
97              
98             @Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::;
99             @Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
100              
101             sub Crypt::Spritz::Cipher::keysize () { 32 }
102             sub Crypt::Spritz::Cipher::blocksize () { 64 }
103              
104             *Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
105              
106             *Crypt::Spritz::Hash::add =
107             *Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
108              
109             *Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
110              
111             *Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
112             *Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
113              
114             *Crypt::Spritz::AEAD::associated_data =
115             *Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
116              
117              
118             =head2 THE Crypt::Spritz CLASS
119              
120             This class implements most of the Spritz primitives. To use it effectively
121             you should understand them, for example, by reading the L
122             paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
123             pp. 5-6.
124              
125             The Spritz primitive corresponding to the Perl method is given as
126             comment.
127              
128             =over 4
129              
130             =item $spritz = new Crypt::Spritz # InitializeState
131              
132             Creates and returns a new, initialised Spritz state.
133              
134             =item $spritz->init # InitializeState
135              
136             Initialises the Spritz state again, throwing away the previous state.
137              
138             =item $another_spritz = $spritz->clone
139              
140             Make an exact copy of the spritz state. This method can be called on all
141             of the objects in this module, but is documented separately to give some
142             cool usage examples.
143              
144             =item $spritz->update # Update
145              
146             =item $spritz->whip ($r) # Whip
147              
148             =item $spritz->crush # Crush
149              
150             =item $spritz->shuffle # Shuffle
151              
152             =item $spritz->output # Output
153              
154             Calls the Spritz primitive ovf the same name - these are not normally
155             called manually.
156              
157             =item $spritz->absorb ($I) # Absorb
158              
159             Absorbs the given data into the state (usually used for key material,
160             nonces, IVs messages to be hashed and so on).
161              
162             =item $spritz->absorb_stop # AbsorbStop
163              
164             Absorbs a special stop symbol - this is usually used as delimiter between
165             multiple strings to be absorbed, to thwart extension attacks.
166              
167             =item $spritz->absorb_and_stop ($I)
168              
169             This is a convenience function that simply calls C followed by
170             C.
171              
172             =item $octet = $spritz->drip # Drip
173              
174             Squeezes out a single byte from the state.
175              
176             =item $octets = $spritz->squeeze ($len) # Squeeze
177              
178             Squeezes 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              
185             This class implements a Pseudorandom Number Generatore (B),
186             sometimes also called a Deterministic Random Bit Generator (B). In
187             fact, it is even cryptographically secure, making it a B.
188              
189             Typical usage as a random number generator involves creating a PRNG
190             object with a seed of your choice, and then fetching randomness via
191             C:
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              
201             Typical usage as a cryptographically secure random number generator is to
202             feed in some secret entropy (32 octets/256 bits are commonly considered
203             enough), for example from C or C, and then
204             generate 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              
226             Creates a new random number generator object. If C<$seed> is given, then
227             the C<$seed> is added to the internal state as if by a call to C.
228              
229             =item $prng->add ($entropy)
230              
231             Adds entropy to the internal state, thereby hopefully making it harder
232             to guess. Good sources for entropy are irregular hardware events, or
233             randomness provided by C or C.
234              
235             The design of the Spritz PRNG should make it strong against attacks where
236             the attacker controls all the entropy, so it should be safe to add entropy
237             from untrusted sources - more is better than less if you need a CSPRNG.
238              
239             For use as PRNG, of course, this matters very little.
240              
241             =item $octets = $prng->get ($length)
242              
243             Generates and returns C<$length> random octets as a string.
244              
245             =back
246              
247              
248             =head2 THE Crypt::Spritz::Hash CLASS
249              
250             This implements the Spritz digest/hash algorithm. It works very similar to
251             other digest modules on CPAN, such as L.
252              
253             Typical 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              
270             Creates a new hasher object.
271              
272             =item $hasher->add ($data)
273              
274             Adds data to be hashed into the hasher state. It doesn't matter whether
275             you 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              
279             Calculates a hash digest of the given length and return it. The object
280             cannot sensibly be used for further hashing afterwards.
281              
282             Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
283             digests, respectively.
284              
285             =item $another_hasher = $hasher->clone
286              
287             Make an exact copy of the hasher state. This can be useful to generate
288             incremental hashes, for example.
289              
290             Example: generate a hash for the data already fed into the hasher, by keeping
291             the original hasher for further C calls and calling C on a C.
292              
293             my $intermediate_hash = $hasher->clone->finish;
294              
295             Example: hash 64KiB of data, and generate a hash after every kilobyte that
296             is 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              
309             These kind of intermediate hashes are sometimes used in communications
310             protocols to protect the integrity of the data incrementally, e.g. to
311             detect errors early, while still having a complete hash at the end of a
312             transfer.
313              
314             =back
315              
316              
317             =head2 THE Crypt::Spritz::MAC CLASS
318              
319             This implements the Spritz Message Authentication Code algorithm. It works
320             very similar to other digest modules on CPAN, such as L, but
321             implements an authenticated digest (like L).
322              
323             I means that, unlike L, where
324             everybody can verify and recreate the hash value for some data, with a
325             MAC, knowledge of the (hopefully) secret key is required both to create
326             and to verify the digest.
327              
328             Typical use for hashing is almost the same as with L,
329             except 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              
346             Creates a new hasher object. The C<$key> can be of any length, but 16 and
347             32 (128 and 256 bit) are customary.
348              
349             =item $hasher->add ($data)
350              
351             Adds data to be hashed into the hasher state. It doesn't matter whether
352             you 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              
356             Calculates a message code of the given length and return it. The object
357             cannot sensibly be used for further hashing afterwards.
358              
359             Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
360             digests, respectively.
361              
362             =item $another_hasher = $hasher->clone
363              
364             Make an exact copy of the hasher state. This can be useful to
365             generate incremental macs, for example.
366              
367             See the description for the C method for some
368             examples.
369              
370             =back
371              
372              
373             =head2 THE Crypt::Spritz::Cipher::XOR CLASS
374              
375             This class implements stream encryption/decryption. It doesn't implement
376             the standard Spritz encryption but the XOR variant (called B
377             in the paper).
378              
379             The XOR variant should be as secure as the standard variant, but
380             doesn't have separate encryption and decryaption functions, which saves
381             codesize. IT is not compatible with standard Spritz encryption, however -
382             drop me a note if you want that implemented as well.
383              
384             Typical use for encryption I decryption (code is identical for
385             decryption, you simply pass the encrypted data to C):
386              
387             # create a cipher - $salt can be a random string you send
388             # with your message, in clear, a counter (best), or empty if
389             # you only want to encrypt one message with the given key.
390             # 16 or 32 octets are typical sizes for the key, for the salt,
391             # use whatever you need to give a unique salt for every
392             # message you encrypt with the same key.
393              
394             my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;
395              
396             # encrypt a message in one or more calls to crypt
397              
398             my $encrypted;
399              
400             $encrypted .= $cipher->crypt ("This is");
401             $encrypted .= $cipher->crypt ("all very");
402             $encrypted .= $cipher->crypt ("secret");
403              
404             # that's all
405              
406             =over 4
407              
408             =item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
409              
410             Creates a new cipher object usable for encryption and decryption. The
411             C<$key> must be provided, the initial vector C<$IV> is optional.
412              
413             Both C<$key> and C<$IV> can be of any length. Typical lengths for the
414             C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
415             be long enough to distinguish repeated uses of tghe same key.
416              
417             =item $encrypted = $cipher->crypt ($cleartext)
418              
419             =item $cleartext = $cipher->crypt ($encrypted)
420              
421             Encrypt or decrypt a piece of a message. This can be called as many times
422             as you want, and the message can be split into as few or many pieces as
423             required without affecting the results.
424              
425             =item $cipher->crypt_inplace ($cleartext_or_ciphertext)
426              
427             Same as C, except it I.
428              
429             =item $another_cipher = $cipher->clone
430              
431             Make an exact copy of the cipher state. This can be useful to cache states
432             for reuse later, for example, to avoid expensive key setups.
433              
434             While there might be use cases for this feature, it makes a lot more sense
435             for C and C, as they allow
436             you to specify the IV/nonce separately.
437              
438             =item $constant_32 = $cipher->keysize
439              
440             =item $constant_64 = $cipher->blocksize
441              
442             These methods are provided for L compatibility and simply
443             return C<32> and C<64>, respectively.
444              
445             Note that it is pointless to use Spritz with L, as Spritz is
446             not a block cipher and already provides an appropriate mode.
447              
448             =back
449              
450              
451             =head2 THE Crypt::Spritz::Cipher CLASS
452              
453             This class is pretty much the same as the C
454             class, with two differences: first, it implements the "standard" Spritz
455             encryption algorithm, and second, while this variant is easier to analyze
456             mathematically, there is little else to recommend it for, as it is slower,
457             and requires lots of code duplication code.
458              
459             So unless you need to be compatible with another implementation that does
460             not offer the XOR variant, stick to C.
461              
462             All the methods from C are available, except
463             C, which has been replaced by separate C and C
464             methods:
465              
466             =over 4
467              
468             =item $encrypted = $cipher->encrypt ($cleartext)
469              
470             =item $cleartext = $cipher->decrypt ($encrypted)
471              
472             Really the same as C, except you need separate
473             calls and code for encryption and decryption.
474              
475             =back
476              
477              
478             =head2 THE Crypt::Spritz::AEAD::XOR CLASS
479              
480             This is the most complicated class - it combines encryption and
481             message authentication into a single "authenticated encryption
482             mode". It is similar to using both L and
483             L, but makes it harder to make mistakes in combining
484             them.
485              
486             You can additionally provide cleartext data that will not be encrypted or
487             decrypted, but that is nevertheless authenticated using the MAC, which
488             is why this mode is called I, I
489             Associated Data>. Associated data is usually used to any header data that
490             is in cleartext, but should nevertheless be authenticated.
491              
492             This implementation implements the XOR variant. Just as with
493             L, this means it is not compatible with
494             the standard mode, but uses less code and doesn't distinguish between
495             encryption and decryption.
496              
497             Typical usage is as follows:
498              
499             # create a new aead object
500             # you use one object per message
501             # key length customarily is 16 or 32
502             my $aead = new Crypt::Spritz::AEAD::XOR $key;
503              
504             # now you must feed the nonce. if you do not need a nonce,
505             # you can provide the empty string, but you have to call it
506             # after creating the object, before calling associated_data.
507             # the nonce must be different for each usage of the $key.
508             # a counter of some kind is good enough.
509             # reusing a nonce with the same key completely
510             # destroys security!
511             $aead->nonce ($counter);
512              
513             # then you must feed any associated data you have. if you
514             # do not have associated cleartext data, you can provide the empty
515             # string, but you have to call it after nonce and before crypt.
516             $aead->associated_data ($header);
517              
518             # next, you call crypt one or more times with your data
519             # to be encrypted (opr decrypted).
520             # all except the last call must use a length that is a
521             # multiple of 64.
522             # the last block can have any length.
523             my $encrypted;
524              
525             $encrypted .= $aead->crypt ("1" x 64);
526             $encrypted .= $aead->crypt ("2" x 64);
527             $encrypted .= $aead->crypt ("3456");
528              
529             # finally you can calculate the MAC for all of the above
530             my $mac = $aead->finish;
531              
532             =over 4
533              
534             =item $aead = new Crypt::Spritz::AEAD::XOR $key
535              
536             Creates a new cipher object usable for encryption and decryption.
537              
538             The C<$key> can be of any length. Typical lengths for the C<$key> are 16
539             (128 bit) or 32 (256 bit).
540              
541             After creation, you have to call C next.
542              
543             =item $aead->nonce ($nonce)
544              
545             Provide the nonce value (nonce means "value used once"), a value the is
546             unique between all uses with the same key. This method I be called
547             I C and I C.
548              
549             If you only ever use a given key once, you can provide an empty nonce -
550             but you still have to call the method.
551              
552             Common strategies to provide a nonce are to implement a persistent counter
553             or to generate a random string of sufficient length to guarantee that it
554             differs each time.
555              
556             The problem with counters is that you might get confused and forget
557             increments, and thus reuse the same sequence number. The problem with
558             random strings i that your random number generator might be hosed and
559             generate the same randomness multiple times (randomness can be very hard
560             to get especially on embedded devices).
561              
562             =item $aead->associated_data ($data)
563              
564             Provide the associated data (cleartext data to be authenticated but not
565             encrypted). This method I be called I C and I
566             C.
567              
568             If you don't have any associated data, you can provide an empty string -
569             but you still have to call the method.
570              
571             Associated data is typically header data - data anybody is allowed to
572             see in cleartext, but that should nevertheless be protected with an
573             authentication code. Typically such data is used to identify where to
574             forward a message to, how to find the key to decrypt the message or in
575             general how to interpret the encrypted part of a message.
576              
577             =item $encrypted = $cipher->crypt ($cleartext)
578              
579             =item $cleartext = $cipher->crypt ($encrypted)
580              
581             Encrypt or decrypt a piece of a message. This can be called as many times
582             as you want, and the message can be split into as few or many pieces as
583             required without affecting the results, with one exception: All except the
584             last call to C needs to pass in a multiple of C<64> octets. The
585             last call to C does not have this limitation.
586              
587             =item $cipher->crypt_inplace ($cleartext_or_ciphertext)
588              
589             Same as C, except it I.
590              
591             =item $another_cipher = $cipher->clone
592              
593             Make an exact copy of the cipher state. This can be useful to cache states
594             for reuse later, for example, to avoid expensive key setups.
595              
596             Example: set up a cipher state with a key, then clone and use it to
597             encrypt messages with different nonces.
598              
599             my $cipher = new Crypt::Spritz::AEAD::XOR $key;
600              
601             my $message_counter;
602              
603             for my $message ("a", "b", "c") {
604             my $clone = $cipher->clone;
605             $clone->nonce (pack "N", ++$message_counter);
606             $clone->associated_data ("");
607             my $encrypted = $clone->crypt ($message);
608             ...
609             }
610              
611             =back
612              
613              
614             =head2 THE Crypt::Spritz::AEAD CLASS
615              
616             This class is pretty much the same as the C
617             class, with two differences: first, it implements the "standard" Spritz
618             encryption algorithm, and second, while this variant is easier to analyze
619             mathematically, there is little else to recommend it for, as it is slower,
620             and requires lots of code duplication code.
621              
622             So unless you need to be compatible with another implementation that does
623             not offer the XOR variant, stick to C.
624              
625             All the methods from C are available, except
626             C, which has been replaced by separate C and C
627             methods:
628              
629             =over 4
630              
631             =item $encrypted = $cipher->encrypt ($cleartext)
632              
633             =item $cleartext = $cipher->decrypt ($encrypted)
634              
635             Really the same as C, except you need separate
636             calls and code for encryption and decryption, but you have the same
637             limitations on usage.
638              
639             =back
640              
641              
642             =head1 SEE ALSO
643              
644             L.
645              
646             =head1 SECURITY CONSIDERATIONS
647              
648             I also cannot give any guarantees for security, Spritz is a very new
649             cryptographic algorithm, and when this module was written, almost
650             completely unproven.
651              
652             =head1 AUTHOR
653              
654             Marc Lehmann
655             http://software.schmorp.de/pkg/Crypt-Spritz
656              
657             =cut
658              
659             1;
660