Crypt-Spritz/Spritz.pm

=head1 NAME

Crypt::Spritz - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng module

=head1 SYNOPSIS

 use Crypt::Spritz;

 # keysize() is 32, but spritz accepts any key size
 # blocksize() is 16, but cna be anything

 $cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;

 $crypted = $cipher->encrypt($plaintext);
 # - OR -
 $plaintext = $cipher->decrypt($crypted);

=head1 DESCRIPTION

This module implements the Spritz spongelike function (with N=256), the
spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.

Its strength is extreme versatility (you get a stream cipher, a hash, a
MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
more) and extremely simple and small code (encryption and authentication
can be had in 1KB of compiled code on amd64, which isn't an issue for most
uses in Perl, but is useful in embedded situations, or e.g. when doing
crypto using javascript in a browser and communicating with Perl).

Its weakness is its relatively slow speed (encryption is a few times
slower than RC4 or AES, hashing many times slower than SHA-3, although
this might be reversed on an 8-bit-cpu) and the fact that it is totally
unproven in the field (as of this writing, the cipher was just a few
months old), so it can't be called production-ready.

All the usual caveats regarding stream ciphers apply - never repeat
your key, never repeat your nonce etc. - you should have some basic
understanding of cryptography before using this cipher in your own
designs.

The Spritz base class is not meant for end users. To make usage simpler
and safer, a number of convenience classes are provided for typical
end-user tasks:

   encryption               - Crypt::Spritz::Cipher::XOR
   hashing                  - Crypt::Spritz::Hash
   message authentication   - Crypt::Spritz::MAC
   authenticated encryption - Crypt::Spritz::AEAD::XOR
   random number generation - Crypt::Spritz::PRNG

=cut

package Crypt::Spritz;

use XSLoader;

$VERSION = '0.0';

XSLoader::load __PACKAGE__, $VERSION;

@Crypt::Spritz::ISA              = Crypt::Spritz::Base::;

@Crypt::Spritz::Hash::ISA        =
@Crypt::Spritz::PRNG::ISA        =
@Crypt::Spritz::Cipher::ISA      =
@Crypt::Spritz::AEAD::ISA        = Crypt::Spritz::Base::;

@Crypt::Spritz::MAC::ISA         = Crypt::Spritz::Hash::;

@Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::;
@Crypt::Spritz::AEAD::XOR::ISA   = Crypt::Spritz::AEAD::;

sub Crypt::Spritz::Cipher::keysize   () { 32 }
sub Crypt::Spritz::Cipher::blocksize () { 64 }

*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;

*Crypt::Spritz::Hash::add =
*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;

*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;

*Crypt::Spritz::AEAD::new             = \&Crypt::Spritz::MAC::new;
*Crypt::Spritz::AEAD::finish          = \&Crypt::Spritz::Hash::finish;

*Crypt::Spritz::AEAD::associated_data =
*Crypt::Spritz::AEAD::nonce           = \&Crypt::Spritz::absorb_and_stop;


=head2 THE Crypt::Spritz CLASS

This class implements most of the Spritz primitives. To use it effectively
you should understand them, for example, by reading the L<Spritz
paper/http://people.csail.mit.edu/rivest/pubs/RS14.pdf>, especially
pp. 5-6.

The Spritz primitive corresponding to the Perl method is given as
comment.

=over 4

=item $spritz = new Crypt::Spritz   # InitializeState

Creates and returns a new, initialised Spritz state.

=item $spritz->init                 # InitializeState

Initialises the Spritz state again, throwing away the previous state.

=item $spritz->update               # Update

=item $spritz->whip ($r)            # Whip

=item $spritz->crush                # Crush

=item $spritz->shuffle              # Shuffle

=item $spritz->output               # Output

Calls the Spritz primitive ovf the same name - these are not normally
called manually.

=item $spritz->absorb ($I)          # Absorb

Absorbs the given data into the state (usually used for key material, nonces, IVs
messages to be hashed and so on).

=item $spritz->absorb_stop          # AbsorbStop

Absorbs a special stop symbol - this is usually used as delimiter between
multiple strings to be absorbed, to thwart extension attacks.

