OpenJDK 27 · javax.crypto.spec.PBEKeySpec · APIdia, the JavaDoc alternative

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.

Modifier and Type	Field and Description
private int	iterationCount
private int	keyLength
private char[]	password
private byte[]	salt

Constructor Summary

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

Method Summary

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

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

iterationCount	back to summary
private int iterationCount

keyLength	back to summary
private int keyLength

password	back to summary
private char[] password

salt	back to summary
private byte[] salt

Constructor Detail

PBEKeySpec back to summary

PBEKeySpec	back to summary
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:char[] the password.

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:char[]: the password.

PBEKeySpec back to summary

PBEKeySpec	back to summary
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:char[] the password. salt:byte[] the salt. iterationCount:int the iteration count. keyLength:int the to-be-derived key length. Exceptions 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, 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:char[]: the password.
salt:byte[]: the salt.
iterationCount:int: the iteration count.
keyLength:int: the to-be-derived key length.

Exceptions

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

PBEKeySpec back to summary

PBEKeySpec	back to summary
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:char[] the password. salt:byte[] the salt. iterationCount:int the iteration count. Exceptions NullPointerException: if `salt` is null. IllegalArgumentException: if `salt` is empty, i.e. 0-length, or `iterationCount` 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:char[]: the password.
salt:byte[]: the salt.
iterationCount:int: the iteration count.

Exceptions

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

Method Detail

clearPassword	back to summary
public final synchronized void clearPassword() Clears the internal copy of the password.

getIterationCount	back to summary
public final int getIterationCount() Returns the iteration count or 0 if not specified. Returns:int the iteration count.

getIterationCount

back to summary

public final int getIterationCount()

Returns the iteration count or 0 if not specified.

Returns:int: the iteration count.

getKeyLength	back to summary
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:int the to-be-derived key length.

getKeyLength

back to summary

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:int: the to-be-derived key length.

getPassword back to summary

getPassword	back to summary
public final synchronized 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:char[] the password. Exceptions IllegalStateException: if password has been cleared by calling `clearPassword` method.

public final synchronized 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:char[]

the password.

Exceptions

IllegalStateException:: if password has been cleared by calling clearPassword method.

getSalt	back to summary
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:byte[] the salt.

getSalt

back to summary

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:byte[]: the salt.

public Class PBEKeySpec

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail