net.ninthtest.crypto.provider.helix

Class HelixCipher

java.lang.Object

javax.crypto.CipherSpi

net.ninthtest.crypto.provider.helix.HelixCipher

public final class HelixCipher
extends CipherSpi

This class provides encryption and decryption (with optional MAC generation and verification) operations for the Helix stream cipher.

Version:

1.1.0

Author:

Matthew Zipay (mattz@ninthtest.net)

See Also:

Helix: Fast Encryption and Authentication in a Single Cryptographic Primitive

Constructor Summary

Constructors

Constructor and Description
HelixCipher() Creates a new HelixCipher and performs the provider self-integrity check.

Method Summary

Modifier and Type	Method and Description
protected byte[]	engineDoFinal(byte[] input, int inputOffset, int inputLen) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
protected int	engineDoFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
protected int	engineGetBlockSize() Returns the block size (in bytes).
protected byte[]	engineGetIV() Returns the initialization vector (IV) in a new buffer.
protected int	engineGetKeySize(Key key) Returns the key size of the given key object in bits.
protected int	engineGetOutputSize(int inputLen) Returns the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length inputLen (in bytes).
protected AlgorithmParameters	engineGetParameters() Returns the parameters used with this cipher.
protected void	engineInit(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
protected void	engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
protected void	engineInit(int opmode, Key key, SecureRandom random) Initializes this cipher with a key and a source of randomness.
protected void	engineSetMode(String mode) Sets the mode of this cipher.
protected void	engineSetPadding(String padding) Sets the padding mechanism of this cipher.
protected Key	engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType) Unwraps a previously wrapped key.
protected byte[]	engineUpdate(byte[] input, int inputOffset, int inputLen) Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
protected int	engineUpdate(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset) Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.
protected byte[]	engineWrap(Key key) Wraps a key.

Methods inherited from class javax.crypto.CipherSpi

engineDoFinal, engineUpdate, engineUpdateAAD, engineUpdateAAD

Methods inherited from class java.lang.Object

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

Constructor Detail

HelixCipher

public HelixCipher()

Creates a new HelixCipher and performs the provider self-integrity check.

Method Detail

engineGetBlockSize

protected int engineGetBlockSize()

Returns the block size (in bytes).

Specified by:

engineGetBlockSize in class CipherSpi

Returns:

0 (zero; Helix is a stream cipher)

See Also:

CipherSpi.engineGetBlockSize()

engineGetKeySize

protected int engineGetKeySize(Key key)
                        throws InvalidKeyException

Returns the key size of the given key object in bits.

Overrides:

engineGetKeySize in class CipherSpi

Parameters:

key - a Helix SecretKey

Returns:

the size of key expressed in number of bits

Throws:

InvalidKeyException - if key is null or not a Helix SecretKey

See Also:

CipherSpi.engineGetKeySize(java.security.Key)

engineInit

protected void engineInit(int opmode,
                          Key key,
                          SecureRandom random)
                   throws InvalidKeyException

Initializes this cipher with a key and a source of randomness.

Initializing the cipher in this manner causes the Helix nonce to be randomly generated; therefore, this method can only be used to initialize the cipher for encryption or key wrapping.

The randomly-generated nonce can be retrieved directly via Cipher.getIV() or indirectly via Cipher.getParameters().

Specified by:

engineInit in class CipherSpi

Parameters:

opmode - the operation mode of this cipher (restricted to Cipher.ENCRYPT_MODE or Cipher.WRAP_MODE)

key - the secret key to be used for encryption or key wrapping (must be a Helix SecretKey)

random - the RNG

Throws:

IllegalArgumentException - if the operation mode is Cipher.DECRYPT_MODE or Cipher.UNWRAP_MODE

InvalidKeyException - if key is null or is not a Helix SecretKey

See Also:

CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

engineInit

protected void engineInit(int opmode,
                          Key key,
                          AlgorithmParameterSpec params,
                          SecureRandom random)
                   throws InvalidKeyException,
                          InvalidAlgorithmParameterException

Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.