=item $spritz->absorb_and_stop ($I)

This is a convenience function that simply calls C<absorb> followed by
C<absorb_stop>.

=item $octet = $spritz->drip        # Drip

Squeezes out a single byte from the state.

=item $octets = $spritz->squeeze ($len) # Squeeze

Squeezes out the requested number of bytes from the state - this is usually

=back


=head2 THE Crypt::Spritz::Cipher::XOR CLASS

This class implements stream encryption/decryption. It doesn't implement
the standard Spritz encryption but the XOR variant (called B<spritz-xor>
in the paper).

The XOR variant should be as secure as the standard variant, but
doesn't have separate encryption and decryaption functions, which saves
codesize. IT is not compatible with standard Spritz encryption, however -
drop me a note if you want that implemented as well.

Typical use for encryption I<and> decryption (code is identical for
decryption, you simply pass the encrypted data to C<crypt>):

   # create a cipher - $salt can be a random string you send
   # with your message, in clear, a counter (best), or empty if
   # you only want to encrypt one message with the given key.
   # 16 or 32 octets are typical sizes for the key, for the salt,
   # use whatever you need to give a unique salt for every
   # message you encrypt with the same key.

   my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;

   # encrypt a message in one or more calls to crypt

   my $encrypted;

   $encrypted .= $cipher->crypt ("This is");
   $encrypted .= $cipher->crypt ("all very");
   $encrypted .= $cipher->crypt ("secret");

   # that's all

=over 4

=item $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]

Creates a new cipher object usable for encryption and decryption. The
C<$key> must be provided, the initial vector C<$IV> is optional.

Both C<$key> and C<$IV> can be of any length. Typical lengths for the
C<$key> are 16 (128 bit) or 32 (256 bit), while the C<$IV> simply needs to
be long enough to distinguish repeated uses of tghe same key.

=item $encrypted = $cipher->crypt ($cleartext)

=item $cleartext = $cipher->crypt ($encrypted)

Encrypt or decrypt a piece of a message. This cna be called as many times
as you want, and the message can be split into as few or many pieces as
required without affecting the results.

=item $cipher->crypt_inplace ($cleartext_or_ciphertext)

Same as C<crypt>, except it I<modifies the argument in-place>.

=item $constant_32 = $cipher->keysize

=item $constant_64 = $cipher->blocksize

These methods are provided for L<Crypt::CBC> compatibility and simply
return C<32> and C<64>, respectively.

Note that it is pointless to use Spritz with L<Crypt::CBC>, as Spritz is
not a block cipher and already provides an appropriate mode.

=back


=head2 THE Crypt::Spritz::Hash CLASS

This implements the Spritz digest/hash algorithm. It works very similar to
other digest modules on CPAN, such as L<Digest::SHA3>.

Typical use for hashing:

   # create hasher object
   my $hasher = new Crypt::Spritz::Hash;

   # now feed data to be hashed into $hasher
   # in as few or many calls as required
   $hasher->add ("Some data");
   $hasher->add ("Some more");

   # extract the hash - the object is not usable afterwards
   my $digest = $hasher->finish (32);

=over 4

=item $hasher = new Crypt::Spritz::Hash

Creates a new hasher object.

=item $hasher->add ($data)

Adds data to be hashed into the hasher state. It doesn't matter whether
you pass your data in in one go or split it up, the hash will be the same.

=item $digest = $hasher->finish ($length)

Calculates a hash digest of the given length and return it. The object
cannot sensibly be used for further hashing afterwards.

Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
digests, respectively.

=back


=head2 THE Crypt::Spritz::MAC CLASS

This implements the Spritz Message Authentication Code algorithm. It works
very similar to other digest modules on CPAN, such as L<Digest::SHA3>, but
implements an authenticated digest (like L<Digest::HMAC>).

I<Authenticated> means that, unlike L<Crypt::Spritz::Hash>, where
everybody can verify and recreate the hash value for some data, with a
MAC, knowledge of the (hopefully) secret key is required both to create
and to verify the digest.

