Previous Next JavaScript must be enabled to correctly display this content

## TDE Keys on Oracle Key Vault for TDE-Enabled Databases

Understand general FAQs on storing TDE keys on Oracle Key Vault for TDE-enabled databases on Oracle Database Appliance.

What is Oracle Key Vault server configuration?

Oracle Key Vault server configuration is an Oracle Database Appliance entity which represents the metadata about the Oracle Key Vault server such as the IP address, host name, the user name, and a brief description about the Oracle Key Vault server. The Oracle Key Vault user password must be provided while creating the Oracle Key Vault server configuration object. The client auto-login wallets are generated with the specified passwords.

What are the four different ways of creating a TDE-enabled database on Oracle Database Appliance which uses Oracle Key Vault to store TDE keys?

Oracle Database Appliance supports the following two ways of creating TDE enabled database that uses Oracle Key Vault to store TDE keys:

- Create TDE-enabled databases using Oracle Key Vault with endpoints in Oracle Key Vault: The virtual wallet and the endpoints are not created by Oracle Database Appliance tooling but created by the user, on Oracle Key Vault server. Oracle Database Appliance tooling only expects the user to specify the okvclient.jar file corresponding to the created endpoint during database creation.
- Create TDE-enabled databases with user credentials: In this case, the virtual wallet and the endpoints are created by Oracle Database Appliance tooling, on Oracle Key Vault server. The user must create an Oracle Key Vault server configuration corresponding to the required Oracle Key Vault server and specify it during database creation.
- Create and Restore TDE-enabled databases manually and register it with Oracle Database Appliance using Oracle Key Vault server configuration object: The database can be either created or restored manually from backups such that it uses Oracle Key Vault to store the TDE keys and then it can be registered using Oracle Key Vault server configuration object. While registering the database using Oracle Key Vault server configuration, the current TDE password must be provided, so that Oracle Database Appliance tooling can change it to a new random password. This new random password is managed by Oracle Database Appliance tooling and is not known to the user.
- Create and Restore TDE-enabled databases manually and register it with Oracle Database Appliance without using Oracle Key Vault server configuration object: The database can be either created or restored manually from backups such that it uses Oracle Key Vault to store the TDE keys and then it can be registered without using Oracle Key Vault server configuration object. Registering the database without using Oracle Key Vault server configuration does not change the current TDE password.

How do I get to know the keystore type of my TDE database?

The `keystoreType` parameter value in the output of `odacli describe-database -n dbname -j` command displays the type of the keystore used by the TDE database.

How do I identify whether a TDE-enabled database is using software keystore or Oracle Key Vault for TDE configuration?

If the `keystoreType` attribute of the database has value `software`, then it means software keystore was used to configure TDE. Else, if the same attribute has OKV as its value, then it means Oracle Key Vault was used to configure TDE.

When should I choose the option of creating TDE-enabled databases using Oracle Key Vault with endpoints in Oracle Key Vault?

If you do not want to use Oracle Key Vault user credentials in Oracle Database Appliance, then you can use the option of creation of TDE-enabled databases that use pre-created virtual wallet and endpoints.

When should I choose the option of creating TDE-enabled databases using Oracle Key Vault with credentials of the user on Oracle Key Vault?

If you want Oracle Database Appliance to interact with Oracle Key Vault directly using the credentials of the Oracle Key Vault user to create virtual wallets and endpoints, then use this option.

Which user can create Oracle Key Vault server configuration?

In multi-user access or multi-user access-passwordless enabled systems, the odaadmin user and users with the ODA-OKVCONFIGADMIN role can create the Oracle Key Vault server configuration. The Oracle Key Vault server configuration can then be shared with the required DB user, that is, user with the ODA-DB role, with only odaadmin so that DB user can create TDE database using the shared Oracle Key Vault server configuration object. This ensures that the Oracle Key Vault server credentials used in creating the Oracle Key Vault server configuration object is not shared with the DB user. However, in case of multi-user access enabled systems, the Oracle Key Vault server configuration is created by the same user who creates the database.

When the database is created using Oracle Key Vault server configuration, Oracle Database Appliance tooling generates a random password and stores it in the wallet on the Oracle Key Vault server. The format of the name of the wallet is db_unique_name_pass_on_oda-cluster-name. This wallet is not deleted when the database is deleted.

Can a TDE database that uses software keystore be converted to use Oracle Key Vault?

Yes. See the Oracle Database Appliance Deployment and User Guide for your hardware model to view the manual steps to migrate from software keystore to Oracle Key Vault. Migration using ODACLI is not supported.

What is the Oracle Key Vault Server port number that must be opened for Oracle Database Appliance to communicate with it?

Oracle Database Appliance relies on port number 5695 to communicate with Oracle Key Vault server. Ensure that port number 5695 is opened on the Oracle Key Vault server so that Oracle Database Appliance can communicate with it.

What is the version of Oracle Key Vault server that Oracle Database Appliance recommends?

Oracle Database Appliance recommends the version of the Oracle Key Vault server to be 21.10.

What are the database versions that support Oracle Key Vault feature on Oracle Database Appliance?

The Oracle Key Vault feature on Oracle Database Appliance is supported with Oracle Database 19c, on both bare metal and DB systems.

What are the database lifecycle management operations available on Oracle Database Appliance, but not supported for TDE databases that use Oracle Key Vault to store TDE keys?

Database lifecycle management operations such as cloning, upgrading, and registering databases are currently not supported for TDE databases that use Oracle Key Vault to store TDE keys.

Should I provide TDE password while creating the database that uses Oracle Key Vault to store TDE keys?

No, the TDE password is not required. The TDE password is randomly generated by Oracle Database Appliance tooling. The TDE password must be provided while creating the database with endpoints and wallet manually created on Oracle Key Vault.

Once the user with ODA-DB role is granted access to the Oracle Key Vault server configuration object, can they delete the Oracle Key Vault server configuration object?

No, the Oracle Key Vault server configuration object can only be deleted by the user who created it or the odaadmin user. The user with ODA-DB role can only use the shared Oracle Key Vault server configuration object and create TDE database but not delete the shared Oracle Key Vault server configuration object. Also, the database that used the Oracle Key Vault server configuration object during creation, must be deleted before deleting the Oracle Key Vault server configuration object.

Does Oracle Database Appliance tooling support backup and recovery of TDE wallet of a database which uses Oracle Key Vault to store TDE keys?

No, Oracle Database Appliance tooling does not support backup and recovery of TDE wallet since the TDE wallet is present outside the Oracle Database Appliance system, in an Oracle Key Vault server. The OKV ADMIN of the Oracle Key Vault server have to manage the backup and recovery of TDE wallet. When you select Oracle Key Vault server, you have the option of TDE wallet management outside the client, in an Oracle Key Vault server.

Does Oracle Database Appliance tooling identify whether the given Oracle Key Vault credentials belong to a user who has the least privilege of `Create Endpoint` on Oracle Key Vault server ?

No, Oracle Database Appliance tooling does not identify whether the given Oracle Key Vault credentials belong to a user who has the least privilege of `Create Endpoint` on Oracle Key Vault server. Ensure that you use the credentials of the least privileged user. This least privilege of `Create Endpoint` is recommended so that the given credentials can only be used to onboard the database on to the Oracle Key Vault server and no other operations are performed on the Oracle Key Vault server.

Why do I need to create a copy of the TDE wallet before restoring a TDE database with Oracle Key Vault keystore?

Oracle Database Appliance tooling does not support backup, recovery, and restore of the TDE wallet if the wallet is stored in the Oracle Key Vault server because the wallet is present outside the appliance. However, if you are restoring the database as a standby in an Oracle Data Guard configuration, then you must specify the wallet of the primary database.

Is NTP configuration required on Oracle Database Appliance to create a database with TDE configuration using Oracle Key Vault?

It is recommended to set up NTP on Oracle Database Appliance because the database creation or restore operation may fail if the clock on Oracle Database Appliance and the Oracle Key Vault server are not synchronized. Hence, you must ensure that the time is consistent across the servers or use NTP on Oracle Database Appliance. While using an NTP server, ensure that the server is reachable from the appliance and that the chrony settings in the `/etc/chrony.conf` file are the same on Oracle Database Appliance and the Oracle Key Vault server.

Why does re-key of TDE wallet fail with `ORA-28353: failed to open wallet` error?

