Description of Policy Server encryption Key- EncryptionKey.txt and how to update/modify it.

Document ID : KB000051331
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

About The Policy Server encryption key (EncryptionKey.txt)

  • Each SiteMinder Policy server requires a policy server encryption key. This key is configured when a Policy server is initially installed and the installation program prompts for this value. The key value configured is encrypted with an RC2 chiper that makes uses of one or more internally hard-coded keys before being stored locally on the Policy server system in a file called, "EncryptionKey.txt".

  • This file is typically located in the <SiteMinder install root>/Bin directory. The location of this file is also present in the SiteMinder registry under the HKEY_LOCAL_MACHINE/Software/Netegrity/SiteMinder/CurrentVersion registry hive, in a field called "MasterKeyFile", on all SiteMinder Policy server platforms.

  • This key is used by the Policy server to encrypt and decrypt "sensitive" information that is entered in the SiteMinder Policy Server Management Console (SMConsole) as well as the SiteMinder Policy Server User Interface. This includes data such as LDAP bind-credentials, ODBC passwords, key-store keys, agent shared secrets etc.
  • Encrypted data from the console is stored in the local Policy server registry. Encrypted data from the UI is stored in the Policy store.

In infrastructures where several web-agents communicate with common shared Policy servers and where SiteMinder policy-stores are replicated, it is mandatory that all such Policy servers should use a common Policy server Encryption key so that they may decipher and use the shared policy-store data.

Solution:

How to Reset/Change/Update the Policy server encryption key

Once a SiteMinder Policy Server encryption key is defined during installation, the clear text encryption key value cannot be retrieved. If a reset of the Policy server encryption key is required, the "smreg" command-line tool can be used to overwrite the old key value. To ensure that sensitive information in the SiteMinder Policy store that is encrypted with the current encryption key is not lost when the Policy server encryption key is reset; the following steps must be carried out:

  1. Run the "smobjexport" command-line tool from the <SiteMinder install root>/Bin directory (as "smuser" on Unix platforms or as the system administrator on Windows platforms) to export the entire Policy Store in clear text as follows:
    smobjexport -o<output text-file name> -c -d<SiteMinder admin ID> -w<SiteMinder admin password> -v -t
    (Note the lack of spaces between parameters and values. Also note that the SiteMinder admin ID has the have the rights to manage the entire Policy store - for e.g., the default global admin ID, "SiteMinder".)

  2. Run the "smreg" command-line tool (as "smuser" on Unix platforms or as the system administrator on Windows platforms) to reset the Policy server encryption key:
    smreg -key <new encryption key value>
    (Note the space between the parameter and value. Also note that the "smreg" tool is not automatically installed into the <SiteMinder install root> directory because the tool is considered sensitive. The tool is located on the SiteMinder CD-ROM installation image under the "/Tools" directory. However, SiteMinder Policy server service-packs may contain updates to this tool. Therefore using the latest version of the tool supplied with the service pack is highly recommended.)

  3. Run the "smobjimport" command-line tool from the <SiteMinder install root>/Bin directory (as "smuser" on Unix platforms or as the system administrator on Windows platforms) to import the previously exported Policy Store in clear text as follows:
    smobjimport -i<input text-file name> -f -c -d<SiteMinder admin ID> -w<SiteMinder admin password> -v -t
    (Note the lack of spaces between parameters and values. Also note that the SiteMinder admin ID has the have the rights to manage the entire Policy store - for e.g., the default global admin ID, "SiteMinder".)

  4. Perform a manual agent key and session key rollover using the "Tools -- Manage Keys" menu option in the SiteMinder Policy Management User Interface. Note that if static session and agent keys were employed prior to the reset of the Policy server encryption key, then these should be manually redefined before performing the rollover.