1. Administrator's Guide
  2. Managing Security Objects in Oracle Key Vault

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.

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.

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 environment variables. This also applies if you are using the Oracle Key Vault RESTful services utility to enroll endpoints.

For information about configuring Oracle Data Guard so that it can work with TDE and Oracle Key Vault:

For information about configuring Oracle Real Application Clusters (Oracle RAC) to work with TDE and Oracle Key Vault:

Parent topic: Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection

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

Parent topic: Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection

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.

These settings include Oracle environment variables and the Oracle COMPATIBILITY parameter.
  1. Log in to the server where the database endpoint is installed.
  2. Ensure that the ORACLE_BASE environment variable is set before you start the oracle process manually.
    This step is very important. If the ORACLE_BASE environment variable is not present, then 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, you must perform this step on all database instances.
  3. Ensure that the COMPATIBILITY initialization parameter is set to 11.2.0.0 or later.
  4. Enroll and provision the endpoint for the Transparent Data Encryption (TDE)-enabled database that contains the TDE data.
    When you initially enroll the endpoint, select ORACLE_DB as the endpoint type for integration with TDE.
  5. Ensure that the endpoint has access to the virtual wallet that you want to use by defining the wallet as the default wallet for that endpoint.
    In Oracle Real Application Clusters (Oracle RAC) and Oracle Data Guard environments, the endpoints of all instances share the same default wallet. The endpoint must have the read, modify, and manage wallet access.
  6. Depending on the Oracle Database release, configure the encryption wallet location.
    • For release 12.2.0.1 and earlier, onfigure the sqlnet.ora file on this database to point to Oracle Key Vault as follows:
      ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=OKV))

      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.

    • For release 18c and later, configure the following parameters:
      • Set WALLET_ROOT to define the installation directory of the Oracle Key Vault client.
      • Set TDE_CONFIGURATION to OKV for Oracle Key Vault.

      Endpoints use the PKCS#11 library support to manage TDE master encryption keys. Execute the root.sh script (in the okvclient_installation_directory/bin directory) to deploy the PKCS#11 library that facilitates the communication between the endpoint and Oracle Key Vault.

      At this stage, the Oracle database will use Oracle Key Vault for centralized key management. For all TDE commands and statements, use the Oracle Key Vault endpoint password that was specified during the endpoint enrollment process.

  7. 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 connect again.
  8. Query the V$ENCRYPTION_WALLET dynamic view to ensure that the METHOD_DATA setting in the sqlnet.ora file changed. 
    SELECT * FROM V$ENCRYPTION_WALLET;

    The output of the query should now show OKV.

The TDE configuration is complete at this stage. You can now encrypt tables or create encrypted tablespaces in the database. Oracle does not recommend using TDE column encryption with an external key manager. (This applies to not only Oracle Key Vault but to all third-party key managers and HSMs.) If you have configured the 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 BACKUP;

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.

Parent topic: Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection

18.1.4 Step 2: Integrate Transparent Data Encryption with Oracle Key Vault

This integration enables Oracle Key Vault to directly manage the TDE master encryption keys.

  1. Ensure that you are logged into the server where the Oracle Key Vault client is installed.
  2. Execute the root script from okvclient_installation_directory/bin.

    This script implements the persistent master encryption key cache feature in the Oracle Key Vault PKCS#11 library, which improves the availability of the database during intermittent network disruptions or Oracle Key Vault upgrade.

    • UNIX: The root script copies the PKCS#11 library into /opt/oracle/extapi/64/hsm/oracle/1.0.0 and minimizes the file access privileges.
    • Windows: Run the root.bat script 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.
  3. 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 "Oracle_Key_Vault_endpoint_password";
    • For Oracle Database 12c or later: As a user who has been granted the SYSKM administrative privilege: 
      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Oracle_Key_Vault_endpoint_password" WITH BACKUP;
  4. 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 and later: 
      ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "Key_Vault_endpoint_password" WITH BACKUP;

Related Topics

Parent topic: Configuring an Oracle Key Vault-to-New TDE-Enabled Database Connection

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.

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.

Related Topics

Parent topic: Migrating Existing TDE Wallets to Oracle Key Vault

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.

  1. Back up the database that contains the data that you want to migrate.
  2. Complete the enrollment of the endpoint.
  3. If you have not done so already, then use the okvutil upload command to upload current and historical master encryption keys from the TDE wallet into the virtual wallet in Oracle Key Vault.
    $ OKV_HOME/bin/okvutil upload -t WALLET -l /path/to/tde-wallet -g name_of_wallet_in_Oracle_Key_Vault -v 4

    This step ensures that Oracle Key Vault has a copy of the wallet that contains all of the historical TDE master encryption keys.

  4. Configure the wallet location.
    • For Oracle Database releases 12.2.0.1 and earlier: Edit the METHOD setting of the Oracle Database sqlnet.ora file for the migration to Oracle Key Vault:
      ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=OKV)(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.

    • For Oracle Database release 18c and later: Set the TDE_CONFIGURATION parameter. 
       ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=OKV|FILE" SCOPE = BOTH;

      The WALLET_ROOT parameter is already so, so you do not need to change it.

  5. Reconnect to the database instance (or restart an Oracle RAC database) to capture the changes in the sqlnet.ora file.
    If you are reconnecting to the database instance, then changes to the TDE_CONFIGURATION parameter in Oracle Databae 18c and later are applied immediately, and no restart is necessary.
  6. Query the V$ENCRYPTION_WALLET dynamic view to ensure that the METHOD_DATA setting in the sqlnet.ora file changed. 
    SELECT * FROM V$ENCRYPTION_WALLET;

    The output of the query should now show METHOD=OKV.

  7. 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:
  8. Close the local Oracle wallet using these steps:
    1. Close the local Oracle wallet as follows:
      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";
    2. In SQL*Plus, open the HSM wallet, open the connection into Oracle Key Vault, where Oracle_Key_Vault_password is the password that was provided when the okvclient.jar file was installed:
      ALTER SYSTEM SET WALLET OPEN IDENTIFIED BY "Oracle_Key_Vault_password";
  9. 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 "Oracle_Key_Vault_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 and later: As a user who has been granted the SYSKM administrative privilege: 
      ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "Oracle_Key_Vault_password" MIGRATE USING "wallet_password" WITH BACKUP;

      Though the WITH BACKUP clause is required for the ADMINISTER KEY MANAGEMENT statement, it is ignored by TDE in Oracle Key Vault.

  10. Open the wallet.
    • For Oracle Database 11g release 2: If the endpoint requires a password to connect to Oracle Key Vault, then enter the password.
      ALTER SYSTEM SET ENCRYPTION WALLET OPEN 
IDENTIFIED BY "Oracle_Key_Vault_endpoint_password";
    • For Oracle Database 12c and later: 
      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN 
IDENTIFIED BY "Oracle_Key_Vault_endpoint_password";
  11. 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.

Related Topics

Parent topic: Migrating Existing TDE Wallets to Oracle Key Vault

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.

When an Oracle database endpoint is converted from a local Oracle wallet file to using Oracle Key Vault, you may need to restore backups that were encrypted by 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, 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.
  1. Download this Oracle wallet from Oracle Key Vault by using the okvutil download command.
  2. On the endpoint where you downloaded the Oracle wallet, edit the sqlnet.ora file to have the following setting:
    ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=wallet_file_path)))

    Put the ENCRYPTION_WALLET_LOCATION setting on one line.

  3. Open the downloaded wallet using the password you specified.

    • 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 "wallet_password";

    • For Oracle Database 12c and later, as a user who has been granted the SYSKM administrative privilege: 

      ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "wallet_password";

    Opening the wallet enables the server to read the contents of the updated sqlnet.ora file. At this point, the endpoint server has been restored to a state where it now can run with the original version of the wallet.

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.

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.

The persistent master encryption key cache is an auto-login wallet or a password-based wallet, depending on how Oracle Key Vault is installed:

  • 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.

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.

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.

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 parameter PKCS11_PERSISTENT_CACHE_TIMEOUT and its default value are included by default in the okvclient.ora file.
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 to 0 (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 to 1.

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).

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.

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

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
  2. Click the Endpoints tab.
  3. On the Endpoints page, select the endpoint for which you want to set EXPIRE PKCS11 PERSISTENT CACHE ON DATABASE SHUTDOWN.
  4. On the Endpoint Details page, scroll to the bottom and then set the Expire PKCS11 Persistent Cache on Database Shutdown checkbox.
  5. 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.

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
  2. Select the Endpoints tab, and then Settings from the left side bar..
  3. In the Global Endpoint Configuration Parameters page, set the Expire PKCS11 Persistent Cache on Database Shutdown checkbox.
  4. Click Save.

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

Version

