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