Generate a TDE Master Encryption Key on the Vectera Plus

2min
To configure Oracle Database 19c TDE with an HSM, we recommend that you refer to the following Oracle knowledge base article:
Oracle Database 19c: https://docs.oracle.com/en/database/oracle/oracledatabase/19/asoag/configuring-transparent-data-encryption.html﻿
This section shows a very basic example of configuring Oracle TDE with an HSM 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) and store it on the .  TDE uses it to encrypt and decrypt the Oracle Table Keys.
This section covers the following Oracle Database implementation methods: A standard implementation of Oracle Database running on a server or desktop and an Oracle Database implementation running in a Docker container.
Choose one of the following methods to perform the implementation:
Standard implementstion Linux
Standard implementation Windows
Docker container implementation
1
Set the Oracle environment with the following commands:
The oraenv tool sets up the Oracle database environment for the current session and enables the sqlplus command. To set the Oracle environment, use the following procedure. 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. All instances on the system require a unique SID.
Shell
su oracle

cd ~

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

cd ~

. /usr/local/bin/oraenv
ORACLE_SID = [oracle] ? orcl
﻿
Upon success, the command returns the following message:
The Oracle base has been set to /home/oracle/app/oracle
2
Connect to the database:
Shell
sqlplus / as sysdba
sqlplus / as sysdba
﻿
3
Start the Oracle instance:
SQL
SQL> startup
SQL> startup
﻿
4
Set the static WALLET_ROOT parameter, which sets the keystore location 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
Open the hardware keystore using the password of the identity created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "HSM_Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "HSM_Identity_Password";
﻿
9
Create the TDE Master Encryption Key by the password of the identity created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "HSM_Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "HSM_Identity_Password";
﻿
If migrating a previously configured TDE Master Encryption Key, refer to this article.
If successful, the following message displays:
System altered.
If the database contains columns encrypted with a public key, the columns are decrypted and re-encrypted with the Oracle table key, which you encrypt or decrypt by using the AES symmetric key generated by HSM-based transparent data encryption.
1
Open a Command Prompt window as Administrator.
2
Connect to the database:
Shell
sqlplus / as sysdba
sqlplus / as sysdba
﻿
3
Start the Oracle instance:
SQL
SQL> startup
SQL> startup
﻿
4
Set the static WALLET_ROOT parameter, which sets the keystore location 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
Open the hardware keystore by using the password of the identity created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "HSM_Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "HSM_Identity_Password";
﻿
9
Create the TDE Master Encryption Key by using the password of the identity created on the :
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "HSM_Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "HSM_Identity_Password";
﻿
if successful, the following message displays:
System altered.
If the database contains columns encrypted with a public key, you decrypt and re-encrypt the columns with the Oracle table key, which is encrypted or decrypted with the AES symmetric key generated by HSM-based transparent data encryption.
The steps outlined in this section describe how 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 Oracle's documentation.
1
On the host computer that runs the Oracle Database container, go to the location of the Oracle Database private key file, tls_skey.pem.
2
Open a terminal and 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. 
Depending on your database version, run one of the following commands:
If you use Oracle Database 19c and the official Oracle Database container images repository on GitHub (https://github.com/oracle/docker-images/blob/main/OracleDatabase), the container is based on Oracle Linux 7, which is OpenSSL 1.0-based. In that case, you need to run the following command:
Shell
OPENSSL_VERSION=OpenSSL-1.0.x
OPENSSL_VERSION=OpenSSL-1.0.x
﻿
If you use Oracle Database running in a container that is OpenSSL 1.1-based, you need to run the following command:
Shell
OPENSSL_VERSION=OpenSSL-1.1.x
OPENSSL_VERSION=OpenSSL-1.1.x
﻿
4
Download the  PKCS #11 (FXPKCS11) library from the  Portal, depending on your OpenSSL version:
If your container is OpenSSL 1.0-based, download the fxpkcs11-redhat-4.xx-xxxx.tar file. 
If your container is OpenSSL 1.1- based, download the fxpkcs11-redhat8-4.xx-xxxx.tar file.
5
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
Open the FXPKCS11 configuration file, fxpkcs11.cfg, in a text editor and modify the connection details in the <HSM> section to enable the FXPKCS11 library to connect to the . The following configuration example shows part of the fxpkcs11.cfg file:
Text
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                </CRYPTO-OPR>
    # Automatically login on session open
    #<CRYPTO-OPR-PASS>       [identity_password]             </CRYPTO-OPR-PASS>

    # Connection information
    <ADDRESS>               10.0.8.30     </ADDRESS>
    <PROD-PORT>             9100                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
#    <PROD-TLS-CA>           /home/user/tls/root.pem        </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub1.pem     </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub2.pem     </PROD-TLS-CA>
    <PROD-TLS-KEY>          /home/user/tls/PKI.p12       </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>
</HSM>
<HSM>
    # Which PKCS11 slot
    <SLOT>                  0                       </SLOT>
    <LABEL>                 Futurex                 </LABEL>

    # HSM crypto operator user name
    <CRYPTO-OPR>            [identity_name]                </CRYPTO-OPR>
    # Automatically login on session open
    #<CRYPTO-OPR-PASS>       [identity_password]             </CRYPTO-OPR-PASS>

    # Connection information
    <ADDRESS>               10.0.8.30     </ADDRESS>
    <PROD-PORT>             9100                    </PROD-PORT>
    <PROD-TLS-ENABLED>      YES                     </PROD-TLS-ENABLED>
    <PROD-TLS-ANONYMOUS>    NO                      </PROD-TLS-ANONYMOUS>
#    <PROD-TLS-CA>           /home/user/tls/root.pem        </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub1.pem     </PROD-TLS-CA>
#    <PROD-TLS-CA>           /home/user/tls/sub2.pem     </PROD-TLS-CA>
    <PROD-TLS-KEY>          /home/user/tls/PKI.p12       </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>
</HSM>
﻿
Field
Description
﻿
<SLOT>
Leave it set to the default value of 0.
﻿
<LABEL>
Leave it set to the default value of Futurex.
﻿
<CRYPTO-OPR>
Specify the name of the identity created for the application partition.
﻿
<CRYPTO-OPR-PASS>
specify the password of the identity configured in the <CRYPTO-OPR> field. You can use this to log the application into the HSM automatically if necessary.
﻿
<ADDRESS>
Specify the IP address of the HSM to which the PKCS #11 library should connect.
﻿
<PROD-PORT>
Set the port number of the HSM that the FXPKCS11 library should connect to.
﻿
<PROD-TLS-ENABLED>
Set the field to YES. 
﻿
<PROD-TLS-ANONYMOUS>
Defines whether the FXPKCS11 library authenticates to the server.
﻿
<PROD-TLS-KEY>
Set the location of the client private key. Supported formats for the TLS private key include the following values:
PKCS #1 clear private keys
PKCS #8 encrypted private keys
A PKCS #12 file containing the private key and certificates encrypted under a password.
Because the <PROD-TLS-KEY> field in this example defines the PKCS #12 file, you don't need to define the signed client cert with the <PROD-TLS-CERT> tag, nor the CA certificates with one or more instances of the <PROD-TLS-CA> tag.
﻿
<PROD-TLS-KEY-PASS>
Set the password of the PKCS #12 file, if necessary.
﻿
<FX-LOAD-BALANCE>
If you use a Guardian to manage HSM devices in a cluster, set this field to YES. 
If you don't use a Guardian, set it to 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 . 
You must run this command from the same directory that stores the extracted 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 the location.
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
﻿
The preceding command takes 10 to 20 minutes to complete, depending on your system resources.
8
After the Oracle Database container is up and 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 to the following and save it:
Shell
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
Connect to the database.
Shell
sqlplus sys/Password123@test as sysdba
sqlplus sys/Password123@test as sysdba
﻿
11
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 the operation succeeds, you see the following response:
SQL
System altered.
System altered.
﻿
﻿
﻿
﻿
﻿
Updated 27 Aug 2024
Did this page help you?
Edit the Futurex PKCS #11 configuration file
Opening the wallet or hardware keystore