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.1 by root, Sat Jan 10 03:15:59 2015 UTC vs.
Revision 1.5 by root, Sat Jan 10 07:19:24 2015 UTC

1=head1 NAME 1=head1 NAME
2 2
3Crypt::Spritz - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng module 3Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use Crypt::Spritz; 7 use Crypt::Spritz;
8 8
9 # keysize() is 32, but spritz accepts any key size 9 # see the commented examples in their respective classes,
10 # blocksize() is 16, but cna be anything 10 # but basically
11 11
12 $cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC; 12 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
13
14 $crypted = $cipher->encrypt($plaintext); 13 $ciphertext = $cipher->crypt ($cleartext);
15 # - OR - 14
16 $plaintext = $cipher->decrypt($crypted); 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);
17 32
18=head1 DESCRIPTION 33=head1 DESCRIPTION
19 34
20This module implements the spritz spongelike function. 35This module implements the Spritz spongelike function (with N=256), the
36spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
21 37
22Although it is C<Crypt::CBC> compliant you usually gain nothing by using 38Its strength is extreme versatility (you get a stream cipher, a hash, a
23that module (except generality, which is often a good thing), since 39MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
24C<Crypt::Twofish2> can work in either ECB or CBC mode itself. 40more) and extremely simple and small code (encryption and authentication
41can be had in 1KB of compiled code on amd64, which isn't an issue for most
42uses in Perl, but is useful in embedded situations, or e.g. when doing
43crypto using javascript in a browser and communicating with Perl).
44
45Its weakness is its relatively slow speed (encryption is a few times
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
48unproven in the field (as of this writing, the cipher was just a few
49months old), so it can't be called production-ready.
50
51All the usual caveats regarding stream ciphers apply - never repeat
52your key, never repeat your nonce and so on - you should have some basic
53understanding of cryptography before using this cipher in your own
54designs.
55
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
58end-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
68package Crypt::Spritz;
69
70use XSLoader;
71
72$VERSION = '0.0';
73
74XSLoader::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
88sub Crypt::Spritz::Cipher::keysize () { 32 }
89sub 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
107This class implements most of the Spritz primitives. To use it effectively
108you should understand them, for example, by reading the L<Spritz
109paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
110pp. 5-6.
111
112The Spritz primitive corresponding to the Perl method is given as
113comment.
25 114
26=over 4 115=over 4
27 116
117=item $spritz = new Crypt::Spritz # InitializeState
118
119Creates and returns a new, initialised Spritz state.
120
121=item $spritz->init # InitializeState
122
123Initialises 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
135Calls the Spritz primitive ovf the same name - these are not normally
136called manually.
137
138=item $spritz->absorb ($I) # Absorb
139
140Absorbs the given data into the state (usually used for key material, nonces, IVs
141messages to be hashed and so on).
142
143=item $spritz->absorb_stop # AbsorbStop
144
145Absorbs a special stop symbol - this is usually used as delimiter between
146multiple strings to be absorbed, to thwart extension attacks.
147
148=item $spritz->absorb_and_stop ($I)
149
150This is a convenience function that simply calls C<absorb> followed by
151C<absorb_stop>.
152
153=item $octet = $spritz->drip # Drip
154
155Squeezes out a single byte from the state.
156
157=item $octets = $spritz->squeeze ($len) # Squeeze
158
159Squeezes 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
166This class implements stream encryption/decryption. It doesn't implement
167the standard Spritz encryption but the XOR variant (called B<spritz-xor>
168in the paper).
169
170The XOR variant should be as secure as the standard variant, but
171doesn't have separate encryption and decryaption functions, which saves
172codesize. IT is not compatible with standard Spritz encryption, however -
173drop me a note if you want that implemented as well.
174
175Typical use for encryption I<and> decryption (code is identical for
176decryption, 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
201Creates a new cipher object usable for encryption and decryption. The
202C<$key> must be provided, the initial vector C<$IV> is optional.
203
204Both C<$key> and C<$IV> can be of any length. Typical lengths for the
205C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
206be 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
212Encrypt or decrypt a piece of a message. This cna be called as many times
213as you want, and the message can be split into as few or many pieces as
214required without affecting the results.
215
216=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
217
218Same 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
224These methods are provided for L<Crypt::CBC> compatibility and simply
225return C<32> and C<64>, respectively.
226
227Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
228not a block cipher and already provides an appropriate mode.
229
230=back
231
232
233=head2 THE Crypt::Spritz::Hash CLASS
234
235This implements the Spritz digest/hash algorithm. It works very similar to
236other digest modules on CPAN, such as L<Digest::SHA3>.
237
238Typical 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
255Creates a new hasher object.
256
257=item $hasher->add ($data)
258
259Adds data to be hashed into the hasher state. It doesn't matter whether
260you 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
264Calculates a hash digest of the given length and return it. The object
265cannot sensibly be used for further hashing afterwards.
266
267Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
268digests, respectively.
269
270=back
271
272
273=head2 THE Crypt::Spritz::MAC CLASS
274
275This implements the Spritz Message Authentication Code algorithm. It works
276very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
277implements an authenticated digest (like L<Digest::HMAC>).
278
279I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
280everybody can verify and recreate the hash value for some data, with a
281MAC, knowledge of the (hopefully) secret key is required both to create
282and to verify the digest.
283
284Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
285except 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
302Creates a new hasher object. The C<$key> can be of any length, but 16 and
30332 (128 and 256 bit) are customary.
304
305=item $hasher->add ($data)
306
307Adds data to be hashed into the hasher state. It doesn't matter whether
308you 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
312Calculates a message code of the given length and return it. The object
313cannot sensibly be used for further hashing afterwards.
314
315Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
316digests, respectively.
317
318=back
319
320
321=head2 THE Crypt::Spritz::AEAD::XOR CLASS
322
323This is the most complicated class - it combines encryption and
324message authentication into a single "authenticated encryption
325mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
326L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
327them.
328
329You can additionally provide cleartext data that will not be encrypted or
330decrypted, but that is nevertheless authenticated using the MAC, which
331is why this mode is called I<AEAD>, I<Authenticated Encryption with
332Associated Data>. Associated data is usually used to any header data that
333is in cleartext, but should nevertheless be authenticated.
334
335This implementation implements the XOR variant. Just as with
336L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
337the standard mode, but uses less code and doesn't distinguish between
338encryption and decryption.
339
340Typical 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
379Creates a new cipher object usable for encryption and decryption.
380
381The C<$key> can be of any length. Typical lengths for the C<$key> are 16
382(128 bit) or 32 (256 bit).
383
384After creation, you have to call C<nonce> next.
385
386=item $aead->nonce ($nonce)
387
388Provide the nonce value (nonce means "value used once"), a value the is
389unique between all uses with the same key. This method I<must> be called
390I<after> C<new> and I<before> C<associated_data>.
391
392If you only ever use a given key once, you can provide an empty nonce -
393but you still have to call the method.
394
395Common strategies to provide a nonce are to implement a persistent counter
396or to generate a random string of sufficient length to guarantee that it
397differs each time.
398
399The problem with counters is that you might get confused and forget
400increments, and thus reuse the same sequence number. The problem with
401random strings i that your random number generator might be hosed and
402generate the same randomness multiple times (randomness can be very hard
403to get especially on embedded devices).
404
405=item $aead->associated_data ($data)(
406
407Provide the associated data (cleartext data to be authenticated but not
408encrypted). This method I<must> be called I<after> C<nonce> and I<before>
409C<crypt>.
410
411If you don't have any associated data, you can provide an empty string -
412but you still have to call the method.
413
414Associated data is typically header data - data anybody is allowed to
415see in cleartext, but that should nevertheless be protected with an
416authentication code. Typically such data is used to identify where to
417forward a message to, how to find the key to decrypt the message or in
418general how to interpret the encrypted part of a message.
419
420=item $encrypted = $cipher->crypt ($cleartext)
421
422=item $cleartext = $cipher->crypt ($encrypted)
423
424Encrypt or decrypt a piece of a message. This cna be called as many times
425as 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
427last 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.
429
430=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
431
432Same as C<crypt>, except it I<modifies the argument in-place>.
433
434=back
435
436
437=head2 THE Crypt::Spritz::PRNG CLASS
438
439This class implements a Pseudorandom Number Generatore (B<PRNG>),
440sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
441fact, it is even cryptographically secure, making it a B<CSPRNG>.
442
443Typical usage as a random number generator involves creating a PRNG
444object with a seed of your choice, and then fetching randomness via
445C<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
455Typical usage as a cryptographically secure random number generator is to
456feed in some secret entropy (32 octets/256 bits are commonly considered
457enough), for example from C</dev/random> or C</dev/urandom>, and then
458generate 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
480Creates a new random number generator object. If C<$seed> is given, then
481the C<$seed> is added to the internal state as if by a call to C<add>.
482
483=item $prng->add ($entropy)
484
485Adds entropy to the internal state, thereby hopefully making it harder
486to guess. Good sources for entropy are irregular hardware events, or
487randomness provided by C</dev/urandom> or C</dev/random>.
488
489The design of the Spritz PRNG should make it strong against attacks where
490the attacker controls all the entropy, so it should be safe to add entropy
491from untrusted sources - more is better than less if you need a CSPRNG.
492
493For use as PRNG, of course, this matters very little.
494
495=item $octets = $prng->get ($length)
496
497Generates and returns C<$length> random octets as a string.
498
499=back
500
501
502=head1 SEE ALSO
503
504L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
505
506=head1 SECURITY CONSIDERATIONS
507
508I also cannot give any guarantees for security, Spritz is a very new
509cryptographic algorithm, and when this module was written, almost
510completely unproven.
511
512=head1 AUTHOR
513
514 Marc Lehmann <schmorp@schmorp.de>
515 http://software.schmorp.de/pkg/Crypt-Spritz
516
28=cut 517=cut
29 518
30package Crypt::Spritz;
31
32use XSLoader;
33
34$VERSION = '0.0';
35
36XSLoader::load __PACKAGE__, $VERSION;
37
38@Crypt::Spritz::CipherBase::ISA =
39@Crypt::Spritz::HASH::ISA =
40@Crypt::Spritz::PRNG::ISA = Crypt::Spritz::;
41
42@Crypt::Spritz::MAC::ISA = Crypt::Spritz::HASH::;
43
44@Crypt::Spritz::CIPHER::XOR::ISA =
45@Crypt::Spritz::CIPHER::XOR::ISA =
46@Crypt::Spritz::AEAD::ISA =
47@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::CipherBase::;
48
49sub Crypt::Spritz::CipherBase::keysize () { 32 }
50sub Crypt::Spritz::CipherBase::blocksize () { 64 }
51
52*Crypt::Spritz::HASH::add =
53*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
54
55*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
56
57*Crypt::Spritz::AEAD::XOR::finish =
58*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::HASH::finish;
59
60*Crypt::Spritz::AEAD::XOR::associated_data =
61*Crypt::Spritz::AEAD::associated_data =
62*Crypt::Spritz::AEAD::XOR::nonce =
63*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absborb_and_stop;
64
65=item keysize
66
67Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually
68supports keylengths of 16, 24 or 32 bytes, but there is no way to
69communicate this to C<Crypt::CBC>.
70
71=item blocksize
72
73The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat
74unique. It is also the reason I need this module myself ;)
75
76=item $cipher = new $key [, $mode]
77
78Create a new C<Crypt::Twofish2> cipher object with the given key (which
79must be 128, 192 or 256 bits long). The additional C<$mode> argument is
80the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the
81default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC>
82does) or C<MODE_CFB1> (1-bit cipher feedback mode).
83
84ECB mode is very insecure (read a book on cryptography if you don't know
85why!), so you should probably use CBC mode. CFB1 mode is not tested and is
86most probably broken, so do not try to use it.
87
88In ECB mode you can use the same cipher object to encrypt and decrypt
89data. However, every change of "direction" causes an internal reordering
90of key data, which is quite slow, so if you want ECB mode and
91encryption/decryption at the same time you should create two seperate
92C<Crypt::Twofish2> objects with the same key.
93
94In CBC mode you have to use seperate objects for encryption/decryption in
95any case.
96
97The C<MODE_*>-constants are not exported by this module, so you must
98specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
99
100=item $cipher->encrypt($data)
101
102Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16
103bytes), otherwise this function will croak. Apart from that, it can be of
104(almost) any length.
105
106=item $cipher->decrypt($data)
107
108The pendant to C<encrypt> in that it I<de>crypts data again.
109
110=back
111
112=head1 SEE ALSO
113
114L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
115
116=head1 SECURITY CONSIDERATIONS
117
118I also cannot guarantee for security.
119
120=head1 AUTHOR
121
122 Marc Lehmann <schmorp@schmorp.de>
123 http://home.schmorp.de/
124
125 The actual twofish encryption is written in horribly microsoft'ish looking
126 almost ansi-c by Doug Whiting.
127
128=cut
129
1301; 5191;
131 520

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines