Federation Security Services Guide › Signing and Encrypting Messages to Secure Federated Transactions › Migrate AM.keystore and Update smkeydatabase › Considerations Before Migrating Key Databases

Considerations Before Migrating Key Databases

Important! Before you migrate the AM.keystore, back up the previous AM.keystore file and the smkeydatabase.properties file. The AM.keystore file is in the location you specified when you first created it.

The smkeydatabase.properties file is in one of the following directories:

Windows: policy_server_home\config\properties

UNIX: policy_server_home/config/properties

policy_server_home

Indicates the installation directory of the policy server.

Before you migrate, consider the following:

• Understand the purpose of aliases in the smkeydatabase

  Aliases enable you to reference any private key/certificate pair in the smkeydatabase. Beginning with 6.0 SP 5/6.x QMR 5, every private key/certificate pair in the smkeydatabase must have a unique alias.

  If you are upgrading from a release prior to 6.0 SP5/6.x QMR 5, your existing smkeydatabase must be migrated to the new model using the migratekeystore tool.

  When you run the tool the first time, an alias data store is created and aliases are added to this store. For existing private key/certificate entries in the smkeydatabase, an alias is created based on the CN value of the certificate subject DN. If the CN attribute does not exist, the first attribute value of the certificate's subject DN is chosen as the alias. If there are duplicate entries, the alias name is calculated using a combination of multiple attribute values from the subject DN.

  Note: You can change an alias value using the renameAlias option of the smkeytool utility.

• Know the Order that SiteMinder Looks for Keys

  The Policy Server at the asserting party uses an enterprise private key to sign SAML messages and to decrypt encrypted SAML messages received from the relying party.

  When SiteMinder looks for a private key in the database, it searches using the following order of preference:

  1. Looks for the key associated with the signing alias, if a signing alias is configured
  2. Looks for the default enterprise private key.Typically, the default enterprise key is the first private key found in the smkeydatabase.
  3. If there is no default enterprise private key, SiteMinder looks for the first private key in the database.

  If you copy data from an AM.keystore to a 6.0 SP6 smkeydatabase, additional private keys and client certificates get added to the smkeydatabase. This may change the order of private keys already in the smkeydatabase. As a result, when you run the migratekeystore tool, it adds an alias named defaultEnterprisePrivateKey for the first private key it finds in the database. If a signing alias is not configured, the Policy Server will use the defaultEnterprisePrivateKey alias as the key for digital signing.

More Information

Run the migratekeystore Tool