Persistent master encryption key cache version

Unique ID

KMIP identifier assigned to the master encryption key

TDE Master Key Identifier

Database ID assigned to the master encryption key

Cache Start Time

Time at which the master encryption key was cached

Maximum Use Time

Time until the master encryption key expires, in seconds, from the moment that the key was placed into the persistent master encryption key cache

Maximum Refresh Window

Extended duration for which the master encryption key is available after it is cached in the persistent master encryption key cache

Status

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.

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.

Uploading the contents of a TDE wallet into Oracle Key Vault is a unique feature of Oracle Key Vault: If you plan to migrate the database to use Oracle Key Vault in online master key mode, then you must upload the wallet content before the migration step. That allows you to delete the file-based wallet after a successful migration from the database server, which is a requirement of the PCI-DSS. The upload operation uploads everything in the Oracle wallet, including security objects and their metadata so that the wallet can be reconstructed during the download process. The Oracle wallet typically contains TDE master encryption keys, historical TDE master encryption keys, SSL or TLS certificates and their metadata (stored in Oracle Key Vault as opaque objects), wallet metadata, as well as keys that you have explicitly added.
  1. Ensure that the server containing the Oracle wallet has been enrolled and provisioned as an Oracle Key Vault endpoint.
  2. Ensure that the endpoint has access to the virtual wallet that you want to use.

    The endpoint must have read, modify, and manage wallet access to the virtual wallet in Oracle Key Vault.

  3. Run the okvutil upload command to upload the wallet.

    For example:

    # okvutil upload -l "/etc/oracle/wallets" -t wallet -g "HRWallet"
Enter wallet password (<enter> for auto-login): password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password
Upload succeeeded

    In this example:

    • -l specifies the directory location of the wallet that you are uploading.

    • -t indicates the type, in this case, an Oracle wallet.

    • -g specifies the Oracle Key Vault virtual wallet that was configured in Step 2, so that this wallet can be part of that virtual wallet.

At this point, the upload is complete. You can now share the virtual wallet with other users and endpoints.

Related Topics

Parent topic: Uploading and Downloading Oracle Wallets

18.4.3 Downloading Oracle Wallets

The okvutil download command downloads an Oracle wallet from the Oracle Key Vault server to an endpoint.

  1. Ensure that the endpoint has Read access on the virtual wallet that you want to download.
  2. Run the okvutil download command to download the wallet.

    For example: 

    # okvutil download -l "/etc/oracle/wallets/orcl/" -t WALLET -g HRWallet
Enter new wallet password(<enter> for auto-login): Oracle_wallet_password
Confirm new wallet password: Oracle_wallet_password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password

    In this example:

    • -l is the location of the wallet to be created.

    • -t indicates the type, in this case, an Oracle wallet.

    • -g specifies the Oracle Key Vault virtual wallet that was configured in Step 1.

    If the wallet already exists and you did not use the -o parameter to overwrite the existing wallet, then the following actions take place:

    • The existing wallet is renamed to a backup name of the format ewallet.p12.current_timestamp where the timestamp is number of seconds since epoch.

    • The newly downloaded wallet is given the name ewallet.p12.

  3. Close and then reopen the wallet.

    Closing and reopening the wallet makes the wallet content, including TDE master keys, available on a database encrypted with TDE, and loads the wallet contents into the TDE database. (Auto-login wallets are automatically opened the next time that they are accessed.)

    • For Oracle Database 11g release 2: 

      ALTER SYSTEM SET ENCRYPTION WALLET CLOSE IDENTIFIED BY "Oracle_wallet_password"; 

ALTER SYSTEM SET ENCRYPTION WALLET OPEN IDENTIFIED BY "Oracle_wallet_password";

    • For Oracle Database 12c or later: 

      ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "Oracle_wallet_password";

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Oracle_wallet_password";
  4. If you are operating in a shared server configuration such as Oracle RAC, then restart the database.

Related Topics

Parent topic: Uploading and Downloading Oracle Wallets

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 and okvutil 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.

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.

  1. Ensure that the server containing the Java keystore has been enrolled and provisioned as an Oracle Key Vault endpoint.
  2. Ensure that access control has been configured for the endpoint.

    If you are uploading the keystore to a virtual wallet, then ensure that the endpoint has the read, modify, and manage wallet access to this virtual wallet.

  3. Run the okvutil upload command to upload the keystore.

    The following examples show how to upload the JKS and JCEKS keystore to a virtual wallet.

    This example shows how to upload a JKS keystore:

    # okvutil upload -l "/etc/oracle/fin_jks.jks" -t JKS -g "FinanceGrp"
