Generate a TDE master encryption key on the KMES Series 3

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 KMES. 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

This implementation uses theoraenv 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. Perform the following steps in Linux to use the standard implementation:

Set the Oracle environment with the following commands:

Shell

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

Run the following command to connect to the database:

Shell

sqlplus / as sysdba

Run the following command to start the Oracle instance:

Sql

SQL> startup

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;

Stop and restart the database after setting the WALLET_ROOT parameter:

Sql

SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;

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 = '*';

Stop and restart the database after setting theTDE_CONFIGURATION parameter:

Sql

SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;

Run the following command to open the hardware keystore with the password of the user created on the KMES:

Sql

SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";

Run the following command to create the TDE master encryption key with the user password created on the KMES:

Sql

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: docs.oracle.com/en/database/oracle/oracle-database/19/asoag/managing-keystore-and-tde-master-encryption-key.html#GUID-4335220F-49FF-40BC-9EB0-21442608F436.

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.

Windows

Perform the following steps in Windows to to use the standard implementation:

Open a command prompt window as Administrator.

Run the following command to connect to the database:

Shell

sqlplus / as sysdba

Run the following command to start the Oracle instance:

Sql

SQL> startup

Run the following command to set the staticWALLET_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;

Stop and restart the database after setting the WALLET_ROOT parameter.

Sql

SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;

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 = '*';

Stop and restart the database after setting theTDE_CONFIGURATION parameter:

Sql

SQL> SHUTDOWN IMMEDIATE;

SQL> STARTUP;

Run the following command to open the hardware keystore with the password of the user created on the KMES:

Sql

SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "KMES_User_Password";

Run the following command to create the TDE master encryption key with the password of the user created on the KMES:

Sql

SQL> ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "KMES_User_Password";

If successful, the following message appears:System altered.

Viewing keys after standard implementation

Keys generated on the KMES Series 3 begin with something similar toORACLE.TDE.HSM.MK. You can view them in theKey Group under Key Management > Keys

Docker container implementation

Use the following steps to configure the Futurex 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.

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.

Run the following command to make the Oracle Database private key readable and executable for all users:

Shell

chmod 555 tls_skey.pem

Set the OpenSSL version to match your container in the OPENSSL_VERSIONenvironment 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

If your Oracle Database runs in a container based on OpenSSL 1.1, run the following command:

Shell

OPENSSL_VERSION=OpenSSL-1.1.x

Download one of the following Futurex PKCS #11 (FXPKCS11) library installations from the Futurex 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.

Run the following command to extract theFXPKCS11 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}')

Edit the fxpkcs11.cfg file to allow the FXPKCS11 library to connect to the KMES Series 3. Set the following fields in the **<KMS> ** section:

None

<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>               [kmes_ip_address]       </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 KMES.
<KEYGROUP-NAME>	Specify the name of the key group that you created on the KMES.
<ADDRESS>	Specify the IP address of the KMES 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 KMES, port `2001`.
<PROD-TLS-ENABLED>	Set the field to YES. The only way to connect to the Host API port on the KMES 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 KMES.
<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.

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 KMES Series 3.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 KMES Series 3 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

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

Modify the /opt/oracle/product/19c/dbhome_1/network/admin/sqlnet.ora file as shown in the following example, and save it:

None

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

Run the following command to connect to the database:

Shell

sqlplus sys/Password123@test as sysdba

Run the following command to create the master encryption key for TDE:

Sql

SQL > ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "<kmes_identity_password>";

If it succeeds, the following message appears:System altered.

​Standard implementation

​Linux

​Windows

​Viewing keys after standard implementation

​Docker container implementation

Standard implementation

Linux

Windows

Viewing keys after standard implementation

Docker container implementation