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

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.1 by root, Sat Jan 10 03:15:59 2015 UTC vs.
Revision 1.7 by root, Sat Jan 10 09:20:24 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).
		55
		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
		78
		79	=cut
		80
		81	package Crypt::Spritz;
		82
		83	use XSLoader;
		84
		85	$VERSION = '0.1';
		86
		87	XSLoader::load __PACKAGE__, $VERSION;
		88
		89	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
		90
		91	@Crypt::Spritz::Hash::ISA =
		92	@Crypt::Spritz::PRNG::ISA =
		93	@Crypt::Spritz::Cipher::ISA =
		94	@Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
		95
		96	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
		97
		98	@Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::;
		99	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
		100
		101	sub Crypt::Spritz::Cipher::keysize () { 32 }
		102	sub Crypt::Spritz::Cipher::blocksize () { 64 }
		103
		104	*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
		105
		106	*Crypt::Spritz::Hash::add =
		107	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
		108
		109	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
		110
		111	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
		112	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
		113
		114	*Crypt::Spritz::AEAD::associated_data =
		115	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
		116
		117
		118	=head2 THE Crypt::Spritz CLASS
		119
		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.
		124
		125	The Spritz primitive corresponding to the Perl method is given as
		126	comment.
25		127
26	=over 4	128	=over 4
27		129
		130	=item $spritz = new Crypt::Spritz # InitializeState
		131
		132	Creates and returns a new, initialised Spritz state.
		133
		134	=item $spritz->init # InitializeState
		135
		136	Initialises the Spritz state again, throwing away the previous state.
		137
		138	=item $another_spritz = $spritz->clone
		139
		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.
		143
		144	=item $spritz->update # Update
		145
		146	=item $spritz->whip ($r) # Whip
		147
		148	=item $spritz->crush # Crush
		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
		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::AEAD::XOR CLASS
		452
		453	This is the most complicated class - it combines encryption and
		454	message authentication into a single "authenticated encryption
		455	mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
		456	L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
		457	them.
		458
		459	You can additionally provide cleartext data that will not be encrypted or
		460	decrypted, but that is nevertheless authenticated using the MAC, which
		461	is why this mode is called I<AEAD>, I<Authenticated Encryption with
		462	Associated Data>. Associated data is usually used to any header data that
		463	is in cleartext, but should nevertheless be authenticated.
		464
		465	This implementation implements the XOR variant. Just as with
		466	L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
		467	the standard mode, but uses less code and doesn't distinguish between
		468	encryption and decryption.
		469
		470	Typical usage is as follows:
		471
		472	# create a new aead object
		473	# you use one object per message
		474	# key length customarily is 16 or 32
		475	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		476
		477	# now you must feed the nonce. if you do not need a nonce,
		478	# you can provide the empty string, but you have to call it
		479	# after creating the object, before calling associated_data.
		480	# the nonce must be different for each usage of the $key.
		481	# a counter of some kind is good enough.
		482	# reusing a nonce with the same key completely
		483	# destroys security!
		484	$aead->nonce ($counter);
		485
		486	# then you must feed any associated data you have. if you
		487	# do not have associated cleartext data, you can provide the empty
		488	# string, but you have to call it after nonce and before crypt.
		489	$aead->associated_data ($header);
		490
		491	# next, you call crypt one or more times with your data
		492	# to be encrypted (opr decrypted).
		493	# all except the last call must use a length that is a
		494	# multiple of 64.
		495	# the last block can have any length.
		496	my $encrypted;
		497
		498	$encrypted .= $aead->crypt ("1" x 64);
		499	$encrypted .= $aead->crypt ("2" x 64);
		500	$encrypted .= $aead->crypt ("3456");
		501
		502	# finally you can calculate the MAC for all of the above
		503	my $mac = $aead->finish;
		504
		505	=over 4
		506
		507	=item $aead = new Crypt::Spritz::AEAD::XOR $key
		508
		509	Creates a new cipher object usable for encryption and decryption.
		510
		511	The C<$key> can be of any length. Typical lengths for the C<$key> are 16
		512	(128 bit) or 32 (256 bit).
		513
		514	After creation, you have to call C<nonce> next.
		515
		516	=item $aead->nonce ($nonce)
		517
		518	Provide the nonce value (nonce means "value used once"), a value the is
		519	unique between all uses with the same key. This method I<must> be called
		520	I<after> C<new> and I<before> C<associated_data>.
		521
		522	If you only ever use a given key once, you can provide an empty nonce -
		523	but you still have to call the method.
		524
		525	Common strategies to provide a nonce are to implement a persistent counter
		526	or to generate a random string of sufficient length to guarantee that it
		527	differs each time.
		528
		529	The problem with counters is that you might get confused and forget
		530	increments, and thus reuse the same sequence number. The problem with
		531	random strings i that your random number generator might be hosed and
		532	generate the same randomness multiple times (randomness can be very hard
		533	to get especially on embedded devices).
		534
		535	=item $aead->associated_data ($data)
		536
		537	Provide the associated data (cleartext data to be authenticated but not
		538	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
		539	C<crypt>.
		540
		541	If you don't have any associated data, you can provide an empty string -
		542	but you still have to call the method.
		543
		544	Associated data is typically header data - data anybody is allowed to
		545	see in cleartext, but that should nevertheless be protected with an
		546	authentication code. Typically such data is used to identify where to
		547	forward a message to, how to find the key to decrypt the message or in
		548	general how to interpret the encrypted part of a message.
		549
		550	=item $encrypted = $cipher->crypt ($cleartext)
		551
		552	=item $cleartext = $cipher->crypt ($encrypted)
		553
		554	Encrypt or decrypt a piece of a message. This can be called as many times
		555	as you want, and the message can be split into as few or many pieces as
		556	required without affecting the results, with one exception: All except the
		557	last call to C<crypt> needs to pass in a multiple of C<64> octets. The
		558	last call to C<crypt> does not have this limitation.
		559
		560	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		561
		562	Same as C<crypt>, except it I<modifies the argument in-place>.
		563
		564	=item $another_cipher = $cipher->clone
		565
		566	Make an exact copy of the cipher state. This can be useful to cache states
		567	for reuse later, for example, to avoid expensive key setups.
		568
		569	Example: set up a cipher state with a key, then clone and use it to
		570	encrypt messages with different nonces.
		571
		572	my $cipher = new Crypt::Spritz::AEAD::XOR $key;
		573
		574	my $message_counter;
		575
		576	for my $message ("a", "b", "c") {
		577	my $clone = $cipher->clone;
		578	$clone->nonce (pack "N", ++$message_counter);
		579	$clone->associated_data ("");
		580	my $encrypted = $clone->crypt ($message);
		581	...
		582	}
		583
		584	=back
		585
		586
		587	=head1 SEE ALSO
		588
		589	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
		590
		591	=head1 SECURITY CONSIDERATIONS
		592
		593	I also cannot give any guarantees for security, Spritz is a very new
		594	cryptographic algorithm, and when this module was written, almost
		595	completely unproven.
		596
		597	=head1 AUTHOR
		598
		599	Marc Lehmann <schmorp@schmorp.de>
		600	http://software.schmorp.de/pkg/Crypt-Spritz
		601
28	=cut	602	=cut
29		603
30	package Crypt::Spritz;
31
32	use XSLoader;
33
34	$VERSION = '0.0';
35
36	XSLoader::load __PACKAGE__, $VERSION;
37
38	@Crypt::Spritz::CipherBase::ISA =
39	@Crypt::Spritz::HASH::ISA =
40	@Crypt::Spritz::PRNG::ISA = Crypt::Spritz::;
41
42	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::HASH::;
43
44	@Crypt::Spritz::CIPHER::XOR::ISA =
45	@Crypt::Spritz::CIPHER::XOR::ISA =
46	@Crypt::Spritz::AEAD::ISA =
47	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::CipherBase::;
48
49	sub Crypt::Spritz::CipherBase::keysize () { 32 }
50	sub Crypt::Spritz::CipherBase::blocksize () { 64 }
51
52	*Crypt::Spritz::HASH::add =
53	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
54
55	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
56
57	*Crypt::Spritz::AEAD::XOR::finish =
58	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::HASH::finish;
59
60	*Crypt::Spritz::AEAD::XOR::associated_data =
61	*Crypt::Spritz::AEAD::associated_data =
62	*Crypt::Spritz::AEAD::XOR::nonce =
63	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absborb_and_stop;
64
65	=item keysize
66
67	Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually
68	supports keylengths of 16, 24 or 32 bytes, but there is no way to
69	communicate this to C<Crypt::CBC>.
70
71	=item blocksize
72
73	The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat
74	unique. It is also the reason I need this module myself ;)
75
76	=item $cipher = new $key [, $mode]
77
78	Create a new C<Crypt::Twofish2> cipher object with the given key (which
79	must be 128, 192 or 256 bits long). The additional C<$mode> argument is
80	the encryption mode, either C<MODE_ECB> (electronic cookbook mode, the
81	default), C<MODE_CBC> (cipher block chaining, the same that C<Crypt::CBC>
82	does) or C<MODE_CFB1> (1-bit cipher feedback mode).
83
84	ECB mode is very insecure (read a book on cryptography if you don't know
85	why!), so you should probably use CBC mode. CFB1 mode is not tested and is
86	most probably broken, so do not try to use it.
87
88	In ECB mode you can use the same cipher object to encrypt and decrypt
89	data. However, every change of "direction" causes an internal reordering
90	of key data, which is quite slow, so if you want ECB mode and
91	encryption/decryption at the same time you should create two seperate
92	C<Crypt::Twofish2> objects with the same key.
93
94	In CBC mode you have to use seperate objects for encryption/decryption in
95	any case.
96
97	The C<MODE_*>-constants are not exported by this module, so you must
98	specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
99
100	=item $cipher->encrypt($data)
101
102	Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16
103	bytes), otherwise this function will croak. Apart from that, it can be of
104	(almost) any length.
105
106	=item $cipher->decrypt($data)
107
108	The pendant to C<encrypt> in that it I<de>crypts data again.
109
110	=back
111
112	=head1 SEE ALSO
113
114	L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
115
116	=head1 SECURITY CONSIDERATIONS
117
118	I also cannot guarantee for security.
119
120	=head1 AUTHOR
121
122	Marc Lehmann <schmorp@schmorp.de>
123	http://home.schmorp.de/
124
125	The actual twofish encryption is written in horribly microsoft'ish looking
126	almost ansi-c by Doug Whiting.
127
128	=cut
129
130	1;	604	1;
131		605

Diff Legend

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

Comparing Crypt-Spritz/Spritz.pm (file contents): Revision 1.1 by root, Sat Jan 10 03:15:59 2015 UTC vs. Revision 1.7 by root, Sat Jan 10 09:20:24 2015 UTC

Diff Legend

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.1 by root, Sat Jan 10 03:15:59 2015 UTC vs.
Revision 1.7 by root, Sat Jan 10 09:20:24 2015 UTC