org.forgerock.openam.shared.security.crypto

Class AESWrapEncryption

java.lang.Object

org.forgerock.openam.shared.security.crypto.AESWrapEncryption

All Implemented Interfaces:

AMEncryption, ConfigurableKey

public class AESWrapEncryption
extends Object
implements AMEncryption, ConfigurableKey

Encryption using AES KeyWrap deterministic authenticated key-wrapping encryption scheme described in RFC 3394, with PBKDF2-HMAC-SHA1 to derive unique encryption keys for each encrypted key from the AM encryption password. The AES KeyWrap algorithm provides strong integrity-protected deterministic encryption that is space efficient (encrypted keys are only slightly larger than the original data), but relatively inefficient performance-wise (still within the microsecond range for reasonable inputs). Key wrapping modes are generally robust in the face of misuse or low-quality random number generators. For instance, AES KeyWrap requires no nonce or random IV, and so the security cannot be compromised by problems in the generation of these components.

As the password provided by the ConfigurableKey interface cannot be guaranteed to be of high quality, this implementation uses PBKDF2KeyDerivation to derive unique keys for each item that is encrypted, using unique 128-bit random salt. This provides significantly improved security compared to just using the encryption password directly or deriving a single master encryption key from it, and as a side-effect also regains unpredictable output from AES KeyWrap as a unique key is used to encrypt each plaintext.

AES KeyWrap (AESKW) is a NIST/FIPS-approved key-wrap algorithm. PBKDF2 with HMAC-SHA1/SHA256/SHA384/SHA512 is a NIST-approved password-based key deriviation function. We use or exceed all current NIST recommendations for parameters to these algorithms. The only non-standard aspect is our use of PKCS#5 padding with AESKW rather than the separate padded variant of AESKW. This is for implementation simplicity given that our supported JREs only provide the non-padded AESKW algorithm and PKCS#5 padding is easier to implement correctly.

Constructor Summary

Constructors

Constructor and Description
AESWrapEncryption() Public default constructor.

Method Summary

Modifier and Type	Method and Description
byte[]	decrypt(byte[] encData) Decrypts the data using AESWrap and the configured key.
byte[]	encrypt(byte[] rawData) Encrypts the data using AESWrap and the configured key.
void	setPassword(String password) Sets the encryption key from a password.

Methods inherited from class java.lang.Object

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

Constructor Detail

AESWrapEncryption

public AESWrapEncryption()

Public default constructor.

Method Detail

setPassword

public void setPassword(String password)
                 throws Exception

Sets the encryption key from a password. The actual encryption key will be derived from the password using the PBKDF2 key derivation algorithm. Use the system properties org.forgerock.openam.encryption.key.salt, org.forgerock.openam.encryption.key.iterations and org.forgerock.openam.encryption.key.size to set the salt (no default, must be set), number of iterations (defaults to 250,000) and output key size (defaults to 128-bits, can be 128, 192 or 256).

Specified by:

setPassword in interface ConfigurableKey

Parameters:

password - the password to use to derive the encryption key. Must be ASCII.

Throws:

Exception - if an error occurs when deriving a key from the password.

encrypt

public byte[] encrypt(byte[] rawData)

Encrypts the data using AESWrap and the configured key.

Specified by:

encrypt in interface AMEncryption

Parameters:

rawData - the data to encrypt.

Returns:

the encrypted data.

Throws:

IllegalStateException - if a key has not been configured.

RuntimeException - if the data cannot be encrypted for any reason.

decrypt

public byte[] decrypt(byte[] encData)

Decrypts the data using AESWrap and the configured key.

Specified by:

decrypt in interface AMEncryption

Parameters:

encData - the data to decrypt.

Returns:

the decrypted data.

Throws:

IllegalStateException - if a key has not been configured.

RuntimeException - if the data cannot be decrypted for any reason.