Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Advanced Topics

Key Caching

search

Key Caching

This section describes how to use the key caching features.

Symmetric Key Caching

The key caching feature enables you to export symmetric keys from the server using NAE-XML, and stores them on the client for a limited time to perform cryptographic operations locally. Keys cached on the client are stored in process memory only; they are not stored on disk. This feature can improve performance, specifically if network latency is high, encryption sizes are small, and local CPU cycles are available. Once keys are cached, your client's cryptographic operations can continue without access to the server.

Only symmetric keys that have been marked Exportable can be cached. In addition, you must have export privileges for the key. Therefore, you must be the key owner or the key must be global. You automatically have full encryption and decryption privileges for all the keys in the client cache; while in the cache, key permissions and authorization policies are ignored.

Your client and its connection to the CipherTrust Manager must be secure. Downloading keys over this connection and storing them on your client exposes them to possible attack. When using the symmetric key caching feature, make sure that you are using a secure method of download and that your client's operating system is secure.

How it Works‌

The following steps describe what happens when the feature is enabled and the client requests a key:

  1. The client requests a key.

  2. The client checks whether Symmetric_Key_Cache_Enabled is yes (or tcp_ok). If the feature is enabled, the client searches for the key in the key cache.

  3. If the client does not find the key in the cache, the client requests the key from the server.

  4. If you have the permission and the key is exportable, the server downloads the key to the client. The key is stored in the cache.

  5. Subsequent requests for that key use the key cache until the time set in Symmetric_Key_Cache_Expiry has passed.

Related Parameters‌

To use the symmetric key cache, you need to set the following parameters in the properties file:

Possible SettingsDescription
Symmetric_Key_Cache_EnabledEnables symmetric key caching. This value must be set to yes or tcp_ok.
Tip: TCP is not a secure communication protocol.
Symmetric_Key_Cache_ExpiryThe time after which a key may be removed from the symmetric key cache. The cache is cleaned only when it is used; therefore, keys may stay in the cache longer than this value.

  • Selecting yes enables key caching over an SSL connection; therefore, you must also configure SSL.

  • Selecting tcp_ok enables key caching over both tcp and ssl connections.

Sample Use Case‌

Oracle Heartbeat is a mechanism to check connectivity between the client and the HSM. In case of network latency in the Heartbeat, database wallet may close. If symmetric cache is turned ON, it will help to reduce the latency by reading the key from cache.

When database is started for the first time, or restarted, a new symmetric cache is formed. HSM must be available at this moment to fetch the TDE master key, which is then stored in the symmetric cache.

Persistent Key Caching

The persistent key cache is a secure cache on the client's disk that is used to store the keys that have been downloaded from the CipherTrust Manager appliance. This cache is used when a key does not exist in the symmetric key cache and when the client can't connect to the server to access the key. The persistent key cache can only be accessed when the correct passphrase is used. The key cache is not transferable between users, client applications, or platforms.

The key cache does not store IVs. You must store those values elsewhere. Downloading keys from the CipherTrust Manager appliance poses a security threat. You must ensure that your network is secure before using this feature. Downloading keys from the CipherTrust Manager to your client exposes them to attack.

How it Works‌

When the key is not found in the symmetric/asymmetric key cache, the client uses the persistent cache to search for a key. If the key is not found in any cache, then the client connects to the CipherTrust Manager for the key.

The following scenarios explain the working of the persistent key cache:

  • When the requested key is present in the persistent key cache

    When the feature is enabled and the key is present in the persistent key cache:

    1. Your application requests a key. The client checks whether the symmetric/asymmetric key caching is enabled. The feature is enabled, so the client searches the symmetric/asymmetric key cache for the key. The key is not found.

    2. The client checks that the persistent key cache is enabled. The feature is enabled, so the client searches the persistent key cache for the key. The key is found. The application's request for the key is served.

  • When the requested key is not present in the persistent key cache

    When the feature is enabled, but the key is not present in the persistent key cache:

    1. Your application requests a key. The client checks whether the symmetric/asymmetric key caching is enabled. The feature is enabled, so the client searches the symmetric/asymmetric key cache for the key. The key is not found.

    2. The client checks that the persistent key cache is enabled. The feature is enabled, so the client searches the persistent key cache for the key. The key is not found.

    3. The client attempts to connect to the CipherTrust Manager but fails. The client does not attempt another connection until the duration specified by Connection_Retry_Interval has passed. The client sends an error message.

    4. If the client is able to connect to the CipherTrust Manager and the key is found, the server checks that the key is exportable and that the user has permission to export.

    5. The key is exported. The downloaded key is stored in the persistent key cache and the symmetric/asymmetric key cache.

    6. The application's request for the key is served. Subsequent requests for that key use the persistent key cache until the time set in Persistent_Key_Cache_Expiry has passed.

