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