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

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

Diff Legend

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

Comparing cvsroot/Crypt-Spritz/Spritz.pm (file contents): Revision 1.3 by root, Sat Jan 10 04:56:38 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.3 by root, Sat Jan 10 04:56:38 2015 UTC vs.
Revision 1.14 by root, Sun Mar 5 16:33:55 2017 UTC