Policy Server Guides › Policy Server Administration Guide › Configuring and Managing Encryption Keys › Key Management Overview

Key Management Overview

To keep key information updated across large deployments, the Policy Server provides an automated key rollover mechanism. You can update keys automatically for Policy Server installations that share the same key store. Automating key changes also ensures the integrity of the keys. For SiteMinder Agents that are configured for single sign-on, the key store must be replicated and shared across all SiteMinder environments in the single sign-on environment.

If the Policy Server determines that a key store that was configured separately from the policy store is unavailable, it attempts to reconnect to the key store to determine if it has come back online. If the connection fails, the Policy Server:

• Goes in to a suspended state and refuses any new requests on established connections until the key store comes back online.

  A Policy Server in a suspended state remains up for the length of time specified in SuspendTimeout, at which point the Policy Server shuts down gracefully. If SuspendTimeout is equal to zero, the Policy Server remains in the suspended state until the key store connection is reestablished.

• Returns an error status to let Web Agents failover to another Policy Server.
• Logs the appropriate error messages.

Additionally, when the Policy Server is started and the key store is unavailable, the Policy Server shuts down gracefully.

You manage keys using the SiteMinder Key Management dialog box in the FSS Administrative UI.

FIPS 140-2

The Federal Information Processing Standards (FIPS) 140-2 publication specifies the requirements for using cryptographic algorithms within a security system protecting sensitive, unclassified data. SiteMinder embeds RSA 's Crypto-C ME v2.0 cryptographic library, which has been validated as meeting the FIPS 140-2 Security Requirements for Cryptographic Modules. The validation certificate number for this module is 608.

SiteMinder's Java-based APIs use a FIPS-compliant version of the Crypto-J cryptographic library.

SiteMinder can operate in a pre-FIPS mode or in a FIPS-only mode. The cryptographic boundaries, that is, the way SiteMinder applies encryption, are the same in both modes, but the algorithms are different.

In FIPS-only mode, SiteMinder uses the following algorithms:

• AES Key Wrap for key encryption.
• AES in OFB mode (HMAC-SHA 256) for channel encryption.
• AES in CBC mode (HMAC-SHA 224) for encrypting tokens used to facilitate single sign-on.

The SiteMinder core components make extensive use of encrypted data:

• The Web Agent encrypts:
  • Cookies using an Agent Key retrieved from the Policy Server
  • Data sent to the Policy Server using a Session Key
  • A Shared Secret using the Host Key. The encrypted Shared Secret is stored in the Host Configuration file.
• The Policy Server encrypts:
  • Data sent to the Web Agent using a Session Key
  • The Policy Store Key using the Host Key
  • Sensitive data in the Policy Store using the Policy Store Key
  • Session Spec using the Session Ticket Key
  • Data sent to the Administrative UI using a Session Key
  • Password Services data in a user directory using the Session Ticket Key

The Policy Store Key is used to encrypt sensitive data stored in the Policy Store. It is derived from a seed string entered during the installation of the Policy Store. The Policy Store Key is also encrypted, using the Host Key, and stored in a system-local file. To support unattended operation, the Host Key is a fixed key embedded in the Policy Store code. Agents use this same Host Key mechanism to encrypt and store their copies of their Shared Secrets.

The Session Ticket Key (used by the Policy Server to form authentication tokens) and Agent Keys (primarily used by Web Agents to encrypt cookie data) are encryption keys stored in the Policy Store (or Key Store, depending on SiteMinder configuration settings) in encrypted form. They are encrypted using the Policy/Key Store Key. The Key Store Key is encrypted in the Policy Store. Agent Shared Secrets (used for Agent authentication and in the TLI Handshake), along with other sensitive data, are also encrypted with the Policy Store Key and stored in the Policy Store.

Agent Keys

SiteMinder Web Agents use an Agent key to encrypt cookies before passing the cookies to a user’s browser. When a Web Agent receives a SiteMinder cookie, the Agent key enables the Agent to decrypt the contents of the cookie. Keys must be set to the same value for all Web Agents communicating with a Policy Server.

The Policy Server provides the following types of Agent keys:

• Dynamic Keys are generated by a Policy Server algorithm and are distributed to connected Policy Servers and any associated SiteMinder Web Agents. Dynamic keys can be rolled over at a regular interval, or by using the Key Management dialog box of the Administrative UI. For security reasons, this is the recommended type of Agent key.
• Static Keys remain the same indefinitely, and can be generated by a Policy Server algorithm or entered manually. SiteMinder deployments uses this type of key for a subset of features that require information to be stored in cookies on a user’s machine over extended periods of time.

  Note: A static agent key is always generated at installation. This static key is used for certain other product features, such as user management, whether or not you use the static key as the Agent key.

More information:

Dynamic Agent Key Rollover

Dynamic Agent Key Rollover

Dynamic Agent key rollover is configured in the Key Management dialog of the FSS Administrative UI. Web Agents poll the Policy Server for key updates at a regular interval. If keys have been updated, Web Agents pick up the changes during polling. The default polling time is 30 seconds, but can be configured by changing the pspollinterval parameter of a Web Agent.

Note: For information about changing the parameters of a Web Agent, see the SiteMinder Web Agent Configuration Guide.

The Policy Server uses an algorithm to generate dynamic keys at a regular interval. These keys are saved in the key store. When a Web Agent detects new keys, it retrieves them from the key store.

Agent Keys Used in Dynamic Key Rollover

SiteMinder deployments use the following keys in a dynamic key rollover and maintain them in the key store:

• An Old Key is a Dynamic key that contains the last value used for the Agent key before the current value.
• A Current Key is a Dynamic key that contains the value of the current Agent key.
• A Future Key is a Dynamic key that contains the next value that will be used as the Current key in an Agent key rollover.
• Static Key

When the Policy Server processes a dynamic Agent key rollover, the value of the current key replaces the value of the old key. The value of the future key replaces the value of the current key, and the Policy Server generates a new value for the future key.

When receiving a cookie from a client browser, the Web Agent uses the current key from the key store to decrypt the cookie. If the decrypted value is not valid, the Web Agent tries the old key, and if necessary, the future key. The old key may be required to decrypt cookies from an Agent that has not yet been updated, or to decrypt existing cookies from a client’s browser. The future key may be required for cookies created by an updated Agent, but read by an Agent that has not yet polled the key store for updated keys.

Rollover Intervals for Agent Keys

At a specified time, the Agent key rollover process begins. To prevent multiple rollovers from multiple Policy Servers, each server sets a rollover wait time of up to 30 minutes. If no update has been performed by the end of the wait time, that Policy Server updates the keys.

All Policy Servers wait for updated keys and then process the new keys to their Agents. Even for a single Policy Server, the update time may be up to 30 minutes beyond the time specified for the rollover.

The Agent Key Rollover process begins at the time(s) specified in the SiteMinder Agent Key Management dialog box. The process can take up to three minutes. In that time period, all Web Agents connected to the Policy Server receive updated keys.

Note: In a deployment that involves multiple replicated Policy Servers, the process for distributing Agent keys may take up to 30 minutes.

Static Keys

A static key is a string used to encrypt data which remains constant. In a SiteMinder deployment that uses the Agent Key rollover feature, a static key provides a method for maintaining user information across an extended period of time.

The following SiteMinder features and situations make use of the static key:

• Saving User Credentials for HTML Forms Authentication

  If an HTML Forms authentication scheme has been configured to allow users to save credentials, the Policy Server uses the static key to encrypt the user’s credentials.

• User Tracking

  If user tracking is turned on, the Policy Server uses the static key to encrypt user identity information.

• Single Sign-on Across Multiple Key Stores

  In a SiteMinder deployment that includes multiple key stores, the static key may be used for single sign-on. In this situation, SiteMinder Agents use the static key for all cookie encryption.

  Note: If you change the static key, any cookies created with the former static key are invalid. Users may be forced to re-authenticate, and user tracking information becomes invalid. In addition, if the static key is used for single sign-on, users are challenged for credentials when they attempt to access resources in another cookie domain.

More information:

Multiple Policy Stores with Separate Key Stores

Session Ticket Keys

When a user successfully logs into a protected resource, the Policy Server creates a session ticket. The session ticket is what the Policy Server uses to determine how long a user’s authentication remains valid. This session ticket is encrypted using the session ticket key and cached in the Agent User Cache.

You can choose to have the Policy Server generate the session ticket key using an algorithm, or you can enter a session ticket key in the SiteMinder Key Management dialog box. For security reasons, the randomly generated key is recommended.

However, if your SiteMinder implementation includes multiple key stores in a single sign-on environment, you must use the same session ticket key for all key stores.

More information:

Cache Management Overview

Manage the Session Ticket Key

Key Management Scenarios

There are three types of scenarios for key management based on how you implement Policy Servers, policy stores and key stores, along with your single sign-on requirements. These scenarios include:

• Common Policy Store and Key Store

  In this scenario, a group of Policy Servers shares a single policy store and key store, providing access control and single sign-on in a single cookie domain.

  The policy store data is maintained in a single policy store. Key data is maintained in a single key store. The key store may be part of the policy store, or may be a separate store.

  Both policy store and key store data may be replicated for failover purposes. Replication must be configured based on the database or directory type selected for the policy store. For information about replication schemes, consult the documentation provided by your database or directory vendor.

• Multiple Policy Stores with a Common Key Store

  In this scenario, groups of Policy Servers connect to separate policy stores, but share a common key store, providing access control and single sign-on across multiple cookie domains.

  The policy store data for each group of Policy Servers is maintained in a single policy store. Key data for all groups of Policy Servers is maintained in a single key store. The separate key store allows Agents associated with all Policy Servers to share keys, enabling single sign-on across separate cookie domains.

  Both policy store and key store data may be replicated for failover purposes. Replication must be configured based on the database or directory type selected for the policy store. For information about replication schemes, consult the documentation provided by your database or directory vendor.

• Multiple Policy Stores and Multiple Key Stores

  In this scenario, each group of Policy Servers shares a single policy store and key store, providing access control and single sign-on across multiple cookie domains where it is desirable for the Policy Servers in each cookie domain to have a separate key store.

  The policy store data for each group of Policy Servers is maintained in a single policy store. Key data for each group of Policy Servers is maintained in a single key store. The key store may be part of the policy store, or may be a separate store. The same set of static keys allows for single sign-on across all Web Agents.

  Both policy store and key store data may be replicated for failover purposes. Replication must be configured based on the database or directory type selected for the policy store. For information about replication schemes, consult the documentation provided by your database or directory vendor.

More information:

Configure LDAP Failover

Configure ODBC Failover

Key Management Considerations

When deciding on the key management scenario for your enterprise, consider the following:

• When configuring dynamic keys in an environment with multiple Policy Servers that share a common key store, a single Policy Server must be nominated to perform Agent Key generation. You should disable key generation on all other Policy Servers.
• In a network configuration with multiple Policy Servers, the Policy Server Management Console enables you to specify a policy store for each Policy Server. Policy stores can be master policy stores that are the primary location for storing SiteMinder objects and policy information, or they can be replicated policy stores that use data copied from a master policy store.
• Master/slave directories or databases must be configured according to the specifications of the directory or database provider. The Policy Server provides the ability to specify a failover order for policy stores, but it does not control data replication. For information about replication schemes, see your directory or database provider’s documentation.
• In any network that uses dynamic key rollover, the key store for a Policy Server may be a master key store or a replicated slave key store. Master key stores receive keys directly from the Policy Server process that generates the keys. Slave key stores receive copies of the keys in the master key store.
• In a master/slave environment, you must configure key generation from Policy Servers that point to the master policy store and key store. The master policy store and key store data must then be replicated across all other policy stores and key stores included in your failover order.
• In any single sign-on environment for multiple cookie domains, dynamic keys can only be used if there is a single master key store, or slave key stores with keys replicated from a single master key store.
• Policy stores and keys stores can be installed on mixed LDAP and ODBC directories. The policy store can reside in an ODBC database and the key store can reside in an LDAP Directory Server or vice versa. For a list of supported databases, go to the Technical Support site and search for the SiteMinder r12.0 SP3 Platform Support Matrix.

More information:

Configure Agent Key Generation

Configure LDAP Failover

Configure ODBC Failover

Common Policy Store and Key Store

The simplest scenario for a SiteMinder configuration that uses key rollover is when multiple Policy Servers use a single policy store (and its associated failover policy stores), along with a single key store.

