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