Manage Encryption Keys

Policy Server Encryption Keys
The Policy Server and Agents use encryption keys to encrypt and decrypt sensitive data passed between Policy Servers and Agents in a
  • Agent keys are used to encrypt
    cookies that may be read by all agents in a single sign-on environment, and are shared by all agents in a single sign-on environment, since each agent must be able to decrypt cookies encrypted by the other agents. Agent keys are managed by the Policy Server, and distributed to agents periodically.
  • Session ticket keys are used by the Policy Server to encrypt session tickets. Session tickets contain credentials and other information relating to a session (including user credentials). Agents embed session tickets in
    cookies, but cannot access the contents since they do not have access to session ticket keys which never leave the Policy Server.
Both types of keys are kept in the Policy Server key store. By default, the key store is part of the Policy Store, but a separate key store database can be created if desired.
Other, special keys are:
  • A policy store key is used to encrypt certain data in the policy store. The policy store key is stored, encrypted, in an on-disk file. The policy store key can include any characters below 128 in the ASCII table. The Policy Server encrypts the policy store key using a proprietary technique. The policy store key is derived from the encryption key specified when you installed the Policy Server.
  • 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.
Key Management
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 helps ensure the integrity of the keys.
agents that are configured for single sign–on:
  • Replicate the key store.
  • Share the replicated store across all
    environments in the single sign–on environment.
If the Policy Server determines that a stand–alone key store is unavailable, it attempts to reconnect to the key store to determine availability. 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. The Policy Server then 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.
Use the Administrative UI to manage keys.
FIPS 140-2 Algorithms
The Federal Information Processing Standards (FIPS) 140-2 publication specifies the requirements for using cryptographic algorithms within a security system protecting sensitive, unclassified data.
embeds OpenSSL FIPS Object Module cryptographic library that is validated as meeting the FIPS 140-2
Security Requirements for Cryptographic Modules
. The validation certificate number for this module is 1747.
Java-based APIs use a FIPS-compliant version of BouncyCastle FIPS Cryptography Libraries.
can operate in a pre-FIPS mode or in a FIPS-only mode. The cryptographic boundaries, that is, the way
applies encryption, are the same in both modes, but the algorithms are different.
In FIPS-only mode,
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.
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
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
Web Agents use an Agent key to encrypt cookies before passing the cookies to a user’s browser. When a Web Agent receives a
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
    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.
    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.
    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.
Dynamic Agent Key Rollover
You configure dynamic agent key rollover in the 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 you can change the default by changing the pspollinterval parameter of a web agent.
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
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
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.
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
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
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
    deployment that includes multiple key stores, the static key may be used for single sign-on. In this situation,
    Agents use the static key for all cookie encryption.
    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.
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
Key Management dialog box. For security reasons, the randomly generated key is recommended.
However, if your
implementation includes multiple key stores in a single sign-on environment, you must use the same session ticket key for all key stores.
Read the following sections for more information: