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

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.3 by root, Sat Jan 10 04:56:38 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.	46	This module implements the Spritz spongelike function (with N=256), the
		47	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
21		48
22	Although it is C<Crypt::CBC> compliant you usually gain nothing by using	49	Its strength is extreme versatility (you get a stream cipher, a hash, a
23	that module (except generality, which is often a good thing), since	50	MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
24	C<Crypt::Twofish2> can work in either ECB or CBC mode itself.	51	more) and extremely simple and small code (encryption and authentication
		52	can be had in 1KB of compiled code on amd64, which isn't an issue for most
		53	uses in Perl, but is useful in embedded situations, or e.g. when doing
		54	crypto using javascript in a browser and communicating with Perl).
25		55
26	=over 4	56	Its weakness is its relatively slow speed (encryption is a few times
		57	slower than RC4 or AES, hashing many times slower than SHA-3, although
		58	this might be reversed on an 8-bit-cpu) and the fact that it is totally
		59	unproven in the field (as of this writing, the cipher was just a few
		60	months old), so it can't be called production-ready.
		61
		62	All the usual caveats regarding stream ciphers apply - never repeat your
		63	key, never repeat your nonce and so on - you should have some basic
		64	understanding of cryptography before using this cipher in your own
		65	designs.
		66
		67	The Spritz base class is not meant for end users. To make usage simpler
		68	and safer, a number of convenience classes are provided for typical
		69	end-user tasks:
		70
		71	random number generation - Crypt::Spritz::PRNG
		72	hashing - Crypt::Spritz::Hash
		73	message authentication - Crypt::Spritz::MAC
		74	encryption - Crypt::Spritz::Cipher::XOR
		75	encryption - Crypt::Spritz::Cipher
		76	authenticated encryption - Crypt::Spritz::AEAD::XOR
		77	authenticated encryption - Crypt::Spritz::AEAD
27		78
28	=cut	79	=cut
29		80
30	package Crypt::Spritz;	81	package Crypt::Spritz;
31		82
32	use XSLoader;	83	use XSLoader;
33		84
34	$VERSION = '0.0';	85	$VERSION = 1.01;
35		86
36	XSLoader::load __PACKAGE__, $VERSION;	87	XSLoader::load __PACKAGE__, $VERSION;
37		88
38	@Crypt::Spritz::CipherBase::ISA =	89	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
		90
39	@Crypt::Spritz::Hash::ISA =	91	@Crypt::Spritz::Hash::ISA =
		92	@Crypt::Spritz::PRNG::ISA =
		93	@Crypt::Spritz::Cipher::ISA =
40	@Crypt::Spritz::PRNG::ISA = Crypt::Spritz::;	94	@Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
41		95
42	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;	96	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
43		97
44	@Crypt::Spritz::Cipher::XOR::ISA =	98	@Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::;
45	@Crypt::Spritz::Cipher::ISA =
46	@Crypt::Spritz::AEAD::ISA =
47	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::CipherBase::;	99	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
48		100
49	sub Crypt::Spritz::CipherBase::keysize () { 32 }	101	sub Crypt::Spritz::Cipher::keysize () { 32 }
50	sub Crypt::Spritz::CipherBase::blocksize () { 64 }	102	sub Crypt::Spritz::Cipher::blocksize () { 64 }
		103
		104	*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
51		105
52	*Crypt::Spritz::Hash::add =	106	*Crypt::Spritz::Hash::add =
53	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;	107	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
54		108
55	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;	109	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
56		110
57	*Crypt::Spritz::AEAD::XOR::new =
58	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;	111	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
59
60	*Crypt::Spritz::AEAD::XOR::finish =
61	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;	112	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
62		113
63	*Crypt::Spritz::AEAD::XOR::associated_data =	114	*Crypt::Spritz::AEAD::associated_data =
64	*Crypt::Spritz::AEAD::associated_data =
65	*Crypt::Spritz::AEAD::XOR::nonce =
66	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absborb_and_stop;	115	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
67		116
68	=item keysize
69		117
70	Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually	118	=head2 THE Crypt::Spritz CLASS
71	supports keylengths of 16, 24 or 32 bytes, but there is no way to
72	communicate this to C<Crypt::CBC>.
73		119
74	=item blocksize	120	This class implements most of the Spritz primitives. To use it effectively
		121	you should understand them, for example, by reading the L<Spritz
		122	paper\|http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
		123	pp. 5-6.
