PBEKeySpec

public class PBEKeySpec extends Object
implements KeySpec

A user-chosen password that can be used with password-based encryption (PBE).

The password can be viewed as some kind of raw key material, from which the encryption mechanism that uses it derives a cryptographic key.

Different PBE mechanisms may consume different bits of each password character. For example, the PBE mechanism defined in PKCS #5 looks at only the low order 8 bits of each character, whereas PKCS #12 looks at all 16 bits of each character.

You convert the password characters to a PBE key by creating an instance of the appropriate secret-key factory. For example, a secret-key factory for PKCS #5 will construct a PBE key from only the low order 8 bits of each password character, whereas a secret-key factory for PKCS #12 will take all 16 bits of each character.

Also note that this class stores passwords as char arrays instead of String objects (which would seem more logical), because the String class is immutable and there is no way to overwrite its internal value when the password stored in it is no longer needed. Hence, this class requests the password as a char array, so it can be overwritten when done.

See Also

• SecretKeyFactory
• PBEParameterSpec

Public Constructor Summary

	PBEKeySpec(char[] password) Constructor that takes a password.
	PBEKeySpec(char[] password, byte[] salt, int iterationCount, int keyLength) Constructor that takes a password, salt, iteration count, and to-be-derived key length for generating PBEKey of variable-key-size PBE ciphers.
	PBEKeySpec(char[] password, byte[] salt, int iterationCount) Constructor that takes a password, salt, iteration count for generating PBEKey of fixed-key-size PBE ciphers.

Public Method Summary

final void	clearPassword() Clears the internal copy of the password.
final int	getIterationCount() Returns the iteration count or 0 if not specified.
final int	getKeyLength() Returns the to-be-derived key length or 0 if not specified.
final char[]	getPassword() Returns a copy of the password.
final byte[]	getSalt() Returns a copy of the salt or null if not specified.

Inherited Method Summary

From class java.lang.Object

Object	clone() Creates and returns a copy of this Object.
boolean	equals(Object obj) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of Class that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait(long timeout, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait(long timeout) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.
final void	wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object.

Public Constructors

public PBEKeySpec (char[] password)

Constructor that takes a password. An empty char[] is used if null is specified.

Note: password is cloned before it is stored in the new PBEKeySpec object.

Parameters

password	the password.

public PBEKeySpec (char[] password, byte[] salt, int iterationCount, int keyLength)

Constructor that takes a password, salt, iteration count, and to-be-derived key length for generating PBEKey of variable-key-size PBE ciphers. An empty char[] is used if null is specified for password.

Note: the password and salt are cloned before they are stored in the new PBEKeySpec object.

Parameters

password	the password.
salt	the salt.
iterationCount	the iteration count.
keyLength	the to-be-derived key length.

Throws

NullPointerException	if salt is null.
IllegalArgumentException	if salt is empty, i.e. 0-length, iterationCount or keyLength is not positive.

public PBEKeySpec (char[] password, byte[] salt, int iterationCount)

Constructor that takes a password, salt, iteration count for generating PBEKey of fixed-key-size PBE ciphers. An empty char[] is used if null is specified for password.

Note: the password and salt are cloned before they are stored in the new PBEKeySpec object.

Parameters

password	the password.
salt	the salt.
iterationCount	the iteration count.

Throws

NullPointerException	if salt is null.
IllegalArgumentException	if salt is empty, i.e. 0-length, or iterationCount is not positive.

Public Methods

public final void clearPassword ()

Clears the internal copy of the password.

public final int getIterationCount ()

Returns the iteration count or 0 if not specified.

Returns

• the iteration count.

public final int getKeyLength ()

Returns the to-be-derived key length or 0 if not specified.

Note: this is used to indicate the preference on key length for variable-key-size ciphers. The actual key size depends on each provider's implementation.

Returns

• the to-be-derived key length.

public final char[] getPassword ()

Returns a copy of the password.

Note: this method returns a copy of the password. It is the caller's responsibility to zero out the password information after it is no longer needed.

Returns

• the password.

Throws

IllegalStateException	if password has been cleared by calling clearPassword method.

public final byte[] getSalt ()

Returns a copy of the salt or null if not specified.

Note: this method should return a copy of the salt. It is the caller's responsibility to zero out the salt information after it is no longer needed.

Returns

• the salt.