Enter source Java keystore password: Java_keystore_password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password
Upload succeeded

    In this example:

    • -l is the location of the Java keystore that is being uploaded.

    • -t is the type of JKS or JCEKS keystore. Ensure that you upload the correct type of Java keystore when you upload and later on, when you download.

    • -g is the virtual wallet in Oracle Key Vault where the Java keystore contents will be uploaded.

    This example shows how to upload a JCEKS keystore:

    # okvutil upload -l "/etc/oracle/hr_jceks.jceks" -t JCEKS -g "HRGrp"
Enter source Java keystore password: password
Enter Oracle Key Vault endpoint password: password
Upload succeeded

At this point, the upload is complete. You are now ready to share or download the Java keystore as needed.

Related Topics

Parent topic: Uploading and Downloading JKS and JCEKS Keystores

18.5.3 Downloading JKS or JCEKS Keystores

The okvutil download command can download an uploaded JKS or JCEKS keystore.

  1. Ensure that the endpoint has the read access on the virtual wallet that you want to download.
  2. As an endpoint administrator, from the command line, run the okvutil download command to download the Java keystore.

    For example: 

    # okvutil download -l "/etc/oracle/new_java_files/hr_jceks.jceks" -t JCEKS -g FinanceGrp
Enter new Java keystore password: password
Confirm new Java keystore password: password
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password

    In this example:

    • -l is the directory to which you want to download the uploaded Java keystore.

    • -t is the type of JKS or JCEKS keystore. Ensure that you download the correct type of Java keystore.

    • -g is the name of the object to download, which in this case is the JKS keystore FinanceGrp.

Related Topics

Parent topic: Uploading and Downloading JKS and JCEKS Keystores

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 and okvutil 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.

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.2 Uploading a Credential File

The okvutil upload command can upload credential files.

  1. Ensure that the server that contains the credential file has been enrolled and provisioned as an Oracle Key Vault endpoint.
  2. Ensure that access control has been configured for the endpoint.

    If you are uploading the credential file to a virtual wallet, then ensure that the endpoint has read, modify, and manage wallet access to the wallet.

  3. Run the okvutil upload command.

    For example: 

    # okvutil upload -l "/etc/oracle/app/creds/hr.keytab" -t kerberos -g HRWallet -d "Kerberos keytab file for HR group, 06_11_14"
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password

    In this example:

    • -l is the directory path to the hr.keytab credential file, which is being uploaded. Enclose the directory location in double quotation marks.

    • -t specifies the type of credential file, which in this example is a Kerberos keytab file. In addition to KERBEROS, other types that you can specify are as follows:

      • SSH for an SSH key file

      • OTHER for other files that store secrets, such as uploaded or downloaded files

    • -g adds the credential file to the HRWallet group, which must already exist. This parameter enables you to upload the credential to a wallet that is specifically for the HR application users' needs, rather than to the default virtual wallet. In this example, HRWallet is the Oracle Key Vault virtual wallet to which access control was configured in Step 2.

    • -d is an optional description. As a best practice, include a brief description of what the credential file is used for and the date you performed the upload. This information helps for future reference and tracking of the credential file. You can modify this description later on in the Oracle Key Vault management console if necessary.

Related Topics

Parent topic: Uploading and Downloading Credential Files

18.6.3 Downloading a Credential File

The okvutil download command can download credential files.

  1. Find the unique ID of the credential file that you must download, by using one of the following methods:

    • Oracle Key Vault management console: Log in as an endpoint administrator or a user who has the necessary access to the virtual wallet. In the Oracle Key Vault management console, from the Keys & Wallets tab, select All Items to find the uploaded files. Note the unique ID of the uploaded file that you want to download. Credential files are listed as opaque objects.

    • okvutil list command: Run the okvutil list command from an endpoint that has access to the credential file or a virtual wallet that contains the credential file. Locate the unique ID of the credential file that you must download based on the description that you provided when you uploaded the file.

  2. From the command line, run the okvutil download command to download the credential file.

    For example: 

    # okvutil download -l "/etc/oracle/app/newcreds/hr.keytab" -t kerberos -i 6ba7b810-9dad-11d1-80b4-00c04fd430c8
