[ViewVC] Diff of: cvs/Crypt-Spritz/Spritz.pm

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.5 by root, Sat Jan 10 07:19:24 2015 UTC vs.
Revision 1.13 by root, Tue Jun 30 01:24:43 2015 UTC

…		…
1	=head1 NAME	1	=head1 NAME
2		2
3	Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module	3	Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use Crypt::Spritz;	7	use Crypt::Spritz;
8		8
9	# see the commented examples in their respective classes,	9	# see the commented examples in their respective classes,
10	# but basically	10	# but basically
11		11
12	my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;	12	my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
13	$ciphertext = $cipher->crypt ($cleartext);	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);
14		18
15	my $hasher = new Crypt::Spritz::Hash;	19	my $hasher = new Crypt::Spritz::Hash;
16	$hasher->add ($data);	20	$hasher->add ($data);
17	$digest = $hasher->finish;	21	$digest = $hasher->finish;
18		22
19	my $hasher = new Crypt::Spritz::MAC $key;	23	my $hasher = new Crypt::Spritz::MAC $key;
20	$hasher->add ($data);	24	$hasher->add ($data);
21	$mac = $hasher->finish;	25	$mac = $hasher->finish;
		26
		27	my $prng = new Crypt::Spritz::PRNG $entropy;
		28	$prng->add ($additional_entropy);
		29	$keydata = $prng->get (32);
22		30
23	my $aead = new Crypt::Spritz::AEAD::XOR $key;	31	my $aead = new Crypt::Spritz::AEAD::XOR $key;
24	$aead->nonce ($counter);	32	$aead->nonce ($counter);
25	$aead->associated_data ($header);	33	$aead->associated_data ($header);
26	$ciphertext = $aead->crypt ($cleartext);	34	$ciphertext = $aead->crypt ($cleartext);
27	$mac = $aead->mac;	35	$mac = $aead->mac;
28		36
29	my $prng = new Crypt::Spritz::PRNG $entropy;	37	my $aead = new Crypt::Spritz::AEAD $key;
30	$prng->add ($additional_entropy);	38	$aead->nonce ($counter);
31	$keydata = $prng->get (32);	39	$aead->associated_data ($header);
		40	$ciphertext = $aead->encrypt ($cleartext);
		41	# $cleartext = $aead->decrypt ($ciphertext);
		42	$mac = $aead->mac;
32		43
33	=head1 DESCRIPTION	44	=head1 DESCRIPTION
34		45
35	This module implements the Spritz spongelike function (with N=256), the	46	This module implements the Spritz spongelike function (with N=256), the
36	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.	47	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
46	slower than RC4 or AES, hashing many times slower than SHA-3, although	57	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	58	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	59	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.	60	months old), so it can't be called production-ready.
50		61
51	All the usual caveats regarding stream ciphers apply - never repeat	62	All the usual caveats regarding stream ciphers apply - never repeat your
52	your key, never repeat your nonce and so on - you should have some basic	63	key, never repeat your nonce and so on - you should have some basic
53	understanding of cryptography before using this cipher in your own	64	understanding of cryptography before using this cipher in your own
54	designs.	65	designs.
55		66
56	The Spritz base class is not meant for end users. To make usage simpler	67	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	68	and safer, a number of convenience classes are provided for typical
58	end-user tasks:	69	end-user tasks:
59		70
60	encryption - Crypt::Spritz::Cipher::XOR	71	random number generation - Crypt::Spritz::PRNG
61	hashing - Crypt::Spritz::Hash	72	hashing - Crypt::Spritz::Hash
62	message authentication - Crypt::Spritz::MAC	73	message authentication - Crypt::Spritz::MAC
		74	encryption - Crypt::Spritz::Cipher::XOR
		75	encryption - Crypt::Spritz::Cipher
