net.ninthtest.crypto.provider.helix
Class HelixCipher

java.lang.Object
  extended by javax.crypto.CipherSpi
      extended by 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.info)
See Also:
Helix: Fast Encryption and Authentication in a Single Cryptographic Primitive

Constructor Summary
HelixCipher()
          Creates a new HelixCipher and performs the provider self-integrity check.
 
Method Summary
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
 
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)


Copyright © 2010-2014 Matthew Zipay. All Rights Reserved.