Enter Oracle Key Vault endpoint password: Key_Vault_endpoint_password

    In this example:

    • -l is the directory to which you want to download the uploaded credential.

    • -t specifies the type of credential file, which in this example is a Kerberos keytab file. In addition to KERBEROS, other types that you can specify are as follows:

      • SSH for an SSH key file

      • OTHER for other files that store secrets, such as uploaded or downloaded files

    • -i is the unique ID of the credential file.

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 and okvutil 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 the okvutil 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.

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

Parent topic: Using a User-Defined Key as the TDE Master Encryption Key

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.

  1. Create a text file containing the raw bytes data of the user-defined key.

    Use the following format:

    TDE Master Encryption Key Identifier: contiguous_TDE_Master_Encryption_Key_Identifier_bytes_encoded_in_32_hex_characters_(16_bytes_long)
TDE Master Encryption Key: contiguous_TDE_Master_Encryption_Key_bytes_encoded_in_64_hex_characters_(32_bytes_long)

    For example:

    TDE Master Encryption Key Identifier: 1F1E1D1C1B1A10191817161514131210
TDE Master Encryption Key: 000102030405060708090A0B0C0D0E0F101112131415161718191A1B1C1D1E1F
  2. Save the file as tde_key_bytes.txt.
  3. Use the okvutil upload command to upload tde_key_bytes.txt.

    The format of the okvutil upload command is: 

    okvutil upload [--overwrite] --location location --type type [--group group] [--
description description] [--verbose verbosity_level]

    Example:

    $OKV_HOME/bin/okvutil upload -l /home/oracle/tde_key_bytes.txt -t TDE_KEY_BYTES -g "FIN_DATABASE_VIRTUAL_WALLET" -d "This key was created for Financial database use on 1st Mar 2019"

    In this example:

    • -l specifies the path to the tde_key_bytes.txt file.

    • -t specifies the type of the object to upload. To upload a user-defined key, specify the type as TDE_KEY_BYTES.

    • -g specifies the name of an Oracle Key Vault virtual wallet to which the key is added.

    • -d specifies a description for the key.

    When -t is TDE_KEY_BYTES, the description specified for –d is displayed as the tag in the V$ENCRYPTION_KEYS dynamic view.
  4. Specify the required parameters and then press Enter.
  5. Enter the Oracle Key Vault endpoint password and press Enter.
    The message Upload succeeded is displayed.
    $OKV_HOME/bin/okvutil upload -l /home/oracle/tde_key_bytes.txt -t TDE_KEY_BYTES -g "FIN_DATABASE_VIRTUAL_WALLET" -d "This key was created for Financial database use on 1st Mar 2019" 
Enter Oracle Key Vault endpoint password:
Upload succeeded
The raw bytes data of the user-defined key is uploaded. The next step is to activate the user-defined key as a TDE master encryption key.

Related Topics

Parent topic: Using a User-Defined Key as the TDE Master Encryption Key

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.

  1. Log in to the Oracle Key Vault management console as a user with the Key Administrator role or as a user with access to the virtual wallet.
  2. Click the Keys & Wallets tab.
    The Wallets page appears.
  3. Click All Items in the left sidebar.
    The All Items page appears displaying all the security objects in Oracle Key Vault.
  4. Click the pencil icon in the Details column corresponding to the user-defined key.
    The Item Details page appears displaying the attributes of the key.
  5. Click Advanced to view the cryptographic attributes of the key.

    The required Key ID is displayed. The Key ID is prefixed with ORACLE.TDE.HSM.MK.

    For example:

    ORACLE.TDE.HSM.MK.061F1E1D1C1B1A10191817161514131210

    The TDE master encryption key identifiers contain the user defined raw bytes data prefixed by additional metadata.

  6. Copy and store the key ID displayed after the prefix ORACLE.TDE.HSM.MK

    For example:

    061F1E1D1C1B1A10191817161514131210
  7. Connect to the database as a user who has privileges to run the ADMINISTER KEY MANAGEMENT SQL statement.
    For example: 
    sqlplus / as sysdba
  8. Activate the key as a TDE master encryption key using the ADMINISTER KEY MANAGEMENT command.
    ADMINISTER KEY MANAGEMENT USE KEY '061F1E1D1C1B1A10191817161514131210' IDENTIFIED BY "password";

    You can query the TAG column of the V$ENCRYPTION_KEYS view for the identifier of the newly created key.

Parent topic: Using a User-Defined Key as the TDE Master Encryption Key