The error code ORA-28353 could be due to incorrect TDE password. Retry the operation with the correct TDE password to resolve the issue. For more information about this error, see the Oracle Database Error Messages Guide at https://docs.oracle.com/en/database/oracle/oracle-database/19/errmg/ORA-24280.html.

Why does creation of a database with TDE configuration using Oracle Key Vault as keystore fail with an error?

You may encounter the following error:

    Internal error encountered: PL/SQL procedure successfully completed.begin
    *
    ERROR at line 1:
    ORA-00600: internal error code, arguments: [kcbtse_populate_tbskey_1], [The
    request operation was denied.], [], [], [], [], [], [], [], [], [], []
    ORA-06512: at line 2.

Creation of the database may fail with the above error, when setting the TDE master encryption key. This error is caused when the clock on the appliance is not synchronized with the clock on the Oracle Key Vault server, causing a lag between the time on Oracle Database Appliance and the Oracle Key Vault server. Due to the lag, the time at which the command to set the TDE master encryption key for the database is run does not match with the time on the Oracle Key Vault server, causing the operation to fail. To synchronize the clocks, set up NTP on Oracle Database Appliance. While setting up NTP, ensure that the NTP server is reachable from Oracle Database Appliance, and that the chrony settings are the same on Oracle Database Appliance and the Oracle Key Vault server.
Run the following commands to set up NTP manually:

    systemctl stop chronyd

    cat /etc/chrony.conf
    server Enter NTP server IP address iburst
    driftfile /var/lib/chrony/drift
    makestep 1.0 -1
    rtcsync
    logdir /var/log/chrony

    systemctl start chronyd

    systemctl enable chronyd

Why does creation of a database with TDE configuration using Oracle Key Vault as keystore fail with an error?

You may encounter the following error:

    { "result" : "Failure", "message" : "Error occurred during install of Oracle Key Vault endpoint software. Check log files for more information. Please cleanup all of the files and directories created by the failed installation attempt before re-install" }.

Creation of the database may fail with the above error, when setting the TDE master encryption key . This error is caused when the clock on the appliance is not synchronized with the clock on the Oracle Key Vault server, causing a lag between the time on Oracle Database Appliance and the Oracle Key Vault server. Due to the lag, the certificate generated for the Oracle Key Vault endpoint is not valid when the command to install the endpoint software is run on Oracle Database Appliance, causing the operation to fail. To synchronize the clocks, set up NTP on Oracle Database Appliance.
Run the following commands to set up NTP manually:

    systemctl stop chronyd

    cat /etc/chrony.conf
    server Enter NTP server IP address iburst
    driftfile /var/lib/chrony/drift
    makestep 1.0 -1
    rtcsync
    logdir /var/log/chrony

    systemctl start chronyd

    systemctl enable chronyd

How is TDE password handled when the database is created with endpoints in Oracle Key Vault and when the database is created with user credentials?

When the database is created with endpoints in Oracle Key Vault, Oracle Database Appliance requires you to provide the TDE password. This password is not known to Oracle Database Appliance and the same password must be provided while performing operations such as rekey and change of TDE password. When the database is created with user credentials, the TDE password is randomly generated by Oracle Database Appliance tooling and is not known to the user. This password is stored in a wallet on the Oracle Key Vault server. You need not specify any TDE password while performing operations such as rekey and change of TDE password.

Registering TDE enabled database that uses Oracle Key Vault to store TDE keys using Oracle Key Vault server configuration is failing with the `ORA-28353: failed to open wallet` error.

This error may occur when an incorrect TDE password is specified. Ensure that you specify the correct TDE password when registering the database and then retry the operation.

A TDE enabled database that uses Oracle Key Vault to store TDE keys was first registered using Oracle Key Vault server configuration. Later, when the same database is re-registered using the same Oracle Key Vault server configuration and the same TDE password, it fails with the `DCS-12737:Failure to change the TDE password for the database wallet '/etc/OKV/db_unique_name/okv/ssl'` error.

When the Oracle Key Vault TDE database is registered using Oracle Key Vault server configuration, its current TDE password is changed to a new random password by the Oracle Database Appliance tooling. This new random password must be specified while re-registering the database using Oracle Key Vault server configuration. The random password generated by Oracle Database Appliance tooling is stored in a wallet created on the Oracle Key Vault server. Following are the steps to retrieve the stored random password. After the password is retrieved, the re-register operation using Oracle Key Vault server configuration can be retried using the retrieved password. For non-multi user access enabled environment, switch to the `oracle` user. For multi-user access enabled and multi-user passwordless environment, switch to the Oracle Key Vault user.