When opmode is Cipher.DECRYPT_MODE or Cipher.UNWRAP_MODE, a MAC specified in params must be exactly 16 bytes in length, in which case Cipher.doFinal() will fail unless the generated MAC matches the MAC specified in params. Otherwise, the MAC can be left null, causing MAC verification to be skipped.

When opmode is Cipher.ENCRYPT_MODE or Cipher.WRAP_MODE, a MAC must not be specified in params. After Cipher.doFinal() completes successfully, the generated MAC can be retrieved indirectly via Cipher.getParameters() (prior to this cipher being re-initialized).

Specified by:

engineInit in class CipherSpi

Parameters:

opmode - the operation mode of this cipher

key - a Helix SecretKey

params - a HelixParameterSpec

random - the RNG (not used)

Throws:

InvalidKeyException - if key is null or is not a Helix SecretKey; or if the algorithm parameters cannot be initialized from the parameter spec

InvalidAlgorithmParameterException - if params is null or is not a HelixParameterSpec; or if a non-null MAC in params is not exactly 16 bytes in length; or if a non- null MAC is specified in params when opmode is Cipher.ENCRYPT_MODE or Cipher.WRAP_MODE

See Also:

CipherSpi.engineInit(int, java.security.Key, java.security.spec.AlgorithmParameterSpec, java.security.SecureRandom)

engineInit

protected void engineInit(int opmode,
                          Key key,
                          AlgorithmParameters params,
                          SecureRandom random)
                   throws InvalidKeyException,
                          InvalidAlgorithmParameterException

Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.

When opmode is Cipher.DECRYPT_MODE or Cipher.UNWRAP_MODE, a MAC specified in params must be exactly 16 bytes in length, in which case Cipher.doFinal() will fail unless the generated MAC matches the MAC specified in params. Otherwise, the MAC can be left null, causing MAC verification to be skipped.

When opmode is Cipher.ENCRYPT_MODE or Cipher.WRAP_MODE, a MAC must not be specified in params. After Cipher.doFinal() completes successfully, the generated MAC can be retrieved indirectly via Cipher.getParameters() (prior to this cipher being re-initialized).

Specified by:

engineInit in class CipherSpi

Parameters:

opmode - the operation mode of this cipher

key - a Helix SecretKey

params - Helix algorithm parameters provided by NinthTest

random - the RNG (not used)

Throws:

InvalidKeyException - if key is null or is not a Helix SecretKey

InvalidAlgorithmParameterException - if params is null or is not a Helix AlgorithmParameters provided by NinthTest; or if a HelixParameterSpec cannot be derived from params; or if a non-null MAC in params is not exactly 16 bytes in length; or if a non-null MAC is specified in params when opmode is either Cipher.ENCRYPT_MODE or Cipher.WRAP_MODE

See Also:

CipherSpi.engineInit(int, java.security.Key, java.security.AlgorithmParameters, java.security.SecureRandom)

engineSetMode

protected void engineSetMode(String mode)
                      throws NoSuchAlgorithmException

Sets the mode of this cipher.

This method always throws UnsupportedOperationException.

Specified by:

engineSetMode in class CipherSpi

Parameters:

mode - the cipher mode

Throws:

NoSuchAlgorithmException - if the requested cipher mode does not exist

UnsupportedOperationException - if this method is invoked

See Also:

CipherSpi.engineSetMode(java.lang.String)

engineSetPadding

protected void engineSetPadding(String padding)
                         throws NoSuchPaddingException

Sets the padding mechanism of this cipher.

This method always throws UnsupportedOperationException.

Specified by:

engineSetPadding in class CipherSpi

Parameters:

padding - the cipher padding method

Throws:

NoSuchPaddingException - if the requested padding mechanism does not exist

UnsupportedOperationException - if this method is invoked

See Also:

CipherSpi.engineSetPadding(java.lang.String)

engineGetParameters

protected AlgorithmParameters engineGetParameters()

Returns the parameters used with this cipher.

This method provides one way of obtaining the randomly-generated nonce after initialization (the other being the Cipher.getIV() method).

The nonce is randomly generated if the cipher is initialized using Cipher.init(int, Key) or Cipher.init(int, Key, SecureRandom).

This method also allows for the retrieval of the generated MAC following a successful encryption or key-wrapping operation.

Specified by:

engineGetParameters in class CipherSpi

Returns:

the algorithm parameters used for the current operation, or null if this cipher has not yet been initialized

See Also:

CipherSpi.engineGetParameters()

engineGetIV

protected byte[] engineGetIV()

Returns the initialization vector (IV) in a new buffer.

This method provides one way of obtaining the randomly-generated nonce after initialization (the other being the Cipher.getParameters() method).

The nonce is randomly generated if the cipher is initialized using Cipher.init(int, Key) or Cipher.init(int, Key, SecureRandom).

Specified by:

engineGetIV in class CipherSpi

Returns:

the Helix nonce used for the current operation, or null if this cipher has not yet been initialized

See Also:

CipherSpi.engineGetIV()

engineGetOutputSize

protected int engineGetOutputSize(int inputLen)

Returns the length in bytes that an output buffer would need to be in order to hold the result of the next update or doFinal operation, given the input length inputLen (in bytes).

Up to three input bytes may be buffered when Cipher.update(byte[]) is called, because input is processed by the underlying Helix primitive one word (i.e. one 32-bit integer) at a time.

Specified by:

engineGetOutputSize in class CipherSpi

Parameters:

inputLen - the number of input bytes that will be passed to the next Cipher.update(byte[]) or Cipher.doFinal() operation

Returns:

the size that the output buffer would need to be to hold the result of the next Cipher.update(byte[]) or Cipher.doFinal() operation (given input of length inputLen)

See Also:

CipherSpi.engineGetOutputSize(int)

engineUpdate

protected byte[] engineUpdate(byte[] input,
                              int inputOffset,
                              int inputLen)

Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

If the input (combined with any previously-buffered input) is not long enough to yield at least four bytes of output, input will be buffered and this method will return null.

If this method returns non-null, the returned byte array will always have a length that is a multiple of four.

Specified by:

engineUpdate in class CipherSpi

Parameters:

input - the input buffer

inputOffset - the index into input where the input bytes begin

inputLen - the number of bytes to be used from input (beginning at inputOffset)

Returns:

four or more bytes of output, or null if there are not enough input bytes to yield at least four bytes of output

See Also:

CipherSpi.engineUpdate(byte[], int, int)

engineUpdate

protected int engineUpdate(byte[] input,
                           int inputOffset,
                           int inputLen,
                           byte[] output,
                           int outputOffset)
                    throws ShortBufferException

Continues a multiple-part encryption or decryption operation (depending on how this cipher was initialized), processing another data part.

If the input (combined with any previously-buffered input) is not long enough to yield at least four bytes of output, input will be buffered, output will not be modified, and this method will return 0 (zero).

The integer returned by this method will always be a multiple of four (or zero, as described above).

Specified by:

engineUpdate in class CipherSpi

Parameters:

input - the input buffer

inputOffset - the index into input where the input bytes begin

inputLen - the number of bytes to be used from input (beginning at inputOffset)

output - the buffer for the result

outputOffset - the index into output where the output bytes are stored

Returns:

the number of bytes that were written to output, or 0 (zero) if there was not enough input to produce at least four bytes of output

Throws:

ShortBufferException - if output (beginning at outputOffset) is not large enough to store the number of bytes produced by this call

See Also:

CipherSpi.engineUpdate(byte[], int, int, byte[], int)

engineDoFinal

protected byte[] engineDoFinal(byte[] input,
                               int inputOffset,
                               int inputLen)
                        throws IllegalBlockSizeException,
                               BadPaddingException

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.

If the current operation mode is Cipher.ENCRYPT_MODE, the Helix-generated MAC will be stored in the algorithm parameters. The MAC can be retrieved indirectly via Cipher.getParameters() prior to this cipher being re-initialized.

If the current operation mode is Cipher.DECRYPT_MODE, and the expected MAC was specified when this cipher was initialized, the expected MAC will be compared to the MAC that was generated for this operation. If the expected and generated MACs are not equal, this method will throw MessageAuthenticationException.

Specified by:

engineDoFinal in class CipherSpi

Parameters:

input - the input buffer

inputOffset - the index into input where the input bytes begin

inputLen - the number of bytes to be used from input (beginning at inputOffset)

Returns:

all remaining bytes of output

Throws:

IllegalBlockSizeException - never (Helix is a stream cipher)

BadPaddingException - never (Helix padding is masked off)

MessageAuthenticationException - for a decryption operation only, if the non-null expected MAC does not match the generated MAC

See Also:

CipherSpi.engineDoFinal(byte[], int, int)

engineDoFinal

protected int engineDoFinal(byte[] input,
                            int inputOffset,
                            int inputLen,
                            byte[] output,
                            int outputOffset)
                     throws ShortBufferException,
                            IllegalBlockSizeException,
                            BadPaddingException

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.

If the current operation mode is Cipher.ENCRYPT_MODE, the generated MAC will be stored in the algorithm parameters, and can be retrieved indirectly via Cipher.getParameters() prior to re-initializing this cipher.

If the current operation mode is Cipher.DECRYPT_MODE, and the expected MAC was specified when this cipher was initialized, the expected MAC will be compared to the MAC that was generated for this operation. If the expected and generated MACs are not equal, this method will throw MessageAuthenticationException.

Specified by:

engineDoFinal in class CipherSpi

Parameters:

input - the input buffer

inputOffset - the index into input where the input bytes begin

inputLen - the number of bytes to be used from input (beginning at inputOffset)

output - the buffer for the result

outputOffset - the index into output where the output bytes are stored

Returns:

all remaining bytes of output

Throws:

ShortBufferException - if output (beginning at outputOffset) is not large enough to store the number of bytes produced by this call

IllegalBlockSizeException - never (Helix is a stream cipher)

BadPaddingException - never (Helix padding is masked off)

MessageAuthenticationException - for a decryption operation only, if the non-null expected MAC does not match the generated MAC

See Also:

CipherSpi.engineDoFinal(byte[], int, int, byte[], int)

engineWrap

protected byte[] engineWrap(Key key)
                     throws IllegalBlockSizeException,
                            InvalidKeyException

Wraps a key.

Overrides:

engineWrap in class CipherSpi

Parameters:

key - the key to be wrapped

Returns:

the wrapped key

Throws:

IllegalBlockSizeException - never (Helix is a stream cipher)

InvalidKeyException - if key is null

See Also:

CipherSpi.engineWrap(java.security.Key)

engineUnwrap

protected Key engineUnwrap(byte[] wrappedKey,
                           String wrappedKeyAlgorithm,
                           int wrappedKeyType)
                    throws InvalidKeyException,
                           NoSuchAlgorithmException

Unwraps a previously wrapped key.

If the expected MAC was specified when this cipher was initialized, the expected MAC will be compared to the MAC that was generated for this operation. If the expected and generated MACs are not equal, this method will throw MessageAuthenticationException.

Overrides:

engineUnwrap in class CipherSpi

Parameters:

wrappedKey - the key to be unwrapped

wrappedKeyAlgorithm - the algorithm associated with the wrapped key

wrappedKeyType - the type of the wrapped key ( Cipher.SECRET_KEY, Cipher.PRIVATE_KEY, or Cipher.PUBLIC_KEY)

Returns:

the unwrapped key

Throws:

InvalidKeyException - if wrappedKey does not represent a key of type wrappedKeyType for the wrappedKeyAlgorithm

NoSuchAlgorithmException - if no installed providers can create keys of type wrappedKeyType for the wrappedKeyAlgorithm

MessageAuthenticationException - if the non-null expected MAC does not match the generated MAC

See Also:

CipherSpi.engineUnwrap(byte[], java.lang.String, int)