javax.crypto.spec: public class: PBEKeySpec

javax.crypto.spec
public class: PBEKeySpec [javadoc | source]

java.lang.Object
   javax.crypto.spec.PBEKeySpec

All Implemented Interfaces:
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.

Also see:

javax.crypto.SecretKeyFactory

PBEParameterSpec

author: Jan - Luehe

author: Valerie - Peng

since: 1.4 -

Constructor:

Constructor:
public PBEKeySpec(char[] password) { if ((password == null) \|\| (password.length == 0)) { this.password = new char[0]; } else { this.password = (char[])password.clone(); } } 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) { if ((password == null) \|\| (password.length == 0)) { this.password = new char[0]; } else { this.password = (char[])password.clone(); } if (salt == null) { throw new NullPointerException("the salt parameter " + "must be non-null"); } else if (salt.length == 0) { throw new IllegalArgumentException("the salt parameter " + "must not be empty"); } else { this.salt = (byte[]) salt.clone(); } if (iterationCount< =0) { throw new IllegalArgumentException("invalid iterationCount value"); } this.iterationCount = 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. exception: `NullPointerException` - if `salt` is null. exception: `IllegalArgumentException` - if `salt` is empty, i.e. 0-length, or `iterationCount` is not positive.
public PBEKeySpec(char[] password, byte[] salt, int iterationCount, int keyLength) { if ((password == null) \|\| (password.length == 0)) { this.password = new char[0]; } else { this.password = (char[])password.clone(); } if (salt == null) { throw new NullPointerException("the salt parameter " + "must be non-null"); } else if (salt.length == 0) { throw new IllegalArgumentException("the salt parameter " + "must not be empty"); } else { this.salt = (byte[]) salt.clone(); } if (iterationCount< =0) { throw new IllegalArgumentException("invalid iterationCount value"); } if (keyLength< =0) { throw new IllegalArgumentException("invalid keyLength value"); } this.iterationCount = iterationCount; this.keyLength = 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. exception: `NullPointerException` - if `salt` is null. exception: `IllegalArgumentException` - if `salt` is empty, i.e. 0-length, `iterationCount` or `keyLength` is not positive.

 public PBEKeySpec(char[] password) {
        if ((password == null) || (password.length == 0)) {
            this.password = new char[0];
        } else {
            this.password = (char[])password.clone();
        }
}

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) {
        if ((password == null) || (password.length == 0)) {
            this.password = new char[0];
        } else {
            this.password = (char[])password.clone();
        }
        if (salt == null) {
            throw new NullPointerException("the salt parameter " +
                                            "must be non-null");
        } else if (salt.length == 0) {
            throw new IllegalArgumentException("the salt parameter " +
                                                "must not be empty");
        } else {
            this.salt = (byte[]) salt.clone();
        }
        if (iterationCount< =0) {
            throw new IllegalArgumentException("invalid iterationCount value");
        }
        this.iterationCount = 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.

exception: NullPointerException - if salt is null.

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

 public PBEKeySpec(char[] password,
    byte[] salt,
    int iterationCount,
    int keyLength) {
        if ((password == null) || (password.length == 0)) {
            this.password = new char[0];
        } else {
            this.password = (char[])password.clone();
        }
        if (salt == null) {
            throw new NullPointerException("the salt parameter " +
                                            "must be non-null");
        } else if (salt.length == 0) {
            throw new IllegalArgumentException("the salt parameter " +
                                                "must not be empty");
        } else {
            this.salt = (byte[]) salt.clone();
        }
        if (iterationCount< =0) {
            throw new IllegalArgumentException("invalid iterationCount value");
        }
        if (keyLength< =0) {
            throw new IllegalArgumentException("invalid keyLength value");
        }
        this.iterationCount = iterationCount;
        this.keyLength = 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.

exception: NullPointerException - if salt is null.

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

Method from javax.crypto.spec.PBEKeySpec Summary:
clearPassword, getIterationCount, getKeyLength, getPassword, getSalt

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

Method from javax.crypto.spec.PBEKeySpec Detail:
public final void clearPassword() { if (password != null) { for (int i = 0; i < password.length; i++) { password[i] = ' '; } password = null; } } Clears the internal copy of the password.
public final int getIterationCount() { return iterationCount; } Returns the iteration count or 0 if not specified.
public final int getKeyLength() { return keyLength; } 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.
public final char[] getPassword() { if (password == null) { throw new IllegalStateException("password has been cleared"); } return (char[]) password.clone(); } 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.
public final byte[] getSalt() { if (salt != null) { return (byte[]) salt.clone(); } else { return null; } } 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.

Method from javax.crypto.spec.PBEKeySpec Detail:

 public final  void clearPassword() {
        if (password != null) {
            for (int i = 0; i <  password.length; i++) {
                password[i] = ' ';
            }
            password = null;
        }
}

Clears the internal copy of the password.

 public final int getIterationCount() {
        return iterationCount;
}

Returns the iteration count or 0 if not specified.

 public final int getKeyLength() {
        return keyLength;
}

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.

 public final char[] getPassword() {
        if (password == null) {
            throw new IllegalStateException("password has been cleared");
        }
        return (char[]) password.clone();
}

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.

 public final byte[] getSalt() {
        if (salt != null) {
            return (byte[]) salt.clone();
        } else {
            return null;
        }
}

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.