75		124
76	The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat	125	The Spritz primitive corresponding to the Perl method is given as
77	unique. It is also the reason I need this module myself ;)	126	comment.
78		127
79	=item $cipher = new $key [, $mode]	128	=over 4
80		129
81	Create a new C<Crypt::Twofish2> cipher object with the given key (which	130	=item $spritz = new Crypt::Spritz # InitializeState
82	must be 128, 192 or 256 bits long). The additional C<$mode> argument is
83	the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the
84	default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC>
85	does) or C<MODE_CFB1> (1-bit cipher feedback mode).
86		131
87	ECB mode is very insecure (read a book on cryptography if you don't know	132	Creates and returns a new, initialised Spritz state.
88	why!), so you should probably use CBC mode. CFB1 mode is not tested and is
89	most probably broken, so do not try to use it.
90		133
91	In ECB mode you can use the same cipher object to encrypt and decrypt	134	=item $spritz->init # InitializeState
92	data. However, every change of "direction" causes an internal reordering
93	of key data, which is quite slow, so if you want ECB mode and
94	encryption/decryption at the same time you should create two seperate
95	C<Crypt::Twofish2> objects with the same key.
96		135
97	In CBC mode you have to use seperate objects for encryption/decryption in	136	Initialises the Spritz state again, throwing away the previous state.
98	any case.
99		137
100	The C<MODE_*>-constants are not exported by this module, so you must	138	=item $another_spritz = $spritz->clone
101	specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
102		139
103	=item $cipher->encrypt($data)	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.
104		143
105	Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16	144	=item $spritz->update # Update
106	bytes), otherwise this function will croak. Apart from that, it can be of
107	(almost) any length.
108		145
109	=item $cipher->decrypt($data)	146	=item $spritz->whip ($r) # Whip
110		147
111	The pendant to C<encrypt> in that it I<de>crypts data again.	148	=item $spritz->crush # Crush
112		149
		150	=item $spritz->shuffle # Shuffle
		151
		152	=item $spritz->output # Output
		153
		154	Calls the Spritz primitive ovf the same name - these are not normally
		155	called manually.
		156
		157	=item $spritz->absorb ($I) # Absorb
		158
		159	Absorbs the given data into the state (usually used for key material,
		160	nonces, IVs messages to be hashed and so on).
		161
		162	=item $spritz->absorb_stop # AbsorbStop
		163
		164	Absorbs a special stop symbol - this is usually used as delimiter between
		165	multiple strings to be absorbed, to thwart extension attacks.
		166
		167	=item $spritz->absorb_and_stop ($I)
		168
		169	This is a convenience function that simply calls C<absorb> followed by
		170	C<absorb_stop>.
		171
		172	=item $octet = $spritz->drip # Drip
		173
		174	Squeezes out a single byte from the state.
		175
		176	=item $octets = $spritz->squeeze ($len) # Squeeze
		177
		178	Squeezes out the requested number of bytes from the state - this is usually
		179
113	=back	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.
		369
		370	=back
		371
		372
		373	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
		374
		375	This class implements stream encryption/decryption. It doesn't implement
		376	the standard Spritz encryption but the XOR variant (called B<spritz-xor>
		377	in the paper).
		378
		379	The XOR variant should be as secure as the standard variant, but
		380	doesn't have separate encryption and decryaption functions, which saves
		381	codesize. IT is not compatible with standard Spritz encryption, however -
		382	drop me a note if you want that implemented as well.
		383
		384	Typical use for encryption I<and> decryption (code is identical for
		385	decryption, you simply pass the encrypted data to C<crypt>):
		386
		387	# create a cipher - $salt can be a random string you send
		388	# with your message, in clear, a counter (best), or empty if
		389	# you only want to encrypt one message with the given key.
		390	# 16 or 32 octets are typical sizes for the key, for the salt,
		391	# use whatever you need to give a unique salt for every
		392	# message you encrypt with the same key.
		393
		394	my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;
		395
		396	# encrypt a message in one or more calls to crypt
		397
		398	my $encrypted;
		399
		400	$encrypted .= $cipher->crypt ("This is");
		401	$encrypted .= $cipher->crypt ("all very");
		402	$encrypted .= $cipher->crypt ("secret");
		403
		404	# that's all
		405
		406	=over 4
		407
		408	=item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
		409
		410	Creates a new cipher object usable for encryption and decryption. The
		411	C<$key> must be provided, the initial vector C<$IV> is optional.
		412
		413	Both C<$key> and C<$IV> can be of any length. Typical lengths for the
		414	C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
		415	be long enough to distinguish repeated uses of tghe same key.
		416
		417	=item $encrypted = $cipher->crypt ($cleartext)
		418
		419	=item $cleartext = $cipher->crypt ($encrypted)
		420
		421	Encrypt or decrypt a piece of a message. This can be called as many times
		422	as you want, and the message can be split into as few or many pieces as
		423	required without affecting the results.
		424
		425	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		426
		427	Same as C<crypt>, except it I<modifies the argument in-place>.
		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
		438	=item $constant_32 = $cipher->keysize
		439
		440	=item $constant_64 = $cipher->blocksize
		441
		442	These methods are provided for L<Crypt::CBC> compatibility and simply
		443	return C<32> and C<64>, respectively.
		444
		445	Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
		446	not a block cipher and already provides an appropriate mode.
		447
		448	=back
		449
		450
		451	=head2 THE Crypt::Spritz::Cipher CLASS
		452
		453	This class is pretty much the same as the C<Crypt::Spritz::Cipher::XOR>
		454	class, with two differences: first, it implements the "standard" Spritz
		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.
		458
		459	So unless you need to be compatible with another implementation that does
		460	not offer the XOR variant, stick to C<Crypt::Spritz::Cipher::XOR>.
		461
		462	All the methods from C<Crypt::Spritz::Cipher::XOR> are available, except
		463	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		464	methods:
		465
		466	=over 4
		467
		468	=item $encrypted = $cipher->encrypt ($cleartext)
		469
		470	=item $cleartext = $cipher->decrypt ($encrypted)
		471
		472	Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
		473	calls and code for encryption and decryption.
		474
		475	=back
		476
		477
		478	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
		479
		480	This is the most complicated class - it combines encryption and
		481	message authentication into a single "authenticated encryption
		482	mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
		483	L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
		484	them.
		485
		486	You can additionally provide cleartext data that will not be encrypted or
		487	decrypted, but that is nevertheless authenticated using the MAC, which
		488	is why this mode is called I<AEAD>, I<Authenticated Encryption with
		489	Associated Data>. Associated data is usually used to any header data that
		490	is in cleartext, but should nevertheless be authenticated.
		491
		492	This implementation implements the XOR variant. Just as with
		493	L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
		494	the standard mode, but uses less code and doesn't distinguish between
		495	encryption and decryption.
		496
		497	Typical usage is as follows:
		498
		499	# create a new aead object
		500	# you use one object per message
		501	# key length customarily is 16 or 32
		502	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		503
		504	# now you must feed the nonce. if you do not need a nonce,
		505	# you can provide the empty string, but you have to call it
		506	# after creating the object, before calling associated_data.
		507	# the nonce must be different for each usage of the $key.
		508	# a counter of some kind is good enough.
		509	# reusing a nonce with the same key completely
		510	# destroys security!
		511	$aead->nonce ($counter);
		512
		513	# then you must feed any associated data you have. if you
		514	# do not have associated cleartext data, you can provide the empty
		515	# string, but you have to call it after nonce and before crypt.
		516	$aead->associated_data ($header);
		517
		518	# next, you call crypt one or more times with your data
		519	# to be encrypted (opr decrypted).
		520	# all except the last call must use a length that is a
		521	# multiple of 64.
		522	# the last block can have any length.
		523	my $encrypted;
		524
		525	$encrypted .= $aead->crypt ("1" x 64);
		526	$encrypted .= $aead->crypt ("2" x 64);
		527	$encrypted .= $aead->crypt ("3456");
		528
		529	# finally you can calculate the MAC for all of the above
		530	my $mac = $aead->finish;
		531
		532	=over 4
		533
		534	=item $aead = new Crypt::Spritz::AEAD::XOR $key
		535
		536	Creates a new cipher object usable for encryption and decryption.
		537
		538	The C<$key> can be of any length. Typical lengths for the C<$key> are 16
		539	(128 bit) or 32 (256 bit).
		540
		541	After creation, you have to call C<nonce> next.
		542
		543	=item $aead->nonce ($nonce)
		544
		545	Provide the nonce value (nonce means "value used once"), a value the is
		546	unique between all uses with the same key. This method I<must> be called
		547	I<after> C<new> and I<before> C<associated_data>.
		548
		549	If you only ever use a given key once, you can provide an empty nonce -
		550	but you still have to call the method.
		551
		552	Common strategies to provide a nonce are to implement a persistent counter
		553	or to generate a random string of sufficient length to guarantee that it
		554	differs each time.
		555
		556	The problem with counters is that you might get confused and forget
		557	increments, and thus reuse the same sequence number. The problem with
		558	random strings i that your random number generator might be hosed and
		559	generate the same randomness multiple times (randomness can be very hard
		560	to get especially on embedded devices).
		561
		562	=item $aead->associated_data ($data)
		563
		564	Provide the associated data (cleartext data to be authenticated but not
		565	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
		566	C<crypt>.
		567
		568	If you don't have any associated data, you can provide an empty string -
		569	but you still have to call the method.
		570
		571	Associated data is typically header data - data anybody is allowed to
		572	see in cleartext, but that should nevertheless be protected with an
		573	authentication code. Typically such data is used to identify where to
		574	forward a message to, how to find the key to decrypt the message or in
		575	general how to interpret the encrypted part of a message.
		576
		577	=item $encrypted = $cipher->crypt ($cleartext)
		578
		579	=item $cleartext = $cipher->crypt ($encrypted)
		580
		581	Encrypt or decrypt a piece of a message. This can be called as many times
		582	as you want, and the message can be split into as few or many pieces as
		583	required without affecting the results, with one exception: All except the
		584	last call to C<crypt> needs to pass in a multiple of C<64> octets. The
		585	last call to C<crypt> does not have this limitation.
		586
		587	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		588
		589	Same as C<crypt>, except it I<modifies the argument in-place>.
		590
		591	=item $another_cipher = $cipher->clone
		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.
		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
		614	=head2 THE Crypt::Spritz::AEAD CLASS
		615
		616	This class is pretty much the same as the C<Crypt::Spritz::AEAD::XOR>
		617	class, with two differences: first, it implements the "standard" Spritz
		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.
		621
		622	So unless you need to be compatible with another implementation that does
		623	not offer the XOR variant, stick to C<Crypt::Spritz::AEAD::XOR>.
		624
		625	All the methods from C<Crypt::Spritz::AEAD::XOR> are available, except
		626	C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
		627	methods:
		628
		629	=over 4
		630
		631	=item $encrypted = $cipher->encrypt ($cleartext)
		632
		633	=item $cleartext = $cipher->decrypt ($encrypted)
		634
		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.
		638
		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.
		673
114		674
115	=head1 SEE ALSO	675	=head1 SEE ALSO
116		676
117	L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	677	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
118		678
119	=head1 SECURITY CONSIDERATIONS	679	=head1 SECURITY CONSIDERATIONS
120		680
121	I also cannot guarantee for security.	681	I also cannot give any guarantees for security, Spritz is a very new
		682	cryptographic algorithm, and when this module was written, almost
		683	completely unproven.
122		684
123	=head1 AUTHOR	685	=head1 AUTHOR
124		686
125	Marc Lehmann <schmorp@schmorp.de>	687	Marc Lehmann <schmorp@schmorp.de>
126	http://home.schmorp.de/	688	http://software.schmorp.de/pkg/Crypt-Spritz
127
128	The actual twofish encryption is written in horribly microsoft'ish looking
129	almost ansi-c by Doug Whiting.
130		689
131	=cut	690	=cut
132		691
133	1;	692	1;
134		693

Diff Legend

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

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