Crypt-Spritz/Spritz.pm

=head1 NAME

Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module

=head1 SYNOPSIS

 use Crypt::Spritz;

 # see the commented examples in their respective classes,
 # but basically

 my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
 $ciphertext = $cipher->crypt ($cleartext);

 my $hasher = new Crypt::Spritz::Hash;
 $hasher->add ($data);
 $digest = $hasher->finish;

 my $hasher = new Crypt::Spritz::MAC $key;
 $hasher->add ($data);
 $mac = $hasher->finish;

 my $aead = new Crypt::Spritz::AEAD::XOR $key;
 $aead->nonce ($counter);
 $aead->associated_data ($header);
 $ciphertext = $aead->crypt ($cleartext);
 $mac = $aead->mac;

 my $prng = new Crypt::Spritz::PRNG $entropy;
 $prng->add ($additional_entropy);
 $keydata = $prng->get (32);

=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 and so on - 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://software.schmorp.de/pkg/Crypt-Spritz

=cut

1;

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