| 1 | =head1 NAME | ||
| 2 | |||
| 3 | Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family | ||
| 4 | |||
| 5 | =head1 SYNOPSIS | ||
| 6 | |||
| 7 | use Crypt::Spritz; | ||
| 8 | |||
| 9 | # see the commented examples in their respective classes, | ||
| 10 | # but basically | ||
| 11 | |||
| 12 | my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv; | ||
| 13 | $ciphertext = $cipher->crypt ($cleartext); | ||
| 14 | |||
| 15 | my $cipher = new Crypt::Spritz::Cipher $key, $iv; | ||
| 16 | $ciphertext = $cipher->encrypt ($cleartext); | ||
| 17 | # $cleartext = $cipher->decrypt ($ciphertext); | ||
| 18 | |||
| 19 | 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 | my $prng = new Crypt::Spritz::PRNG $entropy; | ||
| 28 | $prng->add ($additional_entropy); | ||
| 29 | $keydata = $prng->get (32); | ||
| 30 | |||
| 31 | 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 | 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 | |||
| 44 | =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 | =head1 DESCRIPTION | ||
| 53 | |||
| 54 | This module implements the Spritz spongelike function (with N=256), the | ||
| 55 | spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt. | ||
| 56 | |||
| 57 | 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 | 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 | 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 | random number generation - Crypt::Spritz::PRNG | ||
| 80 | hashing - Crypt::Spritz::Hash | ||
| 81 | message authentication - Crypt::Spritz::MAC | ||
| 82 | encryption - Crypt::Spritz::Cipher::XOR | ||
| 83 | encryption - Crypt::Spritz::Cipher | ||
| 84 | authenticated encryption - Crypt::Spritz::AEAD::XOR | ||
| 85 | authenticated encryption - Crypt::Spritz::AEAD | ||
| 86 | |||
| 87 | =cut | ||
| 88 | |||
| 89 | package Crypt::Spritz; | ||
| 90 | |||
| 91 | 2 | ▶ | use XSLoader; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 92 | |||
| 93 | 2 | $VERSION = 1.02; | |
| 94 | |||
| 95 | 2 | XSLoader::load __PACKAGE__, $VERSION; | |
| 96 | |||
| 97 | 2 | @Crypt::Spritz::ISA = Crypt::Spritz::Base::; | |
| 98 | |||
| 99 | 2 | @Crypt::Spritz::Hash::ISA = | |
| 100 | @Crypt::Spritz::PRNG::ISA = | ||
| 101 | @Crypt::Spritz::Cipher::ISA = | ||
| 102 | @Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::; | ||
| 103 | |||
| 104 | 2 | @Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::; | |
| 105 | |||
| 106 | 2 | @Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::; | |
| 107 | 2 | @Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::; | |
| 108 | |||
| 109 | sub Crypt::Spritz::Cipher::keysize () { 32 } | ||
| 110 | sub Crypt::Spritz::Cipher::blocksize () { 64 } | ||
| 111 | |||
| 112 | 2 | *Crypt::Spritz::Hash::new = \&Crypt::Spritz::new; | |
| 113 | |||
| 114 | 2 | *Crypt::Spritz::Hash::add = | |
| 115 | *Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb; | ||
| 116 | |||
| 117 | 2 | *Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze; | |
| 118 | |||
| 119 | 2 | *Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new; | |
| 120 | 2 | *Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish; | |
| 121 | |||
| 122 | 2 | *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 | paper|http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially | ||
| 131 | 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 | =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 | =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 | Absorbs the given data into the state (usually used for key material, | ||
| 168 | nonces, IVs messages to be hashed and so on). | ||
| 169 | |||
| 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 | =head2 THE Crypt::Spritz::PRNG CLASS | ||
| 192 | |||
| 193 | 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 | |||
| 197 | 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 | |||
| 201 | # create a PRNG object, use a seed string of your choice | ||
| 202 | my $prng = new Crypt::Spritz::PRNG $seed; | ||
| 203 | |||
| 204 | # 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 | |||
| 209 | 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 | |||
| 214 | # create a PRNG object | ||
| 215 | my $prng = new Crypt::Spritz::PRNG; | ||
| 216 | |||
| 217 | # seed some entropy (either via ->add or in the constructor) | ||
| 218 | $prng->add ($some_secret_highly_entropic_string); | ||
| 219 | |||
| 220 | # 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 | |||
| 226 | # 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 | |||
| 230 | =over 4 | ||
| 231 | |||
| 232 | =item $prng = new Crypt::Spritz::PRNG [$seed] | ||
| 233 | |||
| 234 | 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 | |||
| 237 | =item $prng->add ($entropy) | ||
| 238 | |||
| 239 | 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 | |||
| 243 | 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 | |||
| 247 | For use as PRNG, of course, this matters very little. | ||
| 248 | |||
| 249 | =item $octets = $prng->get ($length) | ||
| 250 | |||
| 251 | Generates and returns C<$length> random octets as a string. | ||
| 252 | |||
| 253 | =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 | =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 | =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 | |||
| 364 | Calculates a message code of the given length and return it. The object | ||
| 365 | cannot sensibly be used for further hashing afterwards. | ||
| 366 | |||
| 367 | Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit | ||
| 368 | digests, respectively. | ||
| 369 | |||
| 370 | =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 | =back | ||
| 379 | |||
| 380 | |||
| 381 | =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 | =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 | =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 | |||
| 564 | 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 | |||
| 570 | =item $aead->associated_data ($data) | ||
| 571 | |||
| 572 | 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 | |||
| 576 | If you don't have any associated data, you can provide an empty string - | ||
| 577 | but you still have to call the method. | ||
| 578 | |||
| 579 | 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 | |||
| 585 | =item $encrypted = $cipher->crypt ($cleartext) | ||
| 586 | |||
| 587 | =item $cleartext = $cipher->crypt ($encrypted) | ||
| 588 | |||
| 589 | Encrypt or decrypt a piece of a message. This can be called as many times | ||
| 590 | 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 | |||
| 595 | =item $cipher->crypt_inplace ($cleartext_or_ciphertext) | ||
| 596 | |||
| 597 | Same as C<crypt>, except it I<modifies the argument in-place>. | ||
| 598 | |||
| 599 | =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 | =back | ||
| 620 | |||
| 621 | |||
| 622 | =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 | =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 | 5MB/s on 2014 era hardware, which does SHA-256 at about 200MB/s). | ||
| 673 | |||
| 674 | |||
| 675 | =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 | =head1 SEE ALSO | ||
| 684 | |||
| 685 | L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>. | ||
| 686 | |||
| 687 | =head1 SECURITY CONSIDERATIONS | ||
| 688 | |||
| 689 | 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 | |||
| 693 | =head1 AUTHOR | ||
| 694 | |||
| 695 | Marc Lehmann <schmorp@schmorp.de> | ||
| 696 | http://software.schmorp.de/pkg/Crypt-Spritz | ||
| 697 | |||
| 698 | =cut | ||
| 699 | |||
| 700 | 2 | 1; | |
| 701 | |||