Re-enroll the password store endpoint whose name will be of the format db_name_pass_on_cluster_name. This endpoint uses the password store wallet where the random password is stored, as the default wallet.

     /etc/OKV/okv_server_config_name/bin/okv admin endpoint re-enroll --endpoint db_name_pass_on_cluster_name

Download the `okvclient.jar` file corresponding to the endpoint db_name_pass_on_cluster_name to some temporary location, for example, `/tmp`.

    /etc/OKV/<okv_server_config_name>/bin/okv admin endpoint download --endpoint db_name_pass_on_cluster_name --location /tmp

Go to the temporary location where the `okvclient.jar` file is downloaded and install the endpoint. When prompted for the password, press Enter.

    cd /tmp/db_name_pass_on_cluster_name

        /opt/oracle/dcs/java/1.8.0_xxx/bin/java -jar okvclient.jar
        Detected JAVA_HOME: /opt/oracle/dcs/java/1.8.0_xxx
        Enter new Key Vault endpoint password (enter for auto-login):
        The endpoint software for Oracle Key Vault installed successfully.
        Deleted the file : /tmp/db_name_pass_on_cluster_name/okvclient.jar

Run the following command by replacing the appropriate value to retrieve the UUID corresponding to the stored TDE password.

    /etc/OKV/okv_server_config_name/bin/okv managed-object object locate --okv_client_config /tmp/db_name_pass_on_cluster_name/conf/okvclient.ora --output_format "TEXT" --state "ACTIVE" --custom-attribute '[{"name": "x-REFRESH_STATE", "value": "0"}, {"name": "x-key", "value": "db_resource_id-db_unique_name"}]'

Retrieve the TDE password corresponding to the UUID.

    /etc/OKV/okv_server_config_name/bin/okv managed-object secret get --output_format "TEXT" --okv_client_config /tmp/db_na

When should the endpoints of a database be updated?

The endpoints of a database must be updated whenever the Oracle Key Vault server where the corresponding TDE wallet is present is updated to newer version and whenever the certificates on the Oracle Key Vault server is updated.

Can the endpoints of selective databases among the list of Oracle Key Vault TDE databases created in the system be updated?

Yes, only those databases whose endpoints must be updated can be mentioned in Oracle Key Vault client JSON file, which is used as input in Update Endpoints request.

Why does the overall status of the update endpoints job says 'Success' even though Update endpoints tasks has failed for some databases?

To ensure that the update endpoints job is run for all specified databases, even if there is failure for some databases in between the job run, the overall status of the job is marked as 'Success'.

Update endpoint job of some databases have passed and some have failed. What should I do to update the endpoints of those failed database?

Remove entries corresponding to successful databases in the input Oracle Key Vault Client JSON file and keep the entries corresponding to failed databases only and then retry the operations. Before retrying, make sure the endpoints are re-enrolled and the new 'Oracle Key Vaultclient.jar' corresponding to the re-enrolled endpoints are specified in the Oracle Key Vault client JSON file.

What are Oracle Key Vault PKCS library and Oracle Key Vault REST Client library?

The Oracle Key Vault PKCS library (liborapkcs.so) present at '/opt/oracle/extapi/64/hsm/oracle/1.0.0/' location is to communicate with the Oracle Key Vault Server. Oracle Key Vault REST Client library (Oracle Key Vaultrestcli.jar) present at '/etc/Oracle Key Vault/<Oracle Key Vault_server_config_name>/lib' location is used to make REST API calls to the Oracle Key Vault Server.

When should the Oracle Key Vault PKCS library and Oracle Key Vault REST Client library be updated?

The Oracle Key Vault PKCS library and Oracle Key Vault REST Client library must be updated only when the corresponding Oracle Key Vault Server is updated to a later version.

There are no Oracle Key Vault Server Config objects created in the system. Is it necessary to update the Oracle Key Vault REST Client library?

If there are no Oracle Key Vault Server Config objects created in the system, then the update Oracle Key Vault endpoints job will skip the task of updating the Oracle Key Vault REST Client library.

