--- Crypt-Spritz/Spritz.pm	2015/01/10 07:19:24	1.5
+++ Crypt-Spritz/Spritz.pm	2015/01/10 07:48:29	1.6
@@ -1,6 +1,6 @@
 =head1 NAME
 
-Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG module
+Crypt::Spritz - Spritz stream cipher/hash/MAC/AEAD/CSPRNG family
 
 =head1 SYNOPSIS
 
@@ -48,8 +48,8 @@
 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
+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.
 
@@ -69,7 +69,7 @@
 
 use XSLoader;
 
-$VERSION = '0.0';
+$VERSION = '0.1';
 
 XSLoader::load __PACKAGE__, $VERSION;
 
@@ -122,6 +122,12 @@
 
 Initialises the Spritz state again, throwing away the previous state.
 
+=item $another_spritz = $spritz->clone
+
+Make an exact copy of the spritz state. This method can be called on all
+of the objects in this module, but is documented separately to give some
+cool usage examples.
+
 =item $spritz->update               # Update
 
 =item $spritz->whip ($r)            # Whip
@@ -137,8 +143,8 @@
 
 =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).
+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
 
@@ -209,7 +215,7 @@
 
 =item $cleartext = $cipher->crypt ($encrypted)
 
-Encrypt or decrypt a piece of a message. This cna be called as many times
+Encrypt or decrypt a piece of a message. This can 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.
 
@@ -217,6 +223,15 @@
 
 Same as C<crypt>, except it I<modifies the argument in-place>.
 
+=item $another_cipher = $cipher->clone
+
+Make an exact copy of the cipher state. This can be useful to cache states
+for reuse later, for example, to avoid expensive key setups.
+
+While there might be use cases for this feature, it makes a lot more sense
+for C<Crypt::Spritz::AEAD> and C<Crypt::Spritz::AEAD::XOR>, as they allow
+you to specify the IV/nonce separately.
+
 =item $constant_32 = $cipher->keysize
 
 =item $constant_64 = $cipher->blocksize
@@ -267,6 +282,35 @@
 Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
 digests, respectively.
 
+=item $another_hasher = $hasher->clone
+
+Make an exact copy of the hasher state. This can be useful to generate
+incremental hashes, for example.
+
+Example: generate a hash for the data already fed into the hasher, by keeping
+the original hasher for further C<add> calls and calling C<finish> on a C<clone>.
+
+   my $intermediate_hash = $hasher->clone->finish;
+
+Example: hash 64KiB of data, and generate a hash after every kilobyte that
+is over the full data.
+
+   my $hasher = new Crypt::Spritz::Hash;
+
+   for (0..63) {
+      my $kib = "x" x 1024; # whatever data
+
+      $hasher->add ($kib);
+
+      my $intermediate_hash = $hasher->clone->finish;
+      ...
+   }
+
+These kind of intermediate hashes are sometimes used in communications
+protocols to protect the integrity of the data incrementally, e.g. to
+detect errors early, while still having a complete hash at the end of a
+transfer.
+
 =back
 
 
@@ -315,6 +359,14 @@
 Typical digest lengths are 16 and 32, corresponding to 128 and 256 bit
 digests, respectively.
 
+=item $another_hasher = $hasher->clone
+
+Make an exact copy of the hasher state. This can be useful to
+generate incremental macs, for example.
+
+See the description for the C<Crypt::Spritz::Hash::clone> method for some
+examples.
+
 =back
 
 
@@ -402,7 +454,7 @@
 generate the same randomness multiple times (randomness can be very hard
 to get especially on embedded devices).
 
-=item $aead->associated_data ($data)(
+=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>
@@ -421,7 +473,7 @@
 
 =item $cleartext = $cipher->crypt ($encrypted)
 
-Encrypt or decrypt a piece of a message. This cna be called as many times
+Encrypt or decrypt a piece of a message. This can 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
@@ -431,6 +483,26 @@
 
 Same as C<crypt>, except it I<modifies the argument in-place>.
 
+=item $another_cipher = $cipher->clone
+
+Make an exact copy of the cipher state. This can be useful to cache states
+for reuse later, for example, to avoid expensive key setups.
+
+Example: set up a cipher state with a key, then clone and use it to
+encrypt messages with different nonces.
+
+   my $cipher = new Crypt::Spritz::AEAD::XOR $key;
+
+   my $message_counter;
+
+   for my $message ("a", "b", "c") {
+      my $clone = $cipher->clone;
+      $clone->nonce (pack "N", ++$message_counter);
+      $clone->associated_data ("");
+      my $encrypted = $clone->crypt ($message);
+      ...
+   }
+
 =back