to top
Android APIs
public class

Cipher

extends Object
java.lang.Object
   ↳ javax.crypto.Cipher
Known Direct Subclasses

Class Overview

This class provides access to implementations of cryptographic ciphers for encryption and decryption. Cipher classes can not be instantiated directly, one has to call the Cipher's getInstance method with the name of a requested transformation, optionally with a provider. A transformation specifies an operation (or a set of operations) as a string in the form:

  • "algorithm/mode/padding"
    • or
  • "algorithm"
algorithm is the name of a cryptographic algorithm, mode is the name of a feedback mode and padding is the name of a padding scheme. If mode and/or padding values are omitted, provider specific default values will be used.

A valid transformation would be:

    Cipher c = Cipher.getInstance("AES/CBC/PKCS5Padding");
When a block cipher is requested in in stream cipher mode, the number of bits to be processed at a time can be optionally specified by appending it to the mode name. e.g. "AES/CFB8/NoPadding". If no number is specified, a provider specific default value is used.

Summary

Constants
int DECRYPT_MODE Constant for decryption operation mode.
int ENCRYPT_MODE Constant for encryption operation mode.
int PRIVATE_KEY Constant indicating that the key to be unwrapped is a private key.
int PUBLIC_KEY Constant indicating that the key to be unwrapped is a public key.
int SECRET_KEY Constant indicating that the key to be unwrapped is a secret key.
int UNWRAP_MODE Constant for key unwrapping operation mode.
int WRAP_MODE Constant for key wrapping operation mode.
Protected Constructors
Cipher(CipherSpi cipherSpi, Provider provider, String transformation)
Creates a new Cipher instance.
Public Methods
final int doFinal(byte[] output, int outputOffset)
Finishes a multi-part transformation (encryption or decryption).
final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
Finishes a multi-part transformation (encryption or decryption).
final int doFinal(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Finishes a multi-part transformation (encryption or decryption).
final int doFinal(byte[] input, int inputOffset, int inputLen, byte[] output)
Finishes a multi-part transformation (encryption or decryption).
final byte[] doFinal(byte[] input)
Finishes a multi-part transformation (encryption or decryption).
final int doFinal(ByteBuffer input, ByteBuffer output)
Finishes a multi-part transformation (encryption or decryption).
final byte[] doFinal()
Finishes a multi-part transformation (encryption or decryption).
final String getAlgorithm()
Returns the name of the algorithm of this cipher instance.
final int getBlockSize()
Returns this ciphers block size (in bytes).
final ExemptionMechanism getExemptionMechanism()
Returns the exemption mechanism associated with this cipher.
final byte[] getIV()
Returns the initialization vector for this cipher instance.
final static Cipher getInstance(String transformation, String provider)
Creates a new cipher for the specified transformation provided by the specified provider.
final static Cipher getInstance(String transformation, Provider provider)
Creates a new cipher for the specified transformation.
final static Cipher getInstance(String transformation)
Creates a new Cipher for the specified transformation.
final static int getMaxAllowedKeyLength(String transformation)
Returns the maximum key length for the specified transformation.
final static AlgorithmParameterSpec getMaxAllowedParameterSpec(String transformation)
Returns the maximum cipher parameter value for the specified transformation.
final int getOutputSize(int inputLen)
Returns the length in bytes an output buffer needs to be when this cipher is updated with inputLen bytes.
final AlgorithmParameters getParameters()
Returns the parameters that where used to create this cipher instance.
final Provider getProvider()
Returns the provider of this cipher instance.
final void init(int opmode, Key key)
Initializes this cipher instance with the specified key.
final void init(int opmode, Key key, SecureRandom random)
Initializes this cipher instance with the specified key and a source of randomness.
final void init(int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)
Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.
final void init(int opmode, Key key, AlgorithmParameters params, SecureRandom random)
Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.
final void init(int opmode, Key key, AlgorithmParameterSpec params)
Initializes this cipher instance with the specified key and algorithm parameters.
final void init(int opmode, Certificate certificate, SecureRandom random)
Initializes this cipher instance with the public key from the specified certificate and a source of randomness.
final void init(int opmode, Certificate certificate)
Initializes this cipher instance with the public key from the specified certificate.
final void init(int opmode, Key key, AlgorithmParameters params)
Initializes this cipher instance with the specified key and algorithm parameters.
final Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)
Unwraps a key using this cipher instance.
final int update(ByteBuffer input, ByteBuffer output)
Continues a multi-part transformation (encryption or decryption).
final byte[] update(byte[] input)
Continues a multi-part transformation (encryption or decryption).
final int update(byte[] input, int inputOffset, int inputLen, byte[] output)
Continues a multi-part transformation (encryption or decryption).
final byte[] update(byte[] input, int inputOffset, int inputLen)
Continues a multi-part transformation (encryption or decryption).
final int update(byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)
Continues a multi-part transformation (encryption or decryption).
final void updateAAD(ByteBuffer input)
Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD).
final void updateAAD(byte[] input, int inputOffset, int inputLen)
Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD).
final void updateAAD(byte[] input)
Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD).
final byte[] wrap(Key key)
Wraps a key using this cipher instance.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int DECRYPT_MODE