63	authenticated encryption - Crypt::Spritz::AEAD::XOR	76	authenticated encryption - Crypt::Spritz::AEAD::XOR
64	random number generation - Crypt::Spritz::PRNG	77	authenticated encryption - Crypt::Spritz::AEAD
65		78
66	=cut	79	=cut
67		80
68	package Crypt::Spritz;	81	package Crypt::Spritz;
69		82
70	use XSLoader;	83	use XSLoader;
71		84
72	$VERSION = '0.0';	85	$VERSION = 1.01;
73		86
74	XSLoader::load __PACKAGE__, $VERSION;	87	XSLoader::load __PACKAGE__, $VERSION;
75		88
76	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;	89	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
77		90
…		…
104		117
105	=head2 THE Crypt::Spritz CLASS	118	=head2 THE Crypt::Spritz CLASS
106		119
107	This class implements most of the Spritz primitives. To use it effectively	120	This class implements most of the Spritz primitives. To use it effectively
108	you should understand them, for example, by reading the L<Spritz	121	you should understand them, for example, by reading the L<Spritz
109	paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially	122	paper\|http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
110	pp. 5-6.	123	pp. 5-6.
111		124
112	The Spritz primitive corresponding to the Perl method is given as	125	The Spritz primitive corresponding to the Perl method is given as
113	comment.	126	comment.
114		127
…		…
120		133
121	=item $spritz->init # InitializeState	134	=item $spritz->init # InitializeState
122		135
123	Initialises the Spritz state again, throwing away the previous state.	136	Initialises the Spritz state again, throwing away the previous state.
124		137
		138	=item $another_spritz = $spritz->clone
		139
		140	Make an exact copy of the spritz state. This method can be called on all
		141	of the objects in this module, but is documented separately to give some
		142	cool usage examples.
		143
125	=item $spritz->update # Update	144	=item $spritz->update # Update
126		145
127	=item $spritz->whip ($r) # Whip	146	=item $spritz->whip ($r) # Whip
128		147
129	=item $spritz->crush # Crush	148	=item $spritz->crush # Crush
…		…
135	Calls the Spritz primitive ovf the same name - these are not normally	154	Calls the Spritz primitive ovf the same name - these are not normally
136	called manually.	155	called manually.
137		156
138	=item $spritz->absorb ($I) # Absorb	157	=item $spritz->absorb ($I) # Absorb
139		158
140	Absorbs the given data into the state (usually used for key material, nonces, IVs	159	Absorbs the given data into the state (usually used for key material,
141	messages to be hashed and so on).	160	nonces, IVs messages to be hashed and so on).
142		161
143	=item $spritz->absorb_stop # AbsorbStop	162	=item $spritz->absorb_stop # AbsorbStop
144		163
145	Absorbs a special stop symbol - this is usually used as delimiter between	164	Absorbs a special stop symbol - this is usually used as delimiter between
146	multiple strings to be absorbed, to thwart extension attacks.	165	multiple strings to be absorbed, to thwart extension attacks.
…		…
155	Squeezes out a single byte from the state.	174	Squeezes out a single byte from the state.
156		175
157	=item $octets = $spritz->squeeze ($len) # Squeeze	176	=item $octets = $spritz->squeeze ($len) # Squeeze
158		177
159	Squeezes out the requested number of bytes from the state - this is usually	178	Squeezes out the requested number of bytes from the state - this is usually
		179
		180	=back
		181
		182
		183	=head2 THE Crypt::Spritz::PRNG CLASS
		184
		185	This class implements a Pseudorandom Number Generatore (B<PRNG>),
		186	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
		187	fact, it is even cryptographically secure, making it a B<CSPRNG>.
		188
		189	Typical usage as a random number generator involves creating a PRNG
		190	object with a seed of your choice, and then fetching randomness via
		191	C<get>:
		192
		193	# create a PRNG object, use a seed string of your choice
		194	my $prng = new Crypt::Spritz::PRNG $seed;
		195
		196	# now call get as many times as you wish to get binary randomness
		197	my $some_randomness = $prng->get (17);
		198	my moree_randomness = $prng->get (5000);
		199	...
		200
		201	Typical usage as a cryptographically secure random number generator is to
		202	feed in some secret entropy (32 octets/256 bits are commonly considered
		203	enough), for example from C</dev/random> or C</dev/urandom>, and then
		204	generate some key material.
		205
		206	# create a PRNG object
		207	my $prng = new Crypt::Spritz::PRNG;
		208
		209	# seed some entropy (either via ->add or in the constructor)
		210	$prng->add ($some_secret_highly_entropic_string);
		211
		212	# now call get as many times as you wish to get
		213	# hard to guess binary randomness
		214	my $key1 = $prng->get (32);
		215	my $key2 = $prng->get (16);
		216	...
		217
		218	# for long running programs, it is advisable to
		219	# reseed the PRNG from time to time with new entropy
		220	$prng->add ($some_more_entropy);
		221
		222	=over 4
		223
		224	=item $prng = new Crypt::Spritz::PRNG [$seed]
		225
		226	Creates a new random number generator object. If C<$seed> is given, then
		227	the C<$seed> is added to the internal state as if by a call to C<add>.
		228
		229	=item $prng->add ($entropy)
		230
		231	Adds entropy to the internal state, thereby hopefully making it harder
		232	to guess. Good sources for entropy are irregular hardware events, or
		233	randomness provided by C</dev/urandom> or C</dev/random>.
		234
		235	The design of the Spritz PRNG should make it strong against attacks where
		236	the attacker controls all the entropy, so it should be safe to add entropy
		237	from untrusted sources - more is better than less if you need a CSPRNG.
		238
		239	For use as PRNG, of course, this matters very little.
		240
		241	=item $octets = $prng->get ($length)
		242
		243	Generates and returns C<$length> random octets as a string.
		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.
