18 Managing Security Objects in Oracle Key Vault
Managing security objects includes uploading and downloading security objects, managing the persistent master encryption key cache, and using user-defined TDE keys.
- Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection
You can configure a connection between Oracle Key Vault and a database that has not yet been configured for Transparent Data Encryption. - Migrating Existing TDE Wallets to Oracle Key Vault
A migrated TDE wallet can be used to restore database contents that were previously encrypted by TDE. - Using the Persistent Master Encryption Key Cache
The persistent master encryption key cache feature enables databases to be operational when the Oracle Key Vault server is unavailable. - Uploading and Downloading Oracle Wallets
To store and share Oracle wallets, you must upload them to Oracle Key Vault. - Uploading and Downloading JKS and JCEKS Keystores
Theokvutil upload
andokvutil download
commands can upload and download JKS and JCEKS keystores. - Uploading and Downloading Credential Files
Theokvutil upload
andokvutil download
commands can upload and download credential files. - Using a User-Defined Key as the TDE Master Encryption Key
You can import a generated key to be used as the Transparent Data Encryption (TDE) master encryption key in Oracle Key Vault.
18.1 Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection
You can configure a connection between Oracle Key Vault and a database that has not yet been configured for Transparent Data Encryption.
- About Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection
You can configure a connection between Oracle Key Vault and a database that has not yet been configured for TDE. - Limitations to Transparent Data Encryption Endpoint Integration
This type of Transparent Data Encryption (TDE) endpoint integration can have problems if the versions are incompatible. - Step 1: Configure the Oracle Key Vault Server Environment
Before you can configure the connection, you must ensure that Oracle settings are correct. - Step 2: Integrate Transparent Data Encryption with Oracle Key Vault
This integration enables Oracle Key Vault to directly manage the TDE master encryption keys.
Parent topic: Managing Security Objects in Oracle Key Vault
18.1.1 About Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection
You can configure a connection between Oracle Key Vault and a database that has not yet been configured for TDE.
Before you start configuring the connection, ensure that the Oracle Key Vault installation environment is the same as the database runtime environment. The environment variables ORACLE_HOME
, ORACLE_BASE
, and ORACLE_SID
must be set to the same values in svrctl
and operating system environments. This also applies if you are using the Oracle Key Vault RESTful services utility to enroll endpoints.
18.1.2 Limitations to Transparent Data Encryption Endpoint Integration
This type of Transparent Data Encryption (TDE) endpoint integration can have problems if the versions are incompatible.
The limitations to TDE endpoint integration are as follows:
-
All endpoints on the same computer must use the same version of the Oracle Key Vault library. There is only one location per computer for the
liborapkcs.so
file, which is/opt/oracle/expapi/64/hsm/oracle/1.0.0/liborapkcs.so
. -
On the same computer, you should use the same external key manager for the Oracle database, either Oracle Key Vault or an HSM. Using Oracle Key Vault for one Oracle database and an HSM for another Oracle database can cause the wrong PKCS#11 library to be loaded, because Oracle Database picks up the first PKCS#11 library while traversing the subtree, which is
/opt/oracle/expapi/64/hsm/
.
Caution:
Oracle strongly recommends that you never remove keys from a wallet or the wallet itself after TDE is configured. Loss of keys will result in the loss of encrypted data and hamper the normal functioning of the database. This is true even in the folowing scenarios:-
If there is no encrypted data in the system
-
If all of the encrypted data has been decrypted
-
If you have migrated your keys and wallets to a hardware security module
18.1.3 Step 1: Configure the Oracle Key Vault Server Environment
Before you can configure the connection, you must ensure that Oracle settings are correct.
COMPATIBILITY
parameter.
sqlnet.ora
file correctly along with the rest of the TDE configuration, then a TDE master encryption key is created in Oracle Key Vault when you set the encryption key by using one of the following SQL statements:
ALTER SYSTEM SET [ENCRYPTION] KEY IDENTIFIED BY "password";
ADMINISTER KEY MANAGEMENT SET [ENCRYPTION] KEY IDENTIFIED BY "password";
With both of these SQL statements, the password was defined when the Oracle Key Vault client software was installed. If no password was defined at that time, then the password for these two statements is NULL
.
18.2 Migrating Existing TDE Wallets to Oracle Key Vault
A migrated TDE wallet can be used to restore database contents that were previously encrypted by TDE.
- About Migrating Existing TDE Wallets to Oracle Key Vault
Thesqlnet.ora
file enables the migration of existing TDE wallets to Oracle Key Vault. - Migrating an Existing TDE Wallet to Oracle Key Vault
You can use theokvutil upload
command to migrate an existing TDE wallet to Oracle Key Vault. - Restoring Database Contents Previously Encrypted by TDE Using an Oracle Wallet
You perform the restoration process on the endpoint where you downloaded the Oracle wallet.
Parent topic: Managing Security Objects in Oracle Key Vault
18.2.1 About Migrating Existing TDE Wallets to Oracle Key Vault
The sqlnet.ora
file enables the migration of existing TDE wallets to Oracle Key Vault.
When the Transparent Data Encryption (TDE) wallets already exist, you must modify the sqlnet.ora
file to recognize Oracle Key Vault before you can migrate the existing TDE wallets to Oracle Key Vault.
Along with the current TDE master encryption key, Oracle wallets maintain historical TDE master encryption keys that are replaced by each rekey operation that rotates the TDE master encryption key. These historical TDE master encryption keys help to restore Oracle Database backups that were previously made using one of the historical TDE master encryption keys. During the TDE migration from an Oracle wallet file to Oracle Key Vault, Key Vault generates new master encryption keys. After this master encryption key generation, Oracle Key Vault maintains all new keys.
Oracle recommends that you upload the Oracle wallet to Oracle Key Vault before you perform the migration. This enables you to keep a backup of the wallet with all of the historical key information, before you begin the migration. When the migration is complete, manually delete the old wallet on the client system.
If you are operating in a shared server or an Oracle Real Application Clusters (Oracle RAC) configuration, then you must restart the database so that the new TDE master encryption key is updated to all the endpoint database nodes in the shared server configuration.
18.2.2 Migrating an Existing TDE Wallet to Oracle Key Vault
You can use the okvutil upload
command to migrate an existing TDE wallet to Oracle Key Vault.
-
Back up the database that contains the data that you want to migrate.
-
Complete the enrollment of the endpoint.
-
If you have not done so already, then use the
okvutil upload
command to upload the existing Oracle wallet to Oracle Key Vault.This step ensures that Oracle Key Vault has a copy of the wallet that contains all of the historical TDE master encryption keys.
-
Configure the Oracle Database
sqlnet.ora
file for the HSM as follows:ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=wallet_location)))
By default, the
sqlnet.ora
file is located in theORACLE_HOME
/network/admin
directory or in the location set by theTNS_ADMIN
environment variable. -
Reconnect to the database if you are in SQL*Plus.
The changes do not appear until you restart the database session.
-
Query the
V$ENCRYPTION_WALLET
dynamic view to ensure that theMETHOD_DATA
setting in thesqlnet.ora file
changed.SELECT * FROM V$ENCRYPTION_WALLET;
The output of the query should now show
METHOD=HSM
. -
If the endpoint is a an Oracle Release 11g release 2 database, then close the local Oracle wallet and open the HSM wallet as follows:
-
Close the local Oracle wallet using these steps:
-
If the auto-login wallet is open, execute the following commands:
oracle$ cd wallet_location oracle$ mv cwallet.sso cwallet.sso.bak sqlplus sys as sysdba Enter password: password SQL> ALTER SYSTEM SET WALLET CLOSE;
-
If the password-protected wallet is open, then execute the following statement in SQL*Plus:
ALTER SYSTEM SET WALLET CLOSE IDENTIFIED BY "wallet_password";
-
-
In SQL*Plus, open the HSM wallet, where
HSM_connect_string
is the password provided when theokvclient.jar
file was deployed:ALTER SYSTEM SET WALLET OPEN IDENTIFIED BY "HSM_connect_string";
-
-
Migrate from TDE wallets to Oracle Key Vault.
-
For Oracle Database 11g release 2:
If you entered a password for the wallet while installing the endpoint client software, then in SQL*Plus, execute this statement:
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "endpoint_password" MIGRATE USING "wallet_password";
If you chose the auto-login option while installing the endpoint client software, then execute this statement:
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "NULL" MIGRATE USING "wallet_password";
-
For Oracle Database 12c or later, as a user who has been granted the
SYSKM
administrative privilege:ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "endpoint_password" MIGRATE USING "<wallet password>" with backup;
Though the
WITH BACKUP
clause is required for theADMINISTER KEY MANAGEMENT
statement, it is ignored by TDE in Oracle Key Vault.
-
-
Open the wallet.
If the endpoint requires a password to connect to Oracle Key Vault, then enter the password.
-
For Oracle Database 11g release 2:
ALTER SYSTEM SET ENCRYPTION WALLET OPEN IDENTIFIED BY "Key_Vault_endpoint_password";
-
For Oracle Database 12c or later:
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Key_Vault_endpoint_password";
-
-
After you complete the migration, if you are using an auto-login wallet, then re-enable it by renaming the
cwallet.sso.bak
file tocwallet.sso
.
18.2.3 Restoring Database Contents Previously Encrypted by TDE Using an Oracle Wallet
You perform the restoration process on the endpoint where you downloaded the Oracle wallet.
Finance_DB
database had recently migrated to use an online master key to Oracle Key Vault after you have uploaded the premigration wallet. If a system failure forces you to restore from a database backup taken before the migration to Oracle Key Vault, then you can still restore the contents of the database by using an Oracle wallet downloaded from the Oracle virtual wallet that contains the Finance_DB
wallet data that you had uploaded earlier.
Related Topics
Parent topic: Migrating Existing TDE Wallets to Oracle Key Vault
18.3 Using the Persistent Master Encryption Key Cache
The persistent master encryption key cache feature enables databases to be operational when the Oracle Key Vault server is unavailable.
- About the Persistent Master Encrption Key Cache
The persistent master encryption key cache ensures the availability of TDE master encryption keys. - About Oracle Key Vault Persistent Master Encyrption Key Cache Architecture
The Oracle Key Vault persistent master encryption key cache is implemented in Oracle Key Vault’sPKCS#11
library. - Caching Master Encryption Keys in the In-Memory and Persistent Master Encryption Key Cache
After a master encryption key is created or fetched from a different location, it is stored in an Oracle Key Vault cache. - Storage Location of Persistent Master Encryption Key Cache
The persistent master encryption key cache is created in the same location as the configuration fileokvclient.ora
. - Persistent Master Encryption Key Cache Modes of Operation
The persistent master encryption key cache operates in two modes. - Persistent Master Encryption Key Cache Refresh Window
The persistent master encryption key cache refresh window helps to extend the availability of the master encryption key. - Persistent Master Encryption Key Cache Parameters
Oracle Key Vault provides parameters to configure the persistent master encryption key cache. - Listing the Contents of the Persistent Master Encryption Key Cache
Theokvutil list
command lists the master encryption keys that are cached in the persistent master encryption key cache. - Oracle Database Deployments and Persistent Master Encryption Key Cache
The persistent master encryption key cache affects the integration of other Oracle features with Oracle Key Vault.
Parent topic: Managing Security Objects in Oracle Key Vault
18.3.1 About the Persistent Master Encrption Key Cache
The persistent master encryption key cache ensures the availability of TDE master encryption keys.
It accomplishes this by reducing dependence on the state of the Oracle Key Vault server.
The TDE master encryption key is cached in the persistent master encryption key cache in addition to the in-memory cache, to make the master encryption key available across database processes. It eliminates the need for databases to contact the Oracle Key Vault server for every new process, redo log switch, or database startup operation.
The following are the benefits of ensuring availability of TDE master encryption keys:
-
Continuous operation of endpoints during upgrade, primary-standby configuration, switchover, failover, and other procedures that require an Oracle Key Vault restart operation
-
Less load on the Oracle Key Vault server when multiple sessions of a single database request the same master encryption key
-
Improved scalability of Oracle Key Vault
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.2 About Oracle Key Vault Persistent Master Encyrption Key Cache Architecture
The Oracle Key Vault persistent master encryption key cache is implemented in Oracle Key Vault’s PKCS#11
library.
When the persistent master encryption key cache feature is configured, the Oracle Key Vault PKCS#11
library will create the persistent master encryption key cache when the first master encryption key is retrieved from Oracle Key Vault.
-
If Oracle Key Vault is installed with a password specified, then the persistent master encryption key cache is a password-based wallet.
-
If Oracle Key Vault is installed without a password specified, then the persistent master encryption key cache is an auto-login wallet.
The PKCS#11
library also implements an in-memory master encryption key cache. When the in-memory master encryption key cache feature is configured, the master encryption key is cached in the process memory of the process that loaded the library into memory. The in-memory and persistent master encryption key caches are independent of each other. You can enable and disable these caches independently.
For operations that involve encryption and decryption, PKCS#11
attempts to look up the master encryption key in the in-memory master encryption key cache. If it does not find it, PKCS#11
then it looks up the master encryption key in the persistent master encryption key cache. If the master encryption key is not found in the in-memory or the persistent master encryption key cache, then it is retrieved from the Oracle Key Vault server, if the server is online.
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.3 Caching Master Encryption Keys in the In-Memory and Persistent Master Encryption Key Cache
After a master encryption key is created or fetched from a different location, it is stored in an Oracle Key Vault cache.
When the master encryption key is first fetched from the Oracle Key Vault server, or created in the Oracle Key Vault server, the master encryption key is stored in the in-memory master encryption key cache and in the persistent master encryption key cache.
Master encryption keys stored in the in-memory master encryption key cache are available for a limited time from the moment the key is placed into the persistent cache. The duration is defined by the PKCS11_CACHE_TIMEOUT
parameter in the okvclient.ora
file.
If the persistent cache exists, then it will be used. If the persistent cache does not exist, then Oracle Key Vault creates it. When the key is created, all future sessions will retrieve it from the in-memory master encryption key cache or persistent master encryption key cache.
Persistent master encryption keys that are stored in the persistent master encryption key cache are available for a limited time from the moment the key is placed into the persistent cache. You can define this time by setting the PKCS11_PERSISTENT_CACHE_TIMEOUT
parameter in the okvclient.ora
file.
When the endpoint deletes the master encryption key, the key will be removed from the in-memory master encryption key cache and persistent master encryption key cache.
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.4 Storage Location of Persistent Master Encryption Key Cache
The persistent master encryption key cache is created in the same location as the configuration file okvclient.ora
.
The default location for the okvclient.ora
file is the directory $OKV_HOME/conf
.
It is important that the ORACLE_HOME
, ORACLE_BASE
, and OKV_HOME
environment variables are consistently set across the deployment. If they are not consistent, then operations requiring the persistent cache may fail, and the persistent cache may be created in multiple locations.
If the environment variable OKV_HOME
is set, then the persistent cache is created in $OKV_HOME/conf
.
If OKV_HOME
is not set, but ORACLE_BASE
is set, then the persistent cache is created in $ORACLE_BASE/okv/$ORACLE_SID
.
If neither OKV_HOME
nor ORACLE_BASE
is set, but ORACLE_HOME
is set, then the persistent cache is created in $ORACLE_HOME/okv/$ORACLE_SID
.
Note:
Ensure that the directory in which the persistent cache is created is secure and has restricted permissions.Parent topic: Using the Persistent Master Encryption Key Cache
18.3.5 Persistent Master Encryption Key Cache Modes of Operation
The persistent master encryption key cache operates in two modes.
The difference between the two modes is the order in which the persistent master encryption key cache and Oracle Key Vault are looked up to retrieve the master encryption key.
- Oracle Key Vault First Mode
In Oracle Key Vault first mode, the endpoints attempt to retrieve the master encryption key from the Oracle Key Vault server. - Persistent Master Encryption Key Cache First Mode
In persistent master encryption key cache first mode, the endpoints retrieve the master encryption key from the persistent master encryption key cache.
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.5.1 Oracle Key Vault First Mode
In Oracle Key Vault first mode, the endpoints attempt to retrieve the master encryption key from the Oracle Key Vault server.
If the Oracle Key Vault server is offline, then the endpoints attempt to retrieve the master encryption key from the persistent master encryption key cache.
The endpoints must determine the status of the Oracle Key Vault server, and if it is offline, then the endpoints attempt to retrieve the master encryption key from the persistent master encryption key cache. Hence, database operations that require access to master encryption keys will experience a delay.
18.3.5.2 Persistent Master Encryption Key Cache First Mode
In persistent master encryption key cache first mode, the endpoints retrieve the master encryption key from the persistent master encryption key cache.
If the master encryption key is not available in the persistent master encryption key cache, then the endpoints attempt to retrieve the master encryption key from the Oracle Key Vault server.
The modifications to the master encryption keys on the Oracle Key Vault server are not applied until the key expires in the persistent master encryption key cache.
18.3.6 Persistent Master Encryption Key Cache Refresh Window
The persistent master encryption key cache refresh window helps to extend the availability of the master encryption key.
The refresh window feature of the persistent master encryption key cache enables the database endpoint to make multiple attempts to refresh the expired master encryption key from the Oracle Key Vault server. In that sense, the endpoint waits for the Oracle Key Vault server to be back online for the master encryption key refresh to complete. Meanwhile, if the master encryption key refresh attempt fails, then the keys are retrieved from the persistent cache for the duration of the refresh window.
The refresh window feature of the persistent master encryption key cache therefore extends the duration for which the master encryption key is available after it is cached in the persistent master encryption key cache. At the same time, the endpoints can refresh the key during the refresh window instead of once at the end of the cache time. This addresses the possibility that persistent cache expires during the time when the Oracle Key Vault is unavailable, such as when a primary-standby switchover is in progress. The refresh window terminates and then the cache period begins as soon as the key is refreshed.
In the okvclient.ora
file, you can use the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter to extend the duration for which the master encryption key is available after it is cached in the persistent master encryption key cache. This value reflects the amount of time it takes for the Oracle Key Vault server to recover and return online. You must specify this value in minutes. The default value for PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
is 30
(minutes).
Related Topics
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.7 Persistent Master Encryption Key Cache Parameters
Oracle Key Vault provides parameters to configure the persistent master encryption key cache.
- PKCS11_CACHE_TIMEOUT Parameter
ThePKCS11_CACHE_TIMEOUT
parameter sets how long a master encryption key is available in the in-memory cache. - PKCS11_PERSISTENT_CACHE_TIMEOUT Parameter
ThePKCS11_PERSISTENT_CACHE_TIMEOUT
parameter sets how long the master encryption is available in the persistent cache. - PKCS11_PERSISTENT_CACHE_FIRST Parameter
ThePKCS11_PERSISTENT_CACHE_FIRST
parameter sets the persistent master encryption key cache operation mode. - PKCS11_CONFIG_PARAM_REFRESH_INTERVAL Parameter
ThePKCS11_CONFIG_PARAM_REFRESH_INTERVAL
parameter describes the frequency at which a long-running process will re-read theokvclient.ora
configuration file. - PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW Parameter
ThePKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter extends time the master encryption key is available after it is cached in the persistent master encryption key cache. - EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN Parameter
TheEXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
parameter ensures that the PKCS#11 persistent cache for a given endpoint database automatically expires upon shutdown of the endpoint database.
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.7.1 PKCS11_CACHE_TIMEOUT Parameter
The PKCS11_CACHE_TIMEOUT
parameter sets how long a master encryption key is available in the in-memory cache.
You set the PKCS11_CACHE_TIMEOUT
parameter in the okvclient.ora
file. You must specify the value minutes. When the specified duration of time elapses, the master encryption key expires. Expired master encryption keys are not deleted from the in-memory cache.
The default value for PKCS11_CACHE_TIMEOUT
is 60
(minutes). Oracle recommends that you set the PKCS11_CACHE_TIMEOUT
parameter in the Oracle Key Vault management console, where it is called PKCS11 In-Memory Cache Timeout
.
Related Topics
Parent topic: Persistent Master Encryption Key Cache Parameters
18.3.7.2 PKCS11_PERSISTENT_CACHE_TIMEOUT Parameter
The PKCS11_PERSISTENT_CACHE_TIMEOUT
parameter sets how long the master encryption is available in the persistent cache.
You set the PKCS11_PERSISTENT_CACHE_TIMEOUT
parameter in the okvclient.ora
file. This time starts when the database retrieves the key from the Oracle Key Vault server and puts it in the cache. After this duration has elapsed, the master encryption key expires. At this time, the endpoint will attempt to contact the Oracle Key Vault server in order to retrieve the key, and if it succeeds, the key remains available for another duration specified by this parameter. If it is unable to retrieve the key, the key remains available for the amount of time dictated by the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter, after which the database can no longer use the key without successfully retrieving it again from the Oracle Key Vault server. Expired master encryption keys are not deleted from persistent master encryption key cache.
The Cache Start Time
and Maximum Use Time
values displayed in the OKV Persistent Cache entries
list is updated when the master encryption key is refreshed.
The default value for PKCS11_PERSISTENT_CACHE_TIMEOUT
is 1440
(minutes).
You can disable the persistent master encryption key cache by setting both the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
and the PKCS11_PERSISTENT_CACHE_TIMEOUT
parameters to 0
(zero).
Oracle recommends that you set this global parameter in the Oracle Key Vault management console.
Note:
The parameterPKCS11_PERSISTENT_CACHE_TIMEOUT
and its default value are included by default in the okvclient.ora
file.
Related Topics
Parent topic: Persistent Master Encryption Key Cache Parameters
18.3.7.3 PKCS11_PERSISTENT_CACHE_FIRST Parameter
The PKCS11_PERSISTENT_CACHE_FIRST
parameter sets the persistent master encryption key cache operation mode.
You set the PKCS11_PERSISTENT_CACHE_FIRST
parameter in the okvclient.ora
file.
The following are the modes of operation:
-
Oracle Key Vault First Mode: To enable Oracle Key Vault first mode, set the value of the
PKCS11_PERSISTENT_CACHE_FIRST
parameter to0
(zero). -
Persistent Master Encryption Key Cache First Mode: Persistent master encryption key cache first mode is the default mode.
To enable persistent master encryption key cache first mode, set the value of the
PKCS11_PERSISTENT_CACHE_FIRST
parameter to1
.
18.3.7.4 PKCS11_CONFIG_PARAM_REFRESH_INTERVAL Parameter
The PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
parameter describes the frequency at which a long-running process will re-read the okvclient.ora
configuration file.
When the process cannot use a key from the in-memory cache and instead reaches out to the persistent cache or the Oracle Key Vault server, if it has been longer than the value specified by PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
since okvclient.ora
was last read, the process will re-read okvclient.ora
and start using any changed parameters. Note that if the parameter for the in-memory cache, PKCS11_CACHE_TIMEOUT
, is larger than PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
, then okvclient.ora
will be re-read at intervals described by the PKCS11_CACHE_TIMEOUT
parameter instead.
You set the PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
parameter in okvclient.ora
. You must specify this value in minutes. The default value for PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
is 10
(minutes).
You can disable this parameter by setting the PKCS11_CONFIG_PARAM_REFRESH_INTERVAL
parameter to 0
(zero).
Parent topic: Persistent Master Encryption Key Cache Parameters
18.3.7.5 PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW Parameter
The PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter extends time the master encryption key is available after it is cached in the persistent master encryption key cache.
You set the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter in the okvclient.ora
. You must specify the value in minutes. The default value for PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
is 30
(minutes).
You can disable the persistent master encryption key cache by setting the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
and PKCS11_PERSISTENT_CACHE_TIMEOUT
parameters to 0
(zero). Oracle recommends that you set these global parameters in the Oracle Key Vault management console.
Related Topics
Parent topic: Persistent Master Encryption Key Cache Parameters
18.3.7.6 EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN Parameter
The EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
parameter ensures that the PKCS#11 persistent cache for a given endpoint database automatically expires upon shutdown of the endpoint database.
When enabled, the EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
protects the persistent cache by using a system-generated random password that is independent of the password that was set when an endpoint database was enrolled in Oracle Key Vault, even if an auto-login wallet was used. Having the persistent cache password protected provides better security.
Before you can use the EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
parameter, ensure that the endpoint database has had the patch for bug 29869906: AUTO-LOGIN OKV NEEDS PERSISTENT CACHE PROTECTION KEY FROM RDBMS
applied to it. This patch applies to Oracle Database releases 12.1 through 19c. Contact Oracle Support for more information.
You can set EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
for individual endpoint databases that have been enrolled with Oracle Key Vault, or globally for all endpoint databases that have been enrolled in Oracle Key Vault. This parameter is not available in the okvclient.ora
configuration file for the database endpoint. To set this parameter, use the Oracle Key Vault management console.
After you have enabled EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
, the PKCS#11 persistent cache is created when keys are fetched from Oracle Key Vault. The cache remains available to the endpoint database only as long as the database instance is mounted or open. When the endpoint database is shut down, the PKCS#11 persistent cache is no longer available, but is recreated the next time the endpoint database is started. The persistent cache does, however, remain available when an endpoint pluggable database (PDB) is closed and then re-opened.
Be aware that after you have enabled EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
for a given endpoint database, you can no longer use the okvutil list -t okv_persistent_cache
command to view the contents of the persistent cache. In addition, you must ensure that Oracle Key Vault is available when keys are fetched after the endpoint database is started.
Setting EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN for Individual Endpoint Databases
- Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
- Click the Endpoints tab.
- On the Endpoints page, select the endpoint for which you want to set
EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
. - On the Endpoint Details page, scroll to the bottom and then set the Expire PKCS11 Persistent Cache on Database Shutdown checkbox.
- Click Save.
Setting EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN Globally
The following procedure will apply the EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN
to all current and future endpoint databases that have been enrolled with Oracle Key Vault.
- Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
- Select the Endpoints tab, and then Settings from the left side bar..
- In the Global Endpoint Configuration Parameters page, set the Expire PKCS11 Persistent Cache on Database Shutdown checkbox.
- Click Save.
Related Topics
Parent topic: Persistent Master Encryption Key Cache Parameters
18.3.8 Listing the Contents of the Persistent Master Encryption Key Cache
The okvutil list
command lists the master encryption keys that are cached in the persistent master encryption key cache.
After installing the endpoint software, endpoint administrators can use the command-line utility okvutil
to communicate with Oracle Key Vault to view, upload, and download security objects.
The following example shows how to list the master encryption keys cached in the persistent master encryption key cache:
$ ./okvutil list -t okv_persistent_cache -l $ORACLE_HOME/okv/$ORACLE_SID
Enter Oracle Key Vault endpoint password: password
Output similar to the following appears:
OKV Persistent Cache entries: Current Persistent Cache Timeout is 600 seconds Version Unique ID TDE Master Key Identifier Cache Start Time Maximum Use Time Maximum Refresh Window Status 02 55D745B1-2F30-667F-E053-0100007FAFDB 0636846AAF88F74FC6BF1DB68538797B69 22:38:12 2019-08-03 600 seconds 0 seconds Expired 02 55D745B1-2F2E-667F-E053-0100007FAFDB 063AC48E9433734F7EBF97180276E719C4 22:37:10 2019-08-03 600 seconds 180 seconds Available 02 55D745B1-2F2D-667F-E053-0100007FAFDB 0604425983989C4F6ABF7BD9E1D55459C4 22:37:00 2019-08-03 600 seconds 180 seconds Available 02 55D70FA4-81D1-5C8A-E053-0100007F8217 06172EACB79F4C4F32BFB7D50B0ACA7101 03:44:22 2019-08-03 300 seconds 0 seconds Expired 02 55D745B1-2F2B-667F-E053-0100007FAFDB 06983C4664FFC04F6ABF72F961A15AD943 22:36:49 2019-08-03 600 seconds 300 seconds Available 02 55D745B1-2F29-667F-E053-0100007FAFDB 0639E05D58B27B4FFDBFAEC5EAA08DB301 03:26:40 2019-08-03 300 seconds 0 seconds Expired 02 55D745B1-2F28-667F-E053-0100007FAFDB 06A29F4039E1B74FDCBFA687E0608EEEBA 03:19:17 2019-08-03 300 seconds 0 seconds Expired 02 55D745B1-2F27-667F-E053-0100007FAFDB 0678287C2877B74FF3BF0BA33A17A59F94 03:19:21 2019-08-03 300 seconds 0 seconds Expired
The following table describes the columns in the OKV Persistent Cache entries
list:
Column Name | Description |
---|---|
|
Persistent master encryption key cache version |
|
KMIP identifier assigned to the master encryption key |
|
Database ID assigned to the master encryption key |
|
Time at which the master encryption key was cached |
|
Time until the master encryption key expires, in seconds, from the moment that the key was placed into the persistent master encryption key cache |
|
Extended duration for which the master encryption key is available after it is cached in the persistent master encryption key cache |
|
Indicates whether the master encryption key is available, refreshing or expired |
Parent topic: Using the Persistent Master Encryption Key Cache
18.3.9 Oracle Database Deployments and Persistent Master Encryption Key Cache
The persistent master encryption key cache affects the integration of other Oracle features with Oracle Key Vault.
-
Database restart when the Oracle Key Vault Server is offline: When you configure Oracle Key Vault to use an auto-login wallet, the database connects to the Oracle Key Vault server when the database is restarted. If the Oracle Key Vault server is offline when the database restarts, then the database retrieves master encryption keys from the persistent master encryption key cache. Database operations resume normally if the master encryption keys are active and have not expired.
Ensure that the passwords of the persistent master encryption key cache and the Oracle Key Vault endpoint wallet are synchronized.
Note:
The persistent master encryption key cache must be deleted when the endpoint wallet credentials are modified. -
Using the persistent master encryption key cache in an Oracle Real Application Cluster (Oracle RAC) environment: In an Oracle RAC environment, each Oracle RAC node is an unique database endpoint, and uses a unique persistent master encryption key cache.
In an Oracle RAC Environment, you must query the database from each Oracle RAC node to cache the most recent version of the master encryption key in the persistent master encryption key cache of each Oracle RAC node.
-
Using persistent master encryption key cache in an Oracle Data Guard Environment: Rotation of the master encryption key in the primary server’s database caches the master encryption key in the persistent master encryption key cache of the primary server’s database.
The standby server retrieves and caches the new master encryption key in the persistent master encryption key cache of the standby server’s database after the new
REDO
logs from the primary server are applied on the standby server. To avoid disruptions, you should synchronize the primary and standby servers immediately after the rotation of the master encryption key in the primary server’s database.
Parent topic: Using the Persistent Master Encryption Key Cache
18.4 Uploading and Downloading Oracle Wallets
To store and share Oracle wallets, you must upload them to Oracle Key Vault.
- About Uploading and Downloading Oracle Wallets
You use theokvutil
utility to upload and download Oracle wallets. - Uploading Oracle Wallets
Theokvutil upload
command uploads wallets to Oracle Key Vault. - Downloading Oracle Wallets
Theokvutil download
command downloads an Oracle wallet from the Oracle Key Vault server to an endpoint. - Guidelines for Uploading and Downloading Oracle Wallets
Oracle provides guidelines for uploading and downloading wallets to and from Oracle Key Vault.
Parent topic: Managing Security Objects in Oracle Key Vault
18.4.1 About Uploading and Downloading Oracle Wallets
You use the okvutil
utility to upload and download Oracle wallets.
After you upload a wallet to Oracle Key Vault, you can then create a new virtual wallet in Key Vault, and add security objects to it that you want to share. You must grant endpoints access to the virtual wallet before they can download it. You can use the okvutil upload
and okvutil download
commands to upload and download Oracle wallets between Oracle Key Vault and its endpoints. The okvutil
utility is packaged with the endpoint software that you install at the endpoint.
The Oracle Key Vault okvutil
software can read an Oracle wallet at the granularity level of an individual security object. It therefore uploads the wallet contents as individual items. During download you can recreate the original wallet with the same set of security objects, or create a new wallet with different set of security objects.
You can upload and download both password-based wallets and auto-login wallets. The wallet contents can be downloaded later into a new wallet of either type. For example, an uploaded password-protected wallet can be downloaded as an auto-login wallet, or an uploaded auto-login wallet can be downloaded as a password-protected wallet.
You can use Oracle Key Vault to construct a new virtual wallet containing security objects from previously uploaded Oracle wallets. For example, given a previously uploaded Oracle wallet containing five symmetric keys and three opaque objects, you can create a new virtual wallet consisting of only three of the original five symmetric keys and one of the three original opaque objects. This virtual wallet can be downloaded like the original wallet to provide the endpoint with access to only a subset of the keys. This process does not modify the original wallet.
Related Topics
Parent topic: Uploading and Downloading Oracle Wallets
18.4.2 Uploading Oracle Wallets
The okvutil upload
command uploads wallets to Oracle Key Vault.
At this point, the upload is complete. You can now share the virtual wallet with other users and endpoints.
18.4.3 Downloading Oracle Wallets
The okvutil download
command downloads an Oracle wallet from the Oracle Key Vault server to an endpoint.
18.4.4 Guidelines for Uploading and Downloading Oracle Wallets
Oracle provides guidelines for uploading and downloading wallets to and from Oracle Key Vault.
-
If there is a change to the content of the original wallet, such as a key rotation or a rekey operation, then upload the wallet again to Oracle Key Vault so that Key Vault has the latest copy of the wallet.
-
Use care if you plan to use the
okvutil upload
andokvutil download
commands, which provide an overwrite (-o
) option. This option overwrites data in the virtual wallet that conflicts with the data to be uploaded. Before you use the-o
option, you should create a local backup of the wallet file. -
Do not try to upload the same physical Oracle wallet to more than one virtual wallet on the Oracle Key Vault server. If you want to share an Oracle wallet with multiple endpoints, then create an endpoint group.
Related Topics
Parent topic: Uploading and Downloading Oracle Wallets
18.5 Uploading and Downloading JKS and JCEKS Keystores
The okvutil upload
and okvutil download
commands can upload and download JKS and JCEKS keystores.
- About Uploading and Downloading JKS and JCEKS Keystores
You use theokvutil
utility to upload and download JKS and JCEKS keystores. - Uploading JKS or JCEKS Keystores
Theokvutil upload
command can upload a JKS or JCEKS to the Oracle Key Vault server. - Downloading JKS or JCEKS Keystores
Theokvutil download
command can download an uploaded JKS or JCEKS keystore. - Guidelines for Uploading and Downloading JKS and JCEKS Keystores
Oracle provides recommendations for when you upload and download JKS and JCEKS keystores.
Parent topic: Managing Security Objects in Oracle Key Vault
18.5.1 About Uploading and Downloading JKS and JCEKS Keystores
You use the okvutil
utility to upload and download JKS and JCEKS keystores.
You can upload JKS and JCEKS keystores to Oracle Key Vault for long-term retention, recovery, and sharing, and when you need them, download them to an endpoint.
Similar to wallets, when you upload a JKS or JCEKS keystore, Oracle Key Vault can read each item within the keystore. It uploads the keystore contents as individual items.
Parent topic: Uploading and Downloading JKS and JCEKS Keystores
18.5.2 Uploading JKS or JCEKS Keystores
The okvutil upload
command can upload a JKS or JCEKS to the Oracle Key Vault server.
At this point, the upload is complete. You are now ready to share or download the Java keystore as needed.
18.5.3 Downloading JKS or JCEKS Keystores
The okvutil download
command can download an uploaded JKS or JCEKS keystore.
18.5.4 Guidelines for Uploading and Downloading JKS and JCEKS Keystores
Oracle provides recommendations for when you upload and download JKS and JCEKS keystores.
-
If there is a change to the content of the original JKS or JCEKS keystore, then upload the keystore again to Oracle Key Vault so that Key Vault has the latest copy of the keystore.
-
Use care if you plan to use the
okvutil upload
andokvutil download
commands, which provide an overwrite (-o
) option. This option overwrites data in the file. Before you use the-o
option, you should create backups of the keystore files before downloading them. -
Do not try to upload the same physical JKS or JCEKS keystore to more than one virtual wallet on the Oracle Key Vault server. If you want to share a Java keystore with multiple endpoints, then create an endpoint group.
Related Topics
Parent topic: Uploading and Downloading JKS and JCEKS Keystores
18.6 Uploading and Downloading Credential Files
The okvutil upload
and okvutil download
commands can upload and download credential files.
- About Uploading and Downloading Credential Files
You use theokvutil
utility to upload and download credential files. - Uploading a Credential File
Theokvutil upload
command can upload credential files. - Downloading a Credential File
Theokvutil download
command can download credential files. - Guidelines for Uploading and Downloading Credential Files
Oracle provides recommendations for when you upload and download credential files.
Parent topic: Managing Security Objects in Oracle Key Vault
18.6.1 About Uploading and Downloading Credential Files
You use the okvutil
utility to upload and download credential files.
Credential files are uploaded and stored as opaque objects in Oracle Key Vault, which means that Oracle Key Vault does not parse the contents of the file like an Oracle wallet or Java keystore. The upload process does not alter the credential file.
Examples of opaque objects are as follows:
-
Files that contain X.509 certificates
-
Kerberos keytabs
-
Files containing passwords
-
Files containing SSH keys
Uploading these credential files provides a central, secure location for long-term retention. After you have uploaded a credential file, you can download it in the same server location or share it with other trusted servers. Oracle Key Vault supports credential files up to 128 KB in size.
You can place the credential file anywhere in your server infrastructure (which includes database servers and application servers) that is accessible by an Oracle Key Vault endpoint.
Parent topic: Uploading and Downloading Credential Files
18.6.3 Downloading a Credential File
The okvutil download
command can download credential files.
Related Topics
Parent topic: Uploading and Downloading Credential Files
18.6.4 Guidelines for Uploading and Downloading Credential Files
Oracle provides recommendations for when you upload and download credential files.
-
After you complete the upload, upload the credential file again the next time it is changed. Otherwise, the uploaded (and subsequent downloaded version) file will be outdated. Periodically, you should compare the last modification date of the credential file with the timestamp of the uploaded version.
-
Use care if you use the
okvutil upload
andokvutil download
commands, which provide an overwrite (-o
) option. This option overwrites the uploaded credential file. You may want to create backups of the credential files before beginning the upload and download processes. -
You can share one credential file among multiple server endpoints. Add the opaque object to a virtual wallet and then ensure that all of the endpoints have access to that virtual wallet. Optionally, define an endpoint group and then make all the server endpoints members of that group. Upload the credential file that you would like to share using this common wallet into Oracle Key Vault as a group, using the
-g
option of theokvutil upload
command. Define a wallet and attach it to the endpoint group. Afterward, all the members of the group will have access to that wallet.
Parent topic: Uploading and Downloading Credential Files
18.7 Using a User-Defined Key as the TDE Master Encryption Key
You can import a generated key to be used as the Transparent Data Encryption (TDE) master encryption key in Oracle Key Vault.
- About Using a User-Defined Key as the TDE Master Encryption Key
Key administrators can upload a user-defined key to the groups to which they have write access. - Step 1: Upload the User-Defined Key
Use theokvutil upload
command to upload user-defined master encryption keys to Oracle Key Vault. - Step 2: Activate the User-Defined Key as a TDE Master Encryption Key
After you upload the user-defined key, you are ready to activate the key as a TDE master encryption key.
Parent topic: Managing Security Objects in Oracle Key Vault
18.7.1 About Using a User-Defined Key as the TDE Master Encryption Key
Key administrators can upload a user-defined key to the groups to which they have write access.
This enables it can be used as the Transparent Data Encryption (TDE) master encryption key. This feature provides key administrators with more control on creation of the master encryption key used to encrypt TDE data encryption keys.
The type
parameter of the okvutil upload
command includes the option TDE_KEY_BYTES
, which enables you to upload user-defined key bytes to Oracle Key Vault to be used as the TDE master encryption key. You must then activate the key as a TDE master encryption key by running the ADMINISTER KEY MANAGEMENT
SQL statement on the database.
Related Topics
18.7.2 Step 1: Upload the User-Defined Key
Use the okvutil upload
command to upload user-defined master encryption keys to Oracle Key Vault.
The raw bytes data of the user-defined key is stored in a text file and uploaded to Oracle Key Vault.
The raw bytes data uploaded to Oracle Key Vault forms part of the TDE Master Key
and the TDE Master Key Identifier
. Additional metadata is added to the raw bytes data to enable the database to identify and activate the data as the TDE Master Key
and the TDE Master Key Identifier
. In the text file, the raw bytes data that forms the TDE Master Key
is prefixed by TDE Master Key
. The raw bytes data that forms the TDE Master Key Identifier
is prefixed by TDE Master Key Identifier
. TDE Master Key Identifier
represents the master encryption key in the database. Once the key is activated, you should see the user-defined raw bytes that form the TDE Master Key Identifier
as the subset of the KEY_ID
column of the V$ENCRYPTION_KEYS
view. In Oracle Key Vault, the TDE Master Key
and TDE Master Key Identifier
values are stored as managed KMIP objects with a symmetric key as a KMIP object type.
18.7.3 Step 2: Activate the User-Defined Key as a TDE Master Encryption Key
After you upload the user-defined key, you are ready to activate the key as a TDE master encryption key.
The raw bytes data uploaded to Oracle Key Vault for the TDE Master Key Identifier
is displayed as the NAME
attribute of the KMIP object that is created as the corresponding TDE master encryption key in Oracle Key Vault.