Generate a TDE master encryption key on the KMES Series 3

3min
To configure Oracle Database 19c TDE with an HSM, refer to the following Oracle knowledge base article for Oracle Database 19c: https://docs.oracle.com/en/database/oracle/oracledatabase/19/asoag/configuring-transparent-data-encryption.html﻿
This section provides a very basic example of configuring Oracle TDE with an HSM by using PKCS #11. However, there are many nuances in an Oracle Database environment, so the following steps do not apply directly to all situations and implementations. Use this section only as a general guide and thoroughly consult the preceding Oracle documentation link before implementing Oracle TDE with an HSM in your environment.
To use HSM-based encryption, you must generate a master encryption key (MEK), which you store on the . TDE uses the MEK to encrypt and decrypt the Oracle table keys.
This section covers two Oracle Database implementations: A standard implementation with Oracle Database running on a server or desktop and one with Oracle Database running in a Docker container.
Standard implementation
Choose one of the following operating systems for the standard implementation:
Linux
Windows
This implementation uses the oraenv tool to set up the Oracle database environment for the current session and enable the sqlplus command. To set the Oracle environment, perform the steps in this section. When prompted, specify the system ID (SID) for the instance, orcl in this example, or use the default value indicated between the brackets in line 4 of step 1 in the following process. All instances on the system require a unique SID.
1
Set the Oracle environment with the following commands:
Shell
su oracle

cd ~

. /usr/local/bin/oraenv
ORACLE_SID = [oracle] ? orcl
su oracle

cd ~

. /usr/local/bin/oraenv
ORACLE_SID = [oracle] ? orcl
﻿
If it succeeds, the command returns the following message:
The Oracle base has been set to /home/oracle/app/oracle
2
Run the following command to connect to the database:
Shell
sqlplus / as sysdba
sqlplus / as sysdba
﻿
3
Run the following command to start the Oracle instance:
SQL
SQL> startup
SQL> startup
﻿
4
Run the following command to set the static WALLET_ROOT parameter, which sets the location of the keystore you plan to use:
You must set up the WALLET_ROOT parameter even if you do not use a keystore.
SQL
SQL> ALTER SYSTEM SET WALLET_ROOT = '/opt/oracle/extapi/64/hsm/futurex/4.45/libfxpkcs11.so' SCOPE=SPFILE;
SQL> ALTER SYSTEM SET WALLET_ROOT = '/opt/oracle/extapi/64/hsm/futurex/4.45/libfxpkcs11.so' SCOPE=SPFILE;
﻿
5
Stop and restart the database after setting the WALLET_ROOT parameter:
SQL
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
﻿
6
Set the dynamic TDE_CONFIGURATION parameter that sets the type of keystore you plan to use:
SQL
SQL> ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM' SCOPE=BOTH SID = '*';
SQL> ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM' SCOPE=BOTH SID = '*';
﻿
7
Stop and restart the database after setting the TDE_CONFIGURATION parameter:
SQL
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
﻿
8
Run the following command to open the hardware keystore with the password of the user created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";
﻿
9
Run the following command to create the TDE master encryption key with the user password created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "KMES_User_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "KMES_User_Password";
﻿
If you are migrating a previously configured TDE Master Encryption Key, refer to this article.
If successful, the following message appears:
System altered.
If the database contains columns encrypted with a public key, the Oracle table key decrypts and re-encrypts the columns. The AES symmetric key generated by HSM-based TDE encrypts and decrypts the Oracle table key.
1
Open a command prompt window as Administrator.
2
Run the following command to connect to the database:
Shell
sqlplus / as sysdba
sqlplus / as sysdba
﻿
3
Run the following command to start the Oracle instance:
SQL
SQL> startup
SQL> startup
﻿
4
Run the following command to set the static WALLET_ROOT parameter, which sets the location of the keystore you plan to use:
You must set up the WALLET_ROOT parameter even if you do not use a keystore.
SQL
SQL> ALTER SYSTEM SET WALLET_ROOT = 'C:\oracle\extapi\64\hsm\futurex\5.4.0\fxpkcs11.dll' SCOPE=SPFILE;
SQL> ALTER SYSTEM SET WALLET_ROOT = 'C:\oracle\extapi\64\hsm\futurex\5.4.0\fxpkcs11.dll' SCOPE=SPFILE;
﻿
5
Stop and restart the database after setting the WALLET_ROOT parameter.
SQL
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
﻿
6
Set the dynamic TDE_CONFIGURATION parameter that sets the type of keystore you plan to use:
SQL
SQL> ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM' SCOPE=BOTH SID = '*';
SQL> ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM' SCOPE=BOTH SID = '*';
﻿
7
Stop and restart the database after setting the TDE_CONFIGURATION parameter:
SQL
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;
﻿
8
Run the following command to open the hardware keystore with the password of the user created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";
﻿
9
Run the following command to create the TDE master encryption key with the password of the user created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "KMES_User_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "KMES_User_Password";
﻿
If you are migrating a previously configured TDE Master Encryption Key, refer to this article.
If successful, the following message appears:
System altered.
﻿
Keys generated on the  begin with something similar to ORACLE.TDE.HSM.MK. You can view them in the Key Group under Key Management > Keys
If the database contains columns encrypted with a public key, the Oracle table key decrypts and re-encrypts the columns. The AES symmetric key generated by HSM-based TDE encrypts and decrypts the Oracle table key.
Docker container implementation
Use the following steps to configure the  PKCS #11 (FXPKCS11) library to work with an Oracle Database Docker container. For instructions on how to build and run Oracle Database in a Docker container, refer to the Oracle documentation.
1
On the host computer that runs the Oracle Database container, open a terminal and go to the location where you saved the Oracle Database private key, tls_skey.pem.
2
Run the following command to make the Oracle Database private key readable and executable for all users:
Shell
chmod 555 tls_skey.pem
chmod 555 tls_skey.pem
﻿
3
Set the OpenSSL version to match your container in the OPENSSL_VERSION environment variable. 
If your Oracle Database 19c uses the official Oracle Database container images repository on GitHub (https://github.com/oracle/docker-images/blob/main/OracleDatabase), run the following command because that container image is based on Oracle Linux 7, which is OpenSSL 1.0-based:
Shell
OPENSSL_VERSION=OpenSSL-1.0.x
OPENSSL_VERSION=OpenSSL-1.0.x
﻿
If your Oracle Database runs in a container based on OpenSSL 1.1, run the following command:
Shell
OPENSSL_VERSION=OpenSSL-1.1.x
OPENSSL_VERSION=OpenSSL-1.1.x
﻿
4
Download one of the following  PKCS #11 (FXPKCS11) library installations from the  Portal:
If your container is based on OpenSSL 1.0, download the fxpkcs11-redhat-4.xx-xxxx.tar file. 
If your container is based on OpenSSL 1.1, download the fxpkcs11-redhat8-4.xx-xxxx.tar file.
5
Run the following command to extract the FXPKCS11 library and save the version in the PKCS_VERSION environment variable:
Shell
tar -xvf fxpkcs11*.tar
PKCS_VERSION=$(grep -r --include=*info* Version: | awk 'NR==2{print $2}')
tar -xvf fxpkcs11*.tar
PKCS_VERSION=$(grep -r --include=*info* Version: | awk 'NR==2{print $2}')
﻿
6
Edit the fxpkcs11.cfg file to allow the FXPKCS11 library to connect to the . Set the following fields in the <KMS> section:
Text
<KMS>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            Crypto1                 </CRYPTO-OPR>
    
    # Key group name
    <KEYGROUP-NAME>         OracleTDE               </KEYGROUP-NAME>

    # Connection information
    <ADDRESS>               10.0.8.30               </ADDRESS>
    <PROD-PORT>             2001                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
    <PROD-TLS-CA>           /home/oracle/pki/tls_ca.pem       </PROD-TLS-CA>
    <PROD-TLS-CERT>         /home/oracle/pki/tls_cert.pem     </PROD-TLS-CERT>
    <PROD-TLS-KEY>          /home/oracle/pki/tls_skey.pem     </PROD-TLS-KEY>
    #<PROD-TLS-KEY-PASS>     safest                 </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                      </FX-LOAD-BALANCE>
</KMS>
<KMS>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            Crypto1                 </CRYPTO-OPR>
    
    # Key group name
    <KEYGROUP-NAME>         OracleTDE               </KEYGROUP-NAME>

    # Connection information
    <ADDRESS>               10.0.8.30               </ADDRESS>
    <PROD-PORT>             2001                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
    <PROD-TLS-CA>           /home/oracle/pki/tls_ca.pem       </PROD-TLS-CA>
    <PROD-TLS-CERT>         /home/oracle/pki/tls_cert.pem     </PROD-TLS-CERT>
    <PROD-TLS-KEY>          /home/oracle/pki/tls_skey.pem     </PROD-TLS-KEY>
    #<PROD-TLS-KEY-PASS>     safest                 </PROD-TLS-KEY-PASS>

    # YES = This is communicating through a Guardian
    <FX-LOAD-BALANCE>       NO                      </FX-LOAD-BALANCE>
</KMS>
﻿
Field
Description
﻿
<SLOT>
Can leave it set to the default value of 0.
﻿
<CRYPTO-OPR>
Specify the name of the identity created on the .
﻿
<KEYGROUP-NAME>
Specify the name of the key group that you created on the .
﻿
<ADDRESS>
Specify the IP address of the  to which the PKCS #11 library should connect.
﻿
<PROD-PORT>
Set the PKCS #11 library to connect to the default Host API port on the , port 2001.
﻿
<PROD-TLS-ENABLED>
Set the field to YES. The only way to connect to the Host API port on the  is over TLS.
﻿
<PROD-TLS-ANONYMOUS>
Set this value to NO because you're connecting to the Host API port by using mutual authentication. This field defines whether the PKCS #11 library authenticates to the .
﻿
<PROD-TLS-CA>
Specify the path to where you save the tls_ca.pem file.
﻿
<PROD-TLS-CERT>
Specify the path to where you saved the tls_cert.pem file.
﻿
<PROD-TLS-KEY>
Specify the path to where you saved the tls_skey.pem file.
﻿
<PROD-TLS-KEY-PASS>
Field should remain commented out because a password was not set for the client private key.
﻿
<FX-LOAD-BALANCE>
Set it to the default value of NO.
﻿
7
Run the following command to start the Oracle Database container and bind-mount all of the FXPKCS11 files needed for FXPKCS11 to connect to the .
The command takes up to 20 minutes to complete, and you must run it from the same directory where you extracted the fxpkcs11 directory.
If the TLS certificates for authentication with the  are not stored in the /home/oracle/pki directory on your system, modify the third -v flag in your command to reflect this.
Shell
docker run -d \
    -v $(pwd)/fxpkcs11.cfg:/etc/fxpkcs11.cfg \
    -v $(pwd)/fxpkcs11/x64/${OPENSSL_VERSION}/libfxpkcs11.so:/opt/oracle/extapi/64/hsm/futurex/${PKCS_VERSION}/libfxpkcs11.so \
    -v /home/oracle/pki:/pki \ 
    -p 1521:1521 \
    -p 5500:5500 \
    -e ORACLE_SID=test \
    -e ORACLE_PWD=Password123 \
    -v data:/opt/oracle/oradata \
    --name TDE \
    oracle/database:19.3.0-ee
docker run -d \
    -v $(pwd)/fxpkcs11.cfg:/etc/fxpkcs11.cfg \
    -v $(pwd)/fxpkcs11/x64/${OPENSSL_VERSION}/libfxpkcs11.so:/opt/oracle/extapi/64/hsm/futurex/${PKCS_VERSION}/libfxpkcs11.so \
    -v /home/oracle/pki:/pki \ 
    -p 1521:1521 \
    -p 5500:5500 \
    -e ORACLE_SID=test \
    -e ORACLE_PWD=Password123 \
    -v data:/opt/oracle/oradata \
    --name TDE \
    oracle/database:19.3.0-ee
﻿
8
After the Oracle Database container is running, run the following command to connect to the container file system:
Shell
docker exec -it TDE /bin/bash
docker exec -it TDE /bin/bash
﻿
9
Modify the /opt/oracle/product/19c/dbhome_1/network/admin/sqlnet.ora file as shown in the following example, and save it:
Text
NAME.DIRECTORY_PATH= (TNSNAMES, EZCONNECT, HOSTNAME)
WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
WALLET_ROOT=/opt/oracle/admin/wallet
NAME.DIRECTORY_PATH= (TNSNAMES, EZCONNECT, HOSTNAME)
WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
ENCRYPTION_WALLET_LOCATION=(SOURCE=(METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/wallet)))
WALLET_ROOT=/opt/oracle/admin/wallet
﻿
10
Run the following command to connect to the database:
Shell
sqlplus sys/Password123@test as sysdba
sqlplus sys/Password123@test as sysdba
﻿
11
Run the following command to create the master encryption key for TDE:
SQL
SQL > ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "safest";
SQL > ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "safest";
﻿
If it succeeds, the following message appears:
System altered.
﻿
﻿
Updated 02 Aug 2024
Did this page help you?
Edit the Futurex PKCS #11 configuration file
Open the wallet or hardware keystore