The following figure shows multiple Policy Servers using a single policy store.

In this type of configuration, Policy Servers retrieve dynamic keys from the key store. The Web Agents associated with the Policy Servers collect new keys from the Policy Servers.

More information:

Key Management Considerations

Multiple Policy Stores with a Common Key Store

If a network configuration consists of multiple Policy Servers with separate policy stores in a single sign-on environment, it is possible to have a common key store that all of the Policy Servers use for key rollover.

The following figure shows multiple Policy Servers using a common key store.

One Policy Server generates dynamic keys and stores them in the central key store. Each Policy Server is configured using the Policy Server Management Console to use the central key store; Agent key generation should be disabled for all other Policy Servers. Agents poll their respective Policy Servers to retrieve new keys. The Policy Servers retrieve new keys from the common key store and pass them to the SiteMinder Agents.

Note: This scenario requires an additional registry setting that forces Policy Servers that are not generating keys to poll the key store for key updates.

More information:

Key Management Considerations

Set the EnableKeyUpdate Registry Key

Multiple Policy Stores with Separate Key Stores

If a network configuration is composed of multiple Policy Servers, policy stores, and master key stores, an administrator with appropriate privileges can specify the same static key and session ticket key for each policy store in order to facilitate one or more of the following:

• Single sign-on across all Agents
• Password Services with a common user directory

The following figure shows an environment with multiple Policy Servers and stores.

In the previous example, the same static key is used to encrypt all cookies created by SiteMinder Web Agents.

More information:

Key Management Considerations

Reset the r6.x Policy Store Encryption Key

To reset the r6.x policy store encryption key

1. Log into a Policy Server host system.
2. Run the following command:

   smobjexport -dsiteminder_administrator -wpassword -ofile_name -c
   

   -dsiteminder_administrator

   Specifies the name of the SiteMinder administrator account.

   Note: This administrator must be able to manage all SiteMinder domain objects.

   -wpassword

   Specifies the password of the SiteMinder administrator account.

   -ofile_name

   Specifies the following:

   • The path to the output location
   • The name of smdif file the utility creates

   Note: If this argument is not specified, the default output file names are stdout.smdif and stdout.cfg.

   -c

   Exports sensitive data as clear–text.

   The utility exports the policy store data into the smdif file.

3. Be sure that the smreg utility is located in policy_server_home\bin.

   policy_server_home

   Specifies the Policy Server installation path.

   Note: If the utility is not present, you can find the utility in the Policy Server installation media, which is available on the Support site.

4. Run the following command:

   smreg -key encryption_key
   

   encryption_key

   Specifies the new encryption key.

   Limits: 6 to 24 characters.

   The policy store encryption key is changed.

5. Start the Policy Server Management Console and open the Data tab.
6. Re–enter the policy store administrator password and click Update.

   The administrator password is re–encrypted using the new encryption key.

7. Run the following command:

   smreg -su password
   

   password

   Specifies the SiteMinder super user password.

   The super user password is set and encrypted using the new encryption key.

8. Run the following command:

   smobjimport -dsiteminder_administrator -wpassword -ifile_name -r -f -c
   

   -dsiteminder_administrator

   Specifies the name of the SiteMinder administrator account.

   Note: This administrator must be able to manage all SiteMinder domain objects.

   -wpassword

   Specifies the password of the SiteMinder administrator account.

   -ifile_name

   Specifies the following:

   • The path to the smdif file
   • The name of the smdif file name

   Note: If this argument is not specified, the default input file names are stdout.smdif and stdout.cfg.

   -r

   Specifies that duplicate policy store information can be overwritten during the import.

   -f

   Turns off automatic renaming of objects. By default, when the utility attempts to import an object with a name that exists in the target policy store, the utility creates a duplicate object. The name of the object is nameoid.

   name

   Specifies the name of the object.

   oid

   Specifies the object ID of the new duplicate object.

   The utility returns errors messages for any objects that could not be created because of naming conflicts.

   -c

   Indicates that the input file contains sensitive data in clear–text.

9. Run the following command:

   smreg -su password
   

   password

   Specifies the SiteMinder super user password.

   The super user password is set.

   The policy store encryption key is reset.