Added in API level 1

Constant for decryption operation mode.

Constant Value: 2 (0x00000002)

public static final int ENCRYPT_MODE

Added in API level 1

Constant for encryption operation mode.

Constant Value: 1 (0x00000001)

public static final int PRIVATE_KEY

Added in API level 1

Constant indicating that the key to be unwrapped is a private key.

Constant Value: 2 (0x00000002)

public static final int PUBLIC_KEY

Added in API level 1

Constant indicating that the key to be unwrapped is a public key.

Constant Value: 1 (0x00000001)

public static final int SECRET_KEY

Added in API level 1

Constant indicating that the key to be unwrapped is a secret key.

Constant Value: 3 (0x00000003)

public static final int UNWRAP_MODE

Added in API level 1

Constant for key unwrapping operation mode.

Constant Value: 4 (0x00000004)

public static final int WRAP_MODE

Added in API level 1

Constant for key wrapping operation mode.

Constant Value: 3 (0x00000003)

Protected Constructors

protected Cipher (CipherSpi cipherSpi, Provider provider, String transformation)

Added in API level 1

Creates a new Cipher instance.

Parameters
cipherSpi the implementation delegate of the cipher.
provider the provider of the implementation of this cipher.
transformation the name of the transformation that this cipher performs.
Throws
NullPointerException if either cipherSpi is null or provider is null and cipherSpi is a NullCipherSpi.

Public Methods

public final int doFinal (byte[] output, int outputOffset)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes any bytes that may have been buffered in previous update calls.

The final transformed bytes are stored in the output buffer.

Parameters
output the output buffer.
outputOffset the offset in the output buffer.
Returns
  • the number of bytes placed in the output buffer.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
ShortBufferException if the size of the output buffer is too small.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.

public final byte[] doFinal (byte[] input, int inputOffset, int inputLen)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the inputLen bytes in input buffer at inputOffset, and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
inputOffset the offset in the input buffer.
inputLen the length of the input
Returns
  • the final bytes from the transformation.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if inputOffset and inputLen do not specify an valid chunk in the input buffer.

