Preparing AES Key Wrap Encryption
By default, AM uses the Java Cryptography Extension (JCE) encryption class to encrypt and decrypt system passwords and keys used in the configuration, and by other components, such as agents.
If your deployment requires a more secure encryption algorithm, AM supports the Advanced Encryption Standard (AES) Key Wrap algorithm (RFC3394). AM's implementation of AES Key Wrap uses the Password-Based Key Derivation Function 2 (PBKDF2) (RFC2898) with HMAC-SHA1. This allows administrators to choose key size hash algorithms, such as SHA256, SHA384, or SHA512.
Important
The AES Key Wrap Encryption algorithm is only enabled when installing AM. There is no current upgrade path for existing installations.
The Security Token Service (STS) feature does not support the AES Key Wrap Encryption algorithm. Make sure that you do not deploy this feature in an AM instance configured to use the AES Key Wrap Encryption algorithm.
You must also update the ssoadm command to work with AES key wrap encryption. See "To Configure ssoadm for AES Key Wrap Encryption".
Warning
When implementing AES Key Wrap Encryption, take special care when selecting your encryption key iteration count.
If you select a large iteration count of 20,000, for example, you can effectively slow down a brute-force attack when passwords are of low quality (less than 20 characters and non-randomized). The trade off is that an iteration count of 20,000 can also negatively impact AM startup times if there are many agents in your deployment.
Determine the optimal iteration count for your deployment based on your security and performance requirements. Set the iteration count to a large number only if absolutely necessary.
AM does not have an iteration count requirement. However, it will log a warning if both of the following conditions are true:
The number of iterations is less than 10,000.
The AM encryption key is less than 20 characters long.
Edit your container startup scripts, for example
setenv.sh, to set the following JVM system properties in Tomcat:JAVA_OPTS="$JAVA_OPTS -Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.iterations=10000" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.size=256" JAVA_OPTS="$JAVA_OPTS -Dorg.forgerock.openam.encryption.key.digest=SHA512"
Only the first line in the example is required. The other lines are configurable to meet the needs of your deployment. Key sizes greater than 128 bits require that the JCE Unlimited Strength policy files be installed in your system. PBKDF2 using SHA256, SHA384, and SHA512 is only available on Java 8.
Note
You cannot change these configuration parameters once AM has been installed.
After you enable AES key wrap encryption, update the ssoadm command to work with the new encryption settings.
Add the following properties to the
/path/to/ssoadm/setupand/path/to/ssoadm/bin/ssoadmcommands:-Dcom.iplanet.security.encryptor=org.forgerock.openam.shared.security.crypto.AESWrapEncryption -Dorg.forgerock.openam.encryption.key.iterations=10000 -Dorg.forgerock.openam.encryption.key.size=256 -Dorg.forgerock.openam.encryption.key.digest=SHA512