Migrating Oracle TDE from Third-Party HSM to Fortanix DSM

1.0 Introduction

Oracle Transparent Data Encryption (TDE) protects data at rest (database files, redo logs, and backups) using a two-tier key architecture consisting of Data Encryption Keys (DEKs) and a Master Encryption Key (MEK). By default, the master key is stored in a local file-based wallet; however, organizations seeking stronger security and centralized key management can integrate Oracle TDE with Fortanix-Data-Security-Manager (DSM).

Fortanix DSM enables externalized, centrally managed encryption keys backed by a FIPS-compliant platform, allowing enterprises to securely store and control Oracle TDE master keys outside the database environment. This approach enhances security, simplifies key lifecycle management, and helps meet regulatory compliance requirements, while maintaining transparent encryption for tablespaces and columns with minimal application impact, making it well-suited for high-performance environments such as Oracle Exadata deployments.

This article describes the procedure to migrate Oracle TDE from other third-party Hardware Security Modules (HSMs) to Fortanix DSM.

2.0 Migrating TDE Master Key from Third-Party HSM to Fortanix DSM

Before performing the steps for migrating the TDE master key, it is assumed that Oracle Database TDE is configured with a third-party HSM wallet for accessing the master key.

Perform the following steps:

Create a group and application in Fortanix DSM. For detailed information, refer to Section 5.0: Configure Fortanix DSM in Using Fortanix Data Security Manager with Oracle TDE - Introduction.
Migrate the TDE master encryption key from the third-party HSM keystore to the local file-based keystore. For more information, refer to Section 2.1: Reverse Migration: HSM Wallet to Local File System Wallet.
Remove the existing third-party HSM PKCS#11 library from the Oracle environment. For more information, refer to Section 2.2: Remove Third-Party HSM PKCS#11 Library.
Configure the Fortanix DSM PKCS#11 library and pkcs11.conffile. For more information, refer to Section 2.3: Configure Fortanix DSM PKCS#11 Library and pkcs11.conf File.
Migrate the TDE master encryption key from the local file-based keystore to Fortanix DSM. For more information, refer to Section 2.4: Forward Migration: Local Wallet to Fortanix DSM.

2.1 Reverse Migration: HSM Wallet to Local File System Wallet

Perform the following steps to migrate the TDE master encryption key from the third-party HSM keystore to the local file-based keystore:

Run the following command to verify the wallet status:
```
select * from v$encrypton_wallet;
```
Run the following commands to rename the autologin wallet file:
```
cd <wallet_root_path>/tde 
mv cwallet.sso cwallet.sso_backup
```
Run the following command to restart the database:
```
sqlplus / as sysdba
Shut immediate
startup
```

Run the following command to open the wallet:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY 
"<existing HSM Password>" CONTAINER=ALL;

Run the following command to set the wallet method TDE_CONFIGURATION as FILE:
```
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE";
```

Run the following command to perform the reverse migration:

ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<existing HSM Password>" REVERSE MIGRATE USING "<DSM_APP_PASSWORD>" WITH BACKUP USING 'NewWallet';

Run the following command to validate the keystore status. The file-based keystore must be in the OPEN state for all containers.
```
Select * from v$encrypton_wallet;	
```
At this stage, the TDE master encryption key has been successfully migrated from the third-party HSM keystore to the local file-based keystore.
To maintain consistency, update the keystore password to match the Fortanix DSM application (app) password created in Step 1 in Section 2.0: Migrating TDE Master Key from Third-Party HSM to Fortanix DSM.
```
ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY "<existing HSM Password>" set "<DSM_APP_PASSWORD>" with BACKUP;
```

2.2 Remove Third-Party HSM PKCS#11 Library

Perform the following steps to remove the third-party HSM PKCS#11 library from the Oracle environment:

Run the following command to shut down the database:
```
Sqlplus / as sysdba
Shut immediate
```
The third-party PKCS#11 library is located at: /opt/oracle/extapi/64/hsm/<3rd_party_vendor>/x.xx.xxxx/libpkcs11.so.
Run the following command to remove or relocate the existing library directory to prevent conflicts with the Fortanix DSM PKCS#11 library:
```
mv /opt/oracle/extapi/64/hsm/<3rd_party_vendor> /tmp
```
or
```
rm -rf /opt/oracle/extapi/64/hsm/<3rd_party_vendor>
```

2.3 Configure Fortanix DSM PKCS#11 Library and pkcs11.conf File

Perform the following steps to configure the Fortanix DSM PKCS#11 library and the pkcs11.conf file for Oracle TDE integration:

Fortanix provides a PKCS#11 library (.so file) as a connector for the Oracle database integration, which can be downloaded from here.
Copy the downloaded Fortanix library file to the /opt/oracle/extapi/64/hsm/fortanix/<pkcs_lib_version> directory structure.
For example, if your library version is 4.34.2503, then run the following command to create the directory and copy the downloaded library file:
```
sudo mkdir -p /opt/oracle/extapi/64/hsm/fortanix/4.34.2503
```
Run the following commands to copy the Fortanix library file to the location above, and name it as libpkcs11.so:
```
cp fortanix_pkcs11_4.34.2503.so
/opt/oracle/extapi/64/hsm/fortanix/4.34.2503/libpkcs11.so
```
Run the following commands to set the permissions and ownership of the folder:
```
sudo chown -R oracle:oinstall /opt/oracle
sudo chmod -R 775 /opt/oracle
```
Run the following commands to create the directory for pkcs11.conf file. The default location must be /etc/fortanix.
```
sudo mkdir -p /etc/fortanix
sudo chown -R oracle:oinstall /etc/fortanix
sudo chmod -R 775 /etc/fortanix
```
If the requirement is to use a custom location, then set the environment variable FORTANIX_PKCS11_CONFIG_PATH for the path of the custom location.
For example,
```
export FORTANIX_PKCS11_CONFIG_PATH=/u01/app/oracle/fortanix/pkcs11.conf
```
Run the following command to create the configuration file pkcs11.conf under the /etc/fortanix folder with the following parameters:
```
api_endpoint = "https://<fortanix_dsm_url>"
app_id = "<app id created in step #1>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 60000
[log]
file = "<log filename>"
```
Where,
- api_endpoint is the URL endpoint of the Fortanix DSM installation.
- app_id is the app UUID obtained from the Fortanix DSM user interface (UI) after creating the app in Step 1 in Section 2.0: Migrating TDE Master Key from Third-Party HSM to Fortanix DSM.
- prevent_duplicate_opaque_objects = true to prevent creating duplicate opaque objects.
- retry_timeout_millis can be set in milliseconds, which allows for retries in case of failures from the service side. By default, this is set to 3 seconds.
- file is an optional log file location that can be set. By default, logging is done in /var/log/syslog. Ensure the Oracle instance owner has access to the log file location. For example, /etc/fortanix/fortanix.log.
If Fortanix DSM is installed in an on-premises environment, the Certificate Authority (CA) certificate used for the HTTPS endpoint must be provided in the PKCS#11 configuration. If not set, the TLS communication with Fortanix DSM will fail.
1. Download the CA certificate as a PEM file to the Oracle Database machine and save it as sdkms-ca.crt.
2. Add the location of the CA file in the PKCS#11 configuration file as follows:
```
api_endpoint = "https://<fortanix_dsm_url>"
app_id = "<app id created in step #1>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 60000
ca_certs_file = "</path/to/sdkms-ca.pem>"
[log]
file = "<log filename>"
```
NOTE
- In case of Oracle RAC database environment, repeat Steps 2 to 4 above on all the nodes.
- If you experience any connection issues between Oracle and Fortanix DSM, refer to PKCS#11 Library: Connection Issues for troubleshooting.

2.4 Forward Migration: Local Wallet to Fortanix DSM

