--- title: "Migrating Oracle TDE from Third-Party HSM to Fortanix DSM" slug: "migrating-oracle-tde-from-third-party-hsms-to-fortanix-dsm" updated: 2026-07-30T06:54:40Z published: 2026-07-30T06:54:40Z canonical: "support.fortanix.com/migrating-oracle-tde-from-third-party-hsms-to-fortanix-dsm" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.fortanix.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 Migrate 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: 1. 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*](https://support.fortanix.com/docs/using-fortanix-data-security-manager-with-oracle-tde-introduction)[*.*](https://support.fortanix.com/v1/docs/users-guide-getting-started-with-fortanix-data-security-manager-ui) 2. 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*](/v1/docs/migrating-oracle-tde-from-third-party-hsms-to-fortanix-dsm#21-reverse-migration-hsm-wallet-to-local-file-system-wallet)*.* 3. 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*](/v1/docs/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager#22-remove-thirdparty-hsm-pkcs11-library)*.* 4. Configure the Fortanix DSM PKCS#11 library and `pkcs11.conf` file. *For more information, refer to* [*Section 2.3: Configure Fortanix DSM PKCS#11 Library and pkcs11.conf File*](/v1/docs/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager#23-configure-fortanix-dsm-pkcs11-library-and-pkcs11conf-file)*.* 5. 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*](/v1/docs/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager#24-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: 1. Run the following command to verify the wallet status: ```bash select * from v$encryption_wallet; ``` 2. Run the following commands to rename the autologin wallet file: ```bash cd /tde mv cwallet.sso cwallet.sso_backup ``` 3. Run the following command to restart the database: ```bash sqlplus / as sysdba Shut immediate startup ``` 4. Run the following command to open the wallet: ```bash ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "" CONTAINER=ALL; ``` 5. Run the following command to set the wallet method `TDE_CONFIGURATION` as `FILE`: ```bash ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE"; ``` 6. Run the following command to perform the reverse migration: ```bash ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "" REVERSE MIGRATE USING "" WITH BACKUP USING 'NewWallet'; ``` 7. Run the following command to validate the keystore status. The file-based keystore must be in the `OPEN` state for all containers. ```bash select * from v$encryption_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*](/v1/docs/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager#20-migrating-tde-master-key-from-thirdparty-hsm-to-fortanix-dsm). ```bash ADMINISTER KEY MANAGEMENT ALTER KEYSTORE PASSWORD IDENTIFIED BY "" set "" 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: 1. Run the following command to shut down the database: ```bash Sqlplus / as sysdba Shut immediate ``` 2. The third-party PKCS#11 library is located at: `/opt/oracle/extapi/64/hsm/<3rd_party_vendor>/x.xx.xxxx/libpkcs11.so`. 3. Run the following command to remove or relocate the existing library directory to prevent conflicts with the Fortanix DSM PKCS#11 library: ```bash mv /opt/oracle/extapi/64/hsm/<3rd_party_vendor> /tmp ``` or ```bash 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: 1. Fortanix provides a PKCS#11 library (`.so` file) as a connector for the Oracle database integration, which can be downloaded from [*here*](https://fortanix.zendesk.com/hc/en-us/sections/4408769080724-PKCS-11). 2. 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: ```bash 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`: ```bash 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: ```bash sudo chown -R oracle:oinstall /opt/oracle sudo chmod -R 775 /opt/oracle ``` 3. Run the following commands to create the directory for `pkcs11.conf` file. The default location must be `/etc/fortanix`. ```bash 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, ```bash export FORTANIX_PKCS11_CONFIG_PATH=/u01/app/oracle/fortanix/pkcs11.conf ``` 4. Run the following command to create the configuration file `pkcs11.conf` under the `/etc/fortanix` folder with the following parameters: ```bash api_endpoint = "https://" app_id = "" prevent_duplicate_opaque_objects = true retry_timeout_millis = 60000 [log] file = "" ``` Where, - `api_endpoint` : Refers to 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*](/v1/docs/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager#20-migrating-tde-master-key-from-thirdparty-hsm-to-fortanix-dsm). - `prevent_duplicate_opaque_objects = true` to prevent creating duplicate opaque objects. - `retry_timeout_millis`: Set in milliseconds, which allows for retries in case of failures from the service side. By default, this is set to `3` seconds. - `file`: Refers to 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`. 5. 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. > [!NOTE] > 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*](https://support.fortanix.com/v1/docs/clients-pkcs11-library#55-connection-issues) for troubleshooting. 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: ```bash api_endpoint = "https://" app_id = "" prevent_duplicate_opaque_objects = true retry_timeout_millis = 60000 ca_certs_file = "" [log] file = "" ``` ### 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: 1. Run the following command to start up the database: ```bash Sqlplus / as sysdba startup ``` 2. Run the following command to change the TDE configuration parameter to point to HSM and file: ```bash ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" scope=both; ``` 3. Run the following command to open the wallet: ```bash ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "" 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. 4. Run the following command to migrate the local TDE master key to Fortanix DSM: ```bash ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "" MIGRATE USING "" WITH BACKUP USING 'LocalWallet'; ``` 5. Run the following command to verify the wallet status: ```bash select * from v$encryption_wallet; ``` Both the HSM and file keystores must be in the `OPEN` state across all PDBs and the root container. 6. Run the following command to verify that the master key is created in the Fortanix HSM: ```bash 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**: ![](https://cdn.us.document360.io/c3bd85d2-4ad8-4d85-9f60-f1c168a3aad9/Images/Documentation/migrating-oracle-transparent-data-encryption-to-fortanix-data-security-manager-image-ya5w8ht9(1).png) **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*](https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#ASOAG10434)*.* ### 3.1 Auto-Login in Oracle 19c Perform the following steps to configure auto-login for the TDE keystore in Oracle Database 19c: 1. 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. ```bash select * from v$encryption_wallet; ``` 2. Run the following command to close the HSM keystore if it is open: ```bash ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY ""; CONTAINER = ALL; ``` 3. Run the following command to change the keystore type to a file wallet: ```bash ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" ``` 4. 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. ```bash ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde' IDENTIFIED BY ""; ``` 5. Run the following command to open the software keystore: ```bash ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "" CONTAINER=ALL; ``` 6. 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. ```bash ADMINISTER KEY MANAGEMENT ADD SECRET '' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY "" WITH BACKUP; ``` 7. Run the following command to close the software keystore: ```bash ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY ""; ``` 8. Run the following command to create autologin keystore: ```bash ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '$ORACLE_BASE/admin/$ORACLE_SID/wallet/tde' IDENTIFIED BY ""; ``` 9. Run the following command to set the wallet location to HSM backed by auto-login: ```bash ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" ``` In case of RAC database run following command: ```bash ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE" Sid=’*’; ``` 10. Shut down and restart the database to verify autologin is functioning properly. 11. Run the following command to verify that the wallet is auto-open: ```bash 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] > 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. Fortanix Data Security Manager (DSM) is the world’s first cloud service secured with Intel® SGX. With Fortanix DSM, you can securely generate, store, and use cryptographic keys and certificates, as well as other secrets such as passwords, API keys, tokens, or any blob of data. Your business-critical applications and containers can integrate with Fortanix DSM using legacy cryptographic interfaces (PKCS#11, CNG, and JCE) or using the native Fortanix DSM RESTful interface.