iaik.security.cipher

Class DES

java.lang.Object

javax.crypto.CipherSpi

iaik.security.cipher.DES

Direct Known Subclasses:

PbeWithMD5AndDES_CBC

public class DES
extends javax.crypto.CipherSpi

Extends the BufferedCipher class for adding a buffering mechanism to the underlying DES cipher.

This DES implementation can be used with custom S-Boxes and/or P-Boxes, see the DESParameterSpec class. From these boxes custom tables are automatically generated to allow for a fast DES ciphering. Memory usage is 3.5 kbyte per instance that does not use the standard tables. Calculating these tables also takes a bit of time (each time init() is called), but it is pretty fast and usually neglegible.

The Data Encryption Standard (DES) today is the most popular symmetric block algorithm for data encryption. It operates on data blocks of 64 bit size using a 64 (in fact 56) bit key. The DES algorithm performs 16 rounds permutating and combining data and key bits according to a given scheme.

Initially, the given 64 bit data block is devided into two 32-bit parts, called left and right half. 48 of the 56 key bits are XOR combined with the right data half, which previously is expanded to 48 bits. Each of the resulting 48 combined data-key bits specifies one of 48 address lines into 8 S-boxes (64x4 ROMs a 6 address lines and 4 data output lines). From every S-Box one 4-Bit word is read. The resulting eight 4-bit words are concatenated giving a 32-bit word, which - after a permutation - is combined with the old left data half to produce the new right data half for the next round. The old right data half is shifted to the left half, serving as new left half for the next round. After 16 rounds, left and right data half are combined and permutated to finally produce the encrypted 64 bit block.

Decryption uses the same proceeding, except for applying the keys in reverse order.

This class only creates a BufferedCipher object for the DES cipher.

Applications shall use

Cipher.getInstance("DES", "IAIK");
 

for creating a DES object. They may optionally specifiy operation mode (ECB (default), CBC, PCBC, OFB, CFB) and padding scheme (NoPadding (default), or PKCS5Padding as described in the PKCS #5: Password-Based Cryptography Specification Version 2.0 (RFC 2898)).

When requesting this DES implementation without any mode specification (Cipher.getInstance("DES")), the DES algorithm is used in pure ECB (Electronic Code Book) mode encrypting plaintext blocks into ciphertext blocks independently from each other. The ECB mode is prone to codebook attacks and block replay. A codebook attack may be successfully when being able to read plain- and corresponding ciphertext blocks for a certain quantity of messages making it possible to generate a codebook for decrypting blocks of further messages without knowing the key. For being effective against codebook analyses and block replay (often messages contain common sub-parts making it possible to unnoticed replace these blocks) one can use the CBC mode makes the encryption of one block of plain data conditional on all previously encrypted data blocks.

Since ECB encrypts each single block independently, it enables random access to encrypted data blocks which may be preferable for database encrypting. Often ECB is used for key-encrypting.

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

Warning:

On July 27 2004, NIST announced that the strength of the DES algorithm is no longer sufficient to adequately protect Federal government information. As a result, NIST has proposed withdrawing FIPS 46-3, which specifies DES, and two related standards. Please refer to the excerpt from the Federal Register / Vol. 69, No. 142 / Monday, July 26, 2004 / Notice: Announcing Proposed Withdrawal of Federal Information Processing Standard (FIPS) for the Data Encryption Standard (DES) and Request for Comments.

Future use of DES by Federal agencies is to be permitted only as a component function of the Triple Data Encryption Algorithm ( TDEA)(NIST Special Publication 800-67). TDEA may be used for the protection of Federal information (except keying option 3 (1-key Triple-DES)); however, NIST encourages agencies to implement the faster and stronger algorithm specified by FIPS 197, Advanced Encryption Standard ( AES) instead.

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:

DESParameterSpec, Cipher

Constructor Summary

Constructors

Constructor and Description
DES() The constructor; creates a new instance of the AES 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 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.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.
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

Constructor Detail

DES

public DES()

The constructor; creates a new instance of the AES 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("DES", "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

engineInit

public 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

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

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)

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

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

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)

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

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

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)

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

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)

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

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)

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

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)

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)

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

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