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

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.2 by root, Sat Jan 10 04:14:17 2015 UTC vs.
Revision 1.6 by root, Sat Jan 10 07:48:29 2015 UTC

1	=head1 NAME	1	=head1 NAME
2		2
3	Crypt::Spritz - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng module	3	Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
7	use Crypt::Spritz;	7	use Crypt::Spritz;
8		8
9	# keysize() is 32, but spritz accepts any key size	9	# see the commented examples in their respective classes,
10	# blocksize() is 16, but cna be anything	10	# but basically
11		11
12	$cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;	12	my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
13
14	$crypted = $cipher->encrypt($plaintext);	13	$ciphertext = $cipher->crypt ($cleartext);
15	# - OR -	14
16	$plaintext = $cipher->decrypt($crypted);	15	my $hasher = new Crypt::Spritz::Hash;
		16	$hasher->add ($data);
		17	$digest = $hasher->finish;
		18
		19	my $hasher = new Crypt::Spritz::MAC $key;
		20	$hasher->add ($data);
		21	$mac = $hasher->finish;
		22
		23	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		24	$aead->nonce ($counter);
		25	$aead->associated_data ($header);
		26	$ciphertext = $aead->crypt ($cleartext);
		27	$mac = $aead->mac;
		28
		29	my $prng = new Crypt::Spritz::PRNG $entropy;
		30	$prng->add ($additional_entropy);
		31	$keydata = $prng->get (32);
17		32
18	=head1 DESCRIPTION	33	=head1 DESCRIPTION
19		34
20	This module implements the spritz spongelike function.	35	This module implements the Spritz spongelike function (with N=256), the
		36	spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
21		37
22	Although it is C<Crypt::CBC> compliant you usually gain nothing by using	38	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	39	MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
24	C<Crypt::Twofish2> can work in either ECB or CBC mode itself.	40	more) and extremely simple and small code (encryption and authentication
		41	can be had in 1KB of compiled code on amd64, which isn't an issue for most
		42	uses in Perl, but is useful in embedded situations, or e.g. when doing
		43	crypto using javascript in a browser and communicating with Perl).
25		44
26	=over 4	45	Its weakness is its relatively slow speed (encryption is a few times
		46	slower than RC4 or AES, hashing many times slower than SHA-3, although
		47	this might be reversed on an 8-bit-cpu) and the fact that it is totally
		48	unproven in the field (as of this writing, the cipher was just a few
		49	months old), so it can't be called production-ready.
		50
		51	All the usual caveats regarding stream ciphers apply - never repeat your
		52	key, never repeat your nonce and so on - you should have some basic
		53	understanding of cryptography before using this cipher in your own
		54	designs.
		55
		56	The Spritz base class is not meant for end users. To make usage simpler
		57	and safer, a number of convenience classes are provided for typical
		58	end-user tasks:
		59
		60	encryption - Crypt::Spritz::Cipher::XOR
		61	hashing - Crypt::Spritz::Hash
		62	message authentication - Crypt::Spritz::MAC
		63	authenticated encryption - Crypt::Spritz::AEAD::XOR
		64	random number generation - Crypt::Spritz::PRNG
27		65
28	=cut	66	=cut
29		67
30	package Crypt::Spritz;	68	package Crypt::Spritz;
31		69
32	use XSLoader;	70	use XSLoader;
33		71
34	$VERSION = '0.0';	72	$VERSION = '0.1';
35		73
36	XSLoader::load __PACKAGE__, $VERSION;	74	XSLoader::load __PACKAGE__, $VERSION;
37		75
38	@Crypt::Spritz::CipherBase::ISA =	76	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
		77
39	@Crypt::Spritz::Hash::ISA =	78	@Crypt::Spritz::Hash::ISA =
		79	@Crypt::Spritz::PRNG::ISA =
		80	@Crypt::Spritz::Cipher::ISA =
40	@Crypt::Spritz::PRNG::ISA = Crypt::Spritz::;	81	@Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
41		82
42	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;	83	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
43		84
44	@Crypt::Spritz::Cipher::XOR::ISA =	85	@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::;	86	@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
48		87
49	sub Crypt::Spritz::CipherBase::keysize () { 32 }	88	sub Crypt::Spritz::Cipher::keysize () { 32 }
50	sub Crypt::Spritz::CipherBase::blocksize () { 64 }	89	sub Crypt::Spritz::Cipher::blocksize () { 64 }
		90
		91	*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
51		92
52	*Crypt::Spritz::Hash::add =	93	*Crypt::Spritz::Hash::add =
53	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;	94	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
54		95
55	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;	96	*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
56		97
57	*Crypt::Spritz::AEAD::XOR::finish =	98	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
58	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;	99	*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
59		100
60	*Crypt::Spritz::AEAD::XOR::associated_data =	101	*Crypt::Spritz::AEAD::associated_data =
61	*Crypt::Spritz::AEAD::associated_data =
62	*Crypt::Spritz::AEAD::XOR::nonce =
63	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absborb_and_stop;	102	*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
64		103
65	=item keysize
66		104
67	Returns the keysize, which is 32 (bytes). The Twofish2 cipher actually	105	=head2 THE Crypt::Spritz CLASS
68	supports keylengths of 16, 24 or 32 bytes, but there is no way to
69	communicate this to C<Crypt::CBC>.
70		106
71	=item blocksize	107	This class implements most of the Spritz primitives. To use it effectively
		108	you should understand them, for example, by reading the L<Spritz
		109	paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
		110	pp. 5-6.
