search cancel

Sharedsecret and Encryption Keys Management in Policy Server

book

Article ID: 243878

calendar_today

Updated On:

Products

SITEMINDER CA Single Sign On Agents (SiteMinder) CA Single Sign On Secure Proxy Server (SiteMinder)

Issue/Introduction

 

When running several Policy Servers in a different environment and planning to move from multiple Policy and Key Store configurations to a single Policy and Key Store environment.    

How to renew the static key on each side to provide SSO?

  1. Are sharedsecret for a trustedhost the same as AgentKey?
  2. Where each key is stored? What is each of them used to?
  3. Is an additional registry setting needed when having 1 single Policy and Key Store?
  4. Is EnableKeyGeneration needed to be set on only 1 Policy Server, and set EnableKeyUpdate on the other Policy Server? (1)

Resolution

 

1. Sharedsecret

  • The sharedsecret is written in the SmHost.conf file, and in the Policy Store in an object called Trustedhost. The Trustedhost has a secret field to retain that value. This key is used to make a trusted connection with the Policy Server.
  • The 4 Agent Keys are stored in the Key Store. They are used on the Agent to encrypt and decrypt data like SMSESSION cookies and other cookies.
  • By default, the Key Store resides in the Policy Store. But it can be configured in a separate instance. In that case, a Key Store Key will be defined and as per the documentation, the key is written in the Policy Server registry (2).
  • The rollover is configurable by Web Agent separately and not at the global level. This is can be set at the registration time of the Agent.
  • The Web Agent that is not configured to rollover won't get its sharedsecret modified.
  • If for a given TrustedHost, the sharedsecret isn't configured for rollover, when Policy Server will roll over the sharedsecrets, this one won't be rolled and as such, it will continue to be able to use the same sharedsecret to establish communication with the Policy Server.
  • The "webagent instruct one of the Policy Server its connected to "flag" its sharedSecret as "rollover-compliant" in policyStore" happens at the registration phase and never at the run time (3).
  • So said, only the Web Agent which has been registered with the option to roll shared secret will have the shared secret rolled at the time it's defined in the AdminUI.

2. Keys and their storage overview
   


   Overview of keys use and storage (1)


   | Key                    | Use                                     | Location                        |
   |------------------------+-----------------------------------------+---------------------------------|
   | Agent Keys             | To encrypt SiteMinder cookies           | Policy Store and Agent memory   |
   |                        |                                         |                                 |
   | Session Ticket Key     | Session ticket key contain              | Policy Store only               |
   |                        | credentials and other information       |                                 |
   |                        | relating to a session                   |                                 |
   |                        |                                         |                                 |
   | Encryption Key         | To encrypt certain data in the Policy   | Policy Server file              |
   | (Policy Store Key)     | Store                                   | bin/EncryptionKey.txt           |
   |                        |                                         |                                 |
   | Key Store Key          | To encrypt Agent and Session ticket     | Policy Server registry          |
   |                        | keys                                    | KeyStoreEncryptionKey           |
   |                        |                                         | In single Key Store deployement |
   |                        |                                         | the value of the                |
   |                        |                                         | Encryption Key above is used.   |
   |                        |                                         |                                 |
   | Policy Server Host Key | To encrypt the Encryption Key above     | In the Policy Server hardcoded  |
   | Agent Host Key         | To encrypt shared secret                | In the Agent hardcoded          |
   |                        |                                         |                                 |
   | SharedSecret           | To trust a connection between the Agent | SmHost.conf on the Agent        |
   |                        | and Policy Server                       | TrustedHost.secret object in    |
   |                        |                                         | Policy Store                    |
  • When exporting the Key Store data, 5 keys are shown:

         objectclass: KeyManagement
         objectclass: AgentKey
         objectclass: AgentKey
         objectclass: AgentKey
         objectclass: AgentKey

  • The 4 AgentKey are the Agent Keys above. The KeyManagement is the Session Ticket Key. Agent Keys and the Session Ticket Key are stored in the Key Store. 

                                             

3. Policy Server registry

  • The registry setting should be set when there is more than 1 Policy Server. It will define only 1 Policy Server to generate the new keys. The other Policy Servers will with the other registry look for the key update. They won't update the key.
  • Policy Server configured for key generation is configured in the Policy Server registry by EnableKeyGeneration.
  • The Policy Server having this registry can be used by an AdminUI.

4. Policy Server Agent Keys generation

  • Only 1 Policy Server has to be enabled to generate the Agent Keys, and all other ones should be configured to check if the Agent Keys have been updated (4)(5).
  • If the environment is configured for permanent static keys for an agent, and, surely, they will never change, then there's no need to EnableKeyUpdate as the keys won't change. But if you plan to roll them on regular basis, you do need to enable to make the Policy Server get the new Keys.
  • A restart of the Policy Server will make it to get the new keys.

Additional Information

 

(1)

    Manage Encryption Keys
    

(2)

    Policy Server Encryption Keys

      A key store key is used to encrypt agent and session ticket keys in
      a separately configured key store. The key store key is kept in the
      registry (or UNIX equivalent) encrypted with the policy store key.

    

(3)

    sharedsecrettime parameter explanation in Web Agent SmHost.conf

      If the shared secret rollover is enabled when registering a trusted
      host, a rollover of the shared secrets for trusted hosts can be done
      either manually or periodically in the AdminUI.

    

(4)

    Enable key generation config in mixed environment Policy Server
    

(5)
    
    Agent Keys synchronization issue among distributed Policy Servers