com.ibm.security.pkcs5
Class PKCS5

java.lang.Object
  |
  +--com.ibm.security.pkcs5.PKCS5

public final class PKCS5
extends Object

PKCS #5 object. This interface was derived from the RSA specifications at http://www.rsa.com/rsalabs/pubs/PKCS/. This class implements version 1.5 of the PKCS #5 specifications.

PKCS5 objects are immutable; they cannot be changed once created.


Field Summary
static String CIPHER_ALGORITHM_3DES
           
static String CIPHER_ALGORITHM_DES
          Cipher Algorithm DES.
static String CIPHER_ALGORITHM_DESEDE
           
static String CIPHER_ALGORITHM_RC2
          Cipher Algorithm RC2.
static String CIPHER_ALGORITHM_TRIPLE_DES
          Cipher Algorithm TripleDES.
static String CIPHER_MODE_CBC
          Cipher Mode CBC.
static String ENCRYPTION_ALGORITHM_PBES1
          PKCS5 Encryption Algorithm PBES1.
static String ENCRYPTION_ALGORITHM_PBES2
          PKCS5 Encryption Algorithm PBES2.
static String KEY_ALGORITHM_PBKDF1
          PKCS5 Key Algorithm PBKDF1.
static String KEY_ALGORITHM_PBKDF2
          PKCS5 Key Algorithm PBKDF2.
static String MESSAGE_DIGEST_MD2
          Message Digest MD2.
static String MESSAGE_DIGEST_MD5
          Message Digest MD5.
static String MESSAGE_DIGEST_SHA
          Message Digest SHA.
static String MESSAGE_DIGEST_SHA1
          Message Digest SHA1.
static String PADDING_ALGORITHM_PKCS5
          Padding Algorithm PKCS5Padding.
static int PKCS5_VERSION1
          PKCS5 Supported Version 1.
static int PKCS5_VERSION2
          PKCS5 Supported Version 2.
 
Constructor Summary
PKCS5(byte[] password, byte[] salt, int iterationCount)
          Create a PKCS5 object with the password, salt, and iteration values.
PKCS5(byte[] password, byte[] salt, int iterationCount, String provname)
          Create a PKCS5 object with the password, salt, and iteration values.
PKCS5(byte[] password, byte[] salt, int iterations, String digest, String cipher, String keyFunc, int version)
          Create a PKCS5 object with the input values.
PKCS5(byte[] password, byte[] salt, int iterations, String digest, String cipher, String keyFunc, int version, String provname)
          Create a PKCS5 object with the input values.
 
Method Summary
 byte[] decrypt(byte[] data)
          Decrypts an encrypted byte array with the encryption algorithm and values within the PKCS5 object.
 byte[] encodePBEParameters()
          Returns a DER encoded byte stream representing the PBE parameters stored in the PKCS5 object.
 byte[] encrypt(byte[] data)
          Encrypts a byte array with the encryption algorithm and values within the PKCS5 object.
protected  void finalize()
          Ensures that the password bytes are nulled out when there are no more references to this object.
 byte[] generateMAC(byte[] data)
          Generates a MAC for the specified byte array with the MAC algorithm and values within the PKCS5 object.
 String getCipherAlgorithm()
          Returns the cipher algorithm value used in the PKCS5 methods.
 String getCipherMode()
          Returns the cipher mode value used in the PKCS5 methods.
 String getCipherString()
          Returns a cipher string constructed with "PBEWith" + key encryption function + "And" + cipher algorithm.
 String getDigestAlgorithm()
          Returns the message digest value used in the PKCS5 methods.
 String getEncryptionAlgorithm()
          Returns the encryption algorithm value used in the PKCS5 methods.
 String getHMACString()
          Returns a Hmac string constructed with "Hmac" + message digest algorithm + "And" + cipher algorithm.
 int getIterationCount()
          Returns the iteration count value used in the PKCS5 methods.
 String getKeyAlgorithm()
          Returns the key algorithm value used in the PKCS5 methods.
 String getKeyEncryptionFunction()
          Returns the key encryption function value used in the PKCS5 methods.
 int getKeyLength()
          Returns the key length value used in the PKCS5 methods.
 String getPaddingAlgorithm()
          Returns the padding algorithm value used in the PKCS5 methods.
 byte[] getSalt()
          Returns a copy of the salt value used in the PKCS5 methods.
 int getVersion()
          Returns the version value used in the PKCS5 methods.
