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

Comparing cvsroot/Crypt-Spritz/Spritz.pm (file contents):
Revision 1.4 by root, Sat Jan 10 07:10:46 2015 UTC vs.
Revision 1.14 by root, Sun Mar 5 16:33:55 2017 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;
		43
		44	=head1 WARNING
		45
		46	The best known result (early 2017) against Spritz is a distinguisher
		47	attack on 244 outputs with multiple keys/IVs, and on 260 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.
17		51
18	=head1 DESCRIPTION	52	=head1 DESCRIPTION
19		53
20	This module implements the Spritz spongelike function (with N=256), the	54	This module implements the Spritz spongelike function (with N=256), the
21	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.	55	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	65	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	66	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	67	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.	68	months old), so it can't be called production-ready.
35		69
36	All the usual caveats regarding stream ciphers apply - never repeat	70	All the usual caveats regarding stream ciphers apply - never repeat your
37	your key, never repeat your nonce etc. - you should have some basic	71	key, never repeat your nonce and so on - you should have some basic
38	understanding of cryptography before using this cipher in your own	72	understanding of cryptography before using this cipher in your own
39	designs.	73	designs.
40		74
41	The Spritz base class is not meant for end users. To make usage simpler	75	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	76	and safer, a number of convenience classes are provided for typical
43	end-user tasks:	77	end-user tasks:
44		78
45	encryption - Crypt::Spritz::Cipher::XOR	79	random number generation - Crypt::Spritz::PRNG
46	hashing - Crypt::Spritz::Hash	80	hashing - Crypt::Spritz::Hash
47	message authentication - Crypt::Spritz::MAC	81	message authentication - Crypt::Spritz::MAC
		82	encryption - Crypt::Spritz::Cipher::XOR
		83	encryption - Crypt::Spritz::Cipher
