[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.6 by root, Sat Jan 10 07:48:29 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
14	$crypted = $cipher->encrypt($plaintext);	13	$ciphertext = $cipher->crypt ($cleartext);
15	# - OR -	14
16	$plaintext = $cipher->decrypt($crypted);	15	my $hasher = new Crypt::Spritz::Hash;
		16	$hasher->add ($data);
		17	$digest = $hasher->finish;
		18
		19	my $hasher = new Crypt::Spritz::MAC $key;
		20	$hasher->add ($data);
		21	$mac = $hasher->finish;
		22
		23	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		24	$aead->nonce ($counter);
		25	$aead->associated_data ($header);
		26	$ciphertext = $aead->crypt ($cleartext);
		27	$mac = $aead->mac;
		28
		29	my $prng = new Crypt::Spritz::PRNG $entropy;
		30	$prng->add ($additional_entropy);
		31	$keydata = $prng->get (32);
17		32
18	=head1 DESCRIPTION	33	=head1 DESCRIPTION
19		34
20	This module implements the Spritz spongelike function (with N=256), the	35	This module implements the Spritz spongelike function (with N=256), the
21	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.	36	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	46	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	47	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	48	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.	49	months old), so it can't be called production-ready.
35		50
36	All the usual caveats regarding stream ciphers apply - never repeat	51	All the usual caveats regarding stream ciphers apply - never repeat your
37	your key, never repeat your nonce etc. - you should have some basic	52	key, never repeat your nonce and so on - you should have some basic
38	understanding of cryptography before using this cipher in your own	53	understanding of cryptography before using this cipher in your own
39	designs.	54	designs.
40		55
41	The Spritz base class is not meant for end users. To make usage simpler	56	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	57	and safer, a number of convenience classes are provided for typical
…		…
52		67
53	package Crypt::Spritz;	68	package Crypt::Spritz;
54		69
55	use XSLoader;	70	use XSLoader;
56		71
57	$VERSION = '0.0';	72	$VERSION = '0.1';
58		73
59	XSLoader::load __PACKAGE__, $VERSION;	74	XSLoader::load __PACKAGE__, $VERSION;
60		75
61	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;	76	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
62		77
…		…
105		120
106	=item $spritz->init # InitializeState	121	=item $spritz->init # InitializeState
107		122
108	Initialises the Spritz state again, throwing away the previous state.	123	Initialises the Spritz state again, throwing away the previous state.
109		124
		125	=item $another_spritz = $spritz->clone
		126
		127	Make an exact copy of the spritz state. This method can be called on all
		128	of the objects in this module, but is documented separately to give some
		129	cool usage examples.
		130
110	=item $spritz->update # Update	131	=item $spritz->update # Update
111		132
112	=item $spritz->whip ($r) # Whip	133	=item $spritz->whip ($r) # Whip
113		134
114	=item $spritz->crush # Crush	135	=item $spritz->crush # Crush
…		…
120	Calls the Spritz primitive ovf the same name - these are not normally	141	Calls the Spritz primitive ovf the same name - these are not normally
121	called manually.	142	called manually.
122		143
123	=item $spritz->absorb ($I) # Absorb	144	=item $spritz->absorb ($I) # Absorb
124		145
125	Absorbs the given data into the state (usually used for key material, nonces, IVs	146	Absorbs the given data into the state (usually used for key material,
126	messages to be hashed and so on).	147	nonces, IVs messages to be hashed and so on).
127		148
128	=item $spritz->absorb_stop # AbsorbStop	149	=item $spritz->absorb_stop # AbsorbStop
129		150
130	Absorbs a special stop symbol - this is usually used as delimiter between	151	Absorbs a special stop symbol - this is usually used as delimiter between
131	multiple strings to be absorbed, to thwart extension attacks.	152	multiple strings to be absorbed, to thwart extension attacks.
…		…
192		213
193	=item $encrypted = $cipher->crypt ($cleartext)	214	=item $encrypted = $cipher->crypt ($cleartext)
194		215
195	=item $cleartext = $cipher->crypt ($encrypted)	216	=item $cleartext = $cipher->crypt ($encrypted)
196		217
197	Encrypt or decrypt a piece of a message. This cna be called as many times	218	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	219	as you want, and the message can be split into as few or many pieces as
199	required without affecting the results.	220	required without affecting the results.
200		221
201	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	222	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
202		223
203	Same as C<crypt>, except it I<modifies the argument in-place>.	224	Same as C<crypt>, except it I<modifies the argument in-place>.
		225
		226	=item $another_cipher = $cipher->clone
		227
		228	Make an exact copy of the cipher state. This can be useful to cache states
		229	for reuse later, for example, to avoid expensive key setups.
		230
		231	While there might be use cases for this feature, it makes a lot more sense
		232	for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
		233	you to specify the IV/nonce separately.
