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