org.forgerock.openam.shared.security.crypto

Class PBKDF2KeyDerivation

java.lang.Object

org.forgerock.openam.shared.security.crypto.PBKDF2KeyDerivation

All Implemented Interfaces:

ConfigurableKey

public class PBKDF2KeyDerivation
extends Object
implements ConfigurableKey

A ConfigurableKey implementation that derives a secret key from the input password using the PBKDF2 key deriviation algorithm. The following system properties can be used to configure how the key is derived:

• org.forgerock.openam.encryption.key.digest - the message digest (hash) algorithm to use with PBKDF2. Defaults to "SHA1".
• org.forgerock.openam.encryption.key.iterations - the number of iterations of PBKDF2 to apply when generating keys. Must be at least 10,000, but should typically be as large as you can compute in a reasonable time.

The NIST guidelines (section 5.1.1.2) recommend at least 10,000 iterations of PBKDF2 and a salt of at least 32 bits. The PBKDF2 spec itself recommends a salt of at least 64 bits. We use a salt of 128 bits as per this advice. The default hash algorithm we use is SHA-1, as this is available on all supported platforms. If you are using Java 8 it is better to use a hash like SHA-512 as that greatly increases the memory requirements and will slow down GPU-based brute-force attacks.

Constructor Summary

Constructors

Constructor and Description
PBKDF2KeyDerivation() Default private constructor.

Method Summary

Modifier and Type	Method and Description
void	clear() Clears the configured password for this key derivation function.
PBEKey	deriveSecretKey(int keySize) Derives a secret key of the requested size using a fresh random salt and the configured password and iteration count.
PBEKey	deriveSecretKey(int keySize, byte[] salt) Derives a secret key of the requested using using the given salt and the configured password and iteration count.
void	setPassword(String password) Sets password-based key to use

Methods inherited from class java.lang.Object

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

Constructor Detail

PBKDF2KeyDerivation

public PBKDF2KeyDerivation()

Default private constructor.

Throws:

IllegalStateException - if the configured message digest or iteration count is invalid.

Method Detail

setPassword

public void setPassword(String password)
                 throws Exception

Description copied from interface: ConfigurableKey

Sets password-based key to use

Specified by:

setPassword in interface ConfigurableKey

Throws:

Exception

deriveSecretKey

public PBEKey deriveSecretKey(int keySize)

Derives a secret key of the requested size using a fresh random salt and the configured password and iteration count. The parameters can be read from the generated key.

Parameters:

keySize - the size of the key (in bits) to generate.

Returns:

the generated key.

deriveSecretKey

public PBEKey deriveSecretKey(int keySize,
                              byte[] salt)

Derives a secret key of the requested using using the given salt and the configured password and iteration count.

Parameters:

keySize - the size of the key (in bits) to generate.

salt - the salt to use to generate the key.

Returns:

the derived key.

clear

public void clear()

Clears the configured password for this key derivation function.