How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I change the symmetric key in IDM 5.x and 6?

Last updated Apr 8, 2021

The purpose of this article is to provide information on changing the symmetric key in IDM; this key is used to encrypt values. The approach recommended in this article involves generating a new symmetric key but retaining the old one to ensure existing encrypted data can still be decrypted.


Overview

The default alias for the symmetric key is openidm-sym-default. As of IDM 6.5, an alias can have a dedicated capability and function. This means the default encryption alias is used for multiple purposes as detailed in Integrator's Guide › Configuration Options in secrets.json.

You can change the symmetric key as follows:

Generating a new symmetric key (pre-IDM 6.5)

Warning

If you replace the symmetric key within an existing environment, you will render IDM incapable of decrypting any existing encrypted data stored within the repository or the file-based JSON configuration. This affects both configuration and managed objects.

If replacing the encryption key in the keystore is desired, this article recommends that you generate a new symmetric key with a new alias but retain the old one. The new key will be used when encrypting data but the old key can still be found under the original alias to decrypt any data encrypted with the older key.

  1. Shut down the IDM instance.
  2. Generate a new symmetric key using the keytool command; you must use a different alias name, for example: $ keytool -genseckey -alias idm-sym-new -keyalg AES -keysize 128 -storetype jceks -keystore security/keystore.jceks
  3. Update the openidm.config.crypto.alias property in the boot.properties file (located in install-dir/resolver (IDM 6 and later) or /path/to/idm/conf/boot (IDM 5.x)) to use the new symmetric key you created. For example, change the following: # key in keystore to handle config encryption openidm.config.crypto.alias=openidm-sym-defaultto the new name (idm-sym-new in this example): # key in keystore to handle config encryption openidm.config.crypto.alias=idm-sym-new
  4. Update the encryption keys specified in the managed.json file (located in /path/to/idm/conf) to use the new symmetric key you created. For example, change the following: "password" : {    "title" : "Password",     "type" : "string",     ...     "encryption" : {         "key" : "openidm-sym-default"     },to the new name (idm-sym-new in this example): "password" : {    "title" : "Password",     "type" : "string",     ...     "encryption" : {         "key" : "idm-sym-new"     },
  5. Replace the $crypto blocks within the JSON configuration files across all nodes (whether standalone or clustered) with their corresponding plain text values. For example, to update the password field in the datasource.jdbc-default.json file, you would change the password field from: "password" : {        "$crypto" : {             "value" : {                 "iv" : "5UWV+SLe/Z9gg/7lZRO+Ng==",                 "data" : "7rol/iYruQ4xauop0hq6cQ==",                 "cipher" : "AES/CBC/PKCS5Padding",                 "key" : "openidm-sym-default"            },             "type" : "x-simple-encryption"         }     },to: "password" : "plain_text_value",
  6. Restart all the IDM instances. The startup process will re-encrypt the plain text values with the new symmetric key.

See Also

How do I renew my existing CA certificate in use by IDM (All versions)?

Finding org.forgerock.json.crypto.JsonCryptoException: Decryption failed errors in IDM

Given final block not properly padded error when starting IDM (All versions)

Resource exception: 500 Internal Server Error keeps happening in IDM (All versions)

Integrator's Guide › Securing & Hardening Servers

Integrator's Guide › Command-Line Interface

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.