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

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

…		…
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.
…		…
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.1';	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
…		…
161	Squeezes out a single byte from the state.	174	Squeezes out a single byte from the state.
162		175
163	=item $octets = $spritz->squeeze ($len) # Squeeze	176	=item $octets = $spritz->squeeze ($len) # Squeeze
164		177
165	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.
166		369
167	=back	370	=back
168		371
169		372
170	=head2 THE Crypt::Spritz::Cipher::XOR CLASS	373	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
…		…
243	not a block cipher and already provides an appropriate mode.	446	not a block cipher and already provides an appropriate mode.
244		447
245	=back	448	=back
246		449
247		450
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	451	=head2 THE Crypt::Spritz::Cipher CLASS
318		452
319	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>
320	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
321	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.
322		458
323	I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where	459	So unless you need to be compatible with another implementation that does
324	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>.
325	MAC, knowledge of the (hopefully) secret key is required both to create
326	and to verify the digest.
327		461
328	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
329	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:
330		465
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	466	=over 4
343		467
344	=item $hasher = new Crypt::Spritz::MAC $key	468	=item $encrypted = $cipher->encrypt ($cleartext)
345		469
346	Creates a new hasher object. The C<$key> can be of any length, but 16 and	470	=item $cleartext = $cipher->decrypt ($encrypted)
347	32 (128 and 256 bit) are customary.
348		471
349	=item $hasher->add ($data)	472	Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
350		473	calls and code for encryption and decryption.
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		474
370	=back	475	=back
371		476
372		477
373	=head2 THE Crypt::Spritz::AEAD::XOR CLASS	478	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
…		…
504	}	609	}
505		610
506	=back	611	=back
507		612
508		613
509	=head2 THE Crypt::Spritz::PRNG CLASS	614	=head2 THE Crypt::Spritz::AEAD CLASS
510		615
511	This class implements a Pseudorandom Number Generatore (B<PRNG>),	616	This class is pretty much the same as the C<Crypt::Spritz::AEAD::XOR>
512	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In	617	class, with two differences: first, it implements the "standard" Spritz
513	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.
514		621
515	Typical usage as a random number generator involves creating a PRNG	622	So unless you need to be compatible with another implementation that does
516	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>.
517	C<get>:
518		624
519	# create a PRNG object, use a seed string of your choice	625	All the methods from C<Crypt::Spritz::AEAD::XOR> are available, except
520	my $prng = new Crypt::Spritz::PRNG $seed;	626	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		627	methods:
521		628
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	629	=over 4
549		630
550	=item $prng = new Crypt::Spritz::PRNG [$seed]	631	=item $encrypted = $cipher->encrypt ($cleartext)
551		632
552	Creates a new random number generator object. If C<$seed> is given, then	633	=item $cleartext = $cipher->decrypt ($encrypted)
553	the C<$seed> is added to the internal state as if by a call to C<add>.
554		634
555	=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.
556		638
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	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.
572		673
573		674
574	=head1 SEE ALSO	675	=head1 SEE ALSO
575		676
576	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.6 by root, Sat Jan 10 07:48:29 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.6 by root, Sat Jan 10 07:48:29 2015 UTC vs.
Revision 1.13 by root, Tue Jun 30 01:24:43 2015 UTC