iaik.security.cipher
Class PbeWithSHAAnd3_KeyTripleDES_CBC

java.lang.Object
  |
  +--javax.crypto.CipherSpi
        |
        +--iaik.security.cipher.BufferedCipher
              |
              +--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!):

 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);
 // initialize for decryption
 pbeCipher.init(Cipher.DECRYPT_MODE, pbeKey, pbeParamSpec);
 // decrypt cipher data
 byte[] decrypted_data = pbeCipher.doFinal(cipherdata);
 

See Also:

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

Field Summary

protected AlgorithmParameters

params

Constructor Summary

PbeWithSHAAnd3_KeyTripleDES_CBC()
Creates a new PbeWithSHAAnd3_KeyTripleDES_CBC Cipher object.

Method Summary

AlgorithmParameters	engineGetParameters() Returns the parameters of the algorithm.
void	engineInit(int opmode, Key key, AlgorithmParameterSpec paramSpec, SecureRandom random) Initializes this cipher for encryption or decryption.
void	engineInit(int opmode, Key key, AlgorithmParameters params, SecureRandom random) Initializes this cipher for encryption or decryption.
void	engineInit(int opmode, Key key, 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 void	initCipher(int opmode, Key key, SecureRandom random) Is used by the engineInit methods and initializes the cipher.

Methods inherited from class iaik.security.cipher.BufferedCipher

engineDoFinal, engineDoFinal, engineGetBlockSize, engineGetIV, engineGetOutputSize, engineUpdate, engineUpdate, toString

Methods inherited from class java.lang.Object

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

Field Detail

params

protected AlgorithmParameters params

Constructor Detail

PbeWithSHAAnd3_KeyTripleDES_CBC

public PbeWithSHAAnd3_KeyTripleDES_CBC()
                                throws NoSuchAlgorithmException,
                                       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:

NoSuchAlgorithmException - if there is no implementation for 3DES-CBC

NoSuchPaddingException - if there is no implementaion for PKCS5Padding

See Also:

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

Method Detail

engineGetParameters

public AlgorithmParameters engineGetParameters()

Returns the parameters of the algorithm.

Overrides:

engineGetParameters in class iaik.security.cipher.BufferedCipher

Returns:

the algorithm's parameters

engineInit

public void engineInit(int opmode,
                       Key key,
                       SecureRandom random)
                throws 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.

Overrides:

engineInit in class iaik.security.cipher.BufferedCipher

Parameters:

opmode - Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE

key - the password as PBEKeyBMP

random - not needed - shall be null

Throws:

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

engineInit

public void engineInit(int opmode,
                       Key key,
                       AlgorithmParameters params,
                       SecureRandom random)
                throws InvalidKeyException,
                       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.

Overrides:

engineInit in class iaik.security.cipher.BufferedCipher

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:

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

InvalidAlgorithmParameterException - if the parameter is no instance of PBEParameters

engineInit

public void engineInit(int opmode,
                       Key key,
                       AlgorithmParameterSpec paramSpec,
                       SecureRandom random)
                throws InvalidKeyException,
                       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.

Overrides:

engineInit in class iaik.security.cipher.BufferedCipher

Parameters:

opmode - Cipher.ENCRYPT_MODE or Cipher.DECRYPT_MODE

key - the password as PBEKeyBMP

params - the algorithm parameters of type PBEParameterSpec

random - not needed - shall be null

Throws:

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

InvalidAlgorithmParameterException - if the parameter is no instance of PBEParameterSpec

initCipher

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

Is used by the engineInit methods and initializes the cipher.

engineSetPadding

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

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

Overrides:

engineSetPadding in class iaik.security.cipher.BufferedCipher

Parameters:

padding - the name of the padding scheme

engineSetMode

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

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

Overrides:

engineSetMode in class iaik.security.cipher.BufferedCipher

Parameters:

mode - the cipher mode