view release on metacpan or  search on metacpan

Spritz.pm  view on Meta::CPAN

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

=item $cipher->crypt_inplace ($cleartext_or_ciphertext)

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

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::Cipher CLASS

This class is pretty much the same as the C<Crypt::Spritz::Cipher::XOR>
class, with two differences: first, it implements the "standard" Spritz
encryption algorithm, and second, while this variant is easier to analyze
mathematically, there is little else to recommend it for, as it is slower,
and requires lots of code duplication code.

So unless you need to be compatible with another implementation that does
not offer the XOR variant, stick to C<Crypt::Spritz::Cipher::XOR>.

All the methods from C<Crypt::Spritz::Cipher::XOR> are available, except
C<crypt>, which has been replaced by separate C<encrypt> and C<decrypt>
methods:

=over 4

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

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

Really the same as C<Crypt::Spritz::Cipher::XOR>, except you need separate
calls and code for encryption and decryption.

=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