Related Parameters‌

To use the persistent key cache, set the following parameters in the properties file.

Possible SettingsDescription
Symmetric_Key_Cache_EnabledEnables symmetric key caching. This value must be set to yes or tcp_ok.
Symmetric_Key_Cache_ExpiryThe time after which a key may be removed from the symmetric key cache. The cache is cleaned only when it is used; therefore, keys may stay in the cache longer than this value. This value must be smaller than Persistent_Cache_Expiry_Keys. Otherwise, keys are removed from the persistent key cache before they expire from the symmetric key cache.
Persistent_Cache_EnabledEnables the persistent key cache. This value must be set to yes.
Persistent_Cache_DirectoryThe directory in which the persistent key cache is located. The actual cache file name uses the base name keycache, plus a suffix based on the NAE user name. For example, the cache for user1 is keycache_user1.
When the user name contains an upper case letter, those letters are preceded by #. The cache for UserAlpha, for example, is keycache_#user#alpha. The cache for global users is keycache_no#user.
This value must be set to an existing directory.
Persistent_ Cache_Expiry_ KeysThe time after which a key may be removed from the cache. Setting this to 0 disables the timeout; keys are not removed from the cache.
This value must be larger than Symmetric_Key_Cache_Expiry.
Persistent_Cache_Max_SizeLimits the number of keys in the persistent cache.

If you have an advanced notice that your server is going to be offline, then you can preload keys to ensure that your persistent key cache is populated when you need it.

Sample Use Case‌

While executing heavy queries, Oracle database runs parallel queries with which multiple processes are spawned.

In such a situation:

  • If HSM is not available while new process is spawned, the query will fail.

  • If HSM is not available and persistent cache is ON, it will help to keep the system up and running Oracle database and master key is fetched from the persistent cache.

Persistent cache is shared among multiple processes, provided the user is same.

Use of Persistent cache is recommended, when the network connectivity between client and HSM is erratic or unavailable. However, if it is the first time when cache is not present, HSM must be available to fetch the Oracle TDE master key, and add it to the cache.

Specifying Passphrase for Persistent Cache

To use persistent cache, persistent cache passphrase needs to be entered in credentials along with the CipherTrust Manager username and Password.

CONNECT <oracle_db_user>/<oracle_db_user_password>
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<cm_user:cm_user_password:persistent_cache_passphrase>";

Enable Persistent Key Caching for existing HSM/Software Wallet

To enable persistent key caching for existing HSM/Software wallet, perform the following:

  1. Update Properties file to enable both symmetric and persistent cache.

  2. Change tde config in the Properties file.

    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" scope=both;

  3. Delete or rename cwallet.sso file from soft wallet location.

  4. Restart database.

    Shutdown Immediate;
startup;

  5. Open the wallet manually.

    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<software_keystore_password>";

  6. Delete old secret from the wallet.

    ADMINISTER KEY MANAGEMENT DELETE SECRET FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "admin:Ssl12345#" WITH BACKUP;

  7. Add new secret that would include hsm username and password + persistent cache password.

    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_password:persistent_cache_passphrase>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" WITH BACKUP;

  8. Change software wallet password to add persistent cache password.

    ADMINISTER KEY MANAGEMENT ADD SECRET '<cm_user:cm_user_password:persistent_cache_passphrase>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "<software_keystore_password>" WITH BACKUP;

  9. Create new auto-login.

    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE IDENTIFIED BY "<software_keystore_password>";

  10. Restart database.

    Shutdown Immediate;
startup;

  11. SET TDE Configuration.

    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=both;

On this page