org.cumulus4j.crypto
Interface Cipher

All Known Implementing Classes:

AbstractCipher, AEADBlockCipherImpl, AsymmetricBlockCipherImpl, BufferedBlockCipherImpl, StreamCipherImpl

public interface Cipher

A cipher encrypts or decrypts data.

This interface defines the algorithm-independent API contract to allow for encrypting and decrypting data. It has been introduced in analogy to Cipher and with easy migration from JCE to this API in mind.

Important: Ciphers are not thread-safe!

Use CryptoRegistry.createCipher(String) to obtain a Cipher instance.

This own API is used instead of the JCE, because of the following reasons:

• The JCE has a key length constraint (maximum 128 bit) that requires manual modifications of the Java runtime environment (installing some files that are not included in the operating system's package management).
• The BouncyCastleProvider was not correctly registered in the JCE when using One-JAR to package e.g. the org.cumulus4j.keymanager.cli. Probably because the signatures where not found when looking for the MANIFEST.MF (probably the wrong MANIFEST.MF was picked by the class loader).

Note: Implementors should subclass AbstractCipher instead of directly implementing this interface.

Author:

Marco หงุ่ยตระกูล-Schulze - marco at nightlabs dot de

Method Summary

byte[]	doFinal(byte[] in) Convenience method to encrypt/decrypt the complete input byte array at once.
int	doFinal(byte[] out, int outOff) Process the last block in the buffer.
int	getInputBlockSize() Get the input block size for this cipher (in bytes).
int	getIVSize() Get the required size of the IV (in bytes).
CipherOperationMode	getMode() Get the mode of this cipher.
int	getOutputBlockSize() Get the output block size for this cipher (in bytes).
int	getOutputSize(int length) Return the size of the output buffer required for an update plus a doFinal with an input of length bytes.
CipherParameters	getParameters() Get the parameters of this cipher.
String	getTransformation() Get the transformation that was passed to CryptoRegistry.createCipher(String) for obtaining this Cipher.
int	getUpdateOutputSize(int length) Return the size of the output buffer required for an update of an input of length bytes.
void	init(CipherOperationMode mode, CipherParameters parameters) Initialise the cipher.
void	reset() Reset this cipher.
int	update(byte[] in, int inOff, int inLen, byte[] out, int outOff) Update this cipher with multiple bytes.
int	update(byte in, byte[] out, int outOff) Update this cipher with a single byte.

Method Detail

init

void init(CipherOperationMode mode,
          CipherParameters parameters)
          throws IllegalArgumentException

Initialise the cipher.

A cipher cannot be used, before this method was called.

A cipher can be re-initialised to modify only certain parameters (and keep the others). For example to modify the IV while keeping the key, a cipher can be re-initialised with an IV only (i.e. null is passed to ParametersWithIV.ParametersWithIV(CipherParameters, byte[], int, int) instead of a KeyParameter). This is useful for performance reasons, because modifying an IV is a very fast operation while changing the key is slow (especially Blowfish is known for its very slow key initialisation).

Parameters:

mode - the operation mode; must not be null.

parameters - the parameters; for example an instance of ParametersWithIV with a wrapped KeyParameter to pass IV and secret key.

Throws:

IllegalArgumentException - if the given arguments are invalid - for example if the given parameters are not understood by the implementation (parameters not compatible with the chosen algorithm).

getMode

CipherOperationMode getMode()

Get the mode of this cipher. This is null, before init(CipherOperationMode, CipherParameters) was called the first time.

Returns:

the mode of this cipher.

getParameters

CipherParameters getParameters()

Get the parameters of this cipher. This is null, before init(CipherOperationMode, CipherParameters) was called the first time.

Returns:

the parameters of this cipher.

getTransformation

String getTransformation()

Get the transformation that was passed to CryptoRegistry.createCipher(String) for obtaining this Cipher.

Returns:

the transformation (encryption algorithm, mode and padding) of this cipher.

reset

void reset()

Reset this cipher. After resetting, the state is the same as if it was just freshly initialised.

getInputBlockSize

int getInputBlockSize()

Get the input block size for this cipher (in bytes). If this is a symmetric cipher, this equals getOutputBlockSize().

Returns:

the input block size for this cipher in bytes.

getOutputBlockSize

int getOutputBlockSize()

Get the output block size for this cipher (in bytes). If this is a symmetric cipher, this equals getInputBlockSize().

Returns:

the output block size for this cipher in bytes.

getUpdateOutputSize

int getUpdateOutputSize(int length)

Return the size of the output buffer required for an update of an input of length bytes.

Parameters:

length - the size of the input (in bytes) that is to be passed to update(byte[], int, int, byte[], int).

Returns:

the required length of the output buffer in bytes.

getOutputSize

int getOutputSize(int length)

Return the size of the output buffer required for an update plus a doFinal with an input of length bytes.

Parameters:

length - the size of the input (in bytes) that is to be passed to update(byte[], int, int, byte[], int).

Returns:

the required length of the output buffer in bytes.

update

int update(byte in,
           byte[] out,
           int outOff)
           throws DataLengthException,
                  IllegalStateException,
                  CryptoException

Update this cipher with a single byte. This is synonymous to calling update(byte[], int, int, byte[], int) with an in byte array of length 1 and inOff = 0 and inLen = 1.

Note that data might still be unprocessed in this cipher when this method returns. That is because many ciphers work with blocks and keep a block unprocessed until it is filled up. Call doFinal(byte[], int) after you finished updating this cipher (i.e. all input was passed completely).

Parameters:

in - the input to be encrypted or decrypted (or a part of the input).

out - the buffer receiving the output (data is written into this byte-array). Must not be null.

outOff - the array-index in out at which to start writing. Must be >=0.

Returns:

the number of bytes written into out.

Throws:

DataLengthException - if the buffer out is insufficient.

IllegalStateException - if this cipher has not yet been initialised.

CryptoException - if there is a cryptographic error happening while processing the input. For example when decrypting a padding might be wrong or an authenticating block mode (like GCM) might recognize that the ciphertext has been manipulated/corrupted.

See Also:

update(byte[], int, int, byte[], int), doFinal(byte[], int)

update

int update(byte[] in,
           int inOff,
           int inLen,
           byte[] out,
           int outOff)
           throws DataLengthException,
                  IllegalStateException,
                  CryptoException

Update this cipher with multiple bytes.

Note that data might still be unprocessed in this cipher when this method returns. That is because many ciphers work with blocks and keep a block unprocessed until it is filled up. Call doFinal(byte[], int) after you finished updating this cipher (i.e. all input was passed completely).

Parameters:

in - the input to be encrypted or decrypted (or a part of the input). Must not be null.

inOff - the array-index in in at which to start reading. Must be >=0.

inLen - the number of bytes that should be read from in.

out - the buffer receiving the output (data is written into this byte-array). Must not be null.

outOff - the array-index in out at which to start writing. Must be >=0.

Returns:

the number of bytes written into out.

Throws:

DataLengthException - if the buffer out is insufficient or if inOff + inLen exceeds the input byte array.

IllegalStateException - if this cipher has not yet been initialised.

CryptoException - if there is a cryptographic error happening while processing the input. For example when decrypting a padding might be wrong or an authenticating block mode (like GCM) might recognize that the ciphertext has been manipulated/corrupted.

See Also:

update(byte, byte[], int), doFinal(byte[], int)

doFinal

int doFinal(byte[] out,
            int outOff)
            throws DataLengthException,
                   IllegalStateException,
                   CryptoException

Process the last block in the buffer. After this call, no unprocessed data is left in this cipher and it is reset() implicitly.

Parameters:

out - the buffer receiving the output (data is written into this byte-array). Must not be null.

outOff - the array-index in out at which to start writing. Must be >=0.

Returns:

the number of bytes written into out.

Throws:

DataLengthException - if the buffer out is insufficient or if inOff + inLen exceeds the input byte array.

IllegalStateException - if this cipher has not yet been initialised.

CryptoException - if there is a cryptographic error happening while processing the input. For example when decrypting a padding might be wrong or an authenticating block mode (like GCM) might recognize that the ciphertext has been manipulated/corrupted.

See Also:

update(byte, byte[], int), update(byte[], int, int, byte[], int), doFinal(byte[])

doFinal

byte[] doFinal(byte[] in)
               throws IllegalStateException,
                      CryptoException

Convenience method to encrypt/decrypt the complete input byte array at once. After this method was called, no unprocessed data is left in this cipher and it is reset() implicitly.

Parameters:

in - the input to be encrypted or decrypted. Must not be null.

Returns:

the processed output.

Throws:

IllegalStateException - if the cipher isn't initialised.

CryptoException - if padding is expected and not found or sth. else goes wrong while encrypting or decrypting.

getIVSize

int getIVSize()

Get the required size of the IV (in bytes). If a cipher supports multiple sizes, this is the optimal (most secure) IV size. If the cipher supports no IV, this is 0.

Returns:

the required size of the IV.