Generate a TDE Master Encryption Key on the Vectera Plus

2min
To configure Oracle Database 12c TDE with an HSM, we recommend that you refer to the following Oracle knowledge base article:
Oracle Database 12c: https://docs.oracle.com/database/121/ASOAG/configuring-transparent-dataencryption.htm﻿
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 might not apply directly to certain 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 for encrypting and decrypting 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.
Standard implementation
Docker container implementation
1
Set the Oracle environment by using 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
﻿
2
Connect to the database:
Shell
$ sqlplus / as sysdba
$ sqlplus / as sysdba
﻿
3
Start the Oracle instance:
SQL
SQL> startup
SQL> startup
﻿
4
Open the hardware keystore by using the password of the identity created on the : 
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "Identity_Password";
﻿
5
Perform one of the following options for the TDE Master Encryption Key:
Migrate a previously configured TDE Master Encryption Key by referring to this article.
Create the TDE Master Encryption Key by using the password of the identity that was created on the , by running the following command:
SQL
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "Identity_Password";
SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "Identity_Password";
﻿
If the Master Encryption Key creation succeeds, you see the following message:
Text
System altered.
System altered.
﻿
If the database contains columns encrypted with a public key, the columns are decrypted and reencrypted with the Oracle table key, which is encrypted/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
Open the wallet or hardware keystore