160		369
161	=back	370	=back
162		371
163		372
164	=head2 THE Crypt::Spritz::Cipher::XOR CLASS	373	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
…		…
207		416
208	=item $encrypted = $cipher->crypt ($cleartext)	417	=item $encrypted = $cipher->crypt ($cleartext)
209		418
210	=item $cleartext = $cipher->crypt ($encrypted)	419	=item $cleartext = $cipher->crypt ($encrypted)
211		420
212	Encrypt or decrypt a piece of a message. This cna be called as many times	421	Encrypt or decrypt a piece of a message. This can be called as many times
213	as you want, and the message can be split into as few or many pieces as	422	as you want, and the message can be split into as few or many pieces as
214	required without affecting the results.	423	required without affecting the results.
215		424
216	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	425	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
217		426
218	Same as C<crypt>, except it I<modifies the argument in-place>.	427	Same as C<crypt>, except it I<modifies the argument in-place>.
219		428
		429	=item $another_cipher = $cipher->clone
		430
		431	Make an exact copy of the cipher state. This can be useful to cache states
		432	for reuse later, for example, to avoid expensive key setups.
		433
		434	While there might be use cases for this feature, it makes a lot more sense
		435	for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
		436	you to specify the IV/nonce separately.
		437
220	=item $constant_32 = $cipher->keysize	438	=item $constant_32 = $cipher->keysize
221		439
222	=item $constant_64 = $cipher->blocksize	440	=item $constant_64 = $cipher->blocksize
223		441
224	These methods are provided for L<Crypt::CBC> compatibility and simply	442	These methods are provided for L<Crypt::CBC> compatibility and simply
…		…
228	not a block cipher and already provides an appropriate mode.	446	not a block cipher and already provides an appropriate mode.
229		447
230	=back	448	=back
231		449
232		450
233	=head2 THE Crypt::Spritz::Hash CLASS
234
235	This implements the Spritz digest/hash algorithm. It works very similar to
236	other digest modules on CPAN, such as L<Digest::SHA3>.
237
238	Typical use for hashing:
239
240	# create hasher object
241	my $hasher = new Crypt::Spritz::Hash;
242
243	# now feed data to be hashed into $hasher
244	# in as few or many calls as required
245	$hasher->add ("Some data");
246	$hasher->add ("Some more");
247
248	# extract the hash - the object is not usable afterwards
249	my $digest = $hasher->finish (32);
250
251	=over 4
252
253	=item $hasher = new Crypt::Spritz::Hash
254
255	Creates a new hasher object.
256
257	=item $hasher->add ($data)
258
259	Adds data to be hashed into the hasher state. It doesn't matter whether
260	you pass your data in in one go or split it up, the hash will be the same.
261
262	=item $digest = $hasher->finish ($length)
263
264	Calculates a hash digest of the given length and return it. The object
265	cannot sensibly be used for further hashing afterwards.
266
267	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
268	digests, respectively.
269
270	=back
271
272
273	=head2 THE Crypt::Spritz::MAC CLASS	451	=head2 THE Crypt::Spritz::Cipher CLASS
274		452
275	This implements the Spritz Message Authentication Code algorithm. It works	453	This class is pretty much the same as the C<Crypt::Spritz::Cipher::XOR>
276	very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but	454	class, with two differences: first, it implements the "standard" Spritz
277	implements an authenticated digest (like L<Digest::HMAC>).	455	encryption algorithm, and second, while this variant is easier to analyze
		456	mathematically, there is little else to recommend it for, as it is slower,
		457	and requires lots of code duplication code.
