view release on metacpan or  search on metacpan

README  view on Meta::CPAN

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

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

    $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 "Crypt::Spritz::AEAD" and "Crypt::Spritz::AEAD::XOR", as
        they allow you to specify the IV/nonce separately.

    $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::Cipher CLASS
    This class is pretty much the same as the "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 "Crypt::Spritz::Cipher::XOR".

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

    $encrypted = $cipher->encrypt ($cleartext)
    $cleartext = $cipher->decrypt ($encrypted)
        Really the same as "Crypt::Spritz::Cipher::XOR", except you need
        separate calls and code for encryption and decryption.

  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