Threefish encryption
====================

.. function:: skein.threefish(key, tweak)

    This constructor function returns a cipher object for encryption and
    decryption with the given key and tweak values.
    The key must be a bytes object of length 32, 64, or 128,
    while the tweak must always consist of 16 bytes.


Threefish cipher objects have two methods:

.. method:: encrypt_block(data)

    Encrypt the given block of (bytes) data.
    (String data has to be encoded to bytes first.)
    The block has to have the same length as the key,
    i.e. 32, 64, or 128 bytes.

.. method:: decrypt_block(data)

    Decrypt the given block of (bytes) data.
    The block has to have the same length as the key,
    i.e. 32, 64, or 128 bytes.


Threefish objects have the following attributes:

.. attribute:: tweak

    The tweak value given to the constructor function.
    This attribute is writable, allowing the tweak to be changed without
    creation of a new cipher object.

.. attribute:: block_bits

    Threefish block size (as determined by the key length) in bits, i.e.
    ``256``, ``512``, or ``1024``

.. attribute:: block_size

    Threefish block size in bytes (same as the key length), i.e.
    ``32``, ``64``, or ``128``


Examples
--------

Encryption and decryption of a block of 32 bytes::

    >>> from skein import threefish
    >>> t = threefish(b"key of 32,64 or 128 bytes length", b"tweak: 16 bytes ")
    >>> t.block_size, t.block_bits
    (32, 256)
    >>> c = t.encrypt_block(b"block of data,same length as key")
    >>> c
    b"\x96\xb9\x9f\xefk\xe6\x9d\xc2\x17\xd8d\xc1+\xa6\xe0\x87\xa9\xc7\xa0R\xdd\x9c'\x02\xee\\\r\xa0\xa7y\xba\xa9"
    >>> t.decrypt_block(c)
    b'block of data,same length as key'


Changing the tweak leads to a different cipher text::

    >>> t.tweak = b"some other tweak"
    >>> c = t.encrypt_block(b"block of data,same length as key")
    >>> c
    b"@\xe6]+t\xb77\x8f'\xf73\xf1s\xdf\xf9\x02\x06\xe2\x9f\x1a!\x1c\xe6\x0b8\x8e\xed'@\xaf\xd2{"
    >>> t.decrypt_block(c)
    b'block of data,same length as key'
 