Typical use for hashing is almost the same as with L<Crypt::Spritz::MAC>,
except a key (typically 16 or 32 octets) is provided to the constructor:

   # create hasher object
   my $hasher = new Crypt::Spritz::Mac $key;

   # now feed data to be hashed into $hasher
   # in as few or many calls as required
   $hasher->add ("Some data");
   $hasher->add ("Some more");

   # extract the mac - the object is not usable afterwards
   my $mac = $hasher->finish (32);

=over 4

=item $hasher = new Crypt::Spritz::MAC $key

Creates a new hasher object. The C<$key> can be of any length, but 16 and
32 (128 and 256 bit) are customary.

=item $hasher->add ($data)

Adds data to be hashed into the hasher state. It doesn't matter whether
you pass your data in in one go or split it up, the hash will be the same.

=item $mac = $hasher->finish ($length)

Calculates a message code of the given length and return it. The object
cannot sensibly be used for further hashing afterwards.

Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
digests, respectively.

=back


=head2 THE Crypt::Spritz::AEAD::XOR CLASS

This is the most complicated class - it combines encryption and
message authentication into a single "authenticated encryption
mode". It is similar to using both L<Crypt::Spritz::Cipher::XOR> and
L<Crypt::Spritz::MAC>, but makes it harder to make mistakes in combining
them.

You can additionally provide cleartext data that will not be encrypted or
decrypted, but that is nevertheless authenticated using the MAC, which
is why this mode is called I<AEAD>, I<Authenticated Encryption with
Associated Data>. Associated data is usually used to any header data that
is in cleartext, but should nevertheless be authenticated.

This implementation implements the XOR variant. Just as with
L<Crypt::Spritz::Cipher::XOR>, this means it is not compatible with
the standard mode, but uses less code and doesn't distinguish between
encryption and decryption.

Typical usage is as follows:

   # create a new aead object
   # you use one object per message
   # key length customarily is 16 or 32
   my $aead = new Crypt::Spritz::AEAD::XOR $key;

   # now you must feed the nonce. if you do not need a nonce,
   # you can provide the empty string, but you have to call it
   # after creating the object, before calling associated_data.
   # the nonce must be different for each usage of the $key.
   # a counter of some kind is good enough.
   # reusing a nonce with the same key completely
   # destroys security!
   $aead->nonce ($counter);

   # then you must feed any associated data you have. if you
   # do not have associated cleartext data, you can provide the empty
   # string, but you have to call it after nonce and before crypt.
   $aead->associated_data ($header);

   # next, you call crypt one or more times with your data
   # to be encrypted (opr decrypted).
   # all except the last call must use a length that is a
   # multiple of 64.
   # the last block can have any length.
   my $encrypted;

   $encrypted .= $aead->crypt ("1" x 64);
   $encrypted .= $aead->crypt ("2" x 64);
   $encrypted .= $aead->crypt ("3456");

   # finally you can calculate the MAC for all of the above
   my $mac = $aead->finish;

=over 4

=item $aead = new Crypt::Spritz::AEAD::XOR $key

Creates a new cipher object usable for encryption and decryption.

The C<$key> can be of any length. Typical lengths for the C<$key> are 16
(128 bit) or 32 (256 bit).

After creation, you have to call C<nonce> next.

=item $aead->nonce ($nonce)

Provide the nonce value (nonce means "value used once"), a value the is
unique between all uses with the same key. This method I<must> be called
I<after> C<new> and I<before> C<associated_data>.

If you only ever use a given key once, you can provide an empty nonce -
but you still have to call the method.

Common strategies to provide a nonce are to implement a persistent counter
or to generate a random string of sufficient length to guarantee that it
differs each time.

The problem with counters is that you might get confused and forget
increments, and thus reuse the same sequence number. The problem with
random strings i that your random number generator might be hosed and
generate the same randomness multiple times (randomness can be very hard
to get especially on embedded devices).

=item $aead->associated_data ($data)(

Provide the associated data (cleartext data to be authenticated but not
encrypted). This method I<must> be called I<after> C<nonce> and I<before>
C<crypt>.

If you don't have any associated data, you can provide an empty string -
but you still have to call the method.

Associated data is typically header data - data anybody is allowed to
see in cleartext, but that should nevertheless be protected with an
authentication code. Typically such data is used to identify where to
forward a message to, how to find the key to decrypt the message or in
general how to interpret the encrypted part of a message.

=item $encrypted = $cipher->crypt ($cleartext)

=item $cleartext = $cipher->crypt ($encrypted)

Encrypt or decrypt a piece of a message. This cna be called as many times
as you want, and the message can be split into as few or many pieces as
required without affecting the results, with one exception: All except the
last call to C<crypt> needs to pass in a multiple of C<64> octets. The
last call to C<crypt> does not have this limitation.

=item $cipher->crypt_inplace ($cleartext_or_ciphertext)

Same as C<crypt>, except it I<modifies the argument in-place>.

=back


=head2 THE Crypt::Spritz::PRNG CLASS

This class implements a Pseudorandom Number Generatore (B<PRNG>),
sometimes also called a Deterministic Random Bit Generator (B<DRBG>). In
fact, it is even cryptographically secure, making it a B<CSPRNG>.

Typical usage as a random number generator involves creating a PRNG
object with a seed of your choice, and then fetching randomness via
C<get>:

   # create a PRNG object, use a seed string of your choice
   my $prng = new Crypt::Spritz::PRNG $seed;

   # now call get as many times as you wish to get binary randomness
   my $some_randomness = $prng->get (17);
   my moree_randomness = $prng->get (5000);
   ...

Typical usage as a cryptographically secure random number generator is to
feed in some secret entropy (32 octets/256 bits are commonly considered
enough), for example from C</dev/random> or C</dev/urandom>, and then
generate some key material.

   # create a PRNG object
   my $prng = new Crypt::Spritz::PRNG;

   # seed some entropy (either via ->add or in the constructor)
   $prng->add ($some_secret_highly_entropic_string);

   # now call get as many times as you wish to get
   # hard to guess binary randomness
   my $key1 = $prng->get (32);
   my $key2 = $prng->get (16);
   ...

   # for long running programs, it is advisable to
   # reseed the PRNG from time to time with new entropy
   $prng->add ($some_more_entropy);

=over 4

=item $prng = new Crypt::Spritz::PRNG [$seed]

Creates a new random number generator object. If C<$seed> is given, then
the C<$seed> is added to the internal state as if by a call to C<add>.

=item $prng->add ($entropy)

Adds entropy to the internal state, thereby hopefully making it harder
to guess. Good sources for entropy are irregular hardware events, or
randomness provided by C</dev/urandom> or C</dev/random>.

The design of the Spritz PRNG should make it strong against attacks where
the attacker controls all the entropy, so it should be safe to add entropy
from untrusted sources - more is better than less if you need a CSPRNG.

For use as PRNG, of course, this matters very little.

=item $octets = $prng->get ($length)

Generates and returns C<$length> random octets as a string.

=back


=head1 SEE ALSO

L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.

=head1 SECURITY CONSIDERATIONS

I also cannot give any guarantees for security, Spritz is a very new
cryptographic algorithm, and when this module was written, almost
completely unproven.

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=cut

1;

Revision:	1.4
Committed:	Sat Jan 10 07:10:46 2015 UTC (9 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.3:	+429 -58 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Crypt::Spritz - Crypt::CBC compliant Spritz encryption/hash/mac/aead/prng module
4
5			=head1 SYNOPSIS
6
7			use Crypt::Spritz;
8
9			# keysize() is 32, but spritz accepts any key size
10			# blocksize() is 16, but cna be anything
11
12			$cipher = new Crypt::Twofish2 "a" x 32, Crypt::Twofish2::MODE_CBC;
13
14			$crypted = $cipher->encrypt($plaintext);
15			# - OR -
16			$plaintext = $cipher->decrypt($crypted);
17
18			=head1 DESCRIPTION
19
20	root	1.4	This module implements the Spritz spongelike function (with N=256), the
21			spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
22	root	1.1
23	root	1.4	Its strength is extreme versatility (you get a stream cipher, a hash, a
24			MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
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).
29
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
50	root	1.1
51			=cut
52
53			package Crypt::Spritz;
54
55			use XSLoader;
56
57			$VERSION = '0.0';
58
59			XSLoader::load __PACKAGE__, $VERSION;
60
61	root	1.4	@Crypt::Spritz::ISA = Crypt::Spritz::Base::;
62
63	root	1.2	@Crypt::Spritz::Hash::ISA =
64	root	1.4	@Crypt::Spritz::PRNG::ISA =
65			@Crypt::Spritz::Cipher::ISA =
66			@Crypt::Spritz::AEAD::ISA = Crypt::Spritz::Base::;
67	root	1.1
68	root	1.2	@Crypt::Spritz::MAC::ISA = Crypt::Spritz::Hash::;
69	root	1.1
70	root	1.4	@Crypt::Spritz::Cipher::XOR::ISA = Crypt::Spritz::Cipher::;
71			@Crypt::Spritz::AEAD::XOR::ISA = Crypt::Spritz::AEAD::;
72
73			sub Crypt::Spritz::Cipher::keysize () { 32 }
74			sub Crypt::Spritz::Cipher::blocksize () { 64 }
75	root	1.1
76	root	1.4	*Crypt::Spritz::Hash::new = \&Crypt::Spritz::new;
77	root	1.1
78	root	1.2	*Crypt::Spritz::Hash::add =
79	root	1.1	*Crypt::Spritz::PRNG::add = \&Crypt::Spritz::absorb;
80
81			*Crypt::Spritz::PRNG::get = \&Crypt::Spritz::squeeze;
82
83	root	1.4	*Crypt::Spritz::AEAD::new = \&Crypt::Spritz::MAC::new;
84			*Crypt::Spritz::AEAD::finish = \&Crypt::Spritz::Hash::finish;
85
86			*Crypt::Spritz::AEAD::associated_data =
87			*Crypt::Spritz::AEAD::nonce = \&Crypt::Spritz::absorb_and_stop;
88
89
90			=head2 THE Crypt::Spritz CLASS
91
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.
96
97			The Spritz primitive corresponding to the Perl method is given as
98			comment.
99
100			=over 4
101
102			=item $spritz = new Crypt::Spritz # InitializeState
103
104			Creates and returns a new, initialised Spritz state.
105
106			=item $spritz->init # InitializeState
107
108			Initialises the Spritz state again, throwing away the previous state.
109
110			=item $spritz->update # Update
111
112			=item $spritz->whip ($r) # Whip
113
114			=item $spritz->crush # Crush
115
116			=item $spritz->shuffle # Shuffle
117
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
145
146			=back
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	root	1.3
215	root	1.4	=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	root	1.1
297	root	1.4	Calculates a message code of the given length and return it. The object
298			cannot sensibly be used for further hashing afterwards.
299	root	1.1
300	root	1.4	Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
301			digests, respectively.
302	root	1.1
303	root	1.4	=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	root	1.1
384	root	1.4	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	root	1.1
390	root	1.4	=item $aead->associated_data ($data)(
391	root	1.1
392	root	1.4	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	root	1.1
396	root	1.4	If you don't have any associated data, you can provide an empty string -
397			but you still have to call the method.
398	root	1.1
399	root	1.4	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	root	1.1
405	root	1.4	=item $encrypted = $cipher->crypt ($cleartext)
406	root	1.1
407	root	1.4	=item $cleartext = $cipher->crypt ($encrypted)
408	root	1.1
409	root	1.4	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	root	1.1
415	root	1.4	=item $cipher->crypt_inplace ($cleartext_or_ciphertext)
416	root	1.1
417	root	1.4	Same as C<crypt>, except it I<modifies the argument in-place>.
418	root	1.1
419	root	1.4	=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	root	1.1
468	root	1.4	=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	root	1.1
484			=back
485
486	root	1.4
487	root	1.1	=head1 SEE ALSO
488
489	root	1.4	L<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
490	root	1.1
491			=head1 SECURITY CONSIDERATIONS
492
493	root	1.4	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.
496	root	1.1
497			=head1 AUTHOR
498
499			Marc Lehmann <schmorp@schmorp.de>
500			http://home.schmorp.de/
501
502			=cut
503
504			1;
505