Amster

Create transport keys to export configuration data

To import and export encrypted password values in the configuration files you must generate a transport key, and install it in the keystore of each AM instance that you will be transporting passwords between.

The transport key must be stored in the default AM keystore, located at /path/to/openam/security/keystores/keystore.jceks, and should have a key alias of sms.transport.key.

The presence of the transport key causes additional fields containing encrypted password values to appear in the exported configuration files. These additional fields have a -encrypted suffix, as shown below:

{"authenticatorPushDeviceSettingsEncryptionKeystorePassword":null,
 "authenticatorPushDeviceSettingsEncryptionKeystorePassword-encrypted":"encrypted-pwd"}

Encrypted password fields will only be added to REST calls made by administrative users, such as amAdmin.

Performance of an AM instance with a transport key present will be significantly impacted. You MUST delete the transport key when imports and exports have been completed.

Without a transport key present, all password fields are set to null in the exported configuration files, regardless of their actual value in the configuration.

Generate and install a new transport key

Use the keytool command to generate the transport key by performing the following steps:

  1. Run the keytool command, specifying the location of the .storepass file as the password to use for the keystore, and the location of the .keypass file as the password to use for the key aliases:

    $ keytool -genseckey -alias "sms.transport.key" -keyalg AES -keysize 128 \
  -storetype jceks -keystore "/path/to/openam/security/keystores/keystore.jceks" \
  -storepass:file "/path/to/openam/security/secrets/default/.storepass" \
  -keypass:file "/path/to/openam/security/secrets/default/.keypass"

  2. You must restart AM for the transport key change to take effect.

    The instance will now be able to include encrypted passwords in the exported configuration files.

To decrypt and import configuration files that contain encrypted passwords, you must install the same transport key used to encrypt it into the keystore of the target AM instance.

Duplicate and install a transport key

Use the keytool command to export the transport key from the source instance keystore, and then install the result on the target instance keystore, by performing the following steps:

  1. On the source instance, export the transport key into a keystore that can be transported to another instance by executing the following keytool command:

    $ keytool -importkeystore -srcstoretype jceks -srcalias "sms.transport.key" \
  -deststoretype jceks -destalias "sms.transport.key" \
  -srckeystore "/path/to/openam/security/keystores/keystore.jceks" \
  -destkeystore "/path/to/openam/security/keystores/transport_keystore.jceks" \
  -srckeypass:file "/path/to/openam/security/secrets/default/.keypass" \
  -srcstorepass:file "/path/to/openam/security/secrets/default/.storepass" \
  -destkeypass "myTransp0rtK3yP4ssword" \
  -deststorepass "myTransp0rtK3yP4ssword"

    This command exports the transport key to a temporary keystore file /path/to/openam/security/keystores/transport_keystore.jceks, and set a store and key password of myTransp0rtK3yP4ssword. You need to use these temporary passwords when importing to the target instance.

  2. Move the keystore file created in the previous step, in this example transport_keystore.jceks, to the filesystem of the target server.

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

    $ keytool -importkeystore -srcstoretype jceks -srcalias "sms.transport.key" \
  -deststoretype jceks -destalias "sms.transport.key" \
  -srckeystore "/path/to/openam/security/keystores/transport_keystore.jceks" \
  -destkeystore "/path/to/openam/security/keystores/keystore.jceks" \
  -srckeypass "myTransp0rtK3yP4ssword" \
  -srcstorepass "myTransp0rtK3yP4ssword" \
  -destkeypass:file "/path/to/openam/security/secrets/default/.keypass" \
  -deststorepass:file "/path/to/openam/security/secrets/default/.storepass"

    This command imports the transport key from the temporary keystore file /path/to/openam/security/keystores/transport_keystore.jceks into the AM keystore, and set the transport key password to match the password used by the target keystore.

  4. You must restart the target AM instance for the transport key change to take effect.

    The target instance will now be able to correctly decrypt passwords stored in the imported configuration files.

The presence of the transport key includes encrypted passwords in requests made by an administrative user, causing significant performance degradation. You MUST delete the transport key when imports and exports have been completed.

Delete a transport key

  1. Run the following keytool command:

    $ keytool -delete -alias "sms.transport.key" -storetype jceks \
  -storepass:file "/path/to/openam/security/secrets/default/.storepass" \
  -keystore "/path/to/openam/security/keystores/keystore.jceks"

  2. You must restart the target AM instance for the transport key change to take effect.

    The target instance will no longer include encrypted passwords, nor be able to correctly decrypt passwords stored in configuration files.