com.entrust.toolkit.security.crypto.cipher

Class AsymmetricCipher

java.lang.Object

javax.crypto.CipherSpi

com.entrust.toolkit.security.crypto.cipher.AsymmetricCipher

Direct Known Subclasses:

RsaCipher

public abstract class AsymmetricCipher
extends javax.crypto.CipherSpi

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

An asymmetric cipher is a cryptographic algorithm that provides encryption and decryption using a key pair. The key pair consists of a public key that can be shared publicly (non-sensitive) and a private key that must never be shared publicly (sensitive). Using an asymmetric cipher with a public key, it is computationally 'easy' to calculate ciphertext from plaintext. Then, only with knowledge of the private key, is it computationally 'easy' to perform the reverse transformation and recover plaintext from ciphertext. The private key must be kept secret since it provides the security of the algorithm; the algorithm itself and the public key are usually public knowledge.

The advantage of an asymmetric cipher is that the public key can be distributed publicly; as opposed to a symmetric cipher where the secret key cannot. The disadvantages are that asymmetric ciphers are usually only able to encrypt data of up to a certain size (restricted by the key size) and are typically much, much, slower than symmetric ciphers. For these reasons, asymmetric ciphers are not suitable for protecting large amounts of data. In practice, asymmetric ciphers are used to encrypt secret keys which have been used to encrypt large amounts of data.

An asymmetric 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 the following call:

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

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

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AsymmetricCipher() The constructor; creates a new AsymmetricCipher instance.

Method Summary

Methods

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 abstract 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 abstract 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 abstract void	engineSetMode(java.lang.String mode) Sets the block mode of this cipher.
protected abstract 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 byte[]	engineWrap(java.security.Key key) Wrap a key.
protected java.security.SecureRandom	getPrng() Returns the pseudo-random number generator (PRNG) to be used for parameter generation and encryption/decryption (for algorithms that require it).
protected abstract int	implGetOutputSize(int inputLen) Determines the maximum amount of data in bytes that will be output by a 'process data' operation.
protected abstract int	implInit(int opmode, java.security.Key key, java.security.AlgorithmParameters opaqueParams, java.security.spec.AlgorithmParameterSpec transparentParams) Initializes the underlying asymmetric cipher implementation.
protected abstract byte[]	implProcessData(byte[] input, int inputOffset, int inputLen) Processes the data using the underlying asymmetric cipher implementation.

Methods inherited from class javax.crypto.CipherSpi

engineDoFinal, engineUpdate, engineUpdateAAD, engineUpdateAAD

Methods inherited from class java.lang.Object

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

Constructor Detail

AsymmetricCipher

protected AsymmetricCipher()

The constructor; creates a new AsymmetricCipher instance.

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)
• status output interface (exceptions)

Method Detail

engineGetIV

protected final byte[] engineGetIV()

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

An IV is a parameter typically used by symmetric block ciphers, not asymmetric ciphers. Since this cipher is an asymmetric cipher it does not use an IV, and null is always returned.

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] null since this cipher does not use an IV

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGetBlockSize

protected final int engineGetBlockSize()

Returns the block size (in bytes).

Block size only applies to symmetric block ciphers, not asymmetric ciphers. Since this cipher is an asymmetric cipher, 0 is always returned.

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)
• data output interface (return value)
• status output interface (exceptions)

Specified by:

engineGetBlockSize in class javax.crypto.CipherSpi

Returns:

[FIPS 140-2 data output] 0 since this cipher is not a symmetric block cipher

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

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.

For asymmetric cipher implementations the underlying cryptographic algorithm (public-key cryptosystem) requires all input data prior to processing (plaintext or ciphertext). Thus, an update call simply internally buffers the input provided; it does not process any data. The output of this call only applies to the next doFinal; the next (and subsequent) update calls will always produce 0 bytes of output.

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)

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGetParameters

protected abstract 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

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineGetKeySize

protected abstract 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

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineSetMode

protected abstract 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 abstract 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

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().

If this cipher (including its underlying 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: 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)
• 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 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.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

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 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().

If this cipher (including its underlying 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: 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)
• 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 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.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

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 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().

If this cipher (including its underlying 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: 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)
• 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 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.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

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.

Since asymmetric ciphers require all input data prior to processing (plaintext or ciphertext), this call simply internally buffers the input provided; it does not process any data. All buffered input is subsequently processed on the next doFinal call. Since no data is actually processed by this call, output is never produced and null is always returned.

FIPS 140-2:

FIPS Service: Cryptographic Operation

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] null (output is never produced)

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineUpdate

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

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.

Since asymmetric ciphers require all input data prior to processing (plaintext or ciphertext), this call simply internally buffers the input provided; it does not process any data. All buffered input is subsequently processed on the next doFinal call. Since no data is actually processed by this call, output is never produced and 0 is always returned.

FIPS 140-2:

FIPS Service: Cryptographic Operation

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 (ignored)

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

Returns:

[FIPS 140-2 data output] the number of bytes stored in output, which is always 0 (output is never produced)

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineDoFinal

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

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

Asymmetric ciphers are are only capable of processing data of a certain size based on the key being used. Attempting to process data of an invalid size will result in a IllegalBlockSizeException being raised.

FIPS 140-2:

FIPS Service: Cryptographic Operation

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 the amount of data (plaintext or ciphertext) provided to the underlying asymmetric cipher implementation is in appropriate for the key being used

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

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineDoFinal

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

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

Asymmetric ciphers are are only capable of processing data of a certain size based on the key being used. Attempting to process data of an invalid size will result in a IllegalBlockSizeException being raised.

FIPS 140-2:

FIPS Service: Cryptographic Operation

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 output] 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 the amount of data (plaintext or ciphertext) provided to the underlying asymmetric cipher implementation is in appropriate for the key being used

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, but the decrypted data is not bounded by the appropriate padding bytes

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

engineWrap

protected final byte[] engineWrap(java.security.Key key)
                           throws 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:

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)

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

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.

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations

implInit

protected abstract int implInit(int opmode,
           java.security.Key key,
           java.security.AlgorithmParameters opaqueParams,
           java.security.spec.AlgorithmParameterSpec transparentParams)
                         throws java.security.InvalidKeyException,
                                java.security.InvalidAlgorithmParameterException

Initializes the underlying asymmetric cipher implementation.

FIPS 140-2:

FIPS Service: Modify Object

Although this API is externally accessible (protected), it is intended for internal use only and MUST NOT be called externally by the operator when operating in FIPS mode. Since its use is prohibited, this API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module.

Parameters:

key - the key

opaqueParams - the algorithm parameters in opaque format

transparentParams - the algorithm parameters in transparent format

Returns:

the maximum amount of input that can be process (and thus may need to be buffered)

Throws:

java.security.InvalidKeyException - if the given key is inappropriate for initializing this cipher

java.security.InvalidAlgorithmParameterException - 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.

implProcessData

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

Processes the data using the underlying asymmetric cipher implementation.

FIPS 140-2:

FIPS Service: Cryptographic Operation

Although this API is externally accessible (protected), it is intended for internal use only and MUST NOT be called externally by the operator when operating in FIPS mode. Since its use is prohibited, this API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module.

Parameters:

input - the input buffer

inputOffset - the offset in input where the input starts

inputLen - the input length

Returns:

the new buffer with the result

Throws:

javax.crypto.IllegalBlockSizeException - if the amount of data (plaintext or ciphertext) provided to the underlying asymmetric cipher implementation is in appropriate for the key being used

javax.crypto.BadPaddingException - if this cipher is in decryption mode, but the decrypted data is not bounded by the appropriate padding bytes

implGetOutputSize

protected abstract int implGetOutputSize(int inputLen)

Determines the maximum amount of data in bytes that will be output by a 'process data' operation.

FIPS 140-2:

FIPS Service: Query Object

Although this API is externally accessible (protected), it is intended for internal use only and MUST NOT be called externally by the operator when operating in FIPS mode. Since its use is prohibited, this API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module.

Parameters:

inputLen - the input length (in bytes)

Returns:

the required output buffer size (in bytes)

getPrng

protected final java.security.SecureRandom getPrng()

Returns the pseudo-random number generator (PRNG) to be used for parameter generation and encryption/decryption (for algorithms that require it).

If a PRNG was manually specified during initialization, this PRNG is returned; otherwise an implementation of Entrust's default PRNG is returned.

FIPS 140-2:

FIPS Service: Query Object

Although this API is externally accessible (protected), it is intended for internal use only and MUST NOT be called externally by the operator when operating in FIPS mode. Since its use is prohibited, this API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module.

Returns:

the pseudo-random number generator