1 |
NAME |
2 |
Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module |
3 |
|
4 |
SYNOPSIS |
5 |
use Crypt::Spritz; |
6 |
|
7 |
# see the commented examples in their respective classes, |
8 |
# but basically |
9 |
|
10 |
my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; |
11 |
$ciphertext = $cipher->crypt ($cleartext); |
12 |
|
13 |
my $hasher = new Crypt::Spritz::Hash; |
14 |
$hasher->add ($data); |
15 |
$digest = $hasher->finish; |
16 |
|
17 |
my $hasher = new Crypt::Spritz::MAC $key; |
18 |
$hasher->add ($data); |
19 |
$mac = $hasher->finish; |
20 |
|
21 |
my $aead = new Crypt::Spritz::AEAD::XOR $key; |
22 |
$aead->nonce ($counter); |
23 |
$aead->associated_data ($header); |
24 |
$ciphertext = $aead->crypt ($cleartext); |
25 |
$mac = $aead->mac; |
26 |
|
27 |
my $prng = new Crypt::Spritz::PRNG $entropy; |
28 |
$prng->add ($additional_entropy); |
29 |
$keydata = $prng->get (32); |
30 |
|
31 |
DESCRIPTION |
32 |
This module implements the Spritz spongelike function (with N=256), the |
33 |
spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. |
34 |
|
35 |
Its strength is extreme versatility (you get a stream cipher, a hash, a |
36 |
MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and |
37 |
more) and extremely simple and small code (encryption and authentication |
38 |
can be had in 1KB of compiled code on amd64, which isn't an issue for |
39 |
most uses in Perl, but is useful in embedded situations, or e.g. when |
40 |
doing crypto using javascript in a browser and communicating with Perl). |
41 |
|
42 |
Its weakness is its relatively slow speed (encryption is a few times |
43 |
slower than RC4 or AES, hashing many times slower than SHA-3, although |
44 |
this might be reversed on an 8-bit-cpu) and the fact that it is totally |
45 |
unproven in the field (as of this writing, the cipher was just a few |
46 |
months old), so it can't be called production-ready. |
47 |
|
48 |
All the usual caveats regarding stream ciphers apply - never repeat your |
49 |
key, never repeat your nonce and so on - you should have some basic |
50 |
understanding of cryptography before using this cipher in your own |
51 |
designs. |
52 |
|
53 |
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 |
55 |
end-user tasks: |
56 |
|
57 |
encryption - Crypt::Spritz::Cipher::XOR |
58 |
hashing - Crypt::Spritz::Hash |
59 |
message authentication - Crypt::Spritz::MAC |
60 |
authenticated encryption - Crypt::Spritz::AEAD::XOR |
61 |
random number generation - Crypt::Spritz::PRNG |
62 |
|
63 |
THE Crypt::Spritz CLASS |
64 |
This class implements most of the Spritz primitives. To use it |
65 |
effectively you should understand them, for example, by reading the |
66 |
"http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper, |
67 |
especially pp. 5-6. |
68 |
|
69 |
The Spritz primitive corresponding to the Perl method is given as |
70 |
comment. |
71 |
|
72 |
$spritz = new Crypt::Spritz # InitializeState |
73 |
Creates and returns a new, initialised Spritz state. |
74 |
|
75 |
$spritz->init # InitializeState |
76 |
Initialises the Spritz state again, throwing away the previous |
77 |
state. |
78 |
|
79 |
$spritz->update # Update |
80 |
$spritz->whip ($r) # Whip |
81 |
$spritz->crush # Crush |
82 |
$spritz->shuffle # Shuffle |
83 |
$spritz->output # Output |
84 |
Calls the Spritz primitive ovf the same name - these are not |
85 |
normally called manually. |
86 |
|
87 |
$spritz->absorb ($I) # Absorb |
88 |
Absorbs the given data into the state (usually used for key |
89 |
material, nonces, IVs messages to be hashed and so on). |
90 |
|
91 |
$spritz->absorb_stop # AbsorbStop |
92 |
Absorbs a special stop symbol - this is usually used as delimiter |
93 |
between multiple strings to be absorbed, to thwart extension |
94 |
attacks. |
95 |
|
96 |
$spritz->absorb_and_stop ($I) |
97 |
This is a convenience function that simply calls "absorb" followed |
98 |
by "absorb_stop". |
99 |
|
100 |
$octet = $spritz->drip # Drip |
101 |
Squeezes out a single byte from the state. |
102 |
|
103 |
$octets = $spritz->squeeze ($len) # Squeeze |
104 |
Squeezes out the requested number of bytes from the state - this is |
105 |
usually |
106 |
|
107 |
THE Crypt::Spritz::Cipher::XOR CLASS |
108 |
This class implements stream encryption/decryption. It doesn't implement |
109 |
the standard Spritz encryption but the XOR variant (called spritz-xor in |
110 |
the paper). |
111 |
|
112 |
The XOR variant should be as secure as the standard variant, but doesn't |
113 |
have separate encryption and decryaption functions, which saves |
114 |
codesize. IT is not compatible with standard Spritz encryption, however |
115 |
- drop me a note if you want that implemented as well. |
116 |
|
117 |
Typical use for encryption *and* decryption (code is identical for |
118 |
decryption, you simply pass the encrypted data to "crypt"): |
119 |
|
120 |
# create a cipher - $salt can be a random string you send |
121 |
# with your message, in clear, a counter (best), or empty if |
122 |
# you only want to encrypt one message with the given key. |
123 |
# 16 or 32 octets are typical sizes for the key, for the salt, |
124 |
# use whatever you need to give a unique salt for every |
125 |
# message you encrypt with the same key. |
126 |
|
127 |
my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt; |
128 |
|
129 |
# encrypt a message in one or more calls to crypt |
130 |
|
131 |
my $encrypted; |
132 |
|
133 |
$encrypted .= $cipher->crypt ("This is"); |
134 |
$encrypted .= $cipher->crypt ("all very"); |
135 |
$encrypted .= $cipher->crypt ("secret"); |
136 |
|
137 |
# that's all |
138 |
|
139 |
$cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv] |
140 |
Creates a new cipher object usable for encryption and decryption. |
141 |
The $key must be provided, the initial vector $IV is optional. |
142 |
|
143 |
Both $key and $IV can be of any length. Typical lengths for the $key |
144 |
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. |
146 |
|
147 |
$encrypted = $cipher->crypt ($cleartext) |
148 |
$cleartext = $cipher->crypt ($encrypted) |
149 |
Encrypt or decrypt a piece of a message. This cna be called as many |
150 |
times as you want, and the message can be split into as few or many |
151 |
pieces as required without affecting the results. |
152 |
|
153 |
$cipher->crypt_inplace ($cleartext_or_ciphertext) |
154 |
Same as "crypt", except it *modifies the argument in-place*. |
155 |
|
156 |
$constant_32 = $cipher->keysize |
157 |
$constant_64 = $cipher->blocksize |
158 |
These methods are provided for Crypt::CBC compatibility and simply |
159 |
return 32 and 64, respectively. |
160 |
|
161 |
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. |
163 |
|
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 |
197 |
This implements the Spritz Message Authentication Code algorithm. It |
198 |
works very similar to other digest modules on CPAN, such as |
199 |
Digest::SHA3, but implements an authenticated digest (like |
200 |
Digest::HMAC). |
201 |
|
202 |
*Authenticated* means that, unlike Crypt::Spritz::Hash, where everybody |
203 |
can verify and recreate the hash value for some data, with a MAC, |
204 |
knowledge of the (hopefully) secret key is required both to create and |
205 |
to verify the digest. |
206 |
|
207 |
Typical use for hashing is almost the same as with Crypt::Spritz::MAC, |
208 |
except a key (typically 16 or 32 octets) is provided to the constructor: |
209 |
|
210 |
# create hasher object |
211 |
my $hasher = new Crypt::Spritz::Mac $key; |
212 |
|
213 |
# now feed data to be hashed into $hasher |
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 |
|
237 |
THE Crypt::Spritz::AEAD::XOR CLASS |
238 |
This is the most complicated class - it combines encryption and message |
239 |
authentication into a single "authenticated encryption mode". It is |
240 |
similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC, |
241 |
but makes it harder to make mistakes in combining them. |
242 |
|
243 |
You can additionally provide cleartext data that will not be encrypted |
244 |
or decrypted, but that is nevertheless authenticated using the MAC, |
245 |
which is why this mode is called *AEAD*, *Authenticated Encryption with |
246 |
Associated Data*. Associated data is usually used to any header data |
247 |
that is in cleartext, but should nevertheless be authenticated. |
248 |
|
249 |
This implementation implements the XOR variant. Just as with |
250 |
Crypt::Spritz::Cipher::XOR, this means it is not compatible with the |
251 |
standard mode, but uses less code and doesn't distinguish between |
252 |
encryption and decryption. |
253 |
|
254 |
Typical usage is as follows: |
255 |
|
256 |
# create a new aead object |
257 |
# you use one object per message |
258 |
# key length customarily is 16 or 32 |
259 |
my $aead = new Crypt::Spritz::AEAD::XOR $key; |
260 |
|
261 |
# now you must feed the nonce. if you do not need a nonce, |
262 |
# you can provide the empty string, but you have to call it |
263 |
# after creating the object, before calling associated_data. |
264 |
# the nonce must be different for each usage of the $key. |
265 |
# a counter of some kind is good enough. |
266 |
# reusing a nonce with the same key completely |
267 |
# destroys security! |
268 |
$aead->nonce ($counter); |
269 |
|
270 |
# then you must feed any associated data you have. if you |
271 |
# do not have associated cleartext data, you can provide the empty |
272 |
# string, but you have to call it after nonce and before crypt. |
273 |
$aead->associated_data ($header); |
274 |
|
275 |
# next, you call crypt one or more times with your data |
276 |
# to be encrypted (opr decrypted). |
277 |
# all except the last call must use a length that is a |
278 |
# multiple of 64. |
279 |
# the last block can have any length. |
280 |
my $encrypted; |
281 |
|
282 |
$encrypted .= $aead->crypt ("1" x 64); |
283 |
$encrypted .= $aead->crypt ("2" x 64); |
284 |
$encrypted .= $aead->crypt ("3456"); |
285 |
|
286 |
# finally you can calculate the MAC for all of the above |
287 |
my $mac = $aead->finish; |
288 |
|
289 |
$aead = new Crypt::Spritz::AEAD::XOR $key |
290 |
Creates a new cipher object usable for encryption and decryption. |
291 |
|
292 |
The $key can be of any length. Typical lengths for the $key are 16 |
293 |
(128 bit) or 32 (256 bit). |
294 |
|
295 |
After creation, you have to call "nonce" next. |
296 |
|
297 |
$aead->nonce ($nonce) |
298 |
Provide the nonce value (nonce means "value used once"), a value the |
299 |
is unique between all uses with the same key. This method *must* be |
300 |
called *after* "new" and *before* "associated_data". |
301 |
|
302 |
If you only ever use a given key once, you can provide an empty |
303 |
nonce - but you still have to call the method. |
304 |
|
305 |
Common strategies to provide a nonce are to implement a persistent |
306 |
counter or to generate a random string of sufficient length to |
307 |
guarantee that it differs each time. |
308 |
|
309 |
The problem with counters is that you might get confused and forget |
310 |
increments, and thus reuse the same sequence number. The problem |
311 |
with random strings i that your random number generator might be |
312 |
hosed and generate the same randomness multiple times (randomness |
313 |
can be very hard to get especially on embedded devices). |
314 |
|
315 |
$aead->associated_data ($data)( |
316 |
Provide the associated data (cleartext data to be authenticated but |
317 |
not encrypted). This method *must* be called *after* "nonce" and |
318 |
*before* "crypt". |
319 |
|
320 |
If you don't have any associated data, you can provide an empty |
321 |
string - but you still have to call the method. |
322 |
|
323 |
Associated data is typically header data - data anybody is allowed |
324 |
to see in cleartext, but that should nevertheless be protected with |
325 |
an authentication code. Typically such data is used to identify |
326 |
where to forward a message to, how to find the key to decrypt the |
327 |
message or in general how to interpret the encrypted part of a |
328 |
message. |
329 |
|
330 |
$encrypted = $cipher->crypt ($cleartext) |
331 |
$cleartext = $cipher->crypt ($encrypted) |
332 |
Encrypt or decrypt a piece of a message. This cna be called as many |
333 |
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 |
335 |
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 |
337 |
limitation. |
338 |
|
339 |
$cipher->crypt_inplace ($cleartext_or_ciphertext) |
340 |
Same as "crypt", except it *modifies the argument in-place*. |
341 |
|
342 |
THE Crypt::Spritz::PRNG CLASS |
343 |
This class implements a Pseudorandom Number Generatore (PRNG), sometimes |
344 |
also called a Deterministic Random Bit Generator (DRBG). In fact, it is |
345 |
even cryptographically secure, making it a CSPRNG. |
346 |
|
347 |
Typical usage as a random number generator involves creating a PRNG |
348 |
object with a seed of your choice, and then fetching randomness via |
349 |
"get": |
350 |
|
351 |
# create a PRNG object, use a seed string of your choice |
352 |
my $prng = new Crypt::Spritz::PRNG $seed; |
353 |
|
354 |
# now call get as many times as you wish to get binary randomness |
355 |
my $some_randomness = $prng->get (17); |
356 |
my moree_randomness = $prng->get (5000); |
357 |
... |
358 |
|
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 |
|
400 |
SEE ALSO |
401 |
<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. |
402 |
|
403 |
SECURITY CONSIDERATIONS |
404 |
I also cannot give any guarantees for security, Spritz is a very new |
405 |
cryptographic algorithm, and when this module was written, almost |
406 |
completely unproven. |
407 |
|
408 |
AUTHOR |
409 |
Marc Lehmann <schmorp@schmorp.de> |
410 |
http://software.schmorp.de/pkg/Crypt-Spritz |
411 |
|