72		111
73	The blocksize for Twofish2 is 16 bytes (128 bits), which is somewhat	112	The Spritz primitive corresponding to the Perl method is given as
74	unique. It is also the reason I need this module myself ;)	113	comment.
75		114
76	=item $cipher = new $key [, $mode]	115	=over 4
77		116
78	Create a new C<Crypt::Twofish2> cipher object with the given key (which	117	=item $spritz = new Crypt::Spritz # InitializeState
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		118
84	ECB mode is very insecure (read a book on cryptography if you don't know	119	Creates and returns a new, initialised Spritz state.
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		120
88	In ECB mode you can use the same cipher object to encrypt and decrypt	121	=item $spritz->init # InitializeState
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		122
94	In CBC mode you have to use seperate objects for encryption/decryption in	123	Initialises the Spritz state again, throwing away the previous state.
95	any case.
96		124
97	The C<MODE_*>-constants are not exported by this module, so you must	125	=item $another_spritz = $spritz->clone
98	specify them as C<Crypt::Twofish2::MODE_CBC> etc. (sorry for that).
99		126
100	=item $cipher->encrypt($data)	127	Make an exact copy of the spritz state. This method can be called on all
		128	of the objects in this module, but is documented separately to give some
		129	cool usage examples.
101		130
102	Encrypt data. The size of C<$data> must be a multiple of C<blocksize> (16	131	=item $spritz->update # Update
103	bytes), otherwise this function will croak. Apart from that, it can be of
104	(almost) any length.
105		132
106	=item $cipher->decrypt($data)	133	=item $spritz->whip ($r) # Whip
107		134
108	The pendant to C<encrypt> in that it I<de>crypts data again.	135	=item $spritz->crush # Crush
		136
		137	=item $spritz->shuffle # Shuffle
		138
		139	=item $spritz->output # Output
		140
		141	Calls the Spritz primitive ovf the same name - these are not normally
		142	called manually.
		143
		144	=item $spritz->absorb ($I) # Absorb
		145
		146	Absorbs the given data into the state (usually used for key material,
		147	nonces, IVs messages to be hashed and so on).
		148
		149	=item $spritz->absorb_stop # AbsorbStop
		150
		151	Absorbs a special stop symbol - this is usually used as delimiter between
		152	multiple strings to be absorbed, to thwart extension attacks.
		153
		154	=item $spritz->absorb_and_stop ($I)
		155
		156	This is a convenience function that simply calls C<absorb> followed by
		157	C<absorb_stop>.
		158
		159	=item $octet = $spritz->drip # Drip
		160
		161	Squeezes out a single byte from the state.
		162
		163	=item $octets = $spritz->squeeze ($len) # Squeeze
		164
		165	Squeezes out the requested number of bytes from the state - this is usually
109		166
110	=back	167	=back
111		168
		169
		170	=head2 THE Crypt::Spritz::Cipher::XOR CLASS
		171
		172	This class implements stream encryption/decryption. It doesn't implement
		173	the standard Spritz encryption but the XOR variant (called B<spritz-xor>
		174	in the paper).
		175
		176	The XOR variant should be as secure as the standard variant, but
		177	doesn't have separate encryption and decryaption functions, which saves
		178	codesize. IT is not compatible with standard Spritz encryption, however -
		179	drop me a note if you want that implemented as well.
		180
		181	Typical use for encryption I<and> decryption (code is identical for
		182	decryption, you simply pass the encrypted data to C<crypt>):
		183
		184	# create a cipher - $salt can be a random string you send
		185	# with your message, in clear, a counter (best), or empty if
		186	# you only want to encrypt one message with the given key.
		187	# 16 or 32 octets are typical sizes for the key, for the salt,
		188	# use whatever you need to give a unique salt for every
		189	# message you encrypt with the same key.
		190
		191	my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;
		192
		193	# encrypt a message in one or more calls to crypt
		194
		195	my $encrypted;
		196
		197	$encrypted .= $cipher->crypt ("This is");
		198	$encrypted .= $cipher->crypt ("all very");
		199	$encrypted .= $cipher->crypt ("secret");
		200
		201	# that's all
		202
		203	=over 4
		204
		205	=item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
		206
		207	Creates a new cipher object usable for encryption and decryption. The
		208	C<$key> must be provided, the initial vector C<$IV> is optional.
		209
		210	Both C<$key> and C<$IV> can be of any length. Typical lengths for the
		211	C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
		212	be long enough to distinguish repeated uses of tghe same key.
		213
		214	=item $encrypted = $cipher->crypt ($cleartext)
		215
		216	=item $cleartext = $cipher->crypt ($encrypted)
		217
		218	Encrypt or decrypt a piece of a message. This can be called as many times
		219	as you want, and the message can be split into as few or many pieces as
		220	required without affecting the results.
		221
		222	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		223
		224	Same as C<crypt>, except it I<modifies the argument in-place>.
		225
		226	=item $another_cipher = $cipher->clone
		227
		228	Make an exact copy of the cipher state. This can be useful to cache states
		229	for reuse later, for example, to avoid expensive key setups.
		230
		231	While there might be use cases for this feature, it makes a lot more sense
		232	for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
		233	you to specify the IV/nonce separately.
		234
		235	=item $constant_32 = $cipher->keysize
		236
		237	=item $constant_64 = $cipher->blocksize
		238
		239	These methods are provided for L<Crypt::CBC> compatibility and simply
		240	return C<32> and C<64>, respectively.
		241
		242	Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
		243	not a block cipher and already provides an appropriate mode.
		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::AEAD::XOR CLASS
		374
		375	This is the most complicated class - it combines encryption and
		376	message authentication into a single "authenticated encryption
		377	mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
		378	L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
		379	them.
		380
		381	You can additionally provide cleartext data that will not be encrypted or
		382	decrypted, but that is nevertheless authenticated using the MAC, which
		383	is why this mode is called I<AEAD>, I<Authenticated Encryption with
		384	Associated Data>. Associated data is usually used to any header data that
		385	is in cleartext, but should nevertheless be authenticated.
		386
		387	This implementation implements the XOR variant. Just as with
		388	L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
		389	the standard mode, but uses less code and doesn't distinguish between
		390	encryption and decryption.
		391
		392	Typical usage is as follows:
		393
		394	# create a new aead object
		395	# you use one object per message
		396	# key length customarily is 16 or 32
		397	my $aead = new Crypt::Spritz::AEAD::XOR $key;
		398
		399	# now you must feed the nonce. if you do not need a nonce,
		400	# you can provide the empty string, but you have to call it
		401	# after creating the object, before calling associated_data.
		402	# the nonce must be different for each usage of the $key.
		403	# a counter of some kind is good enough.
		404	# reusing a nonce with the same key completely
		405	# destroys security!
		406	$aead->nonce ($counter);
		407
		408	# then you must feed any associated data you have. if you
		409	# do not have associated cleartext data, you can provide the empty
		410	# string, but you have to call it after nonce and before crypt.
		411	$aead->associated_data ($header);
		412
		413	# next, you call crypt one or more times with your data
		414	# to be encrypted (opr decrypted).
		415	# all except the last call must use a length that is a
		416	# multiple of 64.
		417	# the last block can have any length.
		418	my $encrypted;
		419
		420	$encrypted .= $aead->crypt ("1" x 64);
		421	$encrypted .= $aead->crypt ("2" x 64);
		422	$encrypted .= $aead->crypt ("3456");
		423
		424	# finally you can calculate the MAC for all of the above
		425	my $mac = $aead->finish;
		426
		427	=over 4
		428
		429	=item $aead = new Crypt::Spritz::AEAD::XOR $key
		430
		431	Creates a new cipher object usable for encryption and decryption.
		432
		433	The C<$key> can be of any length. Typical lengths for the C<$key> are 16
		434	(128 bit) or 32 (256 bit).
		435
		436	After creation, you have to call C<nonce> next.
		437
		438	=item $aead->nonce ($nonce)
		439
		440	Provide the nonce value (nonce means "value used once"), a value the is
		441	unique between all uses with the same key. This method I<must> be called
		442	I<after> C<new> and I<before> C<associated_data>.
		443
		444	If you only ever use a given key once, you can provide an empty nonce -
		445	but you still have to call the method.
		446
		447	Common strategies to provide a nonce are to implement a persistent counter
		448	or to generate a random string of sufficient length to guarantee that it
		449	differs each time.
		450
		451	The problem with counters is that you might get confused and forget
		452	increments, and thus reuse the same sequence number. The problem with
		453	random strings i that your random number generator might be hosed and
		454	generate the same randomness multiple times (randomness can be very hard
		455	to get especially on embedded devices).
		456
		457	=item $aead->associated_data ($data)
		458
		459	Provide the associated data (cleartext data to be authenticated but not
		460	encrypted). This method I<must> be called I<after> C<nonce> and I<before>
		461	C<crypt>.
		462
		463	If you don't have any associated data, you can provide an empty string -
		464	but you still have to call the method.
		465
		466	Associated data is typically header data - data anybody is allowed to
		467	see in cleartext, but that should nevertheless be protected with an
		468	authentication code. Typically such data is used to identify where to
		469	forward a message to, how to find the key to decrypt the message or in
		470	general how to interpret the encrypted part of a message.
		471
		472	=item $encrypted = $cipher->crypt ($cleartext)
		473
		474	=item $cleartext = $cipher->crypt ($encrypted)
		475
		476	Encrypt or decrypt a piece of a message. This can be called as many times
		477	as you want, and the message can be split into as few or many pieces as
		478	required without affecting the results, with one exception: All except the
		479	last call to C<crypt> needs to pass in a multiple of C<64> octets. The
		480	last call to C<crypt> does not have this limitation.
		481
		482	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
		483
		484	Same as C<crypt>, except it I<modifies the argument in-place>.
		485
		486	=item $another_cipher = $cipher->clone
		487
		488	Make an exact copy of the cipher state. This can be useful to cache states
		489	for reuse later, for example, to avoid expensive key setups.
		490
		491	Example: set up a cipher state with a key, then clone and use it to
		492	encrypt messages with different nonces.
		493
		494	my $cipher = new Crypt::Spritz::AEAD::XOR $key;
		495
		496	my $message_counter;
		497
		498	for my $message ("a", "b", "c") {
		499	my $clone = $cipher->clone;
		500	$clone->nonce (pack "N", ++$message_counter);
		501	$clone->associated_data ("");
		502	my $encrypted = $clone->crypt ($message);
		503	...
		504	}
		505
		506	=back
		507
		508
		509	=head2 THE Crypt::Spritz::PRNG CLASS
		510
		511	This class implements a Pseudorandom Number Generatore (B<PRNG>),
		512	sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
		513	fact, it is even cryptographically secure, making it a B<CSPRNG>.
		514
		515	Typical usage as a random number generator involves creating a PRNG
		516	object with a seed of your choice, and then fetching randomness via
		517	C<get>:
		518
		519	# create a PRNG object, use a seed string of your choice
		520	my $prng = new Crypt::Spritz::PRNG $seed;
		521
		522	# now call get as many times as you wish to get binary randomness
		523	my $some_randomness = $prng->get (17);
		524	my moree_randomness = $prng->get (5000);
		525	...
		526
		527	Typical usage as a cryptographically secure random number generator is to
		528	feed in some secret entropy (32 octets/256 bits are commonly considered
		529	enough), for example from C</dev/random> or C</dev/urandom>, and then
		530	generate some key material.
		531
		532	# create a PRNG object
		533	my $prng = new Crypt::Spritz::PRNG;
		534
		535	# seed some entropy (either via ->add or in the constructor)
		536	$prng->add ($some_secret_highly_entropic_string);
		537
		538	# now call get as many times as you wish to get
		539	# hard to guess binary randomness
		540	my $key1 = $prng->get (32);
		541	my $key2 = $prng->get (16);
		542	...
		543
		544	# for long running programs, it is advisable to
		545	# reseed the PRNG from time to time with new entropy
		546	$prng->add ($some_more_entropy);
		547
		548	=over 4
		549
		550	=item $prng = new Crypt::Spritz::PRNG [$seed]
		551
		552	Creates a new random number generator object. If C<$seed> is given, then
		553	the C<$seed> is added to the internal state as if by a call to C<add>.
		554
		555	=item $prng->add ($entropy)
		556
		557	Adds entropy to the internal state, thereby hopefully making it harder
		558	to guess. Good sources for entropy are irregular hardware events, or
		559	randomness provided by C</dev/urandom> or C</dev/random>.
		560
		561	The design of the Spritz PRNG should make it strong against attacks where
		562	the attacker controls all the entropy, so it should be safe to add entropy
		563	from untrusted sources - more is better than less if you need a CSPRNG.
		564
		565	For use as PRNG, of course, this matters very little.
		566
		567	=item $octets = $prng->get ($length)
		568
		569	Generates and returns C<$length> random octets as a string.
		570
		571	=back
		572
		573
112	=head1 SEE ALSO	574	=head1 SEE ALSO
113		575
114	L<Crypt::CBC>, L<Digest::HMAC>, L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.	576	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
115		577
116	=head1 SECURITY CONSIDERATIONS	578	=head1 SECURITY CONSIDERATIONS
117		579
118	I also cannot guarantee for security.	580	I also cannot give any guarantees for security, Spritz is a very new
		581	cryptographic algorithm, and when this module was written, almost
		582	completely unproven.
119		583
120	=head1 AUTHOR	584	=head1 AUTHOR
121		585
122	Marc Lehmann <schmorp@schmorp.de>	586	Marc Lehmann <schmorp@schmorp.de>
123	http://home.schmorp.de/	587	http://software.schmorp.de/pkg/Crypt-Spritz
124
125	The actual twofish encryption is written in horribly microsoft'ish looking
126	almost ansi-c by Doug Whiting.
127		588
128	=cut	589	=cut
129		590
130	1;	591	1;
131		592

Diff Legend

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

Comparing Crypt-Spritz/Spritz.pm (file contents): Revision 1.2 by root, Sat Jan 10 04:14:17 2015 UTC vs. Revision 1.6 by root, Sat Jan 10 07:48:29 2015 UTC

Diff Legend

Comparing Crypt-Spritz/Spritz.pm (file contents):
Revision 1.2 by root, Sat Jan 10 04:14:17 2015 UTC vs.
Revision 1.6 by root, Sat Jan 10 07:48:29 2015 UTC