Perform the following steps to migrate the TDE master encryption key from the local file-based keystore to Fortanix DSM:

Run the following command to start up the database:
```
Sqlplus / as sysdba
startup
```
Run the following command to change the TDE configuration parameter to point to HSM and file:
```
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=both;
```
Run the following command to open the wallet:
```
ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<DSM_APP_PASSWORD>" CONTAINER=ALL;
```
Ensure that the file-based keystore is in the OPEN state for all Pluggable Databases and the root container. The HSM keystore must be in the OPEN_NO_MASTER_KEY state across all containers before initiating the migration.

Run the following command to migrate the local TDE master key to Fortanix DSM:

SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "<DSM_APP_PASSWORD>" MIGRATE USING "<DSM_APP_PASSWORD>" WITH BACKUP USING 'LocalWallet';

Run the following command to verify the wallet status:
```
select * from v$encryption_wallet;
```
Both the HSM and file keystores must be in the OPEN state across all PDBs and the root container.
Run the following command to verify that the master key is created in the Fortanix HSM:
```
select con_id,mkid from x$kcbdbk;
```
From the above output, search for all MKIDs (Master Key IDs) in the Fortanix DSM UI under Security Objects:
Figure 1: Security object in Fortanix DSM

3.0 Configuring Auto-Login

Auto Login configuration allows wallets to open automatically in the case of a database restart.

Auto-login stores the Fortanix DSM application secret (password) in a software-based auto-login keystore, while the Fortanix DSM application ID (app UUID) is stored in a configuration file. Oracle TDE passes the application secret from the auto-login keystore as a PIN to the Fortanix DSM PKCS#11 library. The Fortanix DSM KMS PKCS#11 library uses this PIN along with the app ID from the configuration file to generate a basic authentication token for authenticating to Fortanix DSM.

For additional details on Oracle TDE and auto-login keystore, refer to the Oracle official documentation.

3.1 Auto-Login in Oracle 19c

Perform the following steps to configure auto-login for the TDE keystore in Oracle Database 19c:

Check if the HSM key store is open. You can check the status of whether a keystore is open or closed by querying the STATUS column of the V$ENCRYPTION_WALLET view.
```
Select * from V$ENCRYPTION_WALLET;
```

Run the following command to close the HSM keystore if it is open:

ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "<DSM_APP_PASSWORD>" CONTAINER = ALL;

Run the following command to change the keystore type to a file wallet:
```
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE"
```
Run the following command to create a software keystore. The software keystore is used to securely store the HSM keystore password for auto-login. If an existing keystore is available, this step may be skipped.
```
ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde' IDENTIFIED BY "<DSM_APP_PASSWORD>";
```

Run the following command to open the software keystore:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "<DSM_APP_PASSWORD>" CONTAINER=ALL;

Add Fortanix DSM app password as a secret in the software wallet using the client as HSM_PASSWORD. This is an Oracle-defined client name that is used to represent the HSM password as a secret in the software keystore.
```
ADMINISTER KEY MANAGEMENT ADD SECRET '<DSM_APP_PASSWORD>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY ""<DSM_APP_PASSWORD>" WITH BACKUP;
```

Run the following command to close the software keystore:

ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "<DSM_APP_PASSWORD

Run the following command to set the wallet location to HSM backed by auto-login:

ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE"
In case of RAC database run following command.
ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE"   Sid=’*’;

Shut down and restart the database to verify autologin is functioning properly.
Run the following command to verify that the wallet is auto-open:
```
 SELECT * FROM V$ENCRYPTION_WALLET;
```

This completes the auto-login steps for Oracle 19c.

In case of RAC database, transfer the ewallet.p12 and cwallet.sso files to all nodes of RAC at a specified location, $ORACLE_BASE/admin/$ORACLE_SID/wallet/tde.

NOTE
This migration process retains previous key versions in the original third-party HSM keystore. Ensure that these older key versions are securely exported and imported into Fortanix DSM as opaque objects for safekeeping.