The sqlnet.ora file enables the migration of existing TDE wallets to Oracle Key Vault.

For Oracle Database release 12.2.0.1 or earlier, the sqlnet.ora file enables the migration of existing TDE wallets to Oracle Key Vault. For Oracle Database release 18c or later, you must set the parameters TDE_CONFIGURATION and WALLET_ROOT to migrate wallets to Oracle Key Vault.

When the Transparent Data Encryption (TDE) wallets already exist, you must modify the sqlnet.ora file or the TDE_CONFIGURATION parameter 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 on an Oracle Real Application Clusters (Oracle RAC) configuration, ensure that you migrate from a shared TDE wallet (in Oracle Automatic Storage Management (Oracle ASM) or Oracle Advanced Cluster File System (Oracle ACFS)) to Oracle Key Vault. Individual wallets for each Oracle RAC node are not supported.

You can use the okvutil upload command to start the migration of a TDE-enabled database from an existing TDE wallet to Oracle Key Vault.

1. Back up the database 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 allows you to delete the wallet after a successful migration, which is often a requirement of security policies that do not allow encryption keys on the encrypting server.

   Be aware that the Extractable attribute setting for the objects that are created in Oracle Key Vault using okvutil upload is inherited from the endpoint. You can download the wallet, but if the wallet's objects have the Extractable attribute set to FALSE, then those objects cannot be downloaded.

4. Configure the wallet location.
   • For Oracle Database release 12.2.0.1 or 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 or later: Set the TDE_CONFIGURATION parameter.

      ALTER SYSTEM SET TDE_CONFIGURATION = "KEYSTORE_CONFIGURATION=OKV|FILE" SCOPE = BOTH;

     The WALLET_ROOT parameter is already set, 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 or 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 CON_ID, WALLET_TYPE, WALLET_ORDER, STATUS 
   FROM V$ENCRYPTION_WALLET 
   WHERE CON_ID <> 2;

   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, run 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 run the following statement in SQL*Plus:

      ALTER SYSTEM SET WALLET CLOSE IDENTIFIED BY "wallet_password";

   2. In SQL*Plus, 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, run 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 run this statement:

     ALTER SYSTEM SET ENCRYPTION KEY 
     IDENTIFIED BY "NULL" 
     MIGRATE USING "wallet_password";

   • For Oracle Database 12c or later: As a user who has been granted the SYSKM administrative privilege:

     ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "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 or 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.

You perform the restoration process on the endpoint where you downloaded the Oracle wallet.

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

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, and it supports security objects up to 128 KB in size. 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.

Be aware that the Extractable attribute setting for the objects that are created in Oracle Key Vault using okvutil upload is inherited from the endpoint. You can download the wallet, but if the wallet's objects have the Extractable attribute set to FALSE, then those objects cannot be downloaded.

The okvutil upload command uploads wallets to Oracle Key Vault.

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.

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

1. Ensure that security objects in the wallet have an extraction status of TRUE.

   If the object has Extractable attribute setting of FALSE, then you cannot download it. You can check the Extractable attribute setting by navigating to the Object Details page. Select the Keys & Wallets tab, then in the left navigation bar, select Keys & Secrets, then for the key listed, select the Edit icon. The Extractable attribute setting is listed in the Advanced section.

2. Ensure that the endpoint has Read access on the virtual wallet that you want to download.
3. 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 2.

   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.

4. Close and then reopen the wallet.

   Closing and reopening the wallet makes the wallet content, including TDE master encryption 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";
     

5. If you are operating in a shared server configuration such as Oracle RAC, then restart the database.

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.

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, and it supports an item up to 128 KB in size.

Be aware that the Extractable attribute setting for the objects that are created in Oracle Key Vault using okvutil upload is inherited from the endpoint. You can download the JKS and JCEKS keystore, but if this keystore's objects have the Extractable attribute set to FALSE, then those objects cannot be downloaded.

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 or 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
   

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

1. Ensure that security objects in the JKS or JCEKS keystore have an Extractable attribute setting of TRUE.

   If the object has Extractable attribute setting of FALSE, then you cannot download it. You can check the Extractable attribute setting by navigating to the Object Details page. Select the Keys & Wallets tab, then in the left navigation bar, select Keys & Secrets, then for the key listed, select the Edit icon. The Extractable attribute setting is listed in the Advanced section.

2. Ensure that the endpoint has the read access on the virtual wallet that you want to download.
3. 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 HRGrp
   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 HRGrp.

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.