48	authenticated encryption - Crypt::Spritz::AEAD::XOR	84	authenticated encryption - Crypt::Spritz::AEAD::XOR
49	random number generation - Crypt::Spritz::PRNG	85	authenticated encryption - Crypt::Spritz::AEAD
50		86
51	=cut	87	=cut
52		88
53	package Crypt::Spritz;	89	package Crypt::Spritz;
54		90
55	use XSLoader;	91	use XSLoader;
56		92
57	$VERSION = '0.0';	93	$VERSION = 1.02;
58		94
59	XSLoader::load __PACKAGE__, $VERSION;	95	XSLoader::load __PACKAGE__, $VERSION;
60		96
61	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;	97	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
62		98
…		…
89		125
90	=head2 THE Crypt::Spritz CLASS	126	=head2 THE Crypt::Spritz CLASS
91		127
92	This class implements most of the Spritz primitives. To use it effectively	128	This class implements most of the Spritz primitives. To use it effectively
93	you should understand them, for example, by reading the L<Spritz	129	you should understand them, for example, by reading the L<Spritz
94	paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially	130	paper\|http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
95	pp. 5-6.	131	pp. 5-6.
96		132
97	The Spritz primitive corresponding to the Perl method is given as	133	The Spritz primitive corresponding to the Perl method is given as
98	comment.	134	comment.
99		135
…		…
105		141
106	=item $spritz->init # InitializeState	142	=item $spritz->init # InitializeState
107		143
108	Initialises the Spritz state again, throwing away the previous state.	144	Initialises the Spritz state again, throwing away the previous state.
109		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
110	=item $spritz->update # Update	152	=item $spritz->update # Update
111		153
112	=item $spritz->whip ($r) # Whip	154	=item $spritz->whip ($r) # Whip
113		155
114	=item $spritz->crush # Crush	156	=item $spritz->crush # Crush
…		…
120	Calls the Spritz primitive ovf the same name - these are not normally	162	Calls the Spritz primitive ovf the same name - these are not normally
121	called manually.	163	called manually.
122		164
123	=item $spritz->absorb ($I) # Absorb	165	=item $spritz->absorb ($I) # Absorb
124		166
125	Absorbs the given data into the state (usually used for key material, nonces, IVs	167	Absorbs the given data into the state (usually used for key material,
126	messages to be hashed and so on).	168	nonces, IVs messages to be hashed and so on).
127		169
128	=item $spritz->absorb_stop # AbsorbStop	170	=item $spritz->absorb_stop # AbsorbStop
129		171
130	Absorbs a special stop symbol - this is usually used as delimiter between	172	Absorbs a special stop symbol - this is usually used as delimiter between
131	multiple strings to be absorbed, to thwart extension attacks.	173	multiple strings to be absorbed, to thwart extension attacks.
…		…
140	Squeezes out a single byte from the state.	182	Squeezes out a single byte from the state.
141		183
142	=item $octets = $spritz->squeeze ($len) # Squeeze	184	=item $octets = $spritz->squeeze ($len) # Squeeze
143		185
144	Squeezes out the requested number of bytes from the state - this is usually	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.
145		377
146	=back	378	=back
147		379
148		380
149	=head2 THE Crypt::Spritz::Cipher::XOR CLASS	381	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
…		…
192		424
193	=item $encrypted = $cipher->crypt ($cleartext)	425	=item $encrypted = $cipher->crypt ($cleartext)
194		426
195	=item $cleartext = $cipher->crypt ($encrypted)	427	=item $cleartext = $cipher->crypt ($encrypted)
196		428
197	Encrypt or decrypt a piece of a message. This cna be called as many times	429	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	430	as you want, and the message can be split into as few or many pieces as
199	required without affecting the results.	431	required without affecting the results.
200		432
201	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	433	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
202		434
203	Same as C<crypt>, except it I<modifies the argument in-place>.	435	Same as C<crypt>, except it I<modifies the argument in-place>.
204		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
205	=item $constant_32 = $cipher->keysize	446	=item $constant_32 = $cipher->keysize
206		447
207	=item $constant_64 = $cipher->blocksize	448	=item $constant_64 = $cipher->blocksize
208		449
209	These methods are provided for L<Crypt::CBC> compatibility and simply	450	These methods are provided for L<Crypt::CBC> compatibility and simply
…		…
213	not a block cipher and already provides an appropriate mode.	454	not a block cipher and already provides an appropriate mode.
214		455
215	=back	456	=back
216		457
217		458
218	=head2 THE Crypt::Spritz::Hash CLASS	459	=head2 THE Crypt::Spritz::Cipher CLASS
219		460
220	This implements the Spritz digest/hash algorithm. It works very similar to	461	This class is pretty much the same as the C<Crypt::Spritz::Cipher::XOR>
221	other digest modules on CPAN, such as L<Digest::SHA3>.	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.
222		466
223	Typical use for hashing:	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>.
224		469
225	# create hasher object	470	All the methods from C<Crypt::Spritz::Cipher::XOR> are available, except
226	my $hasher = new Crypt::Spritz::Hash;	471	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
227		472	methods:
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		473
236	=over 4	474	=over 4
237		475
238	=item $hasher = new Crypt::Spritz::Hash	476	=item $encrypted = $cipher->encrypt ($cleartext)
239		477
240	Creates a new hasher object.	478	=item $cleartext = $cipher->decrypt ($encrypted)
241		479
242	=item $hasher->add ($data)	480	Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
243		481	calls and code for encryption and decryption.
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
259
260	This implements the Spritz Message Authentication Code algorithm. It works
261	very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
262	implements an authenticated digest (like L<Digest::HMAC>).
263
264	I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
265	everybody can verify and recreate the hash value for some data, with a
266	MAC, knowledge of the (hopefully) secret key is required both to create
267	and to verify the digest.
268
269	Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
270	except a key (typically 16 or 32 octets) is provided to the constructor:
271
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
284
285	=item $hasher = new Crypt::Spritz::MAC $key
286
287	Creates a new hasher object. The C<$key> can be of any length, but 16 and
288	32 (128 and 256 bit) are customary.
289
290	=item $hasher->add ($data)
291
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		482
303	=back	483	=back
304		484
305		485
306	=head2 THE Crypt::Spritz::AEAD::XOR CLASS	486	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
…		…
385	increments, and thus reuse the same sequence number. The problem with	565	increments, and thus reuse the same sequence number. The problem with
386	random strings i that your random number generator might be hosed and	566	random strings i that your random number generator might be hosed and
387	generate the same randomness multiple times (randomness can be very hard	567	generate the same randomness multiple times (randomness can be very hard
388	to get especially on embedded devices).	568	to get especially on embedded devices).
389		569
390	=item $aead->associated_data ($data)(	570	=item $aead->associated_data ($data)
391		571
392	Provide the associated data (cleartext data to be authenticated but not	572	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>	573	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
394	C<crypt>.	574	C<crypt>.
395		575
…		…
404		584
405	=item $encrypted = $cipher->crypt ($cleartext)	585	=item $encrypted = $cipher->crypt ($cleartext)
406		586
407	=item $cleartext = $cipher->crypt ($encrypted)	587	=item $cleartext = $cipher->crypt ($encrypted)
408		588
409	Encrypt or decrypt a piece of a message. This cna be called as many times	589	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	590	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	591	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	592	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.	593	last call to C<crypt> does not have this limitation.
414		594
415	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	595	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
416		596
417	Same as C<crypt>, except it I<modifies the argument in-place>.	597	Same as C<crypt>, except it I<modifies the argument in-place>.
418		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
419	=back	619	=back
420		620
421		621
422	=head2 THE Crypt::Spritz::PRNG CLASS	622	=head2 THE Crypt::Spritz::AEAD CLASS
423		623
424	This class implements a Pseudorandom Number Generatore (B<PRNG>),	624	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	625	class, with two differences: first, it implements the "standard" Spritz
426	fact, it is even cryptographically secure, making it a B<CSPRNG>.	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.
427		629
428	Typical usage as a random number generator involves creating a PRNG	630	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	631	not offer the XOR variant, stick to C<Crypt::Spritz::AEAD::XOR>.
430	C<get>:
431		632
432	# create a PRNG object, use a seed string of your choice	633	All the methods from C<Crypt::Spritz::AEAD::XOR> are available, except
433	my $prng = new Crypt::Spritz::PRNG $seed;	634	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
434		635	methods:
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		636
461	=over 4	637	=over 4
462		638
463	=item $prng = new Crypt::Spritz::PRNG [$seed]	639	=item $encrypted = $cipher->encrypt ($cleartext)
464		640
465	Creates a new random number generator object. If C<$seed> is given, then	641	=item $cleartext = $cipher->decrypt ($encrypted)
466	the C<$seed> is added to the internal state as if by a call to C<add>.
467		642
468	=item $prng->add ($entropy)	643	Really the same as C<Crypt::Spritz::AEAD::XOR>, except you need separate
469		644	calls and code for encryption and decryption, but you have the same
470	Adds entropy to the internal state, thereby hopefully making it harder	645	limitations on usage.
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		646
484	=back	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.
485		681
486		682
487	=head1 SEE ALSO	683	=head1 SEE ALSO
488		684
489	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	685	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
…		…
495	completely unproven.	691	completely unproven.
496		692
497	=head1 AUTHOR	693	=head1 AUTHOR
498		694
499	Marc Lehmann <schmorp@schmorp.de>	695	Marc Lehmann <schmorp@schmorp.de>
500	http://home.schmorp.de/	696	http://software.schmorp.de/pkg/Crypt-Spritz
501		697
502	=cut	698	=cut
503		699
504	1;	700	1;
505		701

Diff Legend

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

Comparing cvsroot/Crypt-Spritz/Spritz.pm (file contents): Revision 1.4 by root, Sat Jan 10 07:10:46 2015 UTC vs. Revision 1.14 by root, Sun Mar 5 16:33:55 2017 UTC

Diff Legend

Comparing cvsroot/Crypt-Spritz/Spritz.pm (file contents):
Revision 1.4 by root, Sat Jan 10 07:10:46 2015 UTC vs.
Revision 1.14 by root, Sun Mar 5 16:33:55 2017 UTC