public final int doFinal (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the inputLen bytes in input buffer at inputOffset, and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
inputOffset the offset in the input buffer.
inputLen the length of the input.
output the output buffer for the transformed bytes.
outputOffset the offset in the output buffer.
Returns
  • the number of bytes placed in the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if inputOffset and inputLen do not specify an valid chunk in the input buffer.

public final int doFinal (byte[] input, int inputOffset, int inputLen, byte[] output)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the inputLen bytes in input buffer at inputOffset, and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
inputOffset the offset in the input buffer.
inputLen the length of the input.
output the output buffer for the transformed bytes.
Returns
  • the number of bytes placed in the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if inputOffset and inputLen do not specify an valid chunk in the input buffer.

public final byte[] doFinal (byte[] input)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the bytes in input buffer, and any bytes that have been buffered in previous update calls.

Parameters
input the input buffer.
Returns
  • the final bytes from the transformation.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.

public final int doFinal (ByteBuffer input, ByteBuffer output)

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes the input.remaining() bytes in input buffer at input.position(), and any bytes that have been buffered in previous update calls. The transformed bytes are placed into output buffer.

Parameters
input the input buffer.
output the output buffer.
Returns
  • the number of bytes placed into the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalArgumentException if the input buffer and the output buffer are the same object.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.

public final byte[] doFinal ()

Added in API level 1

Finishes a multi-part transformation (encryption or decryption).

Processes any bytes that may have been buffered in previous update calls.

Returns
  • the final bytes from the transformation.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
BadPaddingException if the padding of the data does not match the padding scheme.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.

public final String getAlgorithm ()

Added in API level 1

Returns the name of the algorithm of this cipher instance.

This is the name of the transformation argument used in the getInstance call creating this object.

Returns
  • the name of the algorithm of this cipher instance.

public final int getBlockSize ()

Added in API level 1

Returns this ciphers block size (in bytes).

Returns
  • this ciphers block size.

public final ExemptionMechanism getExemptionMechanism ()

Added in API level 1

Returns the exemption mechanism associated with this cipher.

Returns
  • currently null

public final byte[] getIV ()

Added in API level 1

Returns the initialization vector for this cipher instance.

Returns
  • the initialization vector for this cipher instance.

public static final Cipher getInstance (String transformation, String provider)

Added in API level 1

Creates a new cipher for the specified transformation provided by the specified provider.

Parameters
transformation the name of the transformation to create a cipher for.
provider the name of the provider to ask for the transformation.
Returns
  • a cipher for the requested transformation.
Throws
NoSuchAlgorithmException if the specified provider can not provide the transformation, or it is null, empty or in an invalid format.
NoSuchProviderException if no provider with the specified name can be found.
NoSuchPaddingException if the requested padding scheme in the transformation is not available.
IllegalArgumentException if the specified provider is null.

public static final Cipher getInstance (String transformation, Provider provider)

Added in API level 1

Creates a new cipher for the specified transformation.

Parameters
transformation the name of the transformation to create a cipher for.
provider the provider to ask for the transformation.
Returns
  • a cipher for the requested transformation.
Throws
NoSuchAlgorithmException if the specified provider can not provide the transformation, or it is null, empty or in an invalid format.
NoSuchPaddingException if the requested padding scheme in the transformation is not available.
IllegalArgumentException if the provider is null.

public static final Cipher getInstance (String transformation)

Added in API level 1

Creates a new Cipher for the specified transformation. The installed providers are searched in order for an implementation of the specified transformation. The first found provider providing the transformation is used to create the cipher. If no provider is found an exception is thrown.

Parameters
transformation the name of the transformation to create a cipher for.
Returns
  • a cipher for the requested transformation.
Throws
NoSuchAlgorithmException if no installed provider can provide the transformation, or it is null, empty or in an invalid format.
NoSuchPaddingException if no installed provider can provide the padding scheme in the transformation.

public static final int getMaxAllowedKeyLength (String transformation)

Added in API level 1

Returns the maximum key length for the specified transformation.

Parameters
transformation the transformation name.
Returns
  • the maximum key length, currently Integer.MAX_VALUE.
Throws
NoSuchAlgorithmException if no provider for the specified transformation can be found.
NullPointerException if transformation is null.

public static final AlgorithmParameterSpec getMaxAllowedParameterSpec (String transformation)

Added in API level 1

Returns the maximum cipher parameter value for the specified transformation. If there is no maximum limit, null is returned.

Parameters
transformation the transformation name.
Returns
  • a parameter spec holding the maximum value or null. Currently null.
Throws
NoSuchAlgorithmException if no provider for the specified transformation can be found.
NullPointerException if transformation is null.

public final int getOutputSize (int inputLen)

Added in API level 1

Returns the length in bytes an output buffer needs to be when this cipher is updated with inputLen bytes.

Parameters
inputLen the number of bytes of the input.
Returns
  • the output buffer length for the input length.
Throws
IllegalStateException if this cipher instance is in an invalid state.

public final AlgorithmParameters getParameters ()

Added in API level 1

Returns the parameters that where used to create this cipher instance.

These may be a the same parameters that were used to create this cipher instance, or may be a combination of default and random parameters, depending on the underlying cipher implementation.

Returns
  • the parameters that where used to create this cipher instance, or null if this cipher instance does not have any parameters.

public final Provider getProvider ()

Added in API level 1

Returns the provider of this cipher instance.

Returns
  • the provider of this cipher instance.

public final void init (int opmode, Key key)

Added in API level 1

Initializes this cipher instance with the specified key.

The cipher is initialized for the specified operational mode (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

If this cipher instance needs any algorithm parameters or random values that the specified key can not provide, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values).

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, meaning that it is equivalent to creating a new instance and calling its init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.

public final void init (int opmode, Key key, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key and a source of randomness.

The cipher is initialized for the specified operational mode (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

If this cipher instance needs any algorithm parameters or random values that the specified key can not provide, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random;

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.
InvalidParameterException if the specified opmode is invalid.

public final void init (int opmode, Key key, AlgorithmParameterSpec params, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.

The cipher is initialized for the specified operational mode (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

If this cipher instance needs any algorithm parameters and params is null, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random;

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, meaning that it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
params the algorithm parameters.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.
InvalidAlgorithmParameterException it the specified parameters are inappropriate for this cipher.
InvalidParameterException if the specified opmode is invalid.

public final void init (int opmode, Key key, AlgorithmParameters params, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the specified key, algorithm parameters and a source of randomness.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

If this cipher instance needs any algorithm parameters and params is null, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random.

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
params the algorithm parameters.
random the source of randomness to use.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.
InvalidAlgorithmParameterException if the specified parameters are inappropriate for this cipher.
InvalidParameterException if the specified opmode is invalid.

public final void init (int opmode, Key key, AlgorithmParameterSpec params)

Added in API level 1

Initializes this cipher instance with the specified key and algorithm parameters.

The cipher is initialized for the specified operational mode (one of: encryption, decryption, key wrapping or key unwrapping).

If this cipher instance needs any algorithm parameters and params is null, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values).

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
params the algorithm parameters.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.
InvalidAlgorithmParameterException it the specified parameters are inappropriate for this cipher.

public final void init (int opmode, Certificate certificate, SecureRandom random)

Added in API level 1

Initializes this cipher instance with the public key from the specified certificate and a source of randomness.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

It the type of the certificate is X.509 and the certificate has a key usage extension field marked as critical, the specified opmode has the be enabled for this key, otherwise an InvalidKeyException is thrown.

If this cipher instance needs any algorithm parameters that the key in the certificate can not provide, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values). Random values are generated using random.

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
certificate the certificate.
random the source of randomness to be used.
Throws
InvalidKeyException if the public key in the certificate can not be used to initialize this cipher instance.

public final void init (int opmode, Certificate certificate)

Added in API level 1

Initializes this cipher instance with the public key from the specified certificate.

The cipher will be initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

It the type of the certificate is X.509 and the certificate has a key usage extension field marked as critical, the specified opmode has the be enabled for this key, otherwise an InvalidKeyException is thrown.

If this cipher instance needs any algorithm parameters that the key in the certificate can not provide, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values).

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, means it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
certificate the certificate.
Throws
InvalidKeyException if the public key in the certificate can not be used to initialize this cipher instance.

public final void init (int opmode, Key key, AlgorithmParameters params)

Added in API level 1

Initializes this cipher instance with the specified key and algorithm parameters.

The cipher is initialized for the specified operation (one of: encryption, decryption, key wrapping or key unwrapping) depending on opmode.

If this cipher instance needs any algorithm parameters and params is null, the underlying implementation of this cipher is supposed to generate the required parameters (using its provider or random values).

When a cipher instance is initialized by a call to any of the init methods, the state of the instance is overridden, meaning that it is equivalent to creating a new instance and calling it init method.

Parameters
opmode the operation this cipher instance should be initialized for (one of: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE).
key the input key for the operation.
params the algorithm parameters.
Throws
InvalidKeyException if the specified key can not be used to initialize this cipher instance.
InvalidAlgorithmParameterException it the specified parameters are inappropriate for this cipher.

public final Key unwrap (byte[] wrappedKey, String wrappedKeyAlgorithm, int wrappedKeyType)

Added in API level 1

Unwraps a key using this cipher instance.

Parameters
wrappedKey the wrapped key to unwrap.
wrappedKeyAlgorithm the algorithm for the wrapped key.
wrappedKeyType the type of the wrapped key (one of: SECRET_KEY , PRIVATE_KEY or PUBLIC_KEY)
Returns
  • the unwrapped key
Throws
InvalidKeyException if the wrappedKey can not be unwrapped to a key of type wrappedKeyType for the wrappedKeyAlgorithm.
NoSuchAlgorithmException if no provider can be found that can create a key of type wrappedKeyType for the wrappedKeyAlgorithm.
IllegalStateException if this cipher instance is not initialized for unwrapping.

public final int update (ByteBuffer input, ByteBuffer output)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The input.remaining() bytes starting at input.position() are transformed and stored in the output buffer.

If the output.remaining() is too small to hold the transformed bytes a ShortBufferException is thrown. Use getOutputSize to check for the size of the output buffer.

Parameters
input the input buffer to transform.
output the output buffer to store the result within.
Returns
  • the number of bytes stored in the output buffer.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if the input buffer and the output buffer are the identical object.

public final byte[] update (byte[] input)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are returned.

Parameters
input the input bytes to transform.
Returns
  • the transformed bytes in a new buffer, or null if the input has zero length.
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if the input is null.

public final int update (byte[] input, int inputOffset, int inputLen, byte[] output)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are stored in the output buffer.

If the size of the output buffer is too small to hold the result, a ShortBufferException is thrown. Use getOutputSize to check for the size of the output buffer.

Parameters
input the input bytes to transform.
inputOffset the offset in the input to start.
inputLen the length of the input to transform.
output the output buffer.
Returns
  • the number of bytes placed in output.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if the input is null, the output is null, or if inputOffset and inputLen do not specify a valid chunk in the input buffer.

public final byte[] update (byte[] input, int inputOffset, int inputLen)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are returned.

Parameters
input the input bytes to transform.
inputOffset the offset in the input to start.
inputLen the length of the input to transform.
Returns
  • the transformed bytes in a new buffer, or null if the input has zero length.
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if input is null, or if inputOffset and inputLen do not specify a valid chunk in the input buffer.

public final int update (byte[] input, int inputOffset, int inputLen, byte[] output, int outputOffset)

Added in API level 1

Continues a multi-part transformation (encryption or decryption). The transformed bytes are stored in the output buffer.

If the size of the output buffer is too small to hold the result, a ShortBufferException is thrown. Use getOutputSize to check for the size of the output buffer.

Parameters
input the input bytes to transform.
inputOffset the offset in the input to start.
inputLen the length of the input to transform.
output the output buffer.
outputOffset the offset in the output buffer.
Returns
  • the number of bytes placed in output.
Throws
ShortBufferException if the size of the output buffer is too small.
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if the input is null, the output is null, or if inputOffset and inputLen do not specify a valid chunk in the input buffer.

public final void updateAAD (ByteBuffer input)

Added in API level 19

Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD). AAD may only be added after the Cipher is initialized and before any data is passed to the instance.

This is only usable with cipher modes that support Authenticated Encryption with Additional Data (AEAD) such as Galois/Counter Mode (GCM).

Parameters
input buffer of AAD to be used
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
UnsupportedOperationException if the cipher does not support AEAD

public final void updateAAD (byte[] input, int inputOffset, int inputLen)

Added in API level 19

Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD). AAD may only be added after the Cipher is initialized and before any data is passed to the instance.

This is only usable with cipher modes that support Authenticated Encryption with Additional Data (AEAD) such as Galois/Counter Mode (GCM).

Parameters
input bytes of AAD to use with the cipher
inputOffset offset within bytes of additional data to add to cipher
inputLen length of bytes of additional data to add to cipher
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if input is null, or if inputOffset and inputLen do not specify a valid chunk in the input buffer.
UnsupportedOperationException if the cipher does not support AEAD

public final void updateAAD (byte[] input)

Added in API level 19

Continues a multi-part transformation (encryption or decryption) with Authenticated Additional Data (AAD). AAD may only be added after the Cipher is initialized and before any data is passed to the instance.

This is only usable with cipher modes that support Authenticated Encryption with Additional Data (AEAD) such as Galois/Counter Mode (GCM).

Parameters
input bytes of AAD to use with the cipher
Throws
IllegalStateException if this cipher instance is not initialized for encryption or decryption.
IllegalArgumentException if input is null
UnsupportedOperationException if the cipher does not support AEAD

public final byte[] wrap (Key key)

Added in API level 1

Wraps a key using this cipher instance.

Parameters
key the key to wrap.
Returns
  • the wrapped key.
Throws
IllegalBlockSizeException if the size of the resulting bytes is not a multiple of the cipher block size.
InvalidKeyException if this cipher instance can not wrap this key.
IllegalStateException if this cipher instance is not initialized for wrapping.