static boolean isSupportedMessageDigest(String digestAlgorithm)
          Checks if the specified Message Digest is supported by PKCS5.
 String toDetailedString()
          Returns a string representation of the PKCS5 object.
 String toString()
          Returns a string representation of the PKCS5 object.
 void verifyMAC(byte[] mac, byte[] data)
          Verifies a MAC for the specified byte array with the MAC algorithm and values within the PKCS5 object.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MESSAGE_DIGEST_MD2

public static final String MESSAGE_DIGEST_MD2
Message Digest MD2.

MESSAGE_DIGEST_MD5

public static final String MESSAGE_DIGEST_MD5
Message Digest MD5.

MESSAGE_DIGEST_SHA

public static final String MESSAGE_DIGEST_SHA
Message Digest SHA. Same as SHA1.

MESSAGE_DIGEST_SHA1

public static final String MESSAGE_DIGEST_SHA1
Message Digest SHA1.

CIPHER_MODE_CBC

public static final String CIPHER_MODE_CBC
Cipher Mode CBC.

PADDING_ALGORITHM_PKCS5

public static final String PADDING_ALGORITHM_PKCS5
Padding Algorithm PKCS5Padding.

CIPHER_ALGORITHM_DES

public static final String CIPHER_ALGORITHM_DES
Cipher Algorithm DES.

CIPHER_ALGORITHM_TRIPLE_DES

public static final String CIPHER_ALGORITHM_TRIPLE_DES
Cipher Algorithm TripleDES.

CIPHER_ALGORITHM_DESEDE

public static final String CIPHER_ALGORITHM_DESEDE

CIPHER_ALGORITHM_3DES

public static final String CIPHER_ALGORITHM_3DES

CIPHER_ALGORITHM_RC2

public static final String CIPHER_ALGORITHM_RC2
Cipher Algorithm RC2.

PKCS5_VERSION1

public static final int PKCS5_VERSION1
PKCS5 Supported Version 1. When PKCS5 is set to this version, it supports Key Algorithm PBKDF1 and Encryption Algorithm PBES1.

PKCS5_VERSION2

public static final int PKCS5_VERSION2
PKCS5 Supported Version 2. When PKCS5 is set to this version, it supports Key Algorithm PBKDF2 and Encryption Algorithm PBES2.

KEY_ALGORITHM_PBKDF1

public static final String KEY_ALGORITHM_PBKDF1
PKCS5 Key Algorithm PBKDF1. Supported by PKCS5 Version 1.

KEY_ALGORITHM_PBKDF2

public static final String KEY_ALGORITHM_PBKDF2
PKCS5 Key Algorithm PBKDF2. Supported by PKCS5 Version 2.

ENCRYPTION_ALGORITHM_PBES1

public static final String ENCRYPTION_ALGORITHM_PBES1
PKCS5 Encryption Algorithm PBES1. Supported by PKCS5 Version 1.

ENCRYPTION_ALGORITHM_PBES2

public static final String ENCRYPTION_ALGORITHM_PBES2
PKCS5 Encryption Algorithm PBES2. Supported by PKCS5 Version 2.
Constructor Detail

PKCS5

public PKCS5(byte[] password,
             byte[] salt,
             int iterationCount)
Create a PKCS5 object with the password, salt, and iteration values. With this constructor, the default digest algorithm is MD5, the default key encryption function is MD5, the default cipher is DES and the default version is PKCS5_VERSION1.
Parameters:
password - the password.
salt - 8 byte salt value.
iterations - the number of iterations used in the PKCS5 methods. The value must be greater than zero, and it is suggested that it be at least 1000.

PKCS5

public PKCS5(byte[] password,
             byte[] salt,
             int iterationCount,
             String provname)
