com.entrust.toolkit.security.crypto.cipher

Class SymmetricBlockCipher

java.lang.Object

javax.crypto.CipherSpi

com.entrust.toolkit.security.crypto.cipher.SymmetricBlockCipher

Direct Known Subclasses:

AesCipher, AesKeyWrap, AesKeyWrapPad, Cast128Cipher, Cast3Cipher, DesCipher, IdeaCipher, TripleDesCipher

public abstract class SymmetricBlockCipher
extends javax.crypto.CipherSpi

Defines Entrust's symmetric block cipher architecture; it contains all the common functionality used by Entrust's symmetric block cipher algorithms.

A symmetric cipher is a cryptographic algorithm that provides encryption and decryption using a single (symmetric) key. Using a symmetric cipher with a symmetric key, it is computationally 'easy' to calculate ciphertext from plaintext. Then, only with knowledge of the symmetric key, is it computationally 'easy' to perform the reverse transformation and recover plaintext from ciphertext. The key must be kept secret since it provides the security of the algorithm; the algorithm itself is usually public knowledge.

A symmetric block cipher is simply a symmetric cipher that breaks up input into blocks of fixed length, and operates on one block at a time. Symmetric block ciphers can be operated in different block modes using various padding schemes. A block mode, or block mechanism, is an additional algorithm that defines how each block will be calculated using the underlying symmetric cipher. For more information on block mechanisms, please refer to BlockMechanism. A padding scheme, or padding mechanism, defines how plaintext will be padded or unpadded (add or remove additional padding bytes) since plaintext may not necessarily consist of a set of complete blocks (final block may be an incomplete block).

Depending on the block mechanism employed, the symmetric block cipher may require an initialization vector (IV) in order to operate. Also, depending on the block mechanism employed, the symmetric block cipher may or may not be capable of processing data that contains an incomplete final block. A symmetric block cipher with this type of block mechanism must be used in conjunction with a padding mechanism in order for plaintext that has an incomplete final block to be encrypted. (Regardless of whether or not a padding mechanism is used, a symmetric cipher with this type of block mechanism is incapable of decrypting ciphertext that has an incomplete final block.)

A symmetric block cipher algorithm instance can be obtained using the Java Cryptography Architecture (JCA), by requesting the '<algorithm>' cipher from the Entrust cryptographic service provider. This can be done using either of the following calls:

Cipher.getInstance("<algorithm>", "Entrust");
Cipher.getInstance("<algorithm>/<mode>/<padding>", "Entrust");

The following key types are currently supported:

• Standard secret keys (software keys); keys with 'RAW' primary encoding format
• Secret keys that reside on a PKCS#11 device (PKCS#11 keys); instance of TokenSymmetricKey.

The tables below list the block mechanisms and padding mechanisms that are supported by all symmetric block cipher algorithms provided by Entrust (exceptions are noted). The default block mode and padding mechanism correspond to the first entry in each table; defaults are automatically used when either block mode or padding mechanism are not specified in a Cipher.getInstance() call.

Block Mechanisms
<mode>	Implementation	Requires IV	Requires Complete Final Block
ECB	EcbBlockMechanism	no	yes
CBC	CbcBlockMechanism	yes	yes
CFB	CfbBlockMechanism	yes	no
GCM	GcmBlockMechanism Note: only supported by 128-bit block ciphers (e.g. AES)	yes	no
OFB	OfbBlockMechanism	yes	no
OpenPGPCFB	OpenPgpCfbBlockMechanism	no	no

Padding Mechanisms
<padding>	Implementation
NoPadding	implicit
ISO10126Padding	Pkcs5PaddingMechanism
PKCS5Padding	Pkcs5PaddingMechanism
Sp80038aPadding	Sp80038aPaddingMechanism

The supported block mechanisms and padding mechanisms are limited when using the algorithm with a PKCS#11 key. The table below lists the combinations of block and padding mechanisms that are supported for by the PKCS#11 implementations:

Block and Padding Mechanisms Usable With PKCS#11
<mode>	<padding>	Requires IV	Requires Complete Final Block
ECB	NoPadding	no	yes
CBC	NoPadding	yes	yes
CBC	PKCS5Padding	yes	no

Note:

All Entrust symmetric block cipher algorithms support software keys, but only some support PKCS#11 keys; in such cases, the the class documentation of the algorithm which will make note the limitation.

Note:

This class SHOULD NOT be sub-classed outside of the Toolkit.

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Since:

7.1

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(java.security.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 java.security.AlgorithmParameters	engineGetParameters() Returns the parameters used with this cipher.
protected void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec params, java.security.SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
protected void	engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
protected void	engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) Initializes this cipher with a key and a source of randomness.
protected void	engineSetMode(java.lang.String mode) Sets the block mode of this cipher.
protected void	engineSetPadding(java.lang.String padding) Sets the padding type of this cipher.
protected java.security.Key	engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType) Unwrap 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 void	engineUpdateAAD(byte[] src, int offset, int len) Continues a multi-part update of the Additional Authentication Data (AAD), using a subset of the provided buffer.
protected byte[]	engineWrap(java.security.Key key) Wrap a key.

Methods inherited from class javax.crypto.CipherSpi

engineDoFinal, engineUpdate, engineUpdateAAD

Methods inherited from class java.lang.Object

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

Method Detail

engineSetMode

protected void engineSetMode(java.lang.String mode)
                      throws java.security.NoSuchAlgorithmException

Sets the block mode of this cipher.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Specified by:

engineSetMode in class javax.crypto.CipherSpi

Parameters:

mode - [FIPS 140-2 control input] the cipher block mode

Throws:

java.security.NoSuchAlgorithmException - [FIPS 140-2 status output] if the requested cipher block mode is not supported

engineSetPadding

protected void engineSetPadding(java.lang.String padding)
                         throws javax.crypto.NoSuchPaddingException

Sets the padding type of this cipher.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Specified by:

engineSetPadding in class javax.crypto.CipherSpi

Parameters:

padding - [FIPS 140-2 control input] the padding type

Throws:

javax.crypto.NoSuchPaddingException - [FIPS 140-2 status output] if the requested padding type does not exist

engineGetBlockSize

protected final int engineGetBlockSize()

Returns the block size (in bytes).

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGetBlockSize in class javax.crypto.CipherSpi

Returns:

[FIPS 140-2 data output] the block size (in bytes), or 0 if the underlying algorithm is not a block cipher

engineGetOutputSize

protected final 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).

This call takes into account any unprocessed (buffered) data from a previous update call, and padding.

The actual output length of the next update or doFinal call may be smaller than the length returned by this method.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGetOutputSize in class javax.crypto.CipherSpi

Parameters:

inputLen - [FIPS 140-2 data input] the input length (in bytes)

Returns:

[FIPS 140-2 data output] the required output buffer size (in bytes)

engineGetIV

protected final byte[] engineGetIV()

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

This is useful in the context of password-based encryption or decryption, where the IV is derived from a user-provided passphrase.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGetIV in class javax.crypto.CipherSpi

Returns:

[FIPS 140-2 data output] the initialization vector in a new buffer, or null if the underlying algorithm does not use an IV, or if the IV has not yet been set

engineGetKeySize

protected final int engineGetKeySize(java.security.Key key)
                              throws java.security.InvalidKeyException

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

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Overrides:

engineGetKeySize in class javax.crypto.CipherSpi

Parameters:

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key object

Returns:

[FIPS 140-2 data output] the key size of the given key object

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if key is invalid

engineGetParameters

protected final java.security.AlgorithmParameters engineGetParameters()

Returns the parameters used with this cipher.

The returned parameters may be the same that were used to initialize this cipher, or may contain a combination of default and random parameter values used by the underlying cipher implementation if this cipher requires algorithm parameters but was not initialized with any.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGetParameters in class javax.crypto.CipherSpi

Returns:

[FIPS 140-2 data output] the parameters used with this cipher, or null if this cipher does not use any parameters

engineInit

protected final void engineInit(int opmode,
                                java.security.Key key,
                                java.security.SecureRandom random)
                         throws java.security.InvalidKeyException

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

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

If this cipher requires any algorithm parameters that cannot be derived from the given key, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption or key wrapping, and raise an InvalidKeyException if it is being initialized for decryption or key unwrapping. The generated parameters can be retrieved using engineGetParameters() or engineGetIV() (if the parameter is an IV).

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - [FIPS 140-2 control input] the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE)

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the encryption key

random - [FIPS 140-2 control input] the source of randomness

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for initializing this cipher, or if this cipher is being initialized for decryption and requires algorithm parameters that cannot be determined from the given key

engineInit

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

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

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

If this cipher requires any algorithm parameters and params is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption or key wrapping, and raise an InvalidAlgorithmParameterException if it is being initialized for decryption or key unwrapping. The generated parameters can be retrieved using engineGetParameters() or engineGetIV() (if the parameter is an IV).

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - [FIPS 140-2 control input] the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE)

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the encryption key

params - [FIPS 140-2 data input] the algorithm parameters

random - [FIPS 140-2 control input] the source of randomness

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for initializing this cipher

java.security.InvalidAlgorithmParameterException - [FIPS 140-2 status output] if the given algorithm parameters are inappropriate for this cipher, or if this cipher is being initialized for decryption and requires algorithm parameters and params is null

engineInit

protected final void engineInit(int opmode,
                                java.security.Key key,
                                java.security.spec.AlgorithmParameterSpec params,
                                java.security.SecureRandom random)
                         throws java.security.InvalidKeyException,
                                java.security.InvalidAlgorithmParameterException

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

The cipher is initialized for one of the following four operations: encryption, decryption, key wrapping or key unwrapping, depending on the value of opmode.

If this cipher requires any algorithm parameters and params is null, the underlying cipher implementation is supposed to generate the required parameters itself (using provider-specific default or random values) if it is being initialized for encryption or key wrapping, and raise an InvalidAlgorithmParameterException if it is being initialized for decryption or key unwrapping. The generated parameters can be retrieved using engineGetParameters() or engineGetIV() (if the parameter is an IV).

If this cipher (including its underlying feedback or padding scheme) requires any random bytes (e.g., for parameter generation), it will get them from random.

Note that when a Cipher object is initialized, it loses all previously-acquired state. In other words, initializing a Cipher is equivalent to creating a new instance of that Cipher and initializing it.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Specified by:

engineInit in class javax.crypto.CipherSpi

Parameters:

opmode - [FIPS 140-2 control input] the operation mode of this cipher (this is one of the following: ENCRYPT_MODE, DECRYPT_MODE, WRAP_MODE or UNWRAP_MODE)

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the encryption key

params - [FIPS 140-2 data input] the algorithm parameters

random - [FIPS 140-2 control input] the source of randomness

Throws:

java.security.InvalidKeyException - [FIPS 140-2 status output] if the given key is inappropriate for initializing this cipher

java.security.InvalidAlgorithmParameterException - [FIPS 140-2 status output] if the given algorithm parameters are inappropriate for this cipher, or if this cipher is being initialized for decryption and requires algorithm parameters and params is null

engineUpdate

protected final 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.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, are processed, and the result is stored in a new buffer.

FIPS 140-2:

FIPS Service: Symmetric Cipher Encryption/Decryption

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineUpdate in class javax.crypto.CipherSpi

Parameters:

input - [FIPS 140-2 data input] the input buffer

inputOffset - [FIPS 140-2 data input] the offset in input where the input starts

inputLen - [FIPS 140-2 data input] the input length

Returns:

[FIPS 140-2 data output] the new buffer with the result, or null if the underlying cipher is a block cipher and the input data is too short to result in a new block

engineUpdate

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

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

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, are processed, and the result is stored in the output buffer, starting at outputOffset inclusive.

If the output buffer is too small to hold the result, a ShortBufferException is thrown.

FIPS 140-2:

FIPS Service: Symmetric Cipher Encryption/Decryption

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (parameters, return value)
• status output interface (exceptions)

Specified by:

engineUpdate in class javax.crypto.CipherSpi

Parameters:

input - [FIPS 140-2 data input] the input buffer

inputOffset - [FIPS 140-2 data input] the offset in input where the input starts

inputLen - [FIPS 140-2 data input] the input length

output - [FIPS 140-2 data output] the buffer for the result

outputOffset - [FIPS 140-2 data input] the offset in output where the result is stored

Returns:

[FIPS 140-2 data output] the number of bytes stored in output

Throws:

javax.crypto.ShortBufferException - [FIPS 140-2 status output] if the given output buffer is too small to hold the result

engineUpdateAAD

protected final void engineUpdateAAD(byte[] src,
                                     int offset,
                                     int len)

Continues a multi-part update of the Additional Authentication Data (AAD), using a subset of the provided buffer.

Calls to this method provide AAD to the cipher when operating in modes such as AEAD (GCM/CCM). If this cipher is operating in either GCM or CCM mode, all AAD must be supplied before beginning operations on the ciphertext (via the update and doFinal methods).

FIPS 140-2:

FIPS Service: Symmetric Cipher Encryption/Decryption

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• status output interface (exceptions)

Overrides:

engineUpdateAAD in class javax.crypto.CipherSpi

Parameters:

src - the buffer containing the AAD

offset - the offset in src where the AAD input starts

len - the number of AAD bytes

engineDoFinal

protected final byte[] engineDoFinal(byte[] input,
                                     int inputOffset,
                                     int inputLen)
                              throws javax.crypto.IllegalBlockSizeException,
                                     javax.crypto.BadPaddingException

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive and any input bytes that may have been buffered during a previous update operation, are processed, with padding (if requested) being applied. The result is stored in a new buffer.

Upon finishing, this method resets this cipher object to the state it was in when previously initialized via a call to engineInit. That is, the object is reset and available to encrypt or decrypt (depending on the operation mode that was specified in the call to engineInit) more data.

Note: if any exception is thrown, this cipher object may need to be reset before it can be used again.

