[ViewVC] Annotation of: cvs/Crypt-Spritz/README

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

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);

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

  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
    "http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper,
    especially pp. 5-6.

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

    $spritz = new Crypt::Spritz # InitializeState
        Creates and returns a new, initialised Spritz state.

    $spritz->init # InitializeState
        Initialises the Spritz state again, throwing away the previous
        state.

    $spritz->update # Update
    $spritz->whip ($r) # Whip
    $spritz->crush # Crush
    $spritz->shuffle # Shuffle
    $spritz->output # Output
        Calls the Spritz primitive ovf the same name - these are not
        normally called manually.

    $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).

    $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.

    $spritz->absorb_and_stop ($I)
        This is a convenience function that simply calls "absorb" followed
        by "absorb_stop".

    $octet = $spritz->drip # Drip
        Squeezes out a single byte from the state.

    $octets = $spritz->squeeze ($len) # Squeeze
        Squeezes out the requested number of bytes from the state - this is
        usually

  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 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 *and* decryption (code is identical for
    decryption, you simply pass the encrypted data to "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

    $cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
        Creates a new cipher object usable for encryption and decryption.
        The $key must be provided, the initial vector $IV is optional.

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

    $encrypted = $cipher->crypt ($cleartext)
    $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.

    $cipher->crypt_inplace ($cleartext_or_ciphertext)
        Same as "crypt", except it *modifies the argument in-place*.

    $constant_32 = $cipher->keysize
    $constant_64 = $cipher->blocksize
        These methods are provided for Crypt::CBC compatibility and simply
        return 32 and 64, respectively.

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

  THE Crypt::Spritz::Hash CLASS
    This implements the Spritz digest/hash algorithm. It works very similar
    to other digest modules on CPAN, such as 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);

    $hasher = new Crypt::Spritz::Hash
        Creates a new hasher object.

    $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.

    $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.

  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
    Digest::SHA3, but implements an authenticated digest (like
    Digest::HMAC).

    *Authenticated* means that, unlike 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 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);

    $hasher = new Crypt::Spritz::MAC $key
        Creates a new hasher object. The $key can be of any length, but 16
        and 32 (128 and 256 bit) are customary.

    $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.

    $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.

  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 Crypt::Spritz::Cipher::XOR and 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 *AEAD*, *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
    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;

    $aead = new Crypt::Spritz::AEAD::XOR $key
        Creates a new cipher object usable for encryption and decryption.

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

        After creation, you have to call "nonce" next.

    $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 *must* be
        called *after* "new" and *before* "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).

    $aead->associated_data ($data)(
        Provide the associated data (cleartext data to be authenticated but
        not encrypted). This method *must* be called *after* "nonce" and
        *before* "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.

    $encrypted = $cipher->crypt ($cleartext)
    $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 "crypt" needs to pass in a
        multiple of 64 octets. The last call to "crypt" does not have this
        limitation.

    $cipher->crypt_inplace ($cleartext_or_ciphertext)
        Same as "crypt", except it *modifies the argument in-place*.

  THE Crypt::Spritz::PRNG CLASS
    This class implements a Pseudorandom Number Generatore (PRNG), sometimes
    also called a Deterministic Random Bit Generator (DRBG). In fact, it is
    even cryptographically secure, making it a CSPRNG.

    Typical usage as a random number generator involves creating a PRNG
    object with a seed of your choice, and then fetching randomness via
    "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 "/dev/random" or "/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);

    $prng = new Crypt::Spritz::PRNG [$seed]
        Creates a new random number generator object. If $seed is given,
        then the $seed is added to the internal state as if by a call to
        "add".

    $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 "/dev/urandom" or "/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.

    $octets = $prng->get ($length)
        Generates and returns $length random octets as a string.

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

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.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://software.schmorp.de/pkg/Crypt-Spritz

Revision:	1.2
Committed:	Sat Jan 10 07:48:29 2015 UTC (9 years, 4 months ago) by root
Branch:	MAIN
Changes since 1.1:	+411 -0 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.2	NAME
2			Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module
3
4			SYNOPSIS
5			use Crypt::Spritz;
6
7			# see the commented examples in their respective classes,
8			# but basically
9
10			my $cipher = new Crypt::Spritz::Cipher::XOR $key, $iv;
11			$ciphertext = $cipher->crypt ($cleartext);
12
13			my $hasher = new Crypt::Spritz::Hash;
14			$hasher->add ($data);
15			$digest = $hasher->finish;
16
17			my $hasher = new Crypt::Spritz::MAC $key;
18			$hasher->add ($data);
19			$mac = $hasher->finish;
20
21			my $aead = new Crypt::Spritz::AEAD::XOR $key;
22			$aead->nonce ($counter);
23			$aead->associated_data ($header);
24			$ciphertext = $aead->crypt ($cleartext);
25			$mac = $aead->mac;
26
27			my $prng = new Crypt::Spritz::PRNG $entropy;
28			$prng->add ($additional_entropy);
29			$keydata = $prng->get (32);
30
31			DESCRIPTION
32			This module implements the Spritz spongelike function (with N=256), the
33			spiritual successor of RC4 developed by Ron Rivest and Jacob Schuldt.
34
35			Its strength is extreme versatility (you get a stream cipher, a hash, a
36			MAC, a DRBG/CSPRNG, an authenticated encryption block/stream cipher and
37			more) and extremely simple and small code (encryption and authentication
38			can be had in 1KB of compiled code on amd64, which isn't an issue for
39			most uses in Perl, but is useful in embedded situations, or e.g. when
40			doing crypto using javascript in a browser and communicating with Perl).
41
42			Its weakness is its relatively slow speed (encryption is a few times
43			slower than RC4 or AES, hashing many times slower than SHA-3, although
44			this might be reversed on an 8-bit-cpu) and the fact that it is totally
45			unproven in the field (as of this writing, the cipher was just a few
46			months old), so it can't be called production-ready.
47
48			All the usual caveats regarding stream ciphers apply - never repeat your
49			key, never repeat your nonce and so on - you should have some basic
50			understanding of cryptography before using this cipher in your own
51			designs.
52
53			The Spritz base class is not meant for end users. To make usage simpler
54			and safer, a number of convenience classes are provided for typical
55			end-user tasks:
56
57			encryption - Crypt::Spritz::Cipher::XOR
58			hashing - Crypt::Spritz::Hash
59			message authentication - Crypt::Spritz::MAC
60			authenticated encryption - Crypt::Spritz::AEAD::XOR
61			random number generation - Crypt::Spritz::PRNG
62
63			THE Crypt::Spritz CLASS
64			This class implements most of the Spritz primitives. To use it
65			effectively you should understand them, for example, by reading the
66			"http://people.csail.mit.edu/rivest/pubs/RS14.pdf" in Spritz paper,
67			especially pp. 5-6.
68
69			The Spritz primitive corresponding to the Perl method is given as
70			comment.
71
72			$spritz = new Crypt::Spritz # InitializeState
73			Creates and returns a new, initialised Spritz state.
74
75			$spritz->init # InitializeState
76			Initialises the Spritz state again, throwing away the previous
77			state.
78
79			$spritz->update # Update
80			$spritz->whip ($r) # Whip
81			$spritz->crush # Crush
82			$spritz->shuffle # Shuffle
83			$spritz->output # Output
84			Calls the Spritz primitive ovf the same name - these are not
85			normally called manually.
86
87			$spritz->absorb ($I) # Absorb
88			Absorbs the given data into the state (usually used for key
89			material, nonces, IVs messages to be hashed and so on).
90
91			$spritz->absorb_stop # AbsorbStop
92			Absorbs a special stop symbol - this is usually used as delimiter
93			between multiple strings to be absorbed, to thwart extension
94			attacks.
95
96			$spritz->absorb_and_stop ($I)
97			This is a convenience function that simply calls "absorb" followed
98			by "absorb_stop".
99
100			$octet = $spritz->drip # Drip
101			Squeezes out a single byte from the state.
102
103			$octets = $spritz->squeeze ($len) # Squeeze
104			Squeezes out the requested number of bytes from the state - this is
105			usually
106
107			THE Crypt::Spritz::Cipher::XOR CLASS
108			This class implements stream encryption/decryption. It doesn't implement
109			the standard Spritz encryption but the XOR variant (called spritz-xor in
110			the paper).
111
112			The XOR variant should be as secure as the standard variant, but doesn't
113			have separate encryption and decryaption functions, which saves
114			codesize. IT is not compatible with standard Spritz encryption, however
115			- drop me a note if you want that implemented as well.
116
117			Typical use for encryption and decryption (code is identical for
118			decryption, you simply pass the encrypted data to "crypt"):
119
120			# create a cipher - $salt can be a random string you send
121			# with your message, in clear, a counter (best), or empty if
122			# you only want to encrypt one message with the given key.
123			# 16 or 32 octets are typical sizes for the key, for the salt,
124			# use whatever you need to give a unique salt for every
125			# message you encrypt with the same key.
126
127			my $cipher = Crypt::Spritz::Cipher::XOR $key, $salt;
128
129			# encrypt a message in one or more calls to crypt
130
131			my $encrypted;
132
133			$encrypted .= $cipher->crypt ("This is");
134			$encrypted .= $cipher->crypt ("all very");
135			$encrypted .= $cipher->crypt ("secret");
136
137			# that's all
138
139			$cipher = new Crypt::Spritz::Cipher::XOR $key[, $iv]
140			Creates a new cipher object usable for encryption and decryption.
141			The $key must be provided, the initial vector $IV is optional.
142
143			Both $key and $IV can be of any length. Typical lengths for the $key
144			are 16 (128 bit) or 32 (256 bit), while the $IV simply needs to be
145			long enough to distinguish repeated uses of tghe same key.
146
147			$encrypted = $cipher->crypt ($cleartext)
148			$cleartext = $cipher->crypt ($encrypted)
149			Encrypt or decrypt a piece of a message. This cna be called as many
150			times as you want, and the message can be split into as few or many
151			pieces as required without affecting the results.
152
153			$cipher->crypt_inplace ($cleartext_or_ciphertext)
154			Same as "crypt", except it modifies the argument in-place.
155
156			$constant_32 = $cipher->keysize
157			$constant_64 = $cipher->blocksize
158			These methods are provided for Crypt::CBC compatibility and simply
159			return 32 and 64, respectively.
160
161			Note that it is pointless to use Spritz with Crypt::CBC, as Spritz
162			is not a block cipher and already provides an appropriate mode.
163
164			THE Crypt::Spritz::Hash CLASS
165			This implements the Spritz digest/hash algorithm. It works very similar
166			to other digest modules on CPAN, such as Digest::SHA3.
167
168			Typical use for hashing:
169
170			# create hasher object
171			my $hasher = new Crypt::Spritz::Hash;
172
173			# now feed data to be hashed into $hasher
174			# in as few or many calls as required
175			$hasher->add ("Some data");
176			$hasher->add ("Some more");
177
178			# extract the hash - the object is not usable afterwards
179			my $digest = $hasher->finish (32);
180
181			$hasher = new Crypt::Spritz::Hash
182			Creates a new hasher object.
183
184			$hasher->add ($data)
185			Adds data to be hashed into the hasher state. It doesn't matter
186			whether you pass your data in in one go or split it up, the hash
187			will be the same.
188
189			$digest = $hasher->finish ($length)
190			Calculates a hash digest of the given length and return it. The
191			object cannot sensibly be used for further hashing afterwards.
192
193			Typical digest lengths are 16 and 32, corresponding to 128 and 256
194			bit digests, respectively.
195
196			THE Crypt::Spritz::MAC CLASS
197			This implements the Spritz Message Authentication Code algorithm. It
198			works very similar to other digest modules on CPAN, such as
199			Digest::SHA3, but implements an authenticated digest (like
200			Digest::HMAC).
201
202			Authenticated means that, unlike Crypt::Spritz::Hash, where everybody
203			can verify and recreate the hash value for some data, with a MAC,
204			knowledge of the (hopefully) secret key is required both to create and
205			to verify the digest.
206
207			Typical use for hashing is almost the same as with Crypt::Spritz::MAC,
208			except a key (typically 16 or 32 octets) is provided to the constructor:
209
210			# create hasher object
211			my $hasher = new Crypt::Spritz::Mac $key;
212
213			# now feed data to be hashed into $hasher
214			# in as few or many calls as required
215			$hasher->add ("Some data");
216			$hasher->add ("Some more");
217
218			# extract the mac - the object is not usable afterwards
219			my $mac = $hasher->finish (32);
220
221			$hasher = new Crypt::Spritz::MAC $key
222			Creates a new hasher object. The $key can be of any length, but 16
223			and 32 (128 and 256 bit) are customary.
224
225			$hasher->add ($data)
226			Adds data to be hashed into the hasher state. It doesn't matter
227			whether you pass your data in in one go or split it up, the hash
228			will be the same.
229
230			$mac = $hasher->finish ($length)
231			Calculates a message code of the given length and return it. The
232			object cannot sensibly be used for further hashing afterwards.
233
234			Typical digest lengths are 16 and 32, corresponding to 128 and 256
235			bit digests, respectively.
236
237			THE Crypt::Spritz::AEAD::XOR CLASS
238			This is the most complicated class - it combines encryption and message
239			authentication into a single "authenticated encryption mode". It is
240			similar to using both Crypt::Spritz::Cipher::XOR and Crypt::Spritz::MAC,
241			but makes it harder to make mistakes in combining them.
242
243			You can additionally provide cleartext data that will not be encrypted
244			or decrypted, but that is nevertheless authenticated using the MAC,
245			which is why this mode is called AEAD, *Authenticated Encryption with
246			Associated Data*. Associated data is usually used to any header data
247			that is in cleartext, but should nevertheless be authenticated.
248
249			This implementation implements the XOR variant. Just as with
250			Crypt::Spritz::Cipher::XOR, this means it is not compatible with the
251			standard mode, but uses less code and doesn't distinguish between
252			encryption and decryption.
253
254			Typical usage is as follows:
255
256			# create a new aead object
257			# you use one object per message
258			# key length customarily is 16 or 32
259			my $aead = new Crypt::Spritz::AEAD::XOR $key;
260
261			# now you must feed the nonce. if you do not need a nonce,
262			# you can provide the empty string, but you have to call it
263			# after creating the object, before calling associated_data.
264			# the nonce must be different for each usage of the $key.
265			# a counter of some kind is good enough.
266			# reusing a nonce with the same key completely
267			# destroys security!
268			$aead->nonce ($counter);
269
270			# then you must feed any associated data you have. if you
271			# do not have associated cleartext data, you can provide the empty
272			# string, but you have to call it after nonce and before crypt.
273			$aead->associated_data ($header);
274
275			# next, you call crypt one or more times with your data
276			# to be encrypted (opr decrypted).
277			# all except the last call must use a length that is a
278			# multiple of 64.
279			# the last block can have any length.
280			my $encrypted;
281
282			$encrypted .= $aead->crypt ("1" x 64);
283			$encrypted .= $aead->crypt ("2" x 64);
284			$encrypted .= $aead->crypt ("3456");
285
286			# finally you can calculate the MAC for all of the above
287			my $mac = $aead->finish;
288
289			$aead = new Crypt::Spritz::AEAD::XOR $key
290			Creates a new cipher object usable for encryption and decryption.
291
292			The $key can be of any length. Typical lengths for the $key are 16
293			(128 bit) or 32 (256 bit).
294
295			After creation, you have to call "nonce" next.
296
297			$aead->nonce ($nonce)
298			Provide the nonce value (nonce means "value used once"), a value the
299			is unique between all uses with the same key. This method must be
300			called after "new" and before "associated_data".
301
302			If you only ever use a given key once, you can provide an empty
303			nonce - but you still have to call the method.
304
305			Common strategies to provide a nonce are to implement a persistent
306			counter or to generate a random string of sufficient length to
307			guarantee that it differs each time.
308
309			The problem with counters is that you might get confused and forget
310			increments, and thus reuse the same sequence number. The problem
311			with random strings i that your random number generator might be
312			hosed and generate the same randomness multiple times (randomness
313			can be very hard to get especially on embedded devices).
314
315			$aead->associated_data ($data)(
316			Provide the associated data (cleartext data to be authenticated but
317			not encrypted). This method must be called after "nonce" and
318			before "crypt".
319
320			If you don't have any associated data, you can provide an empty
321			string - but you still have to call the method.
322
323			Associated data is typically header data - data anybody is allowed
324			to see in cleartext, but that should nevertheless be protected with
325			an authentication code. Typically such data is used to identify
326			where to forward a message to, how to find the key to decrypt the
327			message or in general how to interpret the encrypted part of a
328			message.
329
330			$encrypted = $cipher->crypt ($cleartext)
331			$cleartext = $cipher->crypt ($encrypted)
332			Encrypt or decrypt a piece of a message. This cna be called as many
333			times as you want, and the message can be split into as few or many
334			pieces as required without affecting the results, with one
335			exception: All except the last call to "crypt" needs to pass in a
336			multiple of 64 octets. The last call to "crypt" does not have this
337			limitation.
338
339			$cipher->crypt_inplace ($cleartext_or_ciphertext)
340			Same as "crypt", except it modifies the argument in-place.
341
342			THE Crypt::Spritz::PRNG CLASS
343			This class implements a Pseudorandom Number Generatore (PRNG), sometimes
344			also called a Deterministic Random Bit Generator (DRBG). In fact, it is
345			even cryptographically secure, making it a CSPRNG.
346
347			Typical usage as a random number generator involves creating a PRNG
348			object with a seed of your choice, and then fetching randomness via
349			"get":
350
351			# create a PRNG object, use a seed string of your choice
352			my $prng = new Crypt::Spritz::PRNG $seed;
353
354			# now call get as many times as you wish to get binary randomness
355			my $some_randomness = $prng->get (17);
356			my moree_randomness = $prng->get (5000);
357			...
358
359			Typical usage as a cryptographically secure random number generator is
360			to feed in some secret entropy (32 octets/256 bits are commonly
361			considered enough), for example from "/dev/random" or "/dev/urandom",
362			and then generate some key material.
363
364			# create a PRNG object
365			my $prng = new Crypt::Spritz::PRNG;
366
367			# seed some entropy (either via ->add or in the constructor)
368			$prng->add ($some_secret_highly_entropic_string);
369
370			# now call get as many times as you wish to get
371			# hard to guess binary randomness
372			my $key1 = $prng->get (32);
373			my $key2 = $prng->get (16);
374			...
375
376			# for long running programs, it is advisable to
377			# reseed the PRNG from time to time with new entropy
378			$prng->add ($some_more_entropy);
379
380			$prng = new Crypt::Spritz::PRNG [$seed]
381			Creates a new random number generator object. If $seed is given,
382			then the $seed is added to the internal state as if by a call to
383			"add".
384
385			$prng->add ($entropy)
386			Adds entropy to the internal state, thereby hopefully making it
387			harder to guess. Good sources for entropy are irregular hardware
388			events, or randomness provided by "/dev/urandom" or "/dev/random".
389
390			The design of the Spritz PRNG should make it strong against attacks
391			where the attacker controls all the entropy, so it should be safe to
392			add entropy from untrusted sources - more is better than less if you
393			need a CSPRNG.
394
395			For use as PRNG, of course, this matters very little.
396
397			$octets = $prng->get ($length)
398			Generates and returns $length random octets as a string.
399
400			SEE ALSO
401			<http://people.csail.mit.edu/rivest/pubs/RS14.pdf>.
402
403			SECURITY CONSIDERATIONS
404			I also cannot give any guarantees for security, Spritz is a very new
405			cryptographic algorithm, and when this module was written, almost
406			completely unproven.
407
408			AUTHOR
409			Marc Lehmann <schmorp@schmorp.de>
410			http://software.schmorp.de/pkg/Crypt-Spritz
411