Create a PKCS5 object with the password, salt, and iteration values. With this constructor, the default digest algorithm is MD5, the default key encryption function is MD5, the default cipher is DES and the default version is PKCS5_VERSION1.
Parameters:
password - the password.
salt - 8 byte salt value.
iterations - the number of iterations used in the PKCS5 methods. The value must be greater than zero, and it is suggested that it be at least 1000.
provname - the name of the java security provider the caller wants to use

PKCS5

public PKCS5(byte[] password,
             byte[] salt,
             int iterations,
             String digest,
             String cipher,
             String keyFunc,
             int version)
Create a PKCS5 object with the input values.
Parameters:
password - the password.
salt - 8 byte salt value.
iterations - the number of iterations used in the PKCS5 methods. The value must be greater than zero, and it is suggested that it be at least 1000.
digest - the digest algorithm used in MAC operations. Valid values are MD2, MD5 or SHA1 (SHA).
cipher - the cipher algorithm used in encryption and decryption operations. Valid values are DES, TripleDES or RC2.
keyFunc - the algorithm used in deriving keys. Currently, only PBKDF1-derived keys are supported and require a key encryption function of MD2, MD5 or SHA1 (SHA).
version - the version. Valid values are PKCS5.PKCS5_VERSION1 and PKCS5.PKCS5_VERSION2.
Throws:
IllegalArgumentException - if any of the input arguments are invalid.

PKCS5

public PKCS5(byte[] password,
             byte[] salt,
             int iterations,
             String digest,
             String cipher,
             String keyFunc,
             int version,
             String provname)
Create a PKCS5 object with the input values.
Parameters:
password - the password.
salt - 8 byte salt value.
iterations - the number of iterations used in the PKCS5 methods. The value must be greater than zero, and it is suggested that it be at least 1000.
digest - the digest algorithm used in MAC operations. Valid values are MD2, MD5 or SHA1 (SHA).
cipher - the cipher algorithm used in encryption and decryption operations. Valid values are DES, TripleDES or RC2.
keyFunc - the algorithm used in deriving keys. Currently, only PBKDF1-derived keys are supported and require a key encryption function of MD2, MD5 or SHA1 (SHA).
version - the version. Valid values are PKCS5.PKCS5_VERSION1 and PKCS5.PKCS5_VERSION2.
provname - the name of the java security provider the caller wants to use
Throws:
IllegalArgumentException - if any of the input arguments are invalid.
Method Detail

isSupportedMessageDigest

public static boolean isSupportedMessageDigest(String digestAlgorithm)
Checks if the specified Message Digest is supported by PKCS5.
Parameters:
digestAlgorithm - Message digest string.
Returns:
true if message digest is supported.

getSalt

public byte[] getSalt()
Returns a copy of the salt value used in the PKCS5 methods.
Returns:
salt value, 8 bytes long.

getIterationCount

public int getIterationCount()
Returns the iteration count value used in the PKCS5 methods. The iteration count is an immutable object.
Returns:
iteration count.

getKeyLength

public int getKeyLength()
Returns the key length value used in the PKCS5 methods. The key length is an immutable object.
Returns:
the key length.

getDigestAlgorithm

public String getDigestAlgorithm()
Returns the message digest value used in the PKCS5 methods. The message digest is an immutable object.
Returns:
the message digest.

getCipherAlgorithm

public String getCipherAlgorithm()
Returns the cipher algorithm value used in the PKCS5 methods. The cipher algorithm is an immutable object.
Returns:
the cipher algorithm.

getPaddingAlgorithm

public String getPaddingAlgorithm()
Returns the padding algorithm value used in the PKCS5 methods. The padding algorithm is an immutable object.
Returns:
the padding algorithm.

getCipherMode

public String getCipherMode()
Returns the cipher mode value used in the PKCS5 methods. The cipher mode is an immutable object.
Returns:
the cipher mode.

getCipherString

public String getCipherString()
Returns a cipher string constructed with "PBEWith" + key encryption function + "And" + cipher algorithm. The cipher string is used within the encode, encrypt, decrypt, and generateMAC methods.

