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

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.4 by root, Sat Jan 10 07:10:46 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 - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng 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	# keysize() is 32, but spritz accepts any key size	9	# see the commented examples in their respective classes,
10	# blocksize() is 16, but cna be anything	10	# but basically
11		11
12	$cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;	12	my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
		13	$ciphertext = $cipher->crypt ($cleartext);
13		14
		15	my $cipher = new Crypt::Spritz::Cipher $key, $iv;
14	$crypted = $cipher->encrypt($plaintext);	16	$ciphertext = $cipher->encrypt ($cleartext);
15	# - OR -
16	$plaintext = $cipher->decrypt($crypted);	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;
17		43
18	=head1 DESCRIPTION	44	=head1 DESCRIPTION
19		45
20	This module implements the Spritz spongelike function (with N=256), the	46	This module implements the Spritz spongelike function (with N=256), the
21	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.	47	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
31	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
32	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
33	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
34	months old), so it can't be called production-ready.	60	months old), so it can't be called production-ready.
35		61
36	All the usual caveats regarding stream ciphers apply - never repeat	62	All the usual caveats regarding stream ciphers apply - never repeat your
37	your key, never repeat your nonce etc. - you should have some basic	63	key, never repeat your nonce and so on - you should have some basic
38	understanding of cryptography before using this cipher in your own	64	understanding of cryptography before using this cipher in your own
39	designs.	65	designs.
40		66
41	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
42	and safer, a number of convenience classes are provided for typical	68	and safer, a number of convenience classes are provided for typical
43	end-user tasks:	69	end-user tasks:
44		70
45	encryption - Crypt::Spritz::Cipher::XOR	71	random number generation - Crypt::Spritz::PRNG
46	hashing - Crypt::Spritz::Hash	72	hashing - Crypt::Spritz::Hash
47	message authentication - Crypt::Spritz::MAC	73	message authentication - Crypt::Spritz::MAC
		74	encryption - Crypt::Spritz::Cipher::XOR
		75	encryption - Crypt::Spritz::Cipher
48	authenticated encryption - Crypt::Spritz::AEAD::XOR	76	authenticated encryption - Crypt::Spritz::AEAD::XOR
49	random number generation - Crypt::Spritz::PRNG	77	authenticated encryption - Crypt::Spritz::AEAD
50		78
51	=cut	79	=cut
52		80
53	package Crypt::Spritz;	81	package Crypt::Spritz;
54		82
55	use XSLoader;	83	use XSLoader;
56		84
57	$VERSION = '0.0';	85	$VERSION = 1.01;
58		86
59	XSLoader::load __PACKAGE__, $VERSION;	87	XSLoader::load __PACKAGE__, $VERSION;
60		88
61	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;	89	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
62		90
…		…
89		117
90	=head2 THE Crypt::Spritz CLASS	118	=head2 THE Crypt::Spritz CLASS
91		119
92	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
93	you should understand them, for example, by reading the L<Spritz	121	you should understand them, for example, by reading the L<Spritz
94	paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially	122	paper\|http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
95	pp. 5-6.	123	pp. 5-6.
96		124
97	The Spritz primitive corresponding to the Perl method is given as	125	The Spritz primitive corresponding to the Perl method is given as
98	comment.	126	comment.
99		127
…		…
105		133
106	=item $spritz->init # InitializeState	134	=item $spritz->init # InitializeState
107		135
108	Initialises the Spritz state again, throwing away the previous state.	136	Initialises the Spritz state again, throwing away the previous state.
109		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
110	=item $spritz->update # Update	144	=item $spritz->update # Update
111		145
112	=item $spritz->whip ($r) # Whip	146	=item $spritz->whip ($r) # Whip
113		147
114	=item $spritz->crush # Crush	148	=item $spritz->crush # Crush
…		…
120	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
121	called manually.	155	called manually.
122		156
123	=item $spritz->absorb ($I) # Absorb	157	=item $spritz->absorb ($I) # Absorb
124		158
125	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,
126	messages to be hashed and so on).	160	nonces, IVs messages to be hashed and so on).
127		161
128	=item $spritz->absorb_stop # AbsorbStop	162	=item $spritz->absorb_stop # AbsorbStop
129		163
130	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
131	multiple strings to be absorbed, to thwart extension attacks.	165	multiple strings to be absorbed, to thwart extension attacks.
…		…
140	Squeezes out a single byte from the state.	174	Squeezes out a single byte from the state.
141		175
142	=item $octets = $spritz->squeeze ($len) # Squeeze	176	=item $octets = $spritz->squeeze ($len) # Squeeze
143		177
144	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.
145		369
146	=back	370	=back
147		371
148		372
149	=head2 THE Crypt::Spritz::Cipher::XOR CLASS	373	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
…		…
192		416
193	=item $encrypted = $cipher->crypt ($cleartext)	417	=item $encrypted = $cipher->crypt ($cleartext)
194		418
195	=item $cleartext = $cipher->crypt ($encrypted)	419	=item $cleartext = $cipher->crypt ($encrypted)
196		420
197	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
198	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
199	required without affecting the results.	423	required without affecting the results.
200		424
201	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	425	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
202		426
203	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>.
204		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
205	=item $constant_32 = $cipher->keysize	438	=item $constant_32 = $cipher->keysize
206		439
207	=item $constant_64 = $cipher->blocksize	440	=item $constant_64 = $cipher->blocksize
208		441
209	These methods are provided for L<Crypt::CBC> compatibility and simply	442	These methods are provided for L<Crypt::CBC> compatibility and simply
…		…
213	not a block cipher and already provides an appropriate mode.	446	not a block cipher and already provides an appropriate mode.
214		447
215	=back	448	=back
216		449
217		450
218	=head2 THE Crypt::Spritz::Hash CLASS
219
220	This implements the Spritz digest/hash algorithm. It works very similar to
221	other digest modules on CPAN, such as L<Digest::SHA3>.
222
223	Typical use for hashing:
224
225	# create hasher object
226	my $hasher = new Crypt::Spritz::Hash;
227
228	# now feed data to be hashed into $hasher
229	# in as few or many calls as required
230	$hasher->add ("Some data");
231	$hasher->add ("Some more");
232
233	# extract the hash - the object is not usable afterwards
234	my $digest = $hasher->finish (32);
235
236	=over 4
237
238	=item $hasher = new Crypt::Spritz::Hash
239
240	Creates a new hasher object.
241
242	=item $hasher->add ($data)
243
244	Adds data to be hashed into the hasher state. It doesn't matter whether
245	you pass your data in in one go or split it up, the hash will be the same.
246
247	=item $digest = $hasher->finish ($length)
248
249	Calculates a hash digest of the given length and return it. The object
250	cannot sensibly be used for further hashing afterwards.
251
252	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
253	digests, respectively.
254
255	=back
256
257
258	=head2 THE Crypt::Spritz::MAC CLASS	451	=head2 THE Crypt::Spritz::Cipher CLASS
259		452
260	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>
261	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
262	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.
263		458
264	I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where	459	So unless you need to be compatible with another implementation that does
265	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>.
266	MAC, knowledge of the (hopefully) secret key is required both to create
267	and to verify the digest.
268		461
269	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
270	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:
271		465
272	# create hasher object
273	my $hasher = new Crypt::Spritz::Mac $key;
274
275	# now feed data to be hashed into $hasher
276	# in as few or many calls as required
277	$hasher->add ("Some data");
278	$hasher->add ("Some more");
279
280	# extract the mac - the object is not usable afterwards
281	my $mac = $hasher->finish (32);
282
283	=over 4	466	=over 4
284		467
285	=item $hasher = new Crypt::Spritz::MAC $key	468	=item $encrypted = $cipher->encrypt ($cleartext)
286		469
287	Creates a new hasher object. The C<$key> can be of any length, but 16 and	470	=item $cleartext = $cipher->decrypt ($encrypted)
288	32 (128 and 256 bit) are customary.
289		471
290	=item $hasher->add ($data)	472	Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
291		473	calls and code for encryption and decryption.
292	Adds data to be hashed into the hasher state. It doesn't matter whether
293	you pass your data in in one go or split it up, the hash will be the same.
294
295	=item $mac = $hasher->finish ($length)
296
297	Calculates a message code of the given length and return it. The object
298	cannot sensibly be used for further hashing afterwards.
299
300	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
301	digests, respectively.
302		474
303	=back	475	=back
304		476
305		477
306	=head2 THE Crypt::Spritz::AEAD::XOR CLASS	478	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
…		…
385	increments, and thus reuse the same sequence number. The problem with	557	increments, and thus reuse the same sequence number. The problem with
386	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
387	generate the same randomness multiple times (randomness can be very hard	559	generate the same randomness multiple times (randomness can be very hard
388	to get especially on embedded devices).	560	to get especially on embedded devices).
389		561
390	=item $aead->associated_data ($data)(	562	=item $aead->associated_data ($data)
391		563
392	Provide the associated data (cleartext data to be authenticated but not	564	Provide the associated data (cleartext data to be authenticated but not
393	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>
394	C<crypt>.	566	C<crypt>.
395		567
…		…
404		576
405	=item $encrypted = $cipher->crypt ($cleartext)	577	=item $encrypted = $cipher->crypt ($cleartext)
406		578
407	=item $cleartext = $cipher->crypt ($encrypted)	579	=item $cleartext = $cipher->crypt ($encrypted)
408		580
409	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
410	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
411	required without affecting the results, with one exception: All except the	583	required without affecting the results, with one exception: All except the
412	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
413	last call to C<crypt> does not have this limitation.	585	last call to C<crypt> does not have this limitation.
414		586
415	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	587	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
416		588
417	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>.
418		590
419	=back	591	=item $another_cipher = $cipher->clone
420		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.
421		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
422	=head2 THE Crypt::Spritz::PRNG CLASS	614	=head2 THE Crypt::Spritz::AEAD CLASS
423		615
424	This class implements a Pseudorandom Number Generatore (B<PRNG>),	616	This class is pretty much the same as the C<Crypt::Spritz::AEAD::XOR>
425	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In	617	class, with two differences: first, it implements the "standard" Spritz
426	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.
427		621
428	Typical usage as a random number generator involves creating a PRNG	622	So unless you need to be compatible with another implementation that does
429	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>.
430	C<get>:
431		624
432	# create a PRNG object, use a seed string of your choice	625	All the methods from C<Crypt::Spritz::AEAD::XOR> are available, except
433	my $prng = new Crypt::Spritz::PRNG $seed;	626	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		627	methods:
434		628
435	# now call get as many times as you wish to get binary randomness
436	my $some_randomness = $prng->get (17);
437	my moree_randomness = $prng->get (5000);
438	...
439
440	Typical usage as a cryptographically secure random number generator is to
441	feed in some secret entropy (32 octets/256 bits are commonly considered
442	enough), for example from C</dev/random> or C</dev/urandom>, and then
443	generate some key material.
444
445	# create a PRNG object
446	my $prng = new Crypt::Spritz::PRNG;
447
448	# seed some entropy (either via ->add or in the constructor)
449	$prng->add ($some_secret_highly_entropic_string);
450
451	# now call get as many times as you wish to get
452	# hard to guess binary randomness
453	my $key1 = $prng->get (32);
454	my $key2 = $prng->get (16);
455	...
456
457	# for long running programs, it is advisable to
458	# reseed the PRNG from time to time with new entropy
459	$prng->add ($some_more_entropy);
460
461	=over 4	629	=over 4
462		630
463	=item $prng = new Crypt::Spritz::PRNG [$seed]	631	=item $encrypted = $cipher->encrypt ($cleartext)
464		632
465	Creates a new random number generator object. If C<$seed> is given, then	633	=item $cleartext = $cipher->decrypt ($encrypted)
466	the C<$seed> is added to the internal state as if by a call to C<add>.
467		634
468	=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.
469		638
470	Adds entropy to the internal state, thereby hopefully making it harder
471	to guess. Good sources for entropy are irregular hardware events, or
472	randomness provided by C</dev/urandom> or C</dev/random>.
473
474	The design of the Spritz PRNG should make it strong against attacks where
475	the attacker controls all the entropy, so it should be safe to add entropy
476	from untrusted sources - more is better than less if you need a CSPRNG.
477
478	For use as PRNG, of course, this matters very little.
479
480	=item $octets = $prng->get ($length)
481
482	Generates and returns C<$length> random octets as a string.
483
484	=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.
485		673
486		674
487	=head1 SEE ALSO	675	=head1 SEE ALSO
488		676
489	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	677	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
…		…
495	completely unproven.	683	completely unproven.
496		684
497	=head1 AUTHOR	685	=head1 AUTHOR
498		686
499	Marc Lehmann <schmorp@schmorp.de>	687	Marc Lehmann <schmorp@schmorp.de>
500	http://home.schmorp.de/	688	http://software.schmorp.de/pkg/Crypt-Spritz
501		689
502	=cut	690	=cut
503		691
504	1;	692	1;
505		693

Diff Legend

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

Comparing Crypt-Spritz/Spritz.pm (file contents): Revision 1.4 by root, Sat Jan 10 07:10:46 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.4 by root, Sat Jan 10 07:10:46 2015 UTC vs.
Revision 1.13 by root, Tue Jun 30 01:24:43 2015 UTC