Why is database restart required while updating the Oracle Key Vault PKCS library?

Since the Oracle Key Vault PKCS library is shared by all Oracle Key Vault TDE databases present in the system, a database restart is required after updating the Oracle Key Vault PKCS library.

Is it mandatory to update all endpoints available in the system before updating the Oracle Key Vault PKCS library?

Yes, it is mandatory to update all endpoints available in the system before updating the Oracle Key Vault PKCS library.

When should I register a database using Oracle Key Vault server configuration?

If the TDE password must be handled by Oracle Database Appliance tooling itself and not by the user, then the database can be registered using Oracle Key Vault server configuration. The current TDE password will be changed to a new random password by Oracle Database Appliance tooling internally.

When should I register a database without using Oracle Key Vault server configuration?

If the TDE password need not be handled by Oracle Database Appliance tooling and user would be handling the TDE password themselves, then the database can be registered without using Oracle Key Vault server configuration. The TDE password will not be changed during the register operation.

An Oracle Key Vault TDE database is already registered with Oracle Key Vault server configuration. Can it be re-registered with or without Oracle Key Vault server configuration?

Once the database is registered with Oracle Key Vault server configuration, its TDE password will be changed to a new random password which will be maintained by Oracle Database Appliance tooling and not known to the user. Since current TDE password is unknown, such databases cannot be Re-Registered, with or without Oracle Key Vault server configuration.

An Oracle Key Vault TDE database is already registered without Oracle Key Vault server configuration. Can it be re-registered again with or without Oracle Key Vault server configuration?

Yes, an Oracle Key Vault TDE database which was registered without Oracle Key Vault server configuration can be re-registered with or without Oracle Key Vault server configuration. However when registered with Oracle Key Vault server configuration, the current TDE password will be changed to a new random password which will be maintained by Oracle Database Appliance tooling and not known to the user.

Is high availability enabled for single-instance Oracle Key Vault TDE database being registered on Oracle Database Appliance high availability system?

No. By default, high availability is not enabled for single-instance Oracle Key Vault TDE database being registered on Oracle Database Appliance high availability system.

How can I identify whether the database was earlier registered with or without Oracle Key Vault server configuration object?

If the Oracle Key `VaultServerConfigName` database attribute is set to the name of the Oracle Key Vault server configuration object that was used during database register operation, then the database was registered with Oracle Key Vault server configuration object. If the Oracle Key `VaultServerConfigName` database attribute is set to `NONE`, then the database was registered without Oracle Key Vault server configuration object.

Before registering the Oracle Key Vault TDE database, can the endpoint software files be copied from the existing location to the required /etc/Oracle Key Vault/<db_unique_name>/Oracle Key Vault location?

No, the endpoint software files must be installed again at the location /etc/Oracle Key Vault/<db_unique_name>/Oracle Key Vault and not copied, before registering.

After registering an Oracle Key Vault TDE database with the Oracle Key Vault server configuration object, an external store autologin wallet (cwallet.sso) is created in the /etc/Oracle Key Vault/db_unqiue_name/tde_seps location by Oracle Database Appliance tooling. Why is it created? Can it be deleted?

The external store autologin wallet is created while registering an Oracle Key Vault TDE database with Oracle Key Vault server configuration object, which is similar to creating the Oracle Key Vault TDE database with Oracle Key Vault server object. It is created because Oracle Database Appliance tooling would be using the clause 'identified by EXTERNAL STORE' and not the actual TDE password identified by `tde_password` in running Administer Key Management commands. This External Store Autologin wallet should not be deleted since its deletion would cause the TDE operations such as rekey through Oracle Database Appliance tooling to fail.

When the command to create a TDE enabled database that uses Oracle Key Vault to store TDE keys, using Oracle Key Vault server configuration object is used, it does not respond. What could be the cause?

The unresponsiveness of the odacli create-database command could be because of the issue where DNS is configured in the Oracle Key Vault server and the IP address is not resolved. Check whether the DNS configured in Oracle Key Vault server is working as expected. If not, then rectify the issue with the DNS and retry the operation. If DNS is working as expected and the issue is observed, contact Oracle Support.

Troubleshooting Oracle Database Appliance

Parent topic: Oracle Database Appliance Frequently Asked Questions