204		234
205	=item $constant_32 = $cipher->keysize	235	=item $constant_32 = $cipher->keysize
206		236
207	=item $constant_64 = $cipher->blocksize	237	=item $constant_64 = $cipher->blocksize
208		238
…		…
250	cannot sensibly be used for further hashing afterwards.	280	cannot sensibly be used for further hashing afterwards.
251		281
252	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit	282	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
253	digests, respectively.	283	digests, respectively.
254		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
255	=back	314	=back
256		315
257		316
258	=head2 THE Crypt::Spritz::MAC CLASS	317	=head2 THE Crypt::Spritz::MAC CLASS
259		318
…		…
297	Calculates a message code of the given length and return it. The object	356	Calculates a message code of the given length and return it. The object
298	cannot sensibly be used for further hashing afterwards.	357	cannot sensibly be used for further hashing afterwards.
299		358
300	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit	359	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
301	digests, respectively.	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.
302		369
303	=back	370	=back
304		371
305		372
306	=head2 THE Crypt::Spritz::AEAD::XOR CLASS	373	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
…		…
385	increments, and thus reuse the same sequence number. The problem with	452	increments, and thus reuse the same sequence number. The problem with
386	random strings i that your random number generator might be hosed and	453	random strings i that your random number generator might be hosed and
387	generate the same randomness multiple times (randomness can be very hard	454	generate the same randomness multiple times (randomness can be very hard
388	to get especially on embedded devices).	455	to get especially on embedded devices).
389		456
390	=item $aead->associated_data ($data)(	457	=item $aead->associated_data ($data)
391		458
392	Provide the associated data (cleartext data to be authenticated but not	459	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>	460	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
394	C<crypt>.	461	C<crypt>.
395		462
…		…
404		471
405	=item $encrypted = $cipher->crypt ($cleartext)	472	=item $encrypted = $cipher->crypt ($cleartext)
406		473
407	=item $cleartext = $cipher->crypt ($encrypted)	474	=item $cleartext = $cipher->crypt ($encrypted)
408		475
409	Encrypt or decrypt a piece of a message. This cna be called as many times	476	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	477	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	478	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	479	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.	480	last call to C<crypt> does not have this limitation.
414		481
415	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)	482	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
416		483
417	Same as C<crypt>, except it I<modifies the argument in-place>.	484	Same as C<crypt>, except it I<modifies the argument in-place>.
		485
		486	=item $another_cipher = $cipher->clone
		487
		488	Make an exact copy of the cipher state. This can be useful to cache states
		489	for reuse later, for example, to avoid expensive key setups.
		490
		491	Example: set up a cipher state with a key, then clone and use it to
		492	encrypt messages with different nonces.
		493
		494	my $cipher = new Crypt::Spritz::AEAD::XOR $key;
		495
		496	my $message_counter;
		497
		498	for my $message ("a", "b", "c") {
		499	my $clone = $cipher->clone;
		500	$clone->nonce (pack "N", ++$message_counter);
		501	$clone->associated_data ("");
		502	my $encrypted = $clone->crypt ($message);
		503	...
		504	}
418		505
419	=back	506	=back
420		507
421		508
422	=head2 THE Crypt::Spritz::PRNG CLASS	509	=head2 THE Crypt::Spritz::PRNG CLASS
…		…
495	completely unproven.	582	completely unproven.
496		583
497	=head1 AUTHOR	584	=head1 AUTHOR
498		585
499	Marc Lehmann <schmorp@schmorp.de>	586	Marc Lehmann <schmorp@schmorp.de>
500	http://home.schmorp.de/	587	http://software.schmorp.de/pkg/Crypt-Spritz
501		588
502	=cut	589	=cut
503		590
504	1;	591	1;
505		592

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.6 by root, Sat Jan 10 07:48:29 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.6 by root, Sat Jan 10 07:48:29 2015 UTC