FIPS 140-2:

FIPS Service: Symmetric Cipher Encryption/Decryption

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineDoFinal in class javax.crypto.CipherSpi

Parameters:

input - [FIPS 140-2 data input] the input buffer

inputOffset - [FIPS 140-2 data input] the offset in input where the input starts

inputLen - [FIPS 140-2 data input] the input length

Returns:

[FIPS 140-2 data output] the new buffer with the result

Throws:

javax.crypto.IllegalBlockSizeException - [FIPS 140-2 status output] if this cipher is a block cipher, no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size; or if this encryption algorithm is unable to process the input data provided

javax.crypto.BadPaddingException - [FIPS 140-2 status output] if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes

engineDoFinal

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

Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation. The data is encrypted or decrypted, depending on how this cipher was initialized.

The first inputLen bytes in the input buffer, starting at inputOffset inclusive, and any input bytes that may have been buffered during a previous update operation, are processed, with padding (if requested) being applied. The result is stored in the output buffer, starting at outputOffset inclusive.

If the output buffer is too small to hold the result, a ShortBufferException is thrown.

Upon finishing, this method resets this cipher object to the state it was in when previously initialized via a call to engineInit. That is, the object is reset and available to encrypt or decrypt (depending on the operation mode that was specified in the call to engineInit) more data.

Note: if any exception is thrown, this cipher object may need to be reset before it can be used again.

FIPS 140-2:

FIPS Service: Symmetric Cipher Encryption/Decryption

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (parameters, return value)
• status output interface (exceptions)

Specified by:

engineDoFinal in class javax.crypto.CipherSpi

Parameters:

input - [FIPS 140-2 data input] the input buffer

inputOffset - [FIPS 140-2 data input] the offset in input where the input starts

inputLen - [FIPS 140-2 data input] the input length

output - [FIPS 140-2 data output] the buffer for the result

outputOffset - [FIPS 140-2 data input] the offset in output where the result is stored

Returns:

[FIPS 140-2 data output] the number of bytes stored in output

Throws:

javax.crypto.IllegalBlockSizeException - [FIPS 140-2 status output] if this cipher is a block cipher, no padding has been requested (only in encryption mode), and the total input length of the data processed by this cipher is not a multiple of block size; or if this encryption algorithm is unable to process the input data provided

javax.crypto.ShortBufferException - [FIPS 140-2 status output] if the given output buffer is too small to hold the result

javax.crypto.BadPaddingException - [FIPS 140-2 status output] if this cipher is in decryption mode, and (un)padding has been requested, but the decrypted data is not bounded by the appropriate padding bytes

engineWrap

protected final byte[] engineWrap(java.security.Key key)
                           throws javax.crypto.IllegalBlockSizeException,
                                  java.security.InvalidKeyException

Wrap a key.

FIPS 140-2:

FIPS Service: Key Transport (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Overrides:

engineWrap in class javax.crypto.CipherSpi

Parameters:

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key to be wrapped

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the wrapped key

Throws:

javax.crypto.IllegalBlockSizeException - [FIPS 140-2 status output] if this cipher is a block cipher, no padding has been requested, and the length of the encoding of the key to be wrapped is not a multiple of the block size

java.security.InvalidKeyException - [FIPS 140-2 status output] if it is impossible or unsafe to wrap the key with this cipher (e.g., a hardware protected key is being passed to a software-only cipher)

engineUnwrap

protected final java.security.Key engineUnwrap(byte[] wrappedKey,
                                               java.lang.String wrappedKeyAlgorithm,
                                               int wrappedKeyType)
                                        throws java.security.InvalidKeyException,
                                               java.security.NoSuchAlgorithmException

Unwrap a previously wrapped key.

FIPS 140-2:

FIPS Service: Key Transport (primitive)

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• data output interface (return value)
• status output interface (exceptions)

Overrides:

engineUnwrap in class javax.crypto.CipherSpi

Parameters:

wrappedKey - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key to be unwrapped

wrappedKeyAlgorithm - [FIPS 140-2 control input] the algorithm associated with the wrapped key

wrappedKeyType - [FIPS 140-2 control input] the type of the wrapped key. This is one of SECRET_KEY, PRIVATE_KEY, or PUBLIC_KEY.

Returns:

[FIPS 140-2 data output] [FIPS 140-2 CSP] the unwrapped key

Throws:

java.security.NoSuchAlgorithmException - [FIPS 140-2 status output] if no installed providers can create keys of type wrappedKeyType for the wrappedKeyAlgorithm

java.security.InvalidKeyException - [FIPS 140-2 status output] if wrappedKey does not represent a wrapped key of type wrappedKeyType for the wrappedKeyAlgorithm