Typical Oracle Key Vault use cases include the upload and download of security objects, the use of an Online Master Key, and TDE-configured Oracle databases. Note that the term Online Master Key replaces TDE direct connect.
In order to store and share Oracle wallets you must upload them to 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.
Parent topic: Oracle Key Vault Use Case Scenarios
The okvutil
utility comes packaged with the endpoint software that you install at the endpoint. You can use the okvutil upload
and okvutil download
commands to upload and download Oracle wallets between Oracle Key Vault and its endpoints.
The Oracle Key Vault endpoint 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.
Parent topic: Uploading and Downloading Oracle Wallets
Uploading wallets to Key Vault is done with the okvutil
upload
command. Everything in the Oracle wallet, security objects and their metadata is uploaded to Key Vault, so that the wallet can be reconstructed during the download process. The Oracle wallet typically contains TDE master keys, historical TDE master keys, SSL or TLS certificates and their metadata (stored in Key Vault as opaque objects), wallet metadata, as well as keys that you have explicitly added.
To upload an Oracle wallet:
At this point, the upload is complete. You can now share the virtual wallet with other users and endpoints.
See Also:
"Managing Endpoints" for more information
"Grant Access to Endpoint Groups, Endpoints, User Groups, and Users" for more information
"okvutil upload Command" for more information about okvutil upload
Parent topic: Uploading and Downloading Oracle Wallets
You can use the okvutil download command to download an Oracle wallet from the Oracle Key Vault server to an endpoint.
To download an Oracle wallet:
See Also:
"okvutil download Command" for more information about okvutil download
"Grant Access to Endpoint Groups, Endpoints, User Groups, and Users"
Oracle Database Advanced Security Guide for information about closing and opening keystores in Oracle Database Release 12c
Parent topic: Uploading and Downloading Oracle Wallets
Oracle provides recommendations for when you upload and download Oracle wallets.
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.
The okvutil upload
and download
commands provide an overwrite (-o
) option. Use care if you plan to specify this option because it 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.
See Also:
Parent topic: Uploading and Downloading Oracle Wallets
You can use the okvutil upload
and okvutil download
commands to upload and download JKS and JCEKS keystores.
Parent topic: Oracle Key Vault Use Case Scenarios
You can upload both 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
You can use the okvutil upload command to upload a Java keystore (JKS) or Java Cryptography Extension keystore (JCEKS) to the Oracle Key Vault server.
To upload a Java keystore:
At this point, the upload is complete. You are now ready to share or download the Java keystore as needed.
See Also:
"okvutil download Command" for more information about okvutil download
"Grant Access to Endpoint Groups, Endpoints, User Groups, and Users"
Oracle Database Advanced Security Guide for information about closing and opening keystores in Oracle Database Release 12c
Parent topic: Uploading and Downloading JKS and JCEKS Keystores
You can use the okvutil download
command to download an uploaded JKS or JCEKS keystore.
To download a Java keystore:
See Also:
"Managing Endpoints" for more information
"okvutil download Command" for more information about okvutil download
"Grant Access to Endpoint Groups, Endpoints, User Groups, and Users"
Parent topic: 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.
The okvutil upload
and download
commands provide an overwrite (-o
) option. Use care if you plan to specify this option because it overwrites the file. You may want to create backups of the keystores 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.
See Also:
"Manage Endpoint Groups" for more instructions to create an endpoint group
Parent topic: Uploading and Downloading JKS and JCEKS Keystores
You can use the okvutil upload
and okvutil download
commands to upload and download credential files.
Parent topic: Oracle Key Vault Use Case Scenarios
Credential files are uploaded and stored as opaque objects in Key Vault, which means that 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 server locations. Oracle Key Vault supports credential files up to 128 KB in size.
The credential file can be located 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
Oracle provides recommendations for when you upload and download credential files.
After you complete the upload, upload 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.
The okvutil upload
and download
commands provide an overwrite (-o
) option. Use care if you plan to specify this option, because it 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 the okvutil upload
command. Define a wallet and attach it to the endpoint group. All the members of the group will have access to that wallet.
Parent topic: Uploading and Downloading Credential Files
You can configure Transparent Data Encryption (TDE) to perform a direct connection to an endpoint to centrally manage TDE master keys.
Note that the term Online Master Key replaces TDE direct connect.
Parent topic: Oracle Key Vault Use Case Scenarios
For Oracle Database 11g Release 2 (11.2) and later, you can use an Online Master Key to centrally manage Transparent Data Encryption (TDE) master keys over a network connection as an alternative to using local Oracle wallet files.
The connection configuration entails using a PKCS#11 library to connect to Oracle Key Vault. After you perform the configuration, all future TDE master keys will be stored and managed in Oracle Key Vault. This section explains two scenarios that you can use:
If the database does not yet have TDE wallets.
If the database has already been configured for TDE.
TDE key management operates with Oracle Key Vault in the same way that it operates with hardware security modules (HSMs). You must open the wallet before encryption and decryption. After you close the wallet, encrypted data in tables and tablespaces is unavailable to you. You should rotate the TDE master encryption key regularly to remain in compliance with the applicable regulations.
Oracle Key Vault supports the SQL statements that were used to administer earlier TDE releases, specifically the use of the ALTER SYSTEM
and ADMINISTER KEY MANAGEMENT
SQL statements.
See Also:
"Configuring a Connection Between Oracle Key Vault and a New TDE-Enabled Database" for a non-TDE database
"Migrating Existing TDE Wallets to Oracle Key Vault" for a TDE database
"Centralized Management of TDE Master Keys Using Online Master Key"
Parent topic: Using an Online Master Key with Oracle Key Vault
You can deploy TDE in multiple topologies with other database features that move or use clustered deployments.
Data movement and replication are major challenges for Oracle Advanced Security TDE because it must keep the master encryption key synchronized at both endpoints. To help with these challenges, Oracle Key Vault supports common Oracle Database features.
To move data, Oracle Key Vault supports:
Oracle Recovery Manager (RMAN) backup and recovery operations
Oracle Data Pump
Transportable tablespaces (Oracle Database 12c and later)
For clustered deployments, Oracle Key Vault supports:
Oracle Active Data Guard
Oracle Real Application Clusters (Oracle RAC)
Oracle GoldenGate
Parent topic: Using an Online Master Key with Oracle Key Vault
You can configure a connection between Oracle Key Vault and a database that has not yet been configured for Transparent Data Encryption.
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
, if used, must be set to the same values in svrctl
and OS environments. This also applies if you are using the Oracle Key Vault RESTful Services utility to enroll endpoints.
Configure the connection as follows:
Ensure that the ORACLE_BASE
environment variable is set before you start the oracle
process manually. This is very important.
If the ORACLE_BASE
environment variable is not present, create a soft link from the:
$ORACLE_BASE/okv/$ORACLE_SID/okvclient.ora
file
to the:
key_vault_endpoint_installation_dir
/conf/okvclient.ora
file.
In an Oracle Real Application Clusters environment, perform this step on all database instances.
Note:
To learn more about using environment variables in SQLNET.ORA
please see the See Also section at the end of this procedure.
Ensure that the COMPATIBILITY
initialization parameter is set to 11.2.0.0
or later.
Enroll and provision the endpoint for the TDE-enabled database that contains the TDE data.
When you initially enroll the endpoint, select Oracle Database as the endpoint type for integration with TDE.
Ensure that the endpoint has access to the virtual wallet that you want to use.
The endpoint must have the Read, Modify, and Manage Wallet access.
Configure the sqlnet.ora
file on this database to point to Oracle Key Vault as follows:
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=HSM))
Transparent Data Encryption uses HSM
as the parameter value for all external key management systems, including Oracle Key Vault. Therefore the configuration settings and administrative commands are similar to those used for an HSM.
By default, the sqlnet.ora
file is located in the ORACLE_HOME
/network/admin
directory or in the location set by the TNS_ADMIN
environment variable. Endpoints use the PKCS#11 library support to manage TDE master encryption keys.
Note:
At this stage, Oracle Key Vault can use TDE and all the TDE-related SQL statements are available. For all TDE commands and statements, use the Key Vault endpoint password that was specified during the endpoint enrollment process.
Reconnect to the database if you are in SQL*Plus.
The changes will appear after you log out of the current SQL*Plus session and then reconnect again.
Query the V$ENCRYPTION_WALLET
dynamic view to ensure that the METHOD_DATA
setting in the sqlnet.ora file
changed.
The output of the query should now show HSM
.
SELECT * FROM V$ENCRYPTION_WALLET;
Configure TDE to integrate with Key Vault, so that Key Vault can directly manage the TDE master keys as follows:
On UNIX platforms, run the root.sh
script as the root user to copy the liborapkcs.so
file (located in the lib
directory) to the /opt/oracle/extapi/64/hsm/oracle/1.0.0
directory.
The persistent master key cache feature is implemented in the Oracle Key Vault PKCS#11 library and improves the availability of the database during intermittent network disruptions or Oracle Key Vault upgrade.
By default, the PKCS#11 library is located in the $OKV_HOME/bin/liborapkcs.so
file. Copy it to the following location on a UNIX system:
/opt/oracle/extapi/64/hsm/oracle/1.0.0
On Windows platforms, run the root.bat
script as the root user to copy the liborapkcs.dll
file (located in the lib
directory) to the C:\oracle\extapi\64\hsm\oracle\1.0.0
directory. Provide the database version when prompted.
For password-protected wallets on the database, open the wallet. (Auto-login wallets are automatically opened.)
For Oracle Database 11g Release 2, as a user who has been granted the ALTER SYSTEM
system privilege:
ALTER SYSTEM SET ENCRYPTION WALLET OPEN IDENTIFIED BY "Key_Vault_endpoint_password";
For Oracle Database 12c, as a user who has been granted the SYSKM
administrative privilege:
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Key_Vault_endpoint_password";
Set the master encryption key.
For Oracle Database 11g Release 2:
ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "Key_Vault_endpoint_password";
For Oracle Database 12c:
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "Key_Vault_endpoint_password";
The TDE configuration is complete at this stage. You can now encrypt tables or create encrypted tablespaces in the database.
If you have configured the sqlnet.ora
file correctly along with the rest of the TDE configuration, a TDE master key is created in Oracle Key Vault when you set the encryption key using one of the following commands:
ALTER SYSTEM SET ENCRYPTION KEY
OR
ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY
Limitations to TDE Endpoint Integration
The limitations to TDE endpoint integration are as follows:
All endpoints on the same machine must use the same version of the Oracle Key Vault library. There is only one location per machine for the liborapkcs.so
file, which is:
/opt/oracle/expapi/64/hsm/oracle/1.0.0/liborapkcs.so
On the same machine it is best to use the same external key manager for Oracle Database, either Oracle Key Vault or HSM. Using Oracle Key Vault for one Oracle Database and 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:
/opt/oracle/expapi/64/hsm/
Caution:
Oracle strongly recommends NEVER to remove keys from a wallet or the wallet itself after TDE is setup. Loss of keys will result in the loss of encrypted data and hamper the normal functioning of the database. This is true even: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
See Also:
"Endpoint Database Requirements" for more information on setting the COMPATIBLE
parameter
"Grant Access to Endpoint Groups, Endpoints, User Groups, and Users" for information on granting access to virtual wallets
Parent topic: Using an Online Master Key with Oracle Key Vault
You can migrate an existing TDE wallet to Oracle Key Vault, and if necessary, restore the database contents that were previously encrypted by TDE, by using an Oracle wallet.
Parent topic: Using an Online Master Key with Oracle Key Vault
When the 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 Key Vault.
Along with the current TDE master key, Oracle wallets maintain historical TDE master keys that are replaced by each rekey operation that rotates the TDE master key. These historical TDE master keys help to restore Oracle Database backups that were previously made using one of the historical TDE master keys. During the TDE migration from an Oracle wallet file to Oracle Key Vault, Key Vault generates new master keys. After this master key generation, Oracle Key Vault maintains all new keys.
Oracle recommends that you upload the Oracle wallet to 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 RAC configuration, then you must restart the database so that the new TDE master key is updated to all the endpoint database nodes in the shared server configuration.
You can use the okvutil upload
command to migrate an existing TDE wallet to Oracle Key Vault. It is very important that you close the software wallet and open the HSM wallet before migrating the wallet in the same SQLPLUS session, as outlined in steps 7 and 8 below:
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 upload the existing Oracle wallet to Key Vault, by using the okvutil upload
command.
This step ensures that Oracle Key Vault has a copy of the wallet that contains all of the historical TDE master 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 the ORACLE_HOME
/network/admin
directory or in the location set by the TNS_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 the METHOD_DATA
setting in the sqlnet.ora file
changed. The output of the query should now show METHOD=HSM
.
SELECT * FROM V$ENCRYPTION_WALLET;
If the endpoint is a Release 11gR2 Oracle 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> alter system set wallet close;
If the password-protected wallet is open, execute the following command:
sqlplus> alter system set wallet close identified by "<wallet password>";
Open the HSM wallet:
sqlplus> 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 execute this command:
sqlplus> 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 command:
sqlplus> alter system set encryption key identified by "null" migrate using "<wallet password>";
For Oracle Database 12c, as a user who has been granted the SYSKM
administrative privilege:
sqlplus> administer key management set encryption key identified by "<endpoint password>" MIGRATE USING "<wallet password>" with backup;
Note:
While the with backup
clause is required for the administer key management
command, 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:
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 to cwallet.sso
.
See Also:
Oracle Database Backup and Recovery User's Guide for more information about backing up a database
Parent topic: Migrating Existing TDE Wallets to Oracle Key Vault
When an Oracle database endpoint is converted from a local Oracle wallet file to using Oracle Key Vault, there may be a subsequent need to restore backups that were encrypted using a key from this local wallet file.
In this case, you must download the necessary key from Oracle Key Vault to a local wallet file to be used when you decrypt the backup during the restore process. For example, suppose that the 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, 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.
To restore previously TDE-encrypted database contents using an Oracle wallet:
See Also:
Parent topic: Migrating Existing TDE Wallets to Oracle Key Vault
The persistent master key cache feature enables databases to be operational when the Oracle Key Vault server is unavailable for any reason. The TDE master key is cached in the persistent master key cache in addition to the in-memory cache, to make the master 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.
Parent topic: Using an Online Master Key with Oracle Key Vault
The persistent master key cache ensures the availability of TDE master encryption keys by reducing dependence on the state of the Oracle Key Vault server.
The TDE master encryption key is cached in the persistent master key cache in addition to the in-memory cache, to make the master 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 keys:
Continuous operation of endpoints during upgrade, primary-standby configuration, switchover, failover, and other procedures that require an Oracle Key Vault restart
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: Persistent Master Key Cache
The Oracle Key Vault persistent master key cache is implemented in Oracle Key Vault’s PKCS#11
library. When the persistent master key cache feature is configured, the Oracle Key Vault PKCS#11
library will create the persistent master key cache when the first master key is retrieved from Oracle Key Vault.
If Oracle Key Vault is installed with a password specified, then the persistent master key cache is a password-based wallet.
If Oracle Key Vault is installed without a password specified, then the persistent master key cache is an auto-login wallet.
The PKCS#11
library also implements an in-memory master key cache. When the in-memory master key cache feature is configured, the master key is cached in the process memory of the process that loaded the library into memory. The in-memory and persistent master key caches are independent of each other. They can be enabled and disabled independently.
For operations that involve encryption and decryption, PKCS#11
attempts to look up the master encryption key in the in-memory master key cache. If it is not found, PKCS#11
then looks up the master encryption key in the persistent master key cache. If the master key is not found in the in-memory or the persistent master key cache, then it is retrieved from the Oracle Key Vault server, if the server is online.
Parent topic: Persistent Master Key Cache
In Oracle Key Vault 12.2.0.5.0 and later, the persistent master key cache operates in two modes, Oracle Key Vault first mode and persistent master encryption key cache first mode.
The difference between the two modes is the order in which the persistent master key cache and Oracle Key Vault are looked up to retrieve the master key.
Parent topic: Persistent Master Key Cache
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 key cache.
The endpoints must determine the status of the Oracle Key Vault server, and if it is offline, the endpoints then attempt to retrieve the master encryption key from the persistent master key cache. Hence, database operations that require access to master keys will experience a delay.
Parent topic: Persistent Master Key Cache Modes of Operation
In Persistent Master Key Cache First mode, the endpoints attempt to retrieve the master encryption key from the persistent master key cache. If the master key is not available in the persistent master 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 key cache.
Parent topic: Persistent Master Key Cache Modes of Operation
The Refresh Window feature of the Persistent Master Key Cache further minimizes endpoint downtime. This feature enables the database endpoint to make multiple attempts to refresh the expired master key from the OKV server. In that sense, the endpoint waits for the OKV server to be back online for the master key refresh to complete. Meanwhile, if the master key refresh attempt fails, the keys are retrieved from the persistent cache for the duration of the refresh window.
The Refresh Window feature of the Persistent Master Key Cache thus extends the duration for which the master key is available after it is cached in the persistent master 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 in the window when the Oracle Key Vault is unavailable such as when HA switchover is in progress. The refresh window terminates and the cache period begins as soon as the key is refreshed.
In the okvclient.ora
file, the parameter PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
is used to extend the duration for which the master key is available after it is cached in the persistent master key cache. This value reflects the amount of time it takes for the Oracle Key Vault server to recover and come back online. The value is specified in minutes. The default value for PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
is 30 (minutes).
For more information about the Persistent Cache Refresh Window, see PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW Parameter.
Parent topic: Persistent Master Key Cache
The following are the parameters used to configure the Persistent Master Key Cache.
Parent topic: Persistent Master Key Cache
The okvclient.ora
file, the parameter PKCS11_CACHE_TIMEOUT
specifies the duration for which the master encryption key is available after it is cached in the in-memory cache. You must specify the value minutes. When the specified duration of time elapses, the master encryption key expires. Expired master keys are not deleted from the in-memory cache.
The default value for PKCS11_CACHE_TIMEOUT
is 60 (minutes).
Parent topic: Persistent Master Key Cache Parameters
In the okvclient.ora
file, the parameter PKCS11_PERSISTENT_CACHE_TIMEOUT
specifies the duration for which the master encryption key is available after it is cached in the persistent master key cache. You must specify this value in minutes. When the specified duration of time elapses, the master encryption key expires. Expired master keys are not deleted from the persistent master 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 key cache by setting the PKCS11_PERSISTENT_CACHE_TIMEOUT
parameter to 0 (zero).
Note:
The parameterPKCS11_PERSISTENT_CACHE_TIMEOUT
and its default value are included by default in the okvclient.ora
file.Parent topic: Persistent Master Key Cache Parameters
In the okvclient.ora
file, the parameter PKCS11_PERSISTENT_CACHE_FIRST
specifies the mode of operation of the persistent master key cache. 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 to 0 (zero).
Persistent Master Key Cache First Mode: Persistent Master Key Cache First mode is the default mode.
To enable Persistent Master Key Cache First mode, set the value of the PKCS11_PERSISTENT_CACHE_FIRST
parameter to 1.
Parent topic: Persistent Master Key Cache Parameters
In the okvclient.ora
file, the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
parameter extends the duration for which the master encryption key is available after it is cached in the persistent master key cache. 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 key cache by setting the PKCS11_PERSISTENT_CACHE_REFRESH_WINDOW
value to 0 (zero).
Parent topic: Persistent Master Key Cache Parameters
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 okvutil list
command enables you to list the master encryption keys that are cached in the persistent master key cache.
The following example shows how to list the master encryption keys cached in the persistent master key cache:
$ ./okvutil list -t okv_persistent_cache -l $ORACLE_HOME/okv/$ORACLE_SID Enter Oracle Key Vault endpoint password: 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 lists the columns in the OKV Persistent Cache entries
list:
Column Name | Description |
---|---|
|
Persistent master key cache version |
|
KMIP identifier assigned to the master key |
|
Database ID assigned to the master key |
|
Time at which the master key was cached |
|
Duration for which the master key was/is cached |
|
Extended duration for which the master key is available after it is cached in the persistent master key cache |
|
Indicates whether the master key is available or expired |
Parent topic: Persistent Master Key Cache
You should be aware of how the persistent master key cache affects the integration of other Oracle features with Oracle Key Vault.
Ensure that the passwords of the persistent master key cache and the Oracle Key Vault endpoint wallet are synchronized.
Note:
The persistent master key cache must be deleted when the endpoint wallet credentials are modified.In an Oracle RAC Environment, you must query the database from each RAC node to cache the most recent version of the master encryption key in the persistent master key cache of each RAC node.
The standby server retrieves and caches the new master key in the persistent master 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: Persistent Master Key Cache
Business-critical operations require data to be accessible and recoverable with minimum downtime. You can configure Oracle Key Vault to ensure minimum downtime in the following ways:
Configuring High Availability: High Availability is configured by adding redundancy in the form of a standby server. The standby server takes over from the primary server in the event of a failure, thus eliminating single points of failure, and minimizing downtime. For more information about configuring High Availability, see Configuring High Availability.
Enabling Read-Only Restricted Mode: High Availability Read-Only Restricted mode ensures endpoint operational continuity when primary or standby Oracle Key Vault servers are affected by server, hardware, or network failures. When an unplanned shutdown causes the standby server to become unreachable, the primary server is still available to the endpoints.
If High Availability Read-Only Restricted mode is disabled, the primary server will become unavailable and stop accepting requests in the event of a standby failure. Endpoints connected to Oracle Key Vault are unable to retrieve keys until connectivity is restored between primary and standby servers.
To ensure endpoint operational continuity in the event of a primary or standby server failure, enable Read-Only Restricted mode.
Enabling Persistent Master Key Cache: The Persistent Master Key Cache ensures that the endpoints can access keys in the event of a primary or standby server failure. While the surviving server is taking over from the failed peer, the endpoints can retrieve keys from the persistent cache and continue operations normally. For more information about Persistent Master Key Cache, see Persistent Master Key Cache.
Apply the TDE Heartbeat database patch on endpoints: Apply the database patch for Bug 22734547 to tune the Oracle Key Vault heartbeat.
It is highly recommended that you back up Key Vault data regularly on a schedule. This practice ensures that backups are current and hold the most recent data. The backup can be used to restore a new or existing Key Vault server and be fully operational with minimum downtime and data loss.
If the OKV installation uses an online master key (formerly known as TDE direct connect), then during an upgrade, ensure that you upgrade database endpoints in parallel to reduce total downtime.
Parent topic: Using an Online Master Key with Oracle Key Vault
You can now import your generated key to be used as the Transparent Data Encryption (TDE) master encryption key in Oracle Key Vault.
Parent topic: Oracle Key Vault Use Case Scenarios
Key Administrators can upload this user-defined key to the groups that they have write access to. This feature provides Key Administrators with more control on creation of the master key used to encrypt TDE data encryption keys.
The type
parameter of the okvutil upload
command features a new option TDE_KEY_BYTES
that allows you to upload user-defined key bytes to Oracle Key Vault to be used as the TDE master key. The key is then activated as a TDE master encryption key by running the ADMINISTER KEY MANAGEMENT
command on the database. For more information about activating a TDE master encryption key, see Activating TDE Master Encryption Keys.
You must first upload the user-defined key, and then activate this key as a TDE master encryption key.
User-defined keys are uploaded to Oracle Key Vault using the okvutil upload
command. 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
.
TDE Master Key
is prefixed by:
TDE Master Key
TDE Master Key Identifier
is prefixed by:
TDE Master Key Identifier
The TDE Master Key Identifier
represents the master 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
are stored as managed KMIP objects with a symmetric key as a KMIP object type.
To upload the user-defined key:
After uploading the user-defined key, activate the key as a TDE master encryption key.
Note:
The raw bytes data uploaded to Oracle Key Vault for theTDE 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.To activate the user-defined key:
The user-defined key is activated as a TDE master encryption key.
Note:
In Oracle Database 12.1 and higher, you can query theTAG
column of the V$ENCRYPTION_KEYS
view for the identifier of the newly created key.In a TDE-configured Oracle database, if you upload Oracle wallets in an Oracle Real Application Cluster (Oracle RAC) environment, then the nodes within the cluster must share a virtual wallet.
You can enable the cluster to share the virtual wallet by using either of the following approaches:
Define a virtual wallet as a shared default wallet for all of the nodes in the cluster.
If each node in the cluster has a separate default wallet, then grant each node access to every other node's default wallet to have the same effect. An endpoint group may be used to simplify the process of granting each node access to the default wallets of the other nodes.
The advantage of this approach over the first is that if you had several nodes that already had default wallets and you wanted them to share wallets, then you would not have to reassign their default wallets. This is particularly important because in the first approach, in order to reassign an endpoint's default wallet, you must reenroll the endpoint. An endpoint group can be used to simplify the process of granting each node access to the default virtual wallets of the other nodes.
As with single-instance database environments, after you download a password-protected wallet, you must manually open it. If you have one wallet on the primary node and then download the wallet to the other nodes, you must explicitly open the wallets on each of these nodes.
Each RAC node is a different end point of the database and has its own individual persistent cache. For RAC databases, a query should be initiated from each RAC node to cache the latest master key in the RAC node for uninterrupted operations
See Also:
Parent topic: Oracle Key Vault Use Case Scenarios
You can migrate Oracle wallets that contain Oracle GoldenGate shared secrets and TDE master keys to the Oracle Key Vault server.
Parent topic: Oracle Key Vault Use Case Scenarios
In an environment where Oracle Key Vault is not used and an Oracle TDE-enabled database is configured with an Oracle wallet with Oracle GoldenGate, this database (called the source database) stores an Oracle GoldenGate shared secret in the same Oracle wallet where master keys are stored.
This means that when you configure the source database as an Oracle Key Vault endpoint, the Oracle GoldenGate shared secret is stored in Oracle Key Vault in the same virtual wallet where the master keys are stored for the TDE-enabled source database.
When you migrate an Oracle wallet that contains an Oracle GoldenGate shared secret and TDE master keys to Oracle Key Vault using the okvutil
command-line utility, the default wallet for the TDE-enabled source database now stores the entire Oracle wallet migrated with shared secret and master keys.
In addition, if the configured target database is an Oracle database, then you must ensure that this target database is TDE-enabled so that all the TDE commands can be replicated. Note that the two Oracle TDE-enabled databases, source and target, do not need to have the same master key in the Oracle wallet. If you configure this target database as a new Key Vault endpoint, then you can upload and download wallets to and from Oracle Key Vault as you normally would with any independent Key Vault endpoint. No additional configuration is necessary.
Note, that the term Online Master Key replaces the term TDE direct connect.
There are two configuration steps to using the Online Master Key in an Oracle GoldenGate deployment:
At this stage, the configuration is complete. If you have configured the sqlnet.ora
file correctly and completed the other configuration required for TDE on the source database, then when you set the encryption key (using either ALTER SYSTEM SET ENCRYPTION KEY
or ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY
), a TDE master key is created in Oracle Key Vault. You can encrypt tables or create encrypted tablespaces in the database. The encrypted data created in the source database continues to be replicated on the target database after this procedure is performed. The other Oracle GoldenGate shared secrets are stored in Oracle Key Vault.
See Also:
"Configuring a Connection Between Oracle Key Vault and a New TDE-Enabled Database" for instructions to connect a source database in GoldenGate to Key Vault.
Oracle Database Advanced Security Guide for more information on configuring the storage of Oracle GoldenGate secrets in the source database.
In an Oracle GoldenGate environment with a TDE-configured database, an Oracle wallet contains both the TDE master keys and the Oracle GoldenGate shared secret.
Note that target databases (if they are Oracle TDE-enabled databases) that are used in this Oracle GoldenGate environment can also be configured to use Oracle Key Vault or continue to use Oracle wallet. You should treat these databases as you would any standalone TDE database endpoint.
After you complete this migration, the configuration is complete. If you have configured the sqlnet.ora
file correctly and completed the other configuration required for TDE, then when you set the encryption key (using either ALTER SYSTEM SET ENCRYPTION KEY
or ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY
), a TDE master key is created in Oracle Key Vault. You can continue to create and use encrypted tables or tablespaces in the database. The encrypted data created in the source database continues to be replicated on the target database after this procedure is performed.
See Also:
"Migrating Existing TDE Wallets to Oracle Key Vault" to migrate the Oracle wallet to Key Vault
You can perform the following activities in an Oracle Active Data Guard environment: upload Oracle wallets to an Oracle Key Vault server, use Online Master Keys, migrate wallets between endpoints, and migrate and check TDE wallets for a logical standby database.
Parent topic: Oracle Key Vault Use Case Scenarios
In an Oracle Active Data Guard environment with a TDE-enabled primary and a standby database using an Oracle wallet, you must physically copy the Oracle wallet file from the primary database to the standby after the initial TDE configuration and later, whenever you rekey the master key on the primary database.
Whereas, when using Oracle Key Vault with a TDE-enabled Active Data Guard database, the primary and standby databases must be registered in Oracle Key Vault as endpoints. You must ensure that the endpoints that are registered for both the primary and standby databases have same default virtual wallet in Oracle Key Vault.
This way, the two databases can achieve centralized key and wallet management without the need of a manual copy of the wallet file from the primary database to the standby database.
Persistent Cache in an Active Data Guard Environment
A REKEY on the primary database will cache the Master Key in its own persistent cache. When the new REDO logs from the primary are applied on the standby, only then will the standby fetch the new key from the OKV and cache it in the persistent cache of the standby. There is a time lag between the caching of the key in primary and the caching of the key in standby. It is recommended that the primary and standby be synchronized as soon as possible after the REKEY.
You can upload an Oracle wallet to an Active Data Guard environment as follows:
okvclient.jar
file for each endpoint on the respective databases.See Also:
"About Using an Online Master Key with Oracle Key Vault" for more information
See Also:
See Oracle Data Guard Concepts and Administration for information about starting the apply process on the standby database
To reverse migrate an Oracle wallet in an Active Data Guard environment:
Note:
If the endpoint password and the local TDE wallet password are different, then use the auto-login HSM feature. See Oracle Database Advanced Security Guide for more information about configuring auto-login wallets.
If you have a logical standby database configured and are using Oracle Database Release 12c, then you can migrate a TDE wallet to Oracle Key Vault as follows:
okvclient.jar
file to each endpoint.V$ENCRYPTION_WALLET
dynamic view.See Also:
Oracle Data Guard Concepts and Administration for more information about the SQL Apply process
In an Oracle Database Release 12c environment, after you have migrated an Oracle TDE wallet in a logical standby configuration, you can check the configuration by querying the WRL_TYPE
and WALLET_ORDER
columns of the V$ENCRYPTION_WALLET
dynamic view.
By querying the V$ENCRYPTION_WALLET
view, you can track the primary keystore. If you have only a single wallet configured, then the WALLET_ORDER
column is set to SINGLE
. In a two-wallet or mixed configuration, the column is set to PRIMARY
or SECONDARY
, depending on where the active master key is located. Consider the following queries.
In the following query, only a single wallet is configured:
SELECT WRL_TYPE, WALLET_ORDER FROM V$ENCRYPTION_WALLET; WRL_TYPE WALLET_OR -------------------- --------- FILE SINGLE
In this query in a logical standby configuration, the active master key has been migrated to an Oracle Key Vault virtual wallet:
SELECT WRL_TYPE, WALLET_ORDER FROM V$ENCRYPTION_WALLET; WRL_TYPE WALLET_OR -------------------- --------- FILE SECONDARY HSM PRIMARY
This query should show the HSM
as the PRIMARY
wallet in both the primary and standby database for the logical configuration.
Oracle Key Vault supports integration with MySQL from Release 12.2 and later.
Note:
MySQL Windows databases are not supported.Oracle Key Vault can manage MySQL TDE encryption keys.
Parent topic: Oracle Key Vault Use Case Scenarios
Copy the keystore from ASM to the file sytem.
Upload the keystore from the file system to Oracle Key Vault.
ADMINISTER KEY MANAGEMENT
statement to move a software keystore out of Automatic Storage Management (ASM) as follows:To copy a keystore from Oracle Key Vault to ASM you would reverse the steps:
Initialize a target keystore on the file system, if it does not exist. If it exists, skip this step.
Copy the keystore from Key Vault to the target keystore on the file system using the okvutil download
command.
$ okvutil download -l location -t type
Where:
location
is the path to the target keystore in the file system
type
is wallet
For example:
$ okvutil download -l etc/ORACLE/KEYSTORE/DB1 -t wallet
Copy the keystore from the target keystore to ASM.
Parent topic: Oracle Key Vault Use Case Scenarios