1 | NAME |
1 | NAME |
2 | Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module |
2 | Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family |
3 | |
3 | |
4 | SYNOPSIS |
4 | SYNOPSIS |
5 | use Crypt::Spritz; |
5 | use Crypt::Spritz; |
6 | |
6 | |
7 | # see the commented examples in their respective classes, |
7 | # see the commented examples in their respective classes, |
8 | # but basically |
8 | # but basically |
9 | |
9 | |
10 | my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; |
10 | my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; |
11 | $ciphertext = $cipher->crypt ($cleartext); |
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); |
12 | |
16 | |
13 | my $hasher = new Crypt::Spritz::Hash; |
17 | my $hasher = new Crypt::Spritz::Hash; |
14 | $hasher->add ($data); |
18 | $hasher->add ($data); |
15 | $digest = $hasher->finish; |
19 | $digest = $hasher->finish; |
16 | |
20 | |
17 | my $hasher = new Crypt::Spritz::MAC $key; |
21 | my $hasher = new Crypt::Spritz::MAC $key; |
18 | $hasher->add ($data); |
22 | $hasher->add ($data); |
19 | $mac = $hasher->finish; |
23 | $mac = $hasher->finish; |
|
|
24 | |
|
|
25 | my $prng = new Crypt::Spritz::PRNG $entropy; |
|
|
26 | $prng->add ($additional_entropy); |
|
|
27 | $keydata = $prng->get (32); |
20 | |
28 | |
21 | my $aead = new Crypt::Spritz::AEAD::XOR $key; |
29 | my $aead = new Crypt::Spritz::AEAD::XOR $key; |
22 | $aead->nonce ($counter); |
30 | $aead->nonce ($counter); |
23 | $aead->associated_data ($header); |
31 | $aead->associated_data ($header); |
24 | $ciphertext = $aead->crypt ($cleartext); |
32 | $ciphertext = $aead->crypt ($cleartext); |
25 | $mac = $aead->mac; |
33 | $mac = $aead->mac; |
26 | |
34 | |
27 | my $prng = new Crypt::Spritz::PRNG $entropy; |
35 | my $aead = new Crypt::Spritz::AEAD $key; |
28 | $prng->add ($additional_entropy); |
36 | $aead->nonce ($counter); |
29 | $keydata = $prng->get (32); |
37 | $aead->associated_data ($header); |
|
|
38 | $ciphertext = $aead->encrypt ($cleartext); |
|
|
39 | # $cleartext = $aead->decrypt ($ciphertext); |
|
|
40 | $mac = $aead->mac; |
30 | |
41 | |
31 | DESCRIPTION |
42 | DESCRIPTION |
32 | This module implements the Spritz spongelike function (with N=256), the |
43 | This module implements the Spritz spongelike function (with N=256), the |
33 | spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. |
44 | spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. |
34 | |
45 | |
… | |
… | |
52 | |
63 | |
53 | The Spritz base class is not meant for end users. To make usage simpler |
64 | 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 |
65 | and safer, a number of convenience classes are provided for typical |
55 | end-user tasks: |
66 | end-user tasks: |
56 | |
67 | |
57 | encryption - Crypt::Spritz::Cipher::XOR |
68 | random number generation - Crypt::Spritz::PRNG |
58 | hashing - Crypt::Spritz::Hash |
69 | hashing - Crypt::Spritz::Hash |
59 | message authentication - Crypt::Spritz::MAC |
70 | message authentication - Crypt::Spritz::MAC |
|
|
71 | encryption - Crypt::Spritz::Cipher::XOR |
|
|
72 | encryption - Crypt::Spritz::Cipher |
60 | authenticated encryption - Crypt::Spritz::AEAD::XOR |
73 | authenticated encryption - Crypt::Spritz::AEAD::XOR |
61 | random number generation - Crypt::Spritz::PRNG |
74 | authenticated encryption - Crypt::Spritz::AEAD |
62 | |
75 | |
63 | THE Crypt::Spritz CLASS |
76 | THE Crypt::Spritz CLASS |
64 | This class implements most of the Spritz primitives. To use it |
77 | This class implements most of the Spritz primitives. To use it |
65 | effectively you should understand them, for example, by reading the |
78 | effectively you should understand them, for example, by reading the |
66 | "http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper, |
79 | "http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper, |
… | |
… | |
73 | Creates and returns a new, initialised Spritz state. |
86 | Creates and returns a new, initialised Spritz state. |
74 | |
87 | |
75 | $spritz->init # InitializeState |
88 | $spritz->init # InitializeState |
76 | Initialises the Spritz state again, throwing away the previous |
89 | Initialises the Spritz state again, throwing away the previous |
77 | state. |
90 | state. |
|
|
91 | |
|
|
92 | $another_spritz = $spritz->clone |
|
|
93 | Make an exact copy of the spritz state. This method can be called on |
|
|
94 | all of the objects in this module, but is documented separately to |
|
|
95 | give some cool usage examples. |
78 | |
96 | |
79 | $spritz->update # Update |
97 | $spritz->update # Update |
80 | $spritz->whip ($r) # Whip |
98 | $spritz->whip ($r) # Whip |
81 | $spritz->crush # Crush |
99 | $spritz->crush # Crush |
82 | $spritz->shuffle # Shuffle |
100 | $spritz->shuffle # Shuffle |
… | |
… | |
102 | |
120 | |
103 | $octets = $spritz->squeeze ($len) # Squeeze |
121 | $octets = $spritz->squeeze ($len) # Squeeze |
104 | Squeezes out the requested number of bytes from the state - this is |
122 | Squeezes out the requested number of bytes from the state - this is |
105 | usually |
123 | usually |
106 | |
124 | |
|
|
125 | THE Crypt::Spritz::PRNG CLASS |
|
|
126 | This class implements a Pseudorandom Number Generatore (PRNG), sometimes |
|
|
127 | also called a Deterministic Random Bit Generator (DRBG). In fact, it is |
|
|
128 | even cryptographically secure, making it a CSPRNG. |
|
|
129 | |
|
|
130 | Typical usage as a random number generator involves creating a PRNG |
|
|
131 | object with a seed of your choice, and then fetching randomness via |
|
|
132 | "get": |
|
|
133 | |
|
|
134 | # create a PRNG object, use a seed string of your choice |
|
|
135 | my $prng = new Crypt::Spritz::PRNG $seed; |
|
|
136 | |
|
|
137 | # now call get as many times as you wish to get binary randomness |
|
|
138 | my $some_randomness = $prng->get (17); |
|
|
139 | my moree_randomness = $prng->get (5000); |
|
|
140 | ... |
|
|
141 | |
|
|
142 | Typical usage as a cryptographically secure random number generator is |
|
|
143 | to feed in some secret entropy (32 octets/256 bits are commonly |
|
|
144 | considered enough), for example from "/dev/random" or "/dev/urandom", |
|
|
145 | and then generate some key material. |
|
|
146 | |
|
|
147 | # create a PRNG object |
|
|
148 | my $prng = new Crypt::Spritz::PRNG; |
|
|
149 | |
|
|
150 | # seed some entropy (either via ->add or in the constructor) |
|
|
151 | $prng->add ($some_secret_highly_entropic_string); |
|
|
152 | |
|
|
153 | # now call get as many times as you wish to get |
|
|
154 | # hard to guess binary randomness |
|
|
155 | my $key1 = $prng->get (32); |
|
|
156 | my $key2 = $prng->get (16); |
|
|
157 | ... |
|
|
158 | |
|
|
159 | # for long running programs, it is advisable to |
|
|
160 | # reseed the PRNG from time to time with new entropy |
|
|
161 | $prng->add ($some_more_entropy); |
|
|
162 | |
|
|
163 | $prng = new Crypt::Spritz::PRNG [$seed] |
|
|
164 | Creates a new random number generator object. If $seed is given, |
|
|
165 | then the $seed is added to the internal state as if by a call to |
|
|
166 | "add". |
|
|
167 | |
|
|
168 | $prng->add ($entropy) |
|
|
169 | Adds entropy to the internal state, thereby hopefully making it |
|
|
170 | harder to guess. Good sources for entropy are irregular hardware |
|
|
171 | events, or randomness provided by "/dev/urandom" or "/dev/random". |
|
|
172 | |
|
|
173 | The design of the Spritz PRNG should make it strong against attacks |
|
|
174 | where the attacker controls all the entropy, so it should be safe to |
|
|
175 | add entropy from untrusted sources - more is better than less if you |
|
|
176 | need a CSPRNG. |
|
|
177 | |
|
|
178 | For use as PRNG, of course, this matters very little. |
|
|
179 | |
|
|
180 | $octets = $prng->get ($length) |
|
|
181 | Generates and returns $length random octets as a string. |
|
|
182 | |
|
|
183 | THE Crypt::Spritz::Hash CLASS |
|
|
184 | This implements the Spritz digest/hash algorithm. It works very similar |
|
|
185 | to other digest modules on CPAN, such as Digest::SHA3. |
|
|
186 | |
|
|
187 | Typical use for hashing: |
|
|
188 | |
|
|
189 | # create hasher object |
|
|
190 | my $hasher = new Crypt::Spritz::Hash; |
|
|
191 | |
|
|
192 | # now feed data to be hashed into $hasher |
|
|
193 | # in as few or many calls as required |
|
|
194 | $hasher->add ("Some data"); |
|
|
195 | $hasher->add ("Some more"); |
|
|
196 | |
|
|
197 | # extract the hash - the object is not usable afterwards |
|
|
198 | my $digest = $hasher->finish (32); |
|
|
199 | |
|
|
200 | $hasher = new Crypt::Spritz::Hash |
|
|
201 | Creates a new hasher object. |
|
|
202 | |
|
|
203 | $hasher->add ($data) |
|
|
204 | Adds data to be hashed into the hasher state. It doesn't matter |
|
|
205 | whether you pass your data in in one go or split it up, the hash |
|
|
206 | will be the same. |
|
|
207 | |
|
|
208 | $digest = $hasher->finish ($length) |
|
|
209 | Calculates a hash digest of the given length and return it. The |
|
|
210 | object cannot sensibly be used for further hashing afterwards. |
|
|
211 | |
|
|
212 | Typical digest lengths are 16 and 32, corresponding to 128 and 256 |
|
|
213 | bit digests, respectively. |
|
|
214 | |
|
|
215 | $another_hasher = $hasher->clone |
|
|
216 | Make an exact copy of the hasher state. This can be useful to |
|
|
217 | generate incremental hashes, for example. |
|
|
218 | |
|
|
219 | Example: generate a hash for the data already fed into the hasher, |
|
|
220 | by keeping the original hasher for further "add" calls and calling |
|
|
221 | "finish" on a "clone". |
|
|
222 | |
|
|
223 | my $intermediate_hash = $hasher->clone->finish; |
|
|
224 | |
|
|
225 | Example: hash 64KiB of data, and generate a hash after every |
|
|
226 | kilobyte that is over the full data. |
|
|
227 | |
|
|
228 | my $hasher = new Crypt::Spritz::Hash; |
|
|
229 | |
|
|
230 | for (0..63) { |
|
|
231 | my $kib = "x" x 1024; # whatever data |
|
|
232 | |
|
|
233 | $hasher->add ($kib); |
|
|
234 | |
|
|
235 | my $intermediate_hash = $hasher->clone->finish; |
|
|
236 | ... |
|
|
237 | } |
|
|
238 | |
|
|
239 | These kind of intermediate hashes are sometimes used in |
|
|
240 | communications protocols to protect the integrity of the data |
|
|
241 | incrementally, e.g. to detect errors early, while still having a |
|
|
242 | complete hash at the end of a transfer. |
|
|
243 | |
|
|
244 | THE Crypt::Spritz::MAC CLASS |
|
|
245 | This implements the Spritz Message Authentication Code algorithm. It |
|
|
246 | works very similar to other digest modules on CPAN, such as |
|
|
247 | Digest::SHA3, but implements an authenticated digest (like |
|
|
248 | Digest::HMAC). |
|
|
249 | |
|
|
250 | *Authenticated* means that, unlike Crypt::Spritz::Hash, where everybody |
|
|
251 | can verify and recreate the hash value for some data, with a MAC, |
|
|
252 | knowledge of the (hopefully) secret key is required both to create and |
|
|
253 | to verify the digest. |
|
|
254 | |
|
|
255 | Typical use for hashing is almost the same as with Crypt::Spritz::MAC, |
|
|
256 | except a key (typically 16 or 32 octets) is provided to the constructor: |
|
|
257 | |
|
|
258 | # create hasher object |
|
|
259 | my $hasher = new Crypt::Spritz::Mac $key; |
|
|
260 | |
|
|
261 | # now feed data to be hashed into $hasher |
|
|
262 | # in as few or many calls as required |
|
|
263 | $hasher->add ("Some data"); |
|
|
264 | $hasher->add ("Some more"); |
|
|
265 | |
|
|
266 | # extract the mac - the object is not usable afterwards |
|
|
267 | my $mac = $hasher->finish (32); |
|
|
268 | |
|
|
269 | $hasher = new Crypt::Spritz::MAC $key |
|
|
270 | Creates a new hasher object. The $key can be of any length, but 16 |
|
|
271 | and 32 (128 and 256 bit) are customary. |
|
|
272 | |
|
|
273 | $hasher->add ($data) |
|
|
274 | Adds data to be hashed into the hasher state. It doesn't matter |
|
|
275 | whether you pass your data in in one go or split it up, the hash |
|
|
276 | will be the same. |
|
|
277 | |
|
|
278 | $mac = $hasher->finish ($length) |
|
|
279 | Calculates a message code of the given length and return it. The |
|
|
280 | object cannot sensibly be used for further hashing afterwards. |
|
|
281 | |
|
|
282 | Typical digest lengths are 16 and 32, corresponding to 128 and 256 |
|
|
283 | bit digests, respectively. |
|
|
284 | |
|
|
285 | $another_hasher = $hasher->clone |
|
|
286 | Make an exact copy of the hasher state. This can be useful to |
|
|
287 | generate incremental macs, for example. |
|
|
288 | |
|
|
289 | See the description for the "Crypt::Spritz::Hash::clone" method for |
|
|
290 | some examples. |
|
|
291 | |
107 | THE Crypt::Spritz::Cipher::XOR CLASS |
292 | THE Crypt::Spritz::Cipher::XOR CLASS |
108 | This class implements stream encryption/decryption. It doesn't implement |
293 | This class implements stream encryption/decryption. It doesn't implement |
109 | the standard Spritz encryption but the XOR variant (called spritz-xor in |
294 | the standard Spritz encryption but the XOR variant (called spritz-xor in |
110 | the paper). |
295 | the paper). |
111 | |
296 | |
… | |
… | |
144 | are 16 (128 bit) or 32 (256 bit), while the $IV simply needs to be |
329 | 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. |
330 | long enough to distinguish repeated uses of tghe same key. |
146 | |
331 | |
147 | $encrypted = $cipher->crypt ($cleartext) |
332 | $encrypted = $cipher->crypt ($cleartext) |
148 | $cleartext = $cipher->crypt ($encrypted) |
333 | $cleartext = $cipher->crypt ($encrypted) |
149 | Encrypt or decrypt a piece of a message. This cna be called as many |
334 | Encrypt or decrypt a piece of a message. This can be called as many |
150 | times as you want, and the message can be split into as few or many |
335 | times as you want, and the message can be split into as few or many |
151 | pieces as required without affecting the results. |
336 | pieces as required without affecting the results. |
152 | |
337 | |
153 | $cipher->crypt_inplace ($cleartext_or_ciphertext) |
338 | $cipher->crypt_inplace ($cleartext_or_ciphertext) |
154 | Same as "crypt", except it *modifies the argument in-place*. |
339 | Same as "crypt", except it *modifies the argument in-place*. |
|
|
340 | |
|
|
341 | $another_cipher = $cipher->clone |
|
|
342 | Make an exact copy of the cipher state. This can be useful to cache |
|
|
343 | states for reuse later, for example, to avoid expensive key setups. |
|
|
344 | |
|
|
345 | While there might be use cases for this feature, it makes a lot more |
|
|
346 | sense for "Crypt::Spritz::AEAD" and "Crypt::Spritz::AEAD::XOR", as |
|
|
347 | they allow you to specify the IV/nonce separately. |
155 | |
348 | |
156 | $constant_32 = $cipher->keysize |
349 | $constant_32 = $cipher->keysize |
157 | $constant_64 = $cipher->blocksize |
350 | $constant_64 = $cipher->blocksize |
158 | These methods are provided for Crypt::CBC compatibility and simply |
351 | These methods are provided for Crypt::CBC compatibility and simply |
159 | return 32 and 64, respectively. |
352 | return 32 and 64, respectively. |
160 | |
353 | |
161 | Note that it is pointless to use Spritz with Crypt::CBC, as Spritz |
354 | 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. |
355 | is not a block cipher and already provides an appropriate mode. |
163 | |
356 | |
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 |
357 | THE Crypt::Spritz::Cipher CLASS |
197 | This implements the Spritz Message Authentication Code algorithm. It |
358 | This class is pretty much the same as the "Crypt::Spritz::Cipher::XOR" |
198 | works very similar to other digest modules on CPAN, such as |
359 | class, with two differences: first, it implements the "standard" Spritz |
199 | Digest::SHA3, but implements an authenticated digest (like |
360 | encryption algorithm, and second, while this variant is easier to |
200 | Digest::HMAC). |
361 | analyze mathematically, there is little else to recommend it for, as it |
|
|
362 | is slower, and requires lots of code duplication code. |
201 | |
363 | |
202 | *Authenticated* means that, unlike Crypt::Spritz::Hash, where everybody |
364 | So unless you need to be compatible with another implementation that |
203 | can verify and recreate the hash value for some data, with a MAC, |
365 | does not offer the XOR variant, stick to "Crypt::Spritz::Cipher::XOR". |
204 | knowledge of the (hopefully) secret key is required both to create and |
|
|
205 | to verify the digest. |
|
|
206 | |
366 | |
207 | Typical use for hashing is almost the same as with Crypt::Spritz::MAC, |
367 | All the methods from "Crypt::Spritz::Cipher::XOR" are available, except |
208 | except a key (typically 16 or 32 octets) is provided to the constructor: |
368 | "crypt", which has been replaced by separate "encrypt" and "decrypt" |
|
|
369 | methods: |
209 | |
370 | |
210 | # create hasher object |
371 | $encrypted = $cipher->encrypt ($cleartext) |
211 | my $hasher = new Crypt::Spritz::Mac $key; |
372 | $cleartext = $cipher->decrypt ($encrypted) |
212 | |
373 | Really the same as "Crypt::Spritz::Cipher::XOR", except you need |
213 | # now feed data to be hashed into $hasher |
374 | separate calls and code for encryption and decryption. |
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 | |
375 | |
237 | THE Crypt::Spritz::AEAD::XOR CLASS |
376 | THE Crypt::Spritz::AEAD::XOR CLASS |
238 | This is the most complicated class - it combines encryption and message |
377 | This is the most complicated class - it combines encryption and message |
239 | authentication into a single "authenticated encryption mode". It is |
378 | authentication into a single "authenticated encryption mode". It is |
240 | similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC, |
379 | similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC, |
… | |
… | |
310 | increments, and thus reuse the same sequence number. The problem |
449 | increments, and thus reuse the same sequence number. The problem |
311 | with random strings i that your random number generator might be |
450 | with random strings i that your random number generator might be |
312 | hosed and generate the same randomness multiple times (randomness |
451 | hosed and generate the same randomness multiple times (randomness |
313 | can be very hard to get especially on embedded devices). |
452 | can be very hard to get especially on embedded devices). |
314 | |
453 | |
315 | $aead->associated_data ($data)( |
454 | $aead->associated_data ($data) |
316 | Provide the associated data (cleartext data to be authenticated but |
455 | Provide the associated data (cleartext data to be authenticated but |
317 | not encrypted). This method *must* be called *after* "nonce" and |
456 | not encrypted). This method *must* be called *after* "nonce" and |
318 | *before* "crypt". |
457 | *before* "crypt". |
319 | |
458 | |
320 | If you don't have any associated data, you can provide an empty |
459 | If you don't have any associated data, you can provide an empty |
… | |
… | |
327 | message or in general how to interpret the encrypted part of a |
466 | message or in general how to interpret the encrypted part of a |
328 | message. |
467 | message. |
329 | |
468 | |
330 | $encrypted = $cipher->crypt ($cleartext) |
469 | $encrypted = $cipher->crypt ($cleartext) |
331 | $cleartext = $cipher->crypt ($encrypted) |
470 | $cleartext = $cipher->crypt ($encrypted) |
332 | Encrypt or decrypt a piece of a message. This cna be called as many |
471 | Encrypt or decrypt a piece of a message. This can be called as many |
333 | times as you want, and the message can be split into as few or many |
472 | 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 |
473 | pieces as required without affecting the results, with one |
335 | exception: All except the last call to "crypt" needs to pass in a |
474 | 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 |
475 | multiple of 64 octets. The last call to "crypt" does not have this |
337 | limitation. |
476 | limitation. |
338 | |
477 | |
339 | $cipher->crypt_inplace ($cleartext_or_ciphertext) |
478 | $cipher->crypt_inplace ($cleartext_or_ciphertext) |
340 | Same as "crypt", except it *modifies the argument in-place*. |
479 | Same as "crypt", except it *modifies the argument in-place*. |
341 | |
480 | |
|
|
481 | $another_cipher = $cipher->clone |
|
|
482 | Make an exact copy of the cipher state. This can be useful to cache |
|
|
483 | states for reuse later, for example, to avoid expensive key setups. |
|
|
484 | |
|
|
485 | Example: set up a cipher state with a key, then clone and use it to |
|
|
486 | encrypt messages with different nonces. |
|
|
487 | |
|
|
488 | my $cipher = new Crypt::Spritz::AEAD::XOR $key; |
|
|
489 | |
|
|
490 | my $message_counter; |
|
|
491 | |
|
|
492 | for my $message ("a", "b", "c") { |
|
|
493 | my $clone = $cipher->clone; |
|
|
494 | $clone->nonce (pack "N", ++$message_counter); |
|
|
495 | $clone->associated_data (""); |
|
|
496 | my $encrypted = $clone->crypt ($message); |
|
|
497 | ... |
|
|
498 | } |
|
|
499 | |
342 | THE Crypt::Spritz::PRNG CLASS |
500 | THE Crypt::Spritz::AEAD CLASS |
343 | This class implements a Pseudorandom Number Generatore (PRNG), sometimes |
501 | This class is pretty much the same as the "Crypt::Spritz::AEAD::XOR" |
344 | also called a Deterministic Random Bit Generator (DRBG). In fact, it is |
502 | class, with two differences: first, it implements the "standard" Spritz |
345 | even cryptographically secure, making it a CSPRNG. |
503 | encryption algorithm, and second, while this variant is easier to |
|
|
504 | analyze mathematically, there is little else to recommend it for, as it |
|
|
505 | is slower, and requires lots of code duplication code. |
346 | |
506 | |
347 | Typical usage as a random number generator involves creating a PRNG |
507 | So unless you need to be compatible with another implementation that |
348 | object with a seed of your choice, and then fetching randomness via |
508 | does not offer the XOR variant, stick to "Crypt::Spritz::AEAD::XOR". |
349 | "get": |
|
|
350 | |
509 | |
351 | # create a PRNG object, use a seed string of your choice |
510 | All the methods from "Crypt::Spritz::AEAD::XOR" are available, except |
352 | my $prng = new Crypt::Spritz::PRNG $seed; |
511 | "crypt", which has been replaced by separate "encrypt" and "decrypt" |
|
|
512 | methods: |
353 | |
513 | |
354 | # now call get as many times as you wish to get binary randomness |
514 | $encrypted = $cipher->encrypt ($cleartext) |
355 | my $some_randomness = $prng->get (17); |
515 | $cleartext = $cipher->decrypt ($encrypted) |
356 | my moree_randomness = $prng->get (5000); |
516 | Really the same as "Crypt::Spritz::AEAD::XOR", except you need |
357 | ... |
517 | separate calls and code for encryption and decryption, but you have |
358 | |
518 | the same limitations on usage. |
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 | |
519 | |
400 | SEE ALSO |
520 | SEE ALSO |
401 | <http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. |
521 | <http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. |
402 | |
522 | |
403 | SECURITY CONSIDERATIONS |
523 | SECURITY CONSIDERATIONS |