[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.4 by root, Sat Jan 10 07:10:46 2015 UTC

…		…
15	# - OR -	15	# - OR -
16	$plaintext = $cipher->decrypt($crypted);	16	$plaintext = $cipher->decrypt($crypted);
17		17
18	=head1 DESCRIPTION	18	=head1 DESCRIPTION
19		19
20	This module implements the spritz spongelike function.	20	This module implements the Spritz spongelike function (with N=256), the
		21	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
21		22
22	Although it is C<Crypt::CBC> compliant you usually gain nothing by using	23	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	24	MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
24	C<Crypt::Twofish2> can work in either ECB or CBC mode itself.	25	more) and extremely simple and small code (encryption and authentication
		26	can be had in 1KB of compiled code on amd64, which isn't an issue for most
		27	uses in Perl, but is useful in embedded situations, or e.g. when doing
		28	crypto using javascript in a browser and communicating with Perl).
25		29
26	=over 4	30	Its weakness is its relatively slow speed (encryption is a few times
		31	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
		33	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.
		35
		36	All the usual caveats regarding stream ciphers apply - never repeat
		37	your key, never repeat your nonce etc. - you should have some basic
		38	understanding of cryptography before using this cipher in your own
		39	designs.
		40
		41	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
		43	end-user tasks:
		44
		45	encryption - Crypt::Spritz::Cipher::XOR
		46	hashing - Crypt::Spritz::Hash
		47	message authentication - Crypt::Spritz::MAC
		48	authenticated encryption - Crypt::Spritz::AEAD::XOR
		49	random number generation - Crypt::Spritz::PRNG
27		50
28	=cut	51	=cut
29		52
30	package Crypt::Spritz;	53	package Crypt::Spritz;
31		54
…		…
33		56
34	$VERSION = '0.0';	57	$VERSION = '0.0';
35		58
36	XSLoader::load __PACKAGE__, $VERSION;	59	XSLoader::load __PACKAGE__, $VERSION;
37		60
38	@Crypt::Spritz::CipherBase::ISA =	61	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
		62
39	@Crypt::Spritz::Hash::ISA =	63	@Crypt::Spritz::Hash::ISA =
		64	@Crypt::Spritz::PRNG::ISA =
		65	@Crypt::Spritz::Cipher::ISA =
40	@Crypt::Spritz::PRNG::ISA = Crypt::Spritz::;	66	@Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
41		67
42	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;	68	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
43		69
44	@Crypt::Spritz::Cipher::XOR::ISA =	70	@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::;	71	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
48		72
49	sub Crypt::Spritz::CipherBase::keysize () { 32 }	73	sub Crypt::Spritz::Cipher::keysize () { 32 }
50	sub Crypt::Spritz::CipherBase::blocksize () { 64 }	74	sub Crypt::Spritz::Cipher::blocksize () { 64 }
		75
		76	*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
51		77
52	*Crypt::Spritz::Hash::add =	78	*Crypt::Spritz::Hash::add =
53	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;	79	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
54		80
55	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;	81	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
56		82
57	*Crypt::Spritz::AEAD::XOR::new =
58	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;	83	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
59
60	*Crypt::Spritz::AEAD::XOR::finish =
61	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;	84	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
62		85
63	*Crypt::Spritz::AEAD::XOR::associated_data =	86	*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;	87	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
67		88
68	=item keysize
69		89
70	Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually	90	=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		91
74	=item blocksize	92	This class implements most of the Spritz primitives. To use it effectively
		93	you should understand them, for example, by reading the L<Spritz
		94	paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
		95	pp. 5-6.
75		96
76	The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat	97	The Spritz primitive corresponding to the Perl method is given as
77	unique. It is also the reason I need this module myself ;)	98	comment.
78		99
79	=item $cipher = new $key [, $mode]	100	=over 4
80		101
81	Create a new C<Crypt::Twofish2> cipher object with the given key (which	102	=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		103
87	ECB mode is very insecure (read a book on cryptography if you don't know	104	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		105
91	In ECB mode you can use the same cipher object to encrypt and decrypt	106	=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		107
97	In CBC mode you have to use seperate objects for encryption/decryption in	108	Initialises the Spritz state again, throwing away the previous state.
98	any case.
99		109
100	The C<MODE_*>-constants are not exported by this module, so you must	110	=item $spritz->update # Update
101	specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
102		111
103	=item $cipher->encrypt($data)	112	=item $spritz->whip ($r) # Whip
104		113
105	Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16	114	=item $spritz->crush # Crush
106	bytes), otherwise this function will croak. Apart from that, it can be of
107	(almost) any length.
108		115
109	=item $cipher->decrypt($data)	116	=item $spritz->shuffle # Shuffle
110		117
111	The pendant to C<encrypt> in that it I<de>crypts data again.	118	=item $spritz->output # Output
		119
		120	Calls the Spritz primitive ovf the same name - these are not normally
		121	called manually.
		122
		123	=item $spritz->absorb ($I) # Absorb
		124
		125	Absorbs the given data into the state (usually used for key material, nonces, IVs
		126	messages to be hashed and so on).
		127
		128	=item $spritz->absorb_stop # AbsorbStop
		129
		130	Absorbs a special stop symbol - this is usually used as delimiter between
		131	multiple strings to be absorbed, to thwart extension attacks.
		132
		133	=item $spritz->absorb_and_stop ($I)
		134
		135	This is a convenience function that simply calls C<absorb> followed by
		136	C<absorb_stop>.
		137
		138	=item $octet = $spritz->drip # Drip
		139
		140	Squeezes out a single byte from the state.
		141
		142	=item $octets = $spritz->squeeze ($len) # Squeeze
		143
		144	Squeezes out the requested number of bytes from the state - this is usually
112		145
113	=back	146	=back
114		147
		148
		149	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
		150
		151	This class implements stream encryption/decryption. It doesn't implement
		152	the standard Spritz encryption but the XOR variant (called B<spritz-xor>
		153	in the paper).
		154
		155	The XOR variant should be as secure as the standard variant, but
		156	doesn't have separate encryption and decryaption functions, which saves
		157	codesize. IT is not compatible with standard Spritz encryption, however -
		158	drop me a note if you want that implemented as well.
		159
		160	Typical use for encryption I<and> decryption (code is identical for
		161	decryption, you simply pass the encrypted data to C<crypt>):
		162
		163	# create a cipher - $salt can be a random string you send
		164	# with your message, in clear, a counter (best), or empty if
		165	# you only want to encrypt one message with the given key.
		166	# 16 or 32 octets are typical sizes for the key, for the salt,
		167	# use whatever you need to give a unique salt for every
		168	# message you encrypt with the same key.
		169
		170	my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;
		171
		172	# encrypt a message in one or more calls to crypt
		173
		174	my $encrypted;
		175
		176	$encrypted .= $cipher->crypt ("This is");
		177	$encrypted .= $cipher->crypt ("all very");
		178	$encrypted .= $cipher->crypt ("secret");
		179
		180	# that's all
		181
		182	=over 4
		183
		184	=item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
		185
		186	Creates a new cipher object usable for encryption and decryption. The
		187	C<$key> must be provided, the initial vector C<$IV> is optional.
		188
		189	Both C<$key> and C<$IV> can be of any length. Typical lengths for the
		190	C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
		191	be long enough to distinguish repeated uses of tghe same key.
		192
		193	=item $encrypted = $cipher->crypt ($cleartext)
		194
		195	=item $cleartext = $cipher->crypt ($encrypted)
		196
		197	Encrypt or decrypt a piece of a message. This cna be called as many times
		198	as you want, and the message can be split into as few or many pieces as
		199	required without affecting the results.
		200
		201	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		202
		203	Same as C<crypt>, except it I<modifies the argument in-place>.
		204
		205	=item $constant_32 = $cipher->keysize
		206
		207	=item $constant_64 = $cipher->blocksize
		208
		209	These methods are provided for L<Crypt::CBC> compatibility and simply
		210	return C<32> and C<64>, respectively.
		211
		212	Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
		213	not a block cipher and already provides an appropriate mode.
		214
		215	=back
		216
		217
		218	=head2 THE Crypt::Spritz::Hash CLASS
		219
		220	This implements the Spritz digest/hash algorithm. It works very similar to
		221	other digest modules on CPAN, such as L<Digest::SHA3>.
		222
		223	Typical use for hashing:
		224
		225	# create hasher object
		226	my $hasher = new Crypt::Spritz::Hash;
		227
		228	# now feed data to be hashed into $hasher
		229	# in as few or many calls as required
		230	$hasher->add ("Some data");
		231	$hasher->add ("Some more");
		232
		233	# extract the hash - the object is not usable afterwards
		234	my $digest = $hasher->finish (32);
		235
		236	=over 4
		237
		238	=item $hasher = new Crypt::Spritz::Hash
		239
		240	Creates a new hasher object.
		241
		242	=item $hasher->add ($data)
		243
		244	Adds data to be hashed into the hasher state. It doesn't matter whether
		245	you pass your data in in one go or split it up, the hash will be the same.
		246
		247	=item $digest = $hasher->finish ($length)
		248
		249	Calculates a hash digest of the given length and return it. The object
		250	cannot sensibly be used for further hashing afterwards.
		251
		252	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
		253	digests, respectively.
		254
		255	=back
		256
		257
		258	=head2 THE Crypt::Spritz::MAC CLASS
		259
		260	This implements the Spritz Message Authentication Code algorithm. It works
		261	very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
		262	implements an authenticated digest (like L<Digest::HMAC>).
		263
		264	I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
		265	everybody can verify and recreate the hash value for some data, with a
		266	MAC, knowledge of the (hopefully) secret key is required both to create
		267	and to verify the digest.
		268
		269	Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
		270	except a key (typically 16 or 32 octets) is provided to the constructor:
		271
		272	# create hasher object
		273	my $hasher = new Crypt::Spritz::Mac $key;
		274
		275	# now feed data to be hashed into $hasher
		276	# in as few or many calls as required
		277	$hasher->add ("Some data");
		278	$hasher->add ("Some more");
		279
		280	# extract the mac - the object is not usable afterwards
		281	my $mac = $hasher->finish (32);
		282
		283	=over 4
		284
		285	=item $hasher = new Crypt::Spritz::MAC $key
		286
		287	Creates a new hasher object. The C<$key> can be of any length, but 16 and
		288	32 (128 and 256 bit) are customary.
		289
		290	=item $hasher->add ($data)
		291
		292	Adds data to be hashed into the hasher state. It doesn't matter whether
		293	you pass your data in in one go or split it up, the hash will be the same.
		294
		295	=item $mac = $hasher->finish ($length)
		296
		297	Calculates a message code of the given length and return it. The object
		298	cannot sensibly be used for further hashing afterwards.
		299
		300	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
		301	digests, respectively.
		302
		303	=back
		304
		305
		306	=head2 THE Crypt::Spritz::AEAD::XOR CLASS
		307
		308	This is the most complicated class - it combines encryption and
		309	message authentication into a single "authenticated encryption
		310	mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
		311	L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
		312	them.
		313
		314	You can additionally provide cleartext data that will not be encrypted or
		315	decrypted, but that is nevertheless authenticated using the MAC, which
		316	is why this mode is called I<AEAD>, I<Authenticated Encryption with
		317	Associated Data>. Associated data is usually used to any header data that
		318	is in cleartext, but should nevertheless be authenticated.
		319
		320	This implementation implements the XOR variant. Just as with
		321	L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
		322	the standard mode, but uses less code and doesn't distinguish between
		323	encryption and decryption.
		324
		325	Typical usage is as follows:
		326
		327	# create a new aead object
		328	# you use one object per message
		329	# key length customarily is 16 or 32
		330	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		331
		332	# now you must feed the nonce. if you do not need a nonce,
		333	# you can provide the empty string, but you have to call it
		334	# after creating the object, before calling associated_data.
		335	# the nonce must be different for each usage of the $key.
		336	# a counter of some kind is good enough.
		337	# reusing a nonce with the same key completely
		338	# destroys security!
		339	$aead->nonce ($counter);
		340
		341	# then you must feed any associated data you have. if you
		342	# do not have associated cleartext data, you can provide the empty
		343	# string, but you have to call it after nonce and before crypt.
		344	$aead->associated_data ($header);
		345
		346	# next, you call crypt one or more times with your data
		347	# to be encrypted (opr decrypted).
		348	# all except the last call must use a length that is a
		349	# multiple of 64.
		350	# the last block can have any length.
		351	my $encrypted;
		352
		353	$encrypted .= $aead->crypt ("1" x 64);
		354	$encrypted .= $aead->crypt ("2" x 64);
		355	$encrypted .= $aead->crypt ("3456");
		356
		357	# finally you can calculate the MAC for all of the above
		358	my $mac = $aead->finish;
		359
		360	=over 4
		361
		362	=item $aead = new Crypt::Spritz::AEAD::XOR $key
		363
		364	Creates a new cipher object usable for encryption and decryption.
		365
		366	The C<$key> can be of any length. Typical lengths for the C<$key> are 16
		367	(128 bit) or 32 (256 bit).
		368
		369	After creation, you have to call C<nonce> next.
		370
		371	=item $aead->nonce ($nonce)
		372
		373	Provide the nonce value (nonce means "value used once"), a value the is
		374	unique between all uses with the same key. This method I<must> be called
		375	I<after> C<new> and I<before> C<associated_data>.
		376
		377	If you only ever use a given key once, you can provide an empty nonce -
		378	but you still have to call the method.
		379
		380	Common strategies to provide a nonce are to implement a persistent counter
		381	or to generate a random string of sufficient length to guarantee that it
		382	differs each time.
		383
		384	The problem with counters is that you might get confused and forget
		385	increments, and thus reuse the same sequence number. The problem with
		386	random strings i that your random number generator might be hosed and
		387	generate the same randomness multiple times (randomness can be very hard
		388	to get especially on embedded devices).
		389
		390	=item $aead->associated_data ($data)(
		391
		392	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>
		394	C<crypt>.
		395
		396	If you don't have any associated data, you can provide an empty string -
		397	but you still have to call the method.
		398
		399	Associated data is typically header data - data anybody is allowed to
		400	see in cleartext, but that should nevertheless be protected with an
		401	authentication code. Typically such data is used to identify where to
		402	forward a message to, how to find the key to decrypt the message or in
		403	general how to interpret the encrypted part of a message.
		404
		405	=item $encrypted = $cipher->crypt ($cleartext)
		406
		407	=item $cleartext = $cipher->crypt ($encrypted)
		408
		409	Encrypt or decrypt a piece of a message. This cna be called as many times
		410	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
		412	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.
		414
		415	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		416
		417	Same as C<crypt>, except it I<modifies the argument in-place>.
		418
		419	=back
		420
		421
		422	=head2 THE Crypt::Spritz::PRNG CLASS
		423
		424	This class implements a Pseudorandom Number Generatore (B<PRNG>),
		425	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
		426	fact, it is even cryptographically secure, making it a B<CSPRNG>.
		427
		428	Typical usage as a random number generator involves creating a PRNG
		429	object with a seed of your choice, and then fetching randomness via
		430	C<get>:
		431
		432	# create a PRNG object, use a seed string of your choice
		433	my $prng = new Crypt::Spritz::PRNG $seed;
		434
		435	# now call get as many times as you wish to get binary randomness
		436	my $some_randomness = $prng->get (17);
		437	my moree_randomness = $prng->get (5000);
		438	...
		439
		440	Typical usage as a cryptographically secure random number generator is to
		441	feed in some secret entropy (32 octets/256 bits are commonly considered
		442	enough), for example from C</dev/random> or C</dev/urandom>, and then
		443	generate some key material.
		444
		445	# create a PRNG object
		446	my $prng = new Crypt::Spritz::PRNG;
		447
		448	# seed some entropy (either via ->add or in the constructor)
		449	$prng->add ($some_secret_highly_entropic_string);
		450
		451	# now call get as many times as you wish to get
		452	# hard to guess binary randomness
		453	my $key1 = $prng->get (32);
		454	my $key2 = $prng->get (16);
		455	...
		456
		457	# for long running programs, it is advisable to
		458	# reseed the PRNG from time to time with new entropy
		459	$prng->add ($some_more_entropy);
		460
		461	=over 4
		462
		463	=item $prng = new Crypt::Spritz::PRNG [$seed]
		464
		465	Creates a new random number generator object. If C<$seed> is given, then
		466	the C<$seed> is added to the internal state as if by a call to C<add>.
		467
		468	=item $prng->add ($entropy)
		469
		470	Adds entropy to the internal state, thereby hopefully making it harder
		471	to guess. Good sources for entropy are irregular hardware events, or
		472	randomness provided by C</dev/urandom> or C</dev/random>.
		473
		474	The design of the Spritz PRNG should make it strong against attacks where
		475	the attacker controls all the entropy, so it should be safe to add entropy
		476	from untrusted sources - more is better than less if you need a CSPRNG.
		477
		478	For use as PRNG, of course, this matters very little.
		479
		480	=item $octets = $prng->get ($length)
		481
		482	Generates and returns C<$length> random octets as a string.
		483
		484	=back
		485
		486
115	=head1 SEE ALSO	487	=head1 SEE ALSO
116		488
117	L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	489	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
118		490
119	=head1 SECURITY CONSIDERATIONS	491	=head1 SECURITY CONSIDERATIONS
120		492
121	I also cannot guarantee for security.	493	I also cannot give any guarantees for security, Spritz is a very new
		494	cryptographic algorithm, and when this module was written, almost
		495	completely unproven.
122		496
123	=head1 AUTHOR	497	=head1 AUTHOR
124		498
125	Marc Lehmann <schmorp@schmorp.de>	499	Marc Lehmann <schmorp@schmorp.de>
126	http://home.schmorp.de/	500	http://home.schmorp.de/
127		501
128	The actual twofish encryption is written in horribly microsoft'ish looking
129	almost ansi-c by Doug Whiting.
130
131	=cut	502	=cut
132		503
133	1;	504	1;
134		505

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.4 by root, Sat Jan 10 07:10:46 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.4 by root, Sat Jan 10 07:10:46 2015 UTC