278		458
279	I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where	459	So unless you need to be compatible with another implementation that does
280	everybody can verify and recreate the hash value for some data, with a	460	not offer the XOR variant, stick to C<Crypt::Spritz::Cipher::XOR>.
281	MAC, knowledge of the (hopefully) secret key is required both to create
282	and to verify the digest.
283		461
284	Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,	462	All the methods from C<Crypt::Spritz::Cipher::XOR> are available, except
285	except a key (typically 16 or 32 octets) is provided to the constructor:	463	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		464	methods:
286		465
287	# create hasher object
288	my $hasher = new Crypt::Spritz::Mac $key;
289
290	# now feed data to be hashed into $hasher
291	# in as few or many calls as required
292	$hasher->add ("Some data");
293	$hasher->add ("Some more");
294
295	# extract the mac - the object is not usable afterwards
296	my $mac = $hasher->finish (32);
297
298	=over 4	466	=over 4
299		467
300	=item $hasher = new Crypt::Spritz::MAC $key	468	=item $encrypted = $cipher->encrypt ($cleartext)
301		469
302	Creates a new hasher object. The C<$key> can be of any length, but 16 and	470	=item $cleartext = $cipher->decrypt ($encrypted)
303	32 (128 and 256 bit) are customary.
304		471
305	=item $hasher->add ($data)	472	Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
306		473	calls and code for encryption and decryption.
307	Adds data to be hashed into the hasher state. It doesn't matter whether
308	you pass your data in in one go or split it up, the hash will be the same.
309
310	=item $mac = $hasher->finish ($length)
311
312	Calculates a message code of the given length and return it. The object
313	cannot sensibly be used for further hashing afterwards.
314
315	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
316	digests, respectively.
317		474
318	=back	475	=back
319		476
320		477
321	=head2 THE Crypt::Spritz::AEAD::XOR CLASS	478	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
…		…
400	increments, and thus reuse the same sequence number. The problem with	557	increments, and thus reuse the same sequence number. The problem with
401	random strings i that your random number generator might be hosed and	558	random strings i that your random number generator might be hosed and
402	generate the same randomness multiple times (randomness can be very hard	559	generate the same randomness multiple times (randomness can be very hard
403	to get especially on embedded devices).	560	to get especially on embedded devices).
404		561
405	=item $aead->associated_data ($data)(	562	=item $aead->associated_data ($data)
406		563
407	Provide the associated data (cleartext data to be authenticated but not	564	Provide the associated data (cleartext data to be authenticated but not
408	encrypted). This method I<must> be called I<after> C<nonce> and I<before>	565	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
409	C<crypt>.	566	C<crypt>.
410		567
…		…
419		576
420	=item $encrypted = $cipher->crypt ($cleartext)	577	=item $encrypted = $cipher->crypt ($cleartext)
421		578
422	=item $cleartext = $cipher->crypt ($encrypted)	579	=item $cleartext = $cipher->crypt ($encrypted)
423		580
424	Encrypt or decrypt a piece of a message. This cna be called as many times	581	Encrypt or decrypt a piece of a message. This can be called as many times
425	as you want, and the message can be split into as few or many pieces as	582	as you want, and the message can be split into as few or many pieces as
426	required without affecting the results, with one exception: All except the	583	required without affecting the results, with one exception: All except the
427	last call to C<crypt> needs to pass in a multiple of C<64> octets. The	584	last call to C<crypt> needs to pass in a multiple of C<64> octets. The
428	last call to C<crypt> does not have this limitation.	585	last call to C<crypt> does not have this limitation.
429		586
430	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	587	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
431		588
432	Same as C<crypt>, except it I<modifies the argument in-place>.	589	Same as C<crypt>, except it I<modifies the argument in-place>.
433		590
434	=back	591	=item $another_cipher = $cipher->clone
435		592
		593	Make an exact copy of the cipher state. This can be useful to cache states
		594	for reuse later, for example, to avoid expensive key setups.
436		595
		596	Example: set up a cipher state with a key, then clone and use it to
		597	encrypt messages with different nonces.
		598
		599	my $cipher = new Crypt::Spritz::AEAD::XOR $key;
		600
		601	my $message_counter;
		602
		603	for my $message ("a", "b", "c") {
		604	my $clone = $cipher->clone;
		605	$clone->nonce (pack "N", ++$message_counter);
		606	$clone->associated_data ("");
		607	my $encrypted = $clone->crypt ($message);
		608	...
		609	}
		610
		611	=back
		612
		613
437	=head2 THE Crypt::Spritz::PRNG CLASS	614	=head2 THE Crypt::Spritz::AEAD CLASS
438		615
439	This class implements a Pseudorandom Number Generatore (B<PRNG>),	616	This class is pretty much the same as the C<Crypt::Spritz::AEAD::XOR>
440	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In	617	class, with two differences: first, it implements the "standard" Spritz
441	fact, it is even cryptographically secure, making it a B<CSPRNG>.	618	encryption algorithm, and second, while this variant is easier to analyze
		619	mathematically, there is little else to recommend it for, as it is slower,
		620	and requires lots of code duplication code.
442		621
443	Typical usage as a random number generator involves creating a PRNG	622	So unless you need to be compatible with another implementation that does
444	object with a seed of your choice, and then fetching randomness via	623	not offer the XOR variant, stick to C<Crypt::Spritz::AEAD::XOR>.
445	C<get>:
446		624
447	# create a PRNG object, use a seed string of your choice	625	All the methods from C<Crypt::Spritz::AEAD::XOR> are available, except
448	my $prng = new Crypt::Spritz::PRNG $seed;	626	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		627	methods:
449		628
450	# now call get as many times as you wish to get binary randomness
451	my $some_randomness = $prng->get (17);
452	my moree_randomness = $prng->get (5000);
453	...
454
455	Typical usage as a cryptographically secure random number generator is to
456	feed in some secret entropy (32 octets/256 bits are commonly considered
457	enough), for example from C</dev/random> or C</dev/urandom>, and then
458	generate some key material.
459
460	# create a PRNG object
461	my $prng = new Crypt::Spritz::PRNG;
462
463	# seed some entropy (either via ->add or in the constructor)
464	$prng->add ($some_secret_highly_entropic_string);
465
466	# now call get as many times as you wish to get
467	# hard to guess binary randomness
468	my $key1 = $prng->get (32);
469	my $key2 = $prng->get (16);
470	...
471
472	# for long running programs, it is advisable to
473	# reseed the PRNG from time to time with new entropy
474	$prng->add ($some_more_entropy);
475
476	=over 4	629	=over 4
477		630
478	=item $prng = new Crypt::Spritz::PRNG [$seed]	631	=item $encrypted = $cipher->encrypt ($cleartext)
479		632
480	Creates a new random number generator object. If C<$seed> is given, then	633	=item $cleartext = $cipher->decrypt ($encrypted)
481	the C<$seed> is added to the internal state as if by a call to C<add>.
482		634
483	=item $prng->add ($entropy)	635	Really the same as C<Crypt::Spritz::AEAD::XOR>, except you need separate
		636	calls and code for encryption and decryption, but you have the same
		637	limitations on usage.
484		638
485	Adds entropy to the internal state, thereby hopefully making it harder
486	to guess. Good sources for entropy are irregular hardware events, or
487	randomness provided by C</dev/urandom> or C</dev/random>.
488
489	The design of the Spritz PRNG should make it strong against attacks where
490	the attacker controls all the entropy, so it should be safe to add entropy
491	from untrusted sources - more is better than less if you need a CSPRNG.
492
493	For use as PRNG, of course, this matters very little.
494
495	=item $octets = $prng->get ($length)
496
497	Generates and returns C<$length> random octets as a string.
498
499	=back	639	=back
		640
		641
		642	=head1 SECURITY CONSIDERATIONS
		643
		644	At the time of this writing, Spritz has not been through a lot of
		645	cryptanalysis - it might get broken tomorrow. That's true for any crypto
		646	algo, but the probability is quite a bit higher with Spritz. Having said
		647	that, Spritz is almost certainly safer than RC4 at this time.
		648
		649	Nevertheless, I wouldn't protect something very expensive with it. I also
		650	would be careful about timing attacks.
		651
		652	Regarding key lengths - as has been pointed out, traditional symmetric key
		653	lengths (128 bit, 256 bit) work fine. Longer keys will be overkill, but
		654	you can expect keys up to about a kilobit to be effective. Longer keys are
		655	safe to use, they will simply be a waste of time.
		656
		657
		658	=head1 PERFORMANCE
		659
		660	As a cipher/prng, Spritz is reasonably fast (about 100MB/s on 2014 era
		661	hardware, for comparison, AES will be more like 200MB/s).
		662
		663	For key setup, ivs, hashing, nonces and so on, Spritz is very slow (about
		664	5MB/s on 2014 era hardware, which does SHA-256 at about 200MB/s).
		665
		666
		667	=head1 SUPPORT FOR THE PERL MULTICORE SPECIFICATION
		668
		669	This module supports the perl multicore specification
		670	(L<http://perlmulticore.schmorp.de/>) for all encryption/decryption
		671	(non-aead > 4000 octets, aead > 400 octets), hashing/absorbing (> 400
		672	octets) and squeezing/prng (> 4000 octets) functions.
500		673
501		674
502	=head1 SEE ALSO	675	=head1 SEE ALSO
503		676
504	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	677	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Crypt-Spritz/Spritz.pm (file contents): Revision 1.5 by root, Sat Jan 10 07:19:24 2015 UTC vs. Revision 1.13 by root, Tue Jun 30 01:24:43 2015 UTC

Diff Legend

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.5 by root, Sat Jan 10 07:19:24 2015 UTC vs.
Revision 1.13 by root, Tue Jun 30 01:24:43 2015 UTC