iaik.security.cipher

Class PbeWithSHAAnd3_KeyTripleDES_CBC

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.TripleDES

iaik.security.cipher.PbeWithSHAAnd3_KeyTripleDES_CBC

public class PbeWithSHAAnd3_KeyTripleDES_CBC
extends TripleDES

This class implements from the PKCS 12 v1.0: Personal Information Exchange Syntax the pbeWithSHAAnd3_KeyTripleDES_CBC algorithm (object identifier: 1.2.840.113549.1.12.1.3).

The pbeWithSHAAnd3_KeyTripleDES_CBC key-encryption algorithm is used to encrypt a given message with the TripleDES algorithm in CBC mode using a secret key which is derived from a password with the SHA hash algorithm.

PKCS#12 breaks with the PKCS#5 recommendation suggesting passwords to consist of printable ASCII characters. PKCS #12 creates passwords from BMPStrings with a NULL terminator by encoding every character of the original BMPString in 2 bytes in big-endian format (most-significant byte first).

As an alternative to the PKCS#5 pbeWithMD5AndDES-CBC and pbeWithMD2AndDES-CBC algorithms, the pbeWithSHAAnd3_KeyTripleDES_CBC algorithm may be used for encrypting private keys, as described in PKCS#8.

Suppose you have created a RSAPrivateKey rsa_priv_key and are going to protect it with a password according to PKCS#5, (PKCS#12) and PKCS#8. You therefore will encode a value of type PrivateKeyInfo according to PKCS#8 to represent the private key in an algorithm-independent manner, which subsequently will be encrypted using the PbeWithSHAAnd3_KeyTripleDES_CBC algorithm and encoded as PKCS#8 EncryptedPrivateKeyInfo (EncryptedPrivateKeyInfo):

 import iaik.pkcs.pkcs8.*;
     ...
 EncryptedPrivateKeyInfo epki = new EncryptedPrivateKeyInfo(rsa_priv_key);
 epki.encrypt("password", AlgorithmID.pbeWithSHAAnd3_KeyTripleDES_CBC, null);
 

Decrypting goes the reverse way obtaining a PrivateKeyInfo from the EncryptedPrivateKeyInfo and "extracting" the RSAPrivateKey:

 RSAPrivateKey rsa_priv_key = (RSAPrivateKey)epki.decrypt("password");
 

You also may use the PbeWithSHAAnd3_KeyTripleDES_CBC algorithm for password based encrypting some message in the common way by directly using the Cipher.getInstance method when not intending to deal with PKCS#8 EncryptedPrivateKeyInfo. When doing so, you will have to use PBEKeyBMP (created from a password, which is treated as a BMPString according to PKCS#12) and PBEParameterSpec (created from salt and iteration count) for properly initializing the cipher; for instance (do not forget to include exception handling!):

 Random random = new Random();
 // salt
 byte[] salt = new byte[16];
 random.nextBytes(salt);
 //iteration count
 int count = 1;
 // PBE paramters
 PBEParameterSpec pbeParamSpec = new PBEParameterSpec(salt, count);
 // PBEKeyBMP from password
 PBEKeyBMP pbeKey = new PBEKeyBMP("password");
 Cipher pbeCipher = Cipher.getInstance("PbeWithSHAAnd3_KeyTripleDES_CBC");
 // initialize for encryption
 pbeCipher.init(Cipher.ENCRYPT_MODE, pbeKey, pbeParamSpec);
 // encrypt data
 byte[] cipher_data = pbeCipher.doFinal(plain_data);
 // now decrypt
 pbeCipher = Cipher.getInstance("PbeWithSHAAnd3_KeyTripleDES_CBC");
 // initialize for decryption
 pbeCipher.init(Cipher.DECRYPT_MODE, pbeKey, pbeParamSpec);
 // decrypt cipher data
 byte[] decrypted_data = pbeCipher.doFinal(cipherdata);
 

This class SHOULD NOT be used directly; it should only be used through the JCA/JCE.

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

See Also:

PrivateKeyInfo, EncryptedPrivateKeyInfo, TripleDES, PBEKeyBMP, PBEParameterSpec, PBEGenParameterSpec, PBEParameterGenerator, PBEParameters, IaikPBEParameterSpec

Field Summary

Fields

Modifier and Type	Field and Description
protected java.security.AlgorithmParameters	params

Constructor Summary

Constructors

Constructor and Description
PbeWithSHAAnd3_KeyTripleDES_CBC() The constructor; creates a new instance of the PbeWithSHAAnd3_KeyTripleDES_CBC symmetric cipher algorithm.

Method Summary

Modifier and Type	Method and Description
byte[]	engineDoFinal(byte[] input, int inputOffset, int inputLen) Encrypts or decrypts data in a single-part operation, or finishes a multiple-part operation.
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.
int	engineGetBlockSize() Returns the block size (in bytes).
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.
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).
java.security.AlgorithmParameters	engineGetParameters() Returns the parameters used with this cipher.
void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec paramSpec, java.security.SecureRandom random) Initializes this cipher with a key, a set of algorithm parameters, and a source of randomness.
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.
void	engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) Initializes this cipher with a key and a source of randomness.
void	engineSetMode(java.lang.String mode) Sets the block mode of this cipher.
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.
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.
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 void	initCipher(int opmode, java.security.Key key, java.security.SecureRandom random) Is used by the engineInit methods and initializes the cipher.
java.lang.String	toString() Returns a string representation of this Cipher.

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, wait, wait, wait

Field Detail

params

protected java.security.AlgorithmParameters params

Constructor Detail

PbeWithSHAAnd3_KeyTripleDES_CBC

public PbeWithSHAAnd3_KeyTripleDES_CBC()

The constructor; creates a new instance of the PbeWithSHAAnd3_KeyTripleDES_CBC symmetric cipher algorithm.

Applications should never use this constructor, instead the symmetric cipher algorithm should be requested from the appropriate JCA/JCE cryptographic service provider as follows: Cipher.getInstance("PbeWithSHAAnd3_KeyTripleDES_CBC", "IAIK").

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

engineGetParameters

public 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)

Returns:

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

engineInit

public 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)

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

public 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)

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

public void engineInit(int opmode,
                       java.security.Key key,
                       java.security.spec.AlgorithmParameterSpec paramSpec,
                       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)

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

paramSpec - [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

engineGetKeySize

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

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

initCipher

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

Is used by the engineInit methods and initializes the cipher.

FIPS 140-2:

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.

Throws:

java.security.InvalidKeyException

java.security.InvalidAlgorithmParameterException

engineSetPadding

public 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)

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

engineSetMode

public 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)

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

engineUpdate

public 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

Throws:

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

engineUpdate

public 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

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

engineGetOutputSize

public 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)

Throws:

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

engineGetIV

public 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

Throws:

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

engineGetBlockSize

public 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

Throws:

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

engineDoFinal

public 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

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

engineDoFinal

public 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

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

toString

public java.lang.String toString()

Returns a string representation of this Cipher.

FIPS 140-2:

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, return value)

Overrides:

toString in class java.lang.Object

Returns:

[FIPS 140-2 status output] a string representation (algorithm name)

engineWrap

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

Wrap a key.

FIPS 140-2:

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)

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

engineUnwrap

protected 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