getHMACString

public String getHMACString()
Returns a Hmac string constructed with "Hmac" + message digest algorithm + "And" + cipher algorithm. The Hmac string is used within the generateMAC methods.

getKeyAlgorithm

public String getKeyAlgorithm()
Returns the key algorithm value used in the PKCS5 methods. The key algorithm is an immutable object.

getEncryptionAlgorithm

public String getEncryptionAlgorithm()
Returns the encryption algorithm value used in the PKCS5 methods. The encryption algorithm is an immutable object.

getKeyEncryptionFunction

public String getKeyEncryptionFunction()
Returns the key encryption function value used in the PKCS5 methods. The key encryption function is an immutable object.

getVersion

public int getVersion()
Returns the version value used in the PKCS5 methods. The version is an immutable object. PKCS5_VERSION1 corresponds to the KEY_ALGORITHM_PBKDF1 derived key algorithm and ENCRYPTION_ALGORITHM_PBES1 encryption algorithm. PKCS5_VERSION2 corresponds to the KEY_ALGORITHM_PBKDF2 derived key algorithm and ENCRYPTION_ALGORITHM_PBES2 encryption algorithm.

toString

public String toString()
Returns a string representation of the PKCS5 object. Consists of the algorithms, functions and cipher block modes used in this object.
Overrides:
toString in class Object

toDetailedString

public String toDetailedString()
Returns a string representation of the PKCS5 object. Returns attribute names and values for debugging.

encodePBEParameters

public byte[] encodePBEParameters()
                           throws NoSuchAlgorithmException,
                                  InvalidParameterSpecException,
                                  IOException
Returns a DER encoded byte stream representing the PBE parameters stored in the PKCS5 object. The DER encoded string will consist of the salt and iteration count.
Throws:
NoSuchAlgorithmException - if PBE parameters are not supported in this Java environment.
InvalidParameterSpecException - if a PBE parameters specification cannot be constructed.
IOException - if the PBE parameters cannot be encoded properly.

encrypt

public byte[] encrypt(byte[] data)
               throws NoSuchAlgorithmException,
                      PKCSException
Encrypts a byte array with the encryption algorithm and values within the PKCS5 object.
Throws:
IllegalArgumentException - if the input data is invalid.
NoSuchAlgorithmException - if the cipher algorithm is not available in this environment.
PKCSException - on encryption errors.

decrypt

public byte[] decrypt(byte[] data)
               throws PKCSException,
                      NoSuchAlgorithmException
Decrypts an encrypted byte array with the encryption algorithm and values within the PKCS5 object.
Parameters:
data - the encrpyted data to decrypt.
Throws:
IllegalArgumentException - if the input data is invalid.
NoSuchAlgorithmException - if the cipher algorithm is not available in this environment.
PKCSException - on decryption errors.

generateMAC

public byte[] generateMAC(byte[] data)
                   throws IllegalArgumentException,
                          NoSuchAlgorithmException,
                          PKCSException
Generates a MAC for the specified byte array with the MAC algorithm and values within the PKCS5 object.
Parameters:
data - the data to generate a new MAC with.
Throws:
IllegalArgumentException - if the input data is invalid.
NoSuchAlgorithmException - if the MAC algorithm is not available in this environment.
PKCSException - on MAC-generation errors.

verifyMAC

public void verifyMAC(byte[] mac,
                      byte[] data)
               throws PKCSException,
                      IllegalArgumentException,
                      NoSuchProviderException,
                      NoSuchAlgorithmException,
                      javax.crypto.NoSuchPaddingException,
                      InvalidKeyException,
                      javax.crypto.BadPaddingException,
                      javax.crypto.IllegalBlockSizeException,
                      InvalidAlgorithmParameterException,
                      InvalidKeySpecException
Verifies a MAC for the specified byte array with the MAC algorithm and values within the PKCS5 object.
Parameters:
mac - the MAC to verify against.
data - the data to generate a new MAC with.

finalize

protected void finalize()
Ensures that the password bytes are nulled out when there are no more references to this object.
Overrides:
finalize in class Object