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 Personal Information Exchange Standard (PKCS#12) 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!):

 SecureRandom random = ...;
 // salt
 byte[] salt = new byte[16];
 random.nextBytes(salt);
 //iteration count
 int count = 1;
 // PBE parameters
 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);
 

Version:

File Revision 26

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() Creates a new PbeWithSHAAnd3_KeyTripleDES_CBC Cipher object.

Method Summary

Methods

Modifier and Type	Method and Description
byte[]	engineDoFinal(byte[] in, int inOff, int inLen) Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data.
int	engineDoFinal(byte[] in, int inOff, int inLen, byte[] out, int outOff) Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data.
int	engineGetBlockSize() Returns the block size corresponding to this cipher.
byte[]	engineGetIV() Returns a byte array containing the initialization vector (IV).
protected int	engineGetKeySize(java.security.Key key) Gets the key size.
int	engineGetOutputSize(int inLen) Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.
java.security.AlgorithmParameters	engineGetParameters() Returns the parameters of the algorithm.
void	engineInit(int opmode, java.security.Key key, java.security.spec.AlgorithmParameterSpec paramSpec, java.security.SecureRandom random) Initializes this cipher for encryption or decryption.
void	engineInit(int opmode, java.security.Key key, java.security.AlgorithmParameters params, java.security.SecureRandom random) Initializes this cipher for encryption or decryption.
void	engineInit(int opmode, java.security.Key key, java.security.SecureRandom random) Initializes this cipher for encryption or decryption.
void	engineSetMode(java.lang.String mode) This method only overwrites the corresponding method in its superclass and does nothing.
void	engineSetPadding(java.lang.String padding) This method only overwrites the corresponding method in its superclass and does nothing.
protected java.security.Key	engineUnwrap(byte[] wrappedKey, java.lang.String wrappedKeyAlgorithm, int wrappedKeyType)
byte[]	engineUpdate(byte[] in, int inOff, int inLen) This method is used to encrypt or decrypt chunks of data of any length.
int	engineUpdate(byte[] in, int inOff, int inLen, byte[] out, int outOff) This method is used to encrypt or decrypt chunks of data of any length.
protected byte[]	engineWrap(java.security.Key key)
int	getModeBlockSize() Returns the block size corresponding to the actual cipher mode.
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()
                                throws java.security.NoSuchAlgorithmException,
                                       javax.crypto.NoSuchPaddingException

Creates a new PbeWithSHAAnd3_KeyTripleDES_CBC Cipher object.

Usually this constructor is not directly called for using the PbeWithSHAAnd3_KeyTripleDES_CBC algorithm for password-based encrypting some message. Rather

 Cipher.getInstance("PbeWithSHAAnd3_KeyTripleDES_CBC")
 

is used to get a PbeWithSHAAnd3_KeyTripleDES_CBC Cipher object. When dealing with PKCS#8 EncryptedPrivateKeyInfo, this algorithm is specified by its appertaining AlgorithmID, e.g.

 epki.encrypt("password", AlgorithmID.pbeWithSHAAnd3_KeyTripleDES_CBC, null);
 

causing a call to the iaik.asn1.structures.AlgorithmID.getInstance() method which in its turn calls Cipher.getInstance(algorithmID.getName()) for actually getting an implementation of the the PbeWithSHAAnd3_KeyTripleDES_CBC algorithm, finally leading to this constructor.

Throws:

java.security.NoSuchAlgorithmException - if there is no implementation for 3DES-CBC

javax.crypto.NoSuchPaddingException - if there is no implementation for PKCS5Padding

See Also:

iaik.asn1.structures, Cipher.getInstance(java.lang.String)

Method Detail

engineGetParameters

public java.security.AlgorithmParameters engineGetParameters()

Returns the parameters of the algorithm.

Returns:

the algorithm's parameters

engineInit

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

Initializes this cipher for encryption or decryption. The key must be a PBEKeyBMP in "RAW" format. This method initializes salt (random value of 8 byte length) and iteration count with 1 as specified in PKCS#5.

Parameters:

opmode - Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE

key - the password as PBEKeyBMP

random - not needed - shall be null

Throws:

java.security.InvalidKeyException - if the key algorithm is not "PBE" or the format is not "RAW_BMP"

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

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 for encryption or decryption. The key must be a PBEKeyBMP in "RAW" format. params is of type PBEParameters, created from salt (of 8 byte length) and iteration count as specified in PKCS#12.

Parameters:

opmode - Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE

key - the password as PBEKeyBMP

params - the algorithm parameters of type PBEParameters

random - not needed - shall be null

Throws:

java.security.InvalidKeyException - if the key algorithm is not "PBE" or the format is not "RAW_BMP"

java.security.InvalidAlgorithmParameterException - if the parameter is no instance of PBEParameters

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

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 for encryption or decryption. The key must be a PBEKeyBMP in "RAW" format. params is of type PBEParameterSpec, created from salt (of 8 byte length) and iteration count as specified in PKCS#12.

Parameters:

opmode - Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE

key - the password as PBEKeyBMP

paramSpec - the algorithm parameters of type PBEParameterSpec

random - not needed - shall be null

Throws:

java.security.InvalidKeyException - if the key algorithm is not "PBE" or the format is not "RAW_BMP"

java.security.InvalidAlgorithmParameterException - if the parameter is no instance of PBEParameterSpec

See Also:

Cipher.init(int, java.security.Key), CipherSpi.engineInit(int, java.security.Key, java.security.SecureRandom)

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.

Throws:

java.security.InvalidKeyException

java.security.InvalidAlgorithmParameterException

engineSetPadding

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

This method only overwrites the corresponding method in its superclass and does nothing. PbeWithSHAAnd3_KeyTripleDES_CBC uses PKCS5Padding.

Parameters:

padding - the name of the padding scheme

Throws:

javax.crypto.NoSuchPaddingException - if this padding scheme is not supported

See Also:

CipherSpi.engineSetPadding(java.lang.String)

engineSetMode

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

This method only overwrites the corresponding method in its superclass and does nothing. PbeWithSHAAnd3_KeyTripleDES_CBC encrypts with TripleDES in CBC mode.

Parameters:

mode - the cipher mode

Throws:

java.security.NoSuchAlgorithmException - if this cipher mode is not supported

See Also:

CipherSpi.engineSetMode(java.lang.String)

engineGetKeySize

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

Gets the key size.

Parameters:

key - the key to be used

Returns:

the key size

Throws:

java.security.InvalidKeyException

engineUpdate

public byte[] engineUpdate(byte[] in,
                  int inOff,
                  int inLen)

This method is used to encrypt or decrypt chunks of data of any length. To get the last data in the buffer use a doFinal() method. This method will automatically allocate an output buffer of the right size.

Specified by:

engineUpdate in class javax.crypto.CipherSpi

Parameters:

in - the input data.

inOff - the offset indicating where the subarray starts in the in array.

inLen - the length of the subarray.

Returns:

array containing the en/decrypted data

See Also:

BufferedCipher.engineDoFinal(byte[], int, int, byte[], int), Cipher.doFinal(), Cipher.update(byte[]), CipherSpi.engineUpdate(byte[], int, int)

engineUpdate

public int engineUpdate(byte[] in,
               int inOff,
               int inLen,
               byte[] out,
               int outOff)
                 throws javax.crypto.ShortBufferException

This method is used to encrypt or decrypt chunks of data of any length. To get get the last data in the buffer use a doFinal() method.

Specified by:

engineUpdate in class javax.crypto.CipherSpi

Parameters:

in - the input data.

inOff - the offset indicating where the subarray starts in the in array.

inLen - the length of the subarray.

out - the output buffer.

outOff - the offset indicating where to start writing the result into the output buffer.

Returns:

number of bytes written to out array.

Throws:

ShoetBufferException - if the buffer size is to short

javax.crypto.ShortBufferException

See Also:

BufferedCipher.engineDoFinal(byte[], int, int, byte[], int), Cipher.doFinal(), Cipher.update(byte[]), CipherSpi.engineUpdate(byte[], int, int)

engineGetOutputSize

public int engineGetOutputSize(int inLen)

Returns the output buffer size necessary for capturing the data resulting from the next update or doFinal operation including any data currently being buffered.

Specified by:

engineGetOutputSize in class javax.crypto.CipherSpi

Parameters:

inLen - the number of bytes to process

Returns:

the size of the output buffer (in bytes)

See Also:

Cipher.getOutputSize(int), CipherSpi.engineGetOutputSize(int)

engineGetIV

public byte[] engineGetIV()

Returns a byte array containing the initialization vector (IV). If the algorithm corresponding to this cipher object does not use an initialization vector, null is returned.

Specified by:

engineGetIV in class javax.crypto.CipherSpi

Returns:

the initialization vector in a byte array if this cipher object operates with an IV and the IV already has been set, null otherwise.

See Also:

Cipher.getIV(), CipherSpi.engineGetIV()

getModeBlockSize

public int getModeBlockSize()

Returns the block size corresponding to the actual cipher mode. This may differ from the actual block size of the cipher in the OFB, CFB and CTR mode. This is the input size that an application must supply to an update call to get an output.

Returns:

The block size (in bytes) of the current mode. This is always at least one.

engineGetBlockSize

public int engineGetBlockSize()

Returns the block size corresponding to this cipher. The block size is returned in bytes. If the implemented algorithm is not a block cipher, 0 is returned.

Specified by:

engineGetBlockSize in class javax.crypto.CipherSpi

Returns:

the block size (in bytes) if this cipher is a block cipher, 0 otherwise.

See Also:

Cipher.getBlockSize(), CipherSpi.engineGetBlockSize()

engineDoFinal

public int engineDoFinal(byte[] in,
                int inOff,
                int inLen,
                byte[] out,
                int outOff)
                  throws javax.crypto.ShortBufferException,
                         javax.crypto.IllegalBlockSizeException,
                         javax.crypto.BadPaddingException

Performs the last step of a multi-step en/decryption operation or a single-step en/decryption operation by processing the given input data and any remaining buffered data.

The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is stored in the given output byte array, beginning at outputOffset. The number of bytes stored in this byte array are returned.

Specified by:

engineDoFinal in class javax.crypto.CipherSpi

Parameters:

in - the byte array holding the data to be processed

inOff - the offset indicating the start position within the input byte array

inLen - the number of bytes to be processed

out - the byte array for holding the result

outOff - the offset indicating the start position within the output byte array to which the en/decrypted data is written

Returns:

the number of bytes stored in the output byte array

Throws:

javax.crypto.ShortBufferException - if the given output buffer is too small for holding the result

javax.crypto.IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

javax.crypto.BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

See Also:

Cipher.doFinal(), CipherSpi.engineDoFinal(byte[], int, int)

engineDoFinal

public byte[] engineDoFinal(byte[] in,
                   int inOff,
                   int inLen)
                     throws javax.crypto.IllegalBlockSizeException,
                            javax.crypto.BadPaddingException

Returns the result of the last step of a multi-step en/decryption operation or the result of a single-step en/decryption operation by processing the given input data and any remaining buffered data.

The data to be processed is given in an input byte array. Beginning at inputOffset, only the first inputLen bytes are en/decrypted, including any buffered bytes of a previous update operation. If necessary, padding is performed. The result is returned as a output byte array.

Specified by:

engineDoFinal in class javax.crypto.CipherSpi

Parameters:

in - the byte array holding the data to be processed

inOff - the offset indicating the start position within the input byte array

inLen - the number of bytes to be processed

Returns:

the byte array containing the en/decrypted data

Throws:

javax.crypto.IllegalBlockSizeException - if the total length of the processed data is not a multiple of the block size for a (no padding performing) block cipher

javax.crypto.BadPaddingException - if the decrypted data is not bounded by the proper padding bytes after data decryption including (un)padding

See Also:

Cipher.doFinal(), CipherSpi.engineDoFinal(byte[], int, int)

toString

public java.lang.String toString()

Returns a string representation of this Cipher.

Overrides:

toString in class java.lang.Object

Returns:

a string representation

engineWrap

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

Overrides:

engineWrap in class javax.crypto.CipherSpi

Throws:

javax.crypto.IllegalBlockSizeException

java.security.InvalidKeyException

engineUnwrap

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

Overrides:

engineUnwrap in class javax.crypto.CipherSpi

Throws:

java.security.InvalidKeyException

java.security.NoSuchAlgorithmException