ThreefishEngine (Bouncy Castle Library 1.52 API Specification)

org.bouncycastle.crypto.engines

## Class ThreefishEngine

- java.lang.Object
- - org.bouncycastle.crypto.engines.ThreefishEngine

- All Implemented Interfaces:
    BlockCipher

      public class ThreefishEngine
      extends java.lang.Object
      implements BlockCipher

  Implementation of the Threefish tweakable large block cipher in 256, 512 and 1024 bit block sizes.

  This is the 1.3 version of Threefish defined in the Skein hash function submission to the NIST SHA-3 competition in October 2010.

  Threefish was designed by Niels Ferguson - Stefan Lucks - Bruce Schneier - Doug Whiting - Mihir Bellare - Tadayoshi Kohno - Jon Callas - Jesse Walker.

  This implementation inlines all round functions, unrolls 8 rounds, and uses 1.2k of static tables to speed up key schedule injection.
  2 x block size state is retained by each cipher instance.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BLOCKSIZE_1024` 1024 bit block size - Threefish-1024
    `static int` | `BLOCKSIZE_256` 256 bit block size - Threefish-256
    `static int` | `BLOCKSIZE_512` 512 bit block size - Threefish-512

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ThreefishEngine(int blocksizeBits)` Constructs a new Threefish cipher, with a specified block size.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static long` | `bytesToWord(byte[] bytes, int off)` Read a single 64 bit word from input in LSB first order.
    `java.lang.String` | `getAlgorithmName()` Return the name of the algorithm the cipher implements.
    `int` | `getBlockSize()` Return the block size for this cipher (in bytes).
    `void` | `init(boolean forEncryption, CipherParameters params)` Initialise the engine.
    `void` | `init(boolean forEncryption, long[] key, long[] tweak)` Initialise the engine, specifying the key and tweak directly.
    `int` | `processBlock(byte[] in, int inOff, byte[] out, int outOff)` Process one block of input from the array in and write it to the out array.
    `int` | `processBlock(long[] in, long[] out)` Process a block of data represented as 64 bit words.
    `void` | `reset()` Reset the cipher.
    `static void` | `wordToBytes(long word, byte[] bytes, int off)` Write a 64 bit word to output in LSB first order.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### BLOCKSIZE_256

          public static final int BLOCKSIZE_256

      256 bit block size - Threefish-256
      See Also:
        Constant Field Values

    - #### BLOCKSIZE_512

          public static final int BLOCKSIZE_512

      512 bit block size - Threefish-512
      See Also:
        Constant Field Values

    - #### BLOCKSIZE_1024

          public static final int BLOCKSIZE_1024

      1024 bit block size - Threefish-1024
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ThreefishEngine

          public ThreefishEngine(int blocksizeBits)

      Constructs a new Threefish cipher, with a specified block size.
      Parameters:
        `blocksizeBits` - the block size in bits, one of `BLOCKSIZE_256`, `BLOCKSIZE_512`, `BLOCKSIZE_1024`.

  - ### Method Detail

    - #### init

          public void init(boolean forEncryption,
                  CipherParameters params)
                    throws java.lang.IllegalArgumentException

      Initialise the engine.
      Specified by:
        `init` in interface `BlockCipher`
      Parameters:
        `params` - an instance of `TweakableBlockCipherParameters`, or `KeyParameter` (to use a 0 tweak)
        `forEncryption` - if true the cipher is initialised for encryption, if false for decryption.
      Throws:
        `java.lang.IllegalArgumentException` - if the params argument is inappropriate.

    - #### init

          public void init(boolean forEncryption,
                  long[] key,
                  long[] tweak)

      Initialise the engine, specifying the key and tweak directly.
      Parameters:
        `forEncryption` - the cipher mode.
        `key` - the words of the key, or `null` to use the current key.
        `tweak` - the 2 word (128 bit) tweak, or `null` to use the current tweak.

    - #### getAlgorithmName

          public java.lang.String getAlgorithmName()

      Description copied from interface: `BlockCipher`
      Return the name of the algorithm the cipher implements.
      Specified by:
        `getAlgorithmName` in interface `BlockCipher`
      Returns:
        the name of the algorithm the cipher implements.

    - #### getBlockSize

          public int getBlockSize()

      Description copied from interface: `BlockCipher`
      Return the block size for this cipher (in bytes).
      Specified by:
        `getBlockSize` in interface `BlockCipher`
      Returns:
        the block size for this cipher in bytes.

    - #### reset

          public void reset()

      Description copied from interface: `BlockCipher`
      Reset the cipher. After resetting the cipher is in the same state as it was after the last init (if there was one).
      Specified by:
        `reset` in interface `BlockCipher`

    - #### processBlock

          public int processBlock(byte[] in,
                         int inOff,
                         byte[] out,
                         int outOff)
                           throws DataLengthException,
                                  java.lang.IllegalStateException

      Description copied from interface: `BlockCipher`
      Process one block of input from the array in and write it to the out array.
      Specified by:
        `processBlock` in interface `BlockCipher`
      Parameters:
        `in` - the array containing the input data.
        `inOff` - offset into the in array the data starts at.
        `out` - the array the output data will be copied into.
        `outOff` - the offset into the out array the output will start at.
      Returns:
        the number of bytes processed and produced.
      Throws:
        `DataLengthException` - if there isn't enough data in in, or space in out.
        `java.lang.IllegalStateException` - if the cipher isn't initialised.

    - #### processBlock

          public int processBlock(long[] in,
                         long[] out)
                           throws DataLengthException,
                                  java.lang.IllegalStateException

      Process a block of data represented as 64 bit words.
      Parameters:
        `in` - a block sized buffer of words to process.
        `out` - a block sized buffer of words to receive the output of the operation.
      Returns:
        the number of 8 byte words processed (which will be the same as the block size).
      Throws:
        `DataLengthException` - if either the input or output is not block sized.
        `java.lang.IllegalStateException` - if this engine is not initialised.

    - #### bytesToWord

          public static long bytesToWord(byte[] bytes,
                         int off)

      Read a single 64 bit word from input in LSB first order.

    - #### wordToBytes

          public static void wordToBytes(long word,
                         byte[] bytes,
                         int off)

      Write a 64 bit word to output in LSB first order.