Managing Key Aliases and Passwords

Whether you need to create new key aliases because you are using more AM features or because you are installing a new environment, consider the following points:

Review the list of features in AM to understand which features use the AM keystore and which ones do not, then manage your secrets accordingly. You should avoid sharing certificates among features when possible, which may result in configuring different keystores or secret stores.
For more information, see "Features in AM That Use Keys".
Make sure keystores, key aliases, and certificates are maintained on every instance; in a site environment, every instance has its own keystore files.
Make sure keystores and secret stores are in the same location across of all of the instances in the site.

The following table contains a list of the tasks you may need to perform when managing key aliases in your environment:

Task	Resources
Create new key alias in an existing keystore or in a new keystore	"Creating Key Aliases"
Copy key aliases between keystores; for example, when configuring IDM's provisioning.	"Copying Key Aliases"
Change key alias passwords.	"Changing Key Alias Passwords"
Change keystore passwords.	"Changing Keystore Passwords".

Creating Key Aliases

Several AM features require key aliases for signing and encryption. New AM installations pre-configure default key aliases for all of the features, but you should create new key aliases for each of them.

You can create key aliases in a new keystore that, for example, will be configured later as the AM keystore, or you can create key aliases in the existing AM keystore:

To Create a Keystore and Key Aliases for Keystore Secret Stores

To create a new AM keystore, see "Managing the AM Keystore" instead.

Acquire a new key from your certificate authority and add it to a new keystore, or generate a new self-signed key in a new keystore.
This example creates a self-signed key alias in a new keystore file, keystoreA.jceks, with a new asymmetric RSA key alias, newkey.
Note than in production environments you should use the strongest algorithm you can.
```
$ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias newkey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=newkey' \
-keystore keystoreA.jceks
Enter keystore password:
Reenter new password:
Enter key password for <newkey>
(RETURN if same as keystore password):
Reenter new password:
```
Take note of the passwords. You need to make them available within another secret store; for example, by using a file system volume secret store, as shown below:
1. Go to the directory that the filesystem volume secret store will point to. For example, /path/to/openam/security/secrets/mydir.
  Since you can encode the content of the files using different modes, we recommend that you create a directory for each encode mode you plan to use, at least.
2. Create two files, one for the keystore password, and another for the password of the keys inside the keystore.
  The files will contain the passwords encoded expected by the file system secret volume store.
  For example, if you chose Base64 encoded as the encoding, you must base64-encode the passwords, and then add them to their respective files.
  For example:
```
$ echo -n bmV3c3RvcmVwYXNzd29yZA== > keystoreA_storepass
$ echo -n bmV3a2V5cGFzc3dvcmQ= > keystoreA_keypass
```
  Important
  Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to open the keystore or the key aliases.
3. Make sure the password files have read-only permission for their owner. For example:
```
$ chmod 400 keystoreA_storepass
$ chmod 400 keystoreA_keypass
```
Create any other keys and keystores required by your environment by repeating the steps in this procedure and/or following the steps in "To Create Key Aliases in an Existing Keystore".
Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.
Configure the keystore in a keystore-type secret store. See "Keystore Secret Stores".
To configure the file system secret store too, see "File System Secret Volumes Secret Stores".

To Create Key Aliases in an Existing Keystore

Perform the following steps to create new key aliases in an existing keystore. For example, the AM keystore:

Change directories to the keystore location, for example, /path/to/openam/security/keystores/.
Acquire a new key from your certificate authority, or generate a new self-signed key.
When you create or import a new key, the keytool command adds the new alias to the specified keystore if it exists, or creates a new keystore if it does not exist.
This example creates a self-signed key alias in the AM keystore, am_keystore.jceks, with a new asymmetric RSA key alias called mynewkey.
Note than in production environments you should use the strongest algorithm you can use.
```
$ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias mynewkey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=mynewkey' \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .keystore_storepass file.
Enter key password for <mynewkey>
(RETURN if same as keystore password): Enter the password in the .keystore_keypass file.
Reenter new password: Enter the password in the .keystore_keypass file.
```
Remember:
- The contents of the password files of the AM keystore are in cleartext.
- The contents of the password files in a file system volume secret store are not in cleartext by default. This means that you need to decode them before you can use them in the keytool command.
Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.
(AM keystore) Restart the AM instances affected by the configuration changes to use the new key aliases.
Configure the new key aliases in AM. For a list of features that use key aliases and links to their relevant sections, see "Features in AM That Use Keys".

To Create Self-Service Key Aliases

User self-service requires a key pair for encryption and a signing secret key to be available in the AM keystore before configuring any of its features. Follow the steps in this procedure to create new key aliases for the user self-service features in the AM keystore:

Acquire a new key from your certificate authority, or generate new self-signed keys. The password of the new keys for the user self-service features must match the passwords of those keys already present in the keystore, and configured in the /path/to/openam/security/secrets/default/.am_keystore_keypass file.

This example generates a self-signed key for encryption and a new signing secret key in the am_keystore.jceks keystore, but you could also import CA-provided keys to the keystore.

Create the new self-signed encryption key alias:

$ cd /path/to/openam/security/keystores/
$ keytool \
-genkeypair \
-alias newenckey \
-keyalg RSA \
-keysize 2048 \
-validity 730 \
-storetype JCEKS \
-dname 'CN=newenckey' \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .am_keystore_storepass file.
Enter key password for <newenckey>
(RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
Reenter new password: Enter the password in the .am_keystore_keypass file.

Create the new signing secret key alias:

$ cd /path/to/openam/security/keystores/
$ keytool \
-genseckey \
-alias newsigkey \
-keyalg HmacSHA256 \
-keysize 256 \
-storetype JCEKS \
-keystore am_keystore.jceks
Enter keystore password: Enter the password in the .am_keystore_storepass file.
Enter key password for <newsigkey>
(RETURN if same as keystore password): Enter the password in the .am_keystore_keypass file.
Reenter new password: Enter the password in the .am_keystore_keypass file.

Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.
Restart the AM instances affected by the configuration changes.
Configure user self-service to use the new keys. For more information, see "Creating a User Self-Service Service Instance".

Copying Key Aliases

Some AM features require access to the key aliases used by other components of the ForgeRock Identity Platform. For example, the IDM Provisioning feature requires access to the key aliases IDM uses for signing and encrypting data.

This section covers copying key aliases from the keystore of a ForgeRock Identity Platform component to AM's default keystore.

To Copy a Key Alias From One Keystore to Another

Use the keytool command to export the key from the source component's keystore. Install the result in the AM keystore, by performing the following steps:

From the source keystore, export the required key into a temporary keystore that can be transported to AM by executing the following keytool command:
```
$ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
-deststoretype jceks -destalias "myKeyAlias" \
-srckeystore "/path/to/openidm/security/keystore.jceks" \
-destkeystore "/path/to/openidm/security/temp_keystore.jceks" \
-srckeypass "changeit" \
-srcstorepass "changeit" \
-destkeypass "myT3mPK3yP4ssword" \
-deststorepass "myT3mPK3yP4ssword"
```
This command exports the myKeyAlias key alias, specified by the srcalias argument, to a temporary keystore file /path/to/openidm/security/temp_keystore.jceks. The store and key password is set to myT3mPK3yP4ssword. You need to use the temporary passwords when importing to the AM instance.
Move the temporary keystore file created in the previous step, in this example temp_keystore.jceks, to the filesystem of the target AM server.

On the target AM server, import the key alias into the AM keystore by executing the following keytool command:

$ keytool -importkeystore -srcstoretype jceks -srcalias "myKeyAlias" \
-deststoretype jceks -destalias "myKeyAlias" \
-srckeystore "/path/to/openam/security/keystores/temp_keystore.jceks" \
-destkeystore "/path/to/openam/security/keystores/am_keystore.jceks" \
-srckeypass "myT3mPK3yP4ssword" \
-srcstorepass "myT3mPK3yP4ssword" \
-destkeypass:file "/path/to/openam/security/secrets/default/.am_keystore_keypass" \
-deststorepass:file "/path/to/openam/security/secrets/default/.am_keystore_storepass"

This command imports the key alias from the temporary temp_keystore.jceks keystore file, which was copied from the IDM instance, into the AM keystore. The command also sets the passwords to match those used by the default AM keystore.

(Optional) Repeat the previous steps to copy any additional key aliases from the source keystore to the destination keystore.
Restart the AM instance for the key change to take effect.
The AM instance will now be able to correctly encrypt, decrypt, sign or verify data and share it with the source ForgeRock Identity Platform component.

Changing Key Alias Passwords

Decrypting a key alias in a keystore requires a password. This password is initially specified when you generate the key, or when you import the key into a keystore, but you might need to update the password at a later time.

To Change Key Alias Passwords

Back up your keystore and password files.
Depending on the location of the key alias whose password you are changing, perform one of the following steps:
- To change the password that opens the AM keystore:
  Replace the old password in the .am_keystore_keypass file with the new one:
```
$ echo -n newpassword > /path/to/openam/security/secrets/default/.am_keystore_keypass
```
  Important
  Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command can use the password in the file, AM may not be able to use the key aliases if there are hidden, trailing, newline characters in the password file.
- To change the password that opens a secret store:
  Replace the old password in the secret containing it with the new one. If the secret is a file in a file system volume secret store, ensure that the new password is encoded appropriately.
  For example, for base64-encoded passwords, use the following command:
```
$ echo -n bmV3a2V5cGFzc3dvcmQ= > keystoreA_keypass
```
- To change a password value used to decrypt a PEM-formatted secret:
  Encode the new password using the https://openam.example.com:8443/openam/encode.jsp page, and write the result to a file system secret or environment variable that uses the am.global.services.secret.pem.decryption secret ID:
```
$ echo -n AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K \
  > am.global.services.secret.pem.decryption
```
```
$ export AM_GLOBAL_SERVICES_SECRET_PEM_DECRYPTION=AQICmX1ntZv3XETMgDo+0zFynC8UMGJgop+K
```

Depending on the location of the secret, perform one of the following steps to update the secret's password to match the value you configured in the previous step:

To change the password of key aliases in the AM Keystore:

Use the keytool command to change the password of each of the key aliases, for example:

$ keytool -keypasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks -alias mykey
  Enter keystore password: Enter the password in the .am_keystore_storepass file
  New key password for <mykey> Enter the password in the .am_keystore_keypass file
  Re-enter new key password for <mykey> Enter the password in the .am_keystore_keypass file

  ** Caution **

  Remember to change the passwords of the configstorepwd and the dsameuserpwd aliases.
  Failure to do so will render AM unbootable.

Tip

You can list the keys and password strings contained in the AM keystore using this command:

$ keytool -list -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks

To change the password of key aliases in a secret store:

Use the keytool command to change the password of each of the key aliases, for example:

$ keytool -keypasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks -alias mykey
  Enter keystore password: Enter the password in the keystoreA_storepass file
  New key password for <mykey> Enter the password in the keystoreA_keypass file
  Re-enter new key password for <mykey> Enter the password in the keystoreA_keypass file

  ** Remember **

  Secrets in file system volume secret stores are, by default, not in cleartext.
  You need to decode them before using them with the keytool command.

Tip

You can list the keys and password strings contained in a secret store using this command:

$ keytool -list -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks

To change the password of a PEM-formatted secret:

Use the openssl command to open, and then export the secret alias with a new password:

$ openssl rsa -aes256 -in originalkey.pem -out new_password_key.pem
  Enter pass phrase for originalkey.pem: Enter the original password
  writing RSA key
  Enter PEM pass phrase: Enter the new password
  Verifying - Enter PEM pass phrase: Re-enter new password

Important

The algorithm you specify must match the input PEM file.

When completed, overwrite the original PEM file with the replacement, for example:

$ mv new_password_key.pem originalkey.pem

(Optional) If you also need to change the keystore password, see "To Change the Keystore Password".
Ensure that password files and keystores are maintained on every instance in your environment. Every AM instance has its own keystores and password files.
(AM keystore) Restart the AM instances affected by the configuration changes.

Changing Keystore Passwords

Decrypting and viewing the contents of a keystore requires a password. This password is specified by the user at the time the keystore is created, but you might need to update the password at a later time.

To Change the Keystore Password

(AM keystore) Replace the old password in the .am_keystore_storepass file with the new one:
```
$ echo -n newpassword > /path/to/openam/security/secrets/default/.am_keystore_storepass
```
Important
Use echo -n to avoid inserting hidden trailing newline characters. Even if the keytool command is able to use the password in the file, AM may not be able to use the key aliases if there are hidden trailing newline characters in the password file.
(Secret stores) Replace the old password in the secret containing it with the new one. If the secret is a file in a file system volume secret store, ensure that the new password is encoded appropriately.
For example, base64-encode the password, and add it to the file:
```
$ echo -n bmV3c3RvcmVwYXNzd29yZA== > keystoreA_storepass
```

Change the password of the keystore:

$ keytool -storepasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/am_keystore.jceks 
Enter keystore password: Enter the password in the .am_keystore_storepass file.
New keystore password: Enter the new password.
Re-enter new keystore password:

$ keytool -storepasswd -storetype JCEKS -keystore /path/to/openam/security/keystores/keystoreA.jceks 
Enter keystore password: Enter the password in the keystoreA_storepass file.
New keystore password: Enter the new password.
Re-enter new keystore password:

 ** Remember **

 Secrets in file system volume secret stores are, by default, not in cleartext.
 That means, you need to decode them before using them with the keytool command.

(Optional) If you also need to change the key aliases' password, see "To Change Key Alias Passwords".
Ensure that password files and keystores are maintained on every instance in your environment. Each AM instance has its own keystores and password files.
(AM keystore only) Restart the AM instance or instances affected by the configuration changes.