Using Fortanix Self-Defending KMS with Oracle TDE

  • Last updated:
  • access_time Reading time:

1.0   Introduction

This article describes how to integrate Fortanix Self-Defending Key Management Service (KMS) with Oracle Transparent Data Encryption (TDE). It also contains the information that a user needs to:

  • Generate a TDE master encryption key in Fortanix Self-Defending KMS
  • Encrypt a tablespace or columns in a table
  • Configure auto-login hardware security module (HSM)
  • Perform hardware keystore migration

1.1   Why Fortanix Self-Defending KMS over Traditional HSM

The biggest security challenge when using TDE is securing the master key (called master encryption key, or MEK in Oracle). The ideal solution for securing the master key is to store it in an HSM and perform the wrapping and unwrapping of intermediate keys inside the HSM. Traditional HSMs often fall short when they are used in real world deployments of databases that have high “transactions per second” requirement and spread geographically. Traditional HSMs do not cluster very well, and even if they do, they rely on a client for load balancing which becomes a bottleneck as well as a security vulnerability.

Fortanix Self-Defending KMS is a next-generation HSM solution equipped to handle the high transaction rates that large commercial databases demand, and the ability to replicate keys across geographically distributed sites with minimal latency and high consistency. Fortanix Self-Defending KMS is designed to be infinitely scalable, highly available, and resilient to disasters and faults.

2.0   Terminology References

Fortanix Self-Defending KMS

Fortanix Self-Defending KMS is the cloud solution secured with Intel® SGX. With Fortanix Self-Defending KMS, you can securely generate, store, and use cryptographic keys and certificates, as well as secrets, such as passwords, API keys, tokens, or any blob of data.

TDE – Transparent Data Encryption

Transparent Data Encryption (TDE) enables you to encrypt sensitive data that you store in tables and tablespaces. Oracle Database uses authentication, authorization, and auditing mechanisms to secure data in the database, but not in the operating system data files where data is stored. To protect these data files, Oracle Database provides Transparent Data Encryption (TDE). To prevent unauthorized decryption, TDE stores the encryption keys in a security module external to the database, called a keystore. For more information, see Introduction to Transparent Data Encryption.

TDE Table Key

TDE Table key is an encryption key that is associated with a table whose columns are marked for encryption. The TDE master encryption key encrypts this table encryption key.

Tablespace Encryption Key

A Tablespace Encryption key is an encryption key for the encryption of a tablespace. The TDE master encryption key encrypts the tablespace encryption key, which in turn encrypts and decrypts data in the tablespace.

HSM – Hardware Security Module

A  Security Module is an external keystore or a separate server or device that provides security storage for encryption keys. External keystores are external to an Oracle database. Oracle Database can interface with external keystores but cannot manipulate them outside of the Oracle interface. The Oracle database can request the external keystore to create a key, but it cannot define how this key is stored in an external database.

3.0   Prerequisites

  • Fortanix Self-Defending KMS
    • CA certificate for on-premise installation Fortanix Self-Defending KMS in PEM format.
  • Oracle Database running on a Linux or Windows server (for example: Oracle database version 12c (Release 12.2.0.1.0) on Red Hat Enterprise Linux Server release 7.5). Supported Oracle Database versions are: 11g R2, 12c, 18c, 19c.
    • For Oracle 11g, make sure Oracle Database patch 18948524 is applied. This patch enabled Auto-login mode of HSM wallet.
  • Download the Fortanix PKCS#11 library from here.

4.0   Configuring Fortanix Self-Defending KMS for TDE

4.1   Obtaining Access in Fortanix Self-Defending KMS

  1. Create an Account in Fortanix Self-Defending KMS if you do not have one already. See Getting Started for more information. Check with an administrator if you need access to an existing account.
  2. Create a new Group, if not already created by the account administrator. This group, say “Oracle TDE”, which maintains the master keys for the TDE setup.

4.2   Create an Application in Fortanix Self-Defending KMS for Oracle TDE

  1. In your Fortanix Self-Defending KMS account, go to the Applications app.png tab (Figure 1).
  2. Create a new Fortanix Self-Defending KMS app using the button add.png . For example: Oracle demo (Figure 1)
  3. The next steps showcase different ways of authenticating Oracle Database to Fortanix Self-Defending KMS. AppTab_Screen.png

    Figure 1: Applications tab in Self-Defending KMS

4.3   Copy the API Key

  1. The API Key authenticates Oracle Database access to Fortanix Self-Defending KMS.
  2. In the Oracle demo app that you created in the previous section, click the COPY API KEY button (Figure 2).

    API_Copy_Key.png

    Figure 2: Copy API key

  3. In the Copy the API key dialog, click COPY API KEY button to copy the key to the clipboard (Figure 3). This will be required in Oracle configuration steps in Section 5.0.

    CopyAPI_Clipboard_Screen.png

    Figure 3: Copy API key to clipboard

4.4   Copy the App ID and Password

note_icon.svg NOTE: This is only required for Auto-login mode of configuring TDE. Refer to the steps in Section 6.0.

  1. In the Oracle demo app that you created in the previous section, click the COPY API KEY button (See Figure 2 above).

  2. In the Copy the API Key dialog, switch to the USERNAME/PASSWORD.

  3. Copy the Password value and the Username (App UUID) value using the Copy copy.png button.

    Copy_Password_screen.png

                    Figure 4: Copy Password

  4. Both the App UUID and password will be required in steps mentioned in Section 6.0.

4.5   Setup Certificate-Based Authentication

  1. Fortanix Self-Defending KMS supports improved authentication using client-side TLS, instead of API Key. This approach reduces the need to share sensitive API Key to the Oracle DBA and performs two-way authentication of client and service.
  2. This requires creation of certificate at DBA side and whitelisting it in Fortanix Self-Defending KMS. Following are sample steps to generate self-signed certificates. You may want to contact your organization CA for the approved steps of generating certificates.
  3. Copy App UUID from Fortanix Self-Defending KMS UI. See the steps in Section 4.4. This is required to be as the Common Name value during certificate generation steps.
  4. Generate the Certificate Signing Request (CSR) to get the client certificate.
    openssl genrsa -out client.key 2048

    openssl req -new -key client.key -out client.csr

    You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields, but you can leave some blank. For some fields there will be a default value. If you enter '.', the field will be left blank.
----

    Country Name (2 letter code) [XX]:.
State or Province Name (full name) []:.
Locality Name (eg, city) [Default City]:.
Organization Name (eg, company) [Default Company Ltd]:.
Organizational Unit Name (eg, section) []:.
Common Name (eg, your name or your server's hostname) []:[]:<SDKMS_APP_UUID>
    Email Address []:.
    Please enter the following 'extra' attributes to be sent with your certificate request
    A challenge password []:
    An optional company name []:
  5. Enter the Fortanix Self-Defending KMS App UUID that you copied in Step 3 in the Common Name field above.
    1. The certificate needs to be signed by your preferred CA provider. The signed certificate should be in PEM format.
    2. Now, whitelist the certificate in Fortanix Self-Defending KMS by changing the app authentication type to Certificate.
      2.png
                                           Figure 4: Change App Authenticate Type
    3. Upload the client certificate using the UPLOAD NEW CERTIFICATE button or copy the content of the signed certificate as input in the text box below.
      3.png
                                                 Figure 5: Add Signed Certificate

5.0   Setup TDE in Oracle using HSM Wallet

5.1   Set Hardware Keystore Type in the sqlnet.ora File

note_icon.svg NOTE: This step only applies for Oracle 11g, 12c, and 18c. Skip to Section 5.2 for Oracle 19c.

To configure a keystore for a hardware security module (hardware keystore), you must first define the keystore in the sqlnet.ora. The Oracle Database checks the sqlnet.ora file for the type of keystore and the directory location of the hardware keystone. If not set, it assumes a software keystore by default.

  1. The sqlnet.ora file is located in the ORACLE_HOMEdbs directory or in the location set by the TNS_ADMIN environment variable. If the file is not present in the directory, create a new one.
  2. Add the following line to the sqlnet.ora file to define the hardware keystore type. 
    ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD=HSM))

5.2   Set Hardware Keystore Type (Oracle 19c Only)

  1. Oracle 19c does not require to edit sqlnet.ora file. The setup of keystore type can be done using Oracle initialization parameters.
  2. Set the Oracle wallet location. Even though HSM Wallet does not reside on local disk, this step is required to set TDE. 
    ALTER SYSTEM SET WALLET_ROOT="/opt/oracle/admin/ORCLCDB/wallet" scope=spfile;
    Where $ORACLE_BASE/admin/$ORACLE_SID/wallet is the wallet location.
  3. Shutdown the system. 
    SQL> shutdown
  4. Startup the system 
    SQL> startup
  5. Set the wallet type to HSM. 
    SQL> ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM" scope=both;

5.3   Install PKCS#11 Library

Oracle Database requires PKCS#11 protocol implemented library of the HSM. The next steps are to install the Fortanix Self-Defending KMS PKCS#11 library to the appropriate location to ensure that Oracle Database can find this library. To download the library, see the section Prerequisites.

  1. Before copying the PKCS#11 library, create the directory location where you will copy the library. Oracle recommends placing the PKCS#11library in a designated directory structure as /opt/oracle/extapi/{32,64}/hsm/<vendor_name>/<pkcs_lib_version > 
    sudo mkdir -p /opt/oracle/extapi/64/hsm/fortanix/3.16.1311

    In the above specification: 

    • 64 specifies whether the supplied binary is 32 bits or 64 bits. This will be 64 usually.
    • fortanix stands for the name of the vendor supplying the library.
    • 3.16.1311 refers to the version of the library. This should preferably be in the format, number.number.number
  2. Now, copy the Fortanix Self-Defending KMS PKCS#11 library to the directory location created in Step 1. 
    /opt/oracle/extapi/64/hsm/fortanix/0.8.0/ fortanix_pkcs11_3.16.1311.so
  3. Change the name of the library file fortanix_pkcs11_3.16.1311.so to follow the syntax libapiname.so. So, the name of the library file should change to libpkcs11.so. 
    sudo mv
    /opt/oracle/extapi/64/hsm/fortanix/3.16.1311/fortanix_pkcs11_3.16.1311.so
    /opt/oracle/extapi/64/hsm/fortanix/3.16.1311/libpkcs11.so
    Set the permission and ownership of the folder that contains the Fortanix Self-Defending KMS PKCS#11 library. 
    sudo chown -R oracle:oinstall /opt/oracle
    sudo chmod -R 775 /opt/oracle

5.4   Configure PKCS#11 Parameters

  1. Fortanix Self-Defending KMS PKCS#11 library can be configured for authentication and other behaviors using a configuration file.
  2. We recommend using the default location for the configuration file, which is /etc/fortanix/pkcs11.conf.
    sudo mkdir /etc/fortanix
    sudo chown -R oracle:oinstall /etc/fortanix
    sudo chmod -R 775 /etc/fortanix
    1. 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. This can be useful in RAC setup, where single configuration file can be hosted on a shared ASM disk group. e.g: 
      export FORTANIX_PKCS11_CONFIG_PATH=/u01/app/oracle/fortanix/pkcs11.conf
  3. Create a file named pkcs11.conf in the desired folder (see step 2 above).
  4. Add parameters in the file as follows:
    • API Key: See Section 4.3 on how to get the API Key from Fortanix Self-Defending KMS.
      • note_icon.svg NOTE : The Fortanix Self-Defending KMS App API Key size is 160+ characters long. Due to the SQL command size limitation, the long API Key will not fit in the command line. To solve this problem, you must store the API key in this config file and pass the path of this file in the wallet creation query in Section 5.7.
    • API Endpoint: This is the URL endpoint of the Fortanix Self-Defending KMS installation.
    • To prevent creating duplicate opaque objects, set prevent_duplicate_opaque_objects = true in the config file. This would skip creating new Opaque objects if there is an existing Opaque object with the same CKA_LABEL. This is recommended.
    • Optionally, a log file location can be set. By default, logging is done in /var/log/syslog.
    • Optionally, a retry timeout can be set in milliseconds, which allows for retries in case of failures from service side. By default, this is set for 3 seconds. 
      api_endpoint = "https://sdkms.fortanix.com"
      api_key = "MWY5YT...TO5n" 
      prevent_duplicate_opaque_objects = true
      retry_timeout_millis = 3000

      [log]
      file = "<log filename>"

5.5   Configure CA Certificate

If Fortanix Self-Defending KMS is installed in an on-premise environment, the CA certificate used for HTTPS endpoint need to be provided in PKCS#11 configuration. If not set, the TLS communication to Fortanix Self-Defending KMS will not be successful.

  1. Download the CA certificate as a PEM file on the Oracle Database machine. File name can be syslogsdkms-ca.crt.
  2. Make sure the full certificate chain is part of the file.
  3. Add the location of CA file in PKCS#11 conf file as following: 
    api_endpoint = "https://sdkms.fortanix.com"
    api_key = "MWY5YT...TO5n"
    prevent_duplicate_opaque_objects = true
    retry_timeout_millis = 3000
    ca_certs_file = "/path/to/sdkms-ca.pem"
    [log]
    file = "<log filename>"

5.6   Configure for Client Certificate Authentication

Alternatively, client certificate-based authentication can be set, instead of API Key based authentication. It brings stronger security as sensitive credential like API Key need not be shared to the DBA directly.

See the steps in Section 4.5 on how to create a client-side certificate and whitelist with Fortanix Self-Defending KMS.

Once the above steps are done, the following is required:

  • the location of client key
  • the location of the client certificate
  • App UUID 
    api_endpoint = "https://sdkms.fortanix.com"
    prevent_duplicate_opaque_objects = true
    retry_timeout_millis = 3000
    ca_certs_file = "/path/to/sdkms-ca.pem"
    app_id = "<SDKMS_APP_UUID>"
    key_file = "/path/to/client-key.pem"
    cert_file = "/path/to/client-cert.pem"
    [log]
    file = "<log filename>"
    note_icon.svg NOTE : api_key is removed from the config file.

5.7   Setup Keystore and Master Key (for Oracle 11g only)

Log in with User sys with role sysdba.

Sqlplus / as sysdba

note_icon.svg NOTE: If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora file changes can take effect.

5.7.1   Open Keystore 

To open the hardware key store, run the following command:

ALTER SYSTEM SET ENCRYPTION WALLET OPEN IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf";

In the above specification,

  • IDENTIFIED BY points to the location of the PKCS#11 configuration file prefixed with file:// (Based on step 2 of Section 5.4).

note_icon.svg NOTE: Above command is required to open the keystore for use by database, on every start of the database.

5.7.2   Set TDE Master Encryption key

Next you must create a TDE master encryption key that is stored inside the Fortanix hardware keystore. Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys or tablespace encryption keys inside the hardware security module

  1. Run the following command: 
    ALTER SYSTEM SET ENCRYPTION KEY IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf";
    2. The above command sets the Oracle database for TDE. Open the Fortanix Self-Defending KMS Web UI and go to the audit log to confirm if the master key was generated and used. 
  2. Click the Settings settings.png tab , and then in the left panel click the LOG MANAGEMENT tab to see the audit logs. Audit_logs_screen.png

    Figure 6: Audit Logs

    The Fortanix Self-Defending KMS is now successfully integrated with the Oracle TDE.
    From here you can proceed to:
    1. Start encrypting data.
    2. Improving the setup with Auto login. This allows to auto open the keystore on database restarts.

5.8   Setup Keystore and Master Key for Oracle 12c, 18c, and 19c

Log in with User sys with role sysdba.

Sqlplus / as sysdba

note_icon.svg NOTE: If SQL*Plus is already open and you had modified the sqlnet.ora file during this time, then reconnect to SQL*Plus. The database session must be changed before the sqlnet.ora file changes can take effect.

Switch to root container (if it is a container database). The keystore needs to be opened in the root container first. Run the following command in SQL*Plus:

ALTER SESSION SET CONTAINER = CDB$ROOT;

5.8.1   Open Keystore 

To open the hardware key store, run the following command:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;

In the above specification,

  • IDENTIFIED BY points to the location of the PKCS#11 Configuration file (prefixed
  • with file:// (Based on step 2 of Section 5.4).
  • CONTAINER is for use in a multitenant environment. Enter ALL to set the keystore in all the pluggable databases (PDBs) in this container database (CDB), or CURRENT for the current PDB.

note_icon.svg NOTE: Above command is required to open the keystore for use by database, on every start of the database.

5.8.2   Set TDE Master Encryption key

Next you must create a TDE master encryption key that is stored inside the Fortanix hardware keystore. Oracle Database uses the TDE master encryption key to encrypt or decrypt TDE table keys or tablespace encryption keys inside the hardware security module

  1. Run the following command: 
    ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
    2. The above command sets the Oracle database for TDE. Open the Fortanix Self-Defending KMS Web UI and go to the audit log to confirm if the master key was generated and used.
  2. Click the Settings settings.png tab , and then in the left panel click the LOG MANAGEMENT tab to see the audit logs. Audit_logs_screen.png

    Figure 7: Audit Logs

    The Fortanix Self-Defending KMS is now successfully integrated with the Oracle TDE.
    From here you can proceed to:
    1. Start encrypting data.
    2. Improving the setup with Auto login. This allows to auto open the keystore on database restarts.

6.0   Encrypt Your Data

Once TDE is setup on the Oracle Database, we can proceed with data encryption. There are 2 ways of encrypting data:

  1. Column Encryption: Selected columns of a table to be encrypted.
  2. Tablespace Encryption: Encrypt entire tablespace using TDE. This is recommended by Oracle due to better performance.

6.1   Column Encryption

  1. Connect to SQL*plus as a non-sysadmin user to enable encryption on a table.
  2. Next, create a table with an encrypted column. Use the CREATE TABLE SQL statement with the ENCRYPT clause. 
    CREATE TABLE employee (first_name VARCHAR2(128), last_name VARCHAR2(128), empID NUMBER, salary NUMBER(6) ENCRYPT)
  3. Now insert some data into the table. 
    INSERT INTO employee VALUES ('JOHN', 'SMITH',001, 10000);
  4. To list the encrypted columns in your database, run the following command: 
    select * from dba_encrypted_columns;

    OWNER TABLE_NAME COLUMN_NAME ENCRYPTION_ALG SALT INTEGRITY_ALG
    ------- ---------- ----------- -------------- ---- -------------
    OE EMPLOYEE SALARY AES 192 bits key YES SHA-1

More details can be found here https://docs.oracle.com/database/121/TDPSG/GUID-61259237-5514-4531-AFB4-CF716F93F1E5.htm#TDPSG44324

6.2   Tablespace Encryption

  1. Connect to SQL*plus as a non-sysadmin user to create a new encrypted tablespace.
    note_icon.svgNOTE: Oracle Database does not support encrypting existing tablespace. See notes here https://docs.oracle.com/database/121/TDPSG/GUID-61259237-5514-4531-AFB4-CF716F93F1E5.htm#GUID-956B2FB6-345B-4402-8D13-ED48D6357438
  2. Make sure that COMPATIBLE Initialization parameter setting is 11.2.0.0 or higher. This is typically an issue with older 11g databases.
    SHOW PARAMETER COMPATIBLE
    NAME                        TYPE                VALUE
    compatible                  string              11.2.0.0
    noncdbcompatible            BOOLEAN             FALSE

    // If above is less than 11.2.0.0, then run following
    alter system set COMPATIBLE='11.2.0.0' scope=spfile;
    shutdown
    startup
  3. Create a new encrypted tablespace using CREATE TABLESPACE SQL statement with the ENCRYPT clause. 
    CREATE TABLESPACE encrypted_ts (
    DATAFILE '/u01/app/oracle/oradata/DB11G/encrypted_ts01.dbf' SIZE 128K
    AUTOEXTEND ON NEXT 64K
    ENCRYPTION USING 'AES256'
    DEFAULT STORAGE(ENCRYPT);

    ALTER USER test QUOTA UNLIMITED ON encrypted_ts;
  4. Now insert some data into the table or tablespace.
    CREATE TABLE ets_test (
       id NUMBER(10),
       data VARCHAR2(50)
    )
    TABLESPACE encrypted_ts;

    INSERT INTO ets_test (id, data) VALUES (1, 'This is a secret!');
    COMMIT;
  5. The ENCRYPTED column of the DBA_TABLESPACES and USER_TABLESPACES views indicates if the tablespace is encrypted or not.
    SELECT tablespace_name, encrypted FROM dba_tablespaces;
    TABLESPACE NAME             ENC
    ____________________________________________________________________ 
    SYSTEM                      NO
    SYSAUX                      NO
    ENCRYPTED_TS                YES

    3 rows selected

7.0   Configuring Auto-Login

The method described in "Section 5.0" requires saving the Fortanix Self-Defending KMS API key in a config file. If you do not want to expose the API key in a file, you can configure the HSM key store to use auto-login using App ID and Password. The advantages would be:

  1. The API Key is not exposed to the database machine.
  2. In the case of database restart, the wallet is opened automatically.

In this method we will store the Fortanix Self-Defending KMS App’s secret/password in an auto-login keystore using a software keystore and the App Id (App UUID) will be stored in a config file. The Oracle TDE will pass the app secret stored in auto-login keystore as PIN to Fortanix Self-Defending KMS PKCS11 library. Fortanix Self-Defending KMS PKCS11 library will use this PIN and combine with App Id in the config file to create the basic authentication token for authenticating to Fortanix Self-Defending KMS. 

For additional details on Oracle TDE and auto-login keystore, please see: https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#ASOAG10434

7.1   Auto Login in Oracle 11G

note_icon.svg NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.

  1. Close the HSM keystore if it is open. 
    ALTER SYSTEM SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
  2. Create a new entry in sqlnet.ora file (Replace the existing WALLET setting). 
    ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD = HSM) (METHOD_DATA = (DIRECTORY = <wallet absolute Path>)))
    Where $ORACLE_BASE/admin/$ORACLE_SID/wallet/Fortanix is the wallet location.
  3. Create an auto-open and encryption wallet in the directory mentioned above: 
    orapki wallet create -wallet . -auto_login -pwd <password>
    Where "." signifies the current directory. For example: 
    orapki wallet create -wallet . -auto_login -pwd password123
    note.png NOTE: When prompted for a password, provide a password of at least 8 characters. This will be your software wallet password. Remember it for future use.
  4. Add the following entry to the empty wallets to enable an ‘auto-open HSM’: 
    mkstore -wrl . -createEntry ORACLE.TDE.HSM.AUTOLOGIN <any-non-empty-string>
    Where,
    • <any-non-empty-string> could be any string and it is used only one time. For example: 
       mkstore -wrl . -createEntry ORACLE.TDE.HSM.AUTOLOGIN TESTDE
      This command will prompt for a password, so enter the software wallet password set earlier.
    1. Oracle opens the encryption wallet first and if not present then it will open the auto wallet. Rename the encryption wallet (ewallet.p12) or move it out of the ‘ENCRYPTION_WALLET_LOCATION’ defined in the ‘sqlnet.ora’ file to a secure location;
    IMPORTANT: Do not delete the encryption wallet and do not forget the wallet password. For example: 
    mv ewallet.p12 ewallet.p12.orig
  5. Edit the existing PKCS#11 config file:
    • Remove API Key if exists in the file.
    • Add App Id. This value can be fetched from Section 4.4.
    The updated contents of pkcs11.conf is: 
    api_endpoint = "https://sdkms.fortanix.com"
    app_id = "<App UUID>"
    prevent_duplicate_opaque_objects = true
    retry_timeout_millis = 3000
    [log]
    file = "<log filename>"
    note.png NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert_file, key_file, etc. This means the configuration is applicable for certificate-based authenticate mode too.
  6. Create a TDE master encryption key inside the HSM using App password. The password can be fetched as per Section 4.4. 
    alter system set encryption key identified by "	<SDKMS_APP_PASSWORD>";
    This will insert "SDKMS_APP_PASSWORD" into the auto-login wallet. From now on, no password is required to access encrypted data with the TDE master encryption key stored in an HSM.
    note.png NOTE: If certificate-based authentication is set (See Section 4.5), then password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password. 
    alter system set encryption key identified by "file:///etc/fortanix/pkcs11.conf";
  7. Run the following command to check the wallet open status. 
    SELECT * FROM V$ENCRYPTION_WALLET;
  8. Shutdown the database immediately.
  9. Startup the database.
  10. Run the following command to verify that the wallet is auto-open. 
      SELECT * FROM V$ENCRYPTION_WALLET;

This completes the auto-login steps for Oracle 11g.

7.2  Auto-Login in Oracle 12c and 18c

note_icon.svg NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.

  1. Check if 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. 
    Select * from V$ENCRYPTION_WALLET
  2. Close the HSM keystore if it is open. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
  3. Create directory for software wallet. 
    mkdir /opt/oracle/admin/ORCLCDB/wallet/Fortanix
    Where $ORACLE_BASE/admin/$ORACLE_SID/wallet/Fortanix is the wallet location.
  4. Now create a software keystore. This keystore will store the password to the HSM wallet for the purpose of auto-login. Make sure you use “<SDKMS_APP_PASSWORD>” as the wallet password in this step.
    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE "/opt/oracle/admin/ORCLCDB/wallet/Fortanix" IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
    note_icon.svg NOTE:
    • Provide a password of at least 8 characters above. This will be your software wallet password. Remember it for future use.
    • From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For 12.2 database and above, it is also required to keep the wallet password the same as “<SDKMS_APP_PASSWORD>”.
  5. Reconfigure the sqlnet.ora file and add the keystore location of the software keystore created in Step 3 to the DIRECTORY setting of the ENCRYPTION_WALLET_LOCATION setting. For example: 
    ENCRYPTION_WALLET_LOCATION=
 (SOURCE=(METHOD=FILE)(METHOD_DATA=
   (DIRECTORY=/home/oracle/WALLETS/Fortanix)))
  6. Reconnect to the database, or log out and then log back in again, so that the change that you made in the previous step takes effect.
  7. Open the software keystore. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY password;
  8. Add Fortanix Self-Defending KMS 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. The app password can be fetched as per Section 4.4.
    ADMINISTER KEY MANAGEMENT ADD SECRET '<SDKMS_APP_PASSWORD>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY “<SDKMS_APP_PASSWORD>” WITH BACKUP;
    note_icon.svg NOTE: If certificate-based authentication is set (See Section 4.5), then the password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password. 
    ADMINISTER KEY MANAGEMENT ADD SECRET 'file:///etc/fortanix/pkcs11.conf' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY password WITH BACKUP;
  9. Edit the existing PKCS#11 config file:
    • Remove API Key if it exists in the file.
    • Add App Id. This value can be fetched from Section 4.4.
      The updated contents of pkcs11.conf is: 
      api_endpoint = "https://sdkms.fortanix.com"#
app_id = "<App UUID>"
      prevent_duplicate_opaque_objects = true
      retry_timeout_millis = 3000
[log]
file = "<log filename>"

    note_icon.svg NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert_file, key_file, etc. This means the configuration is applicable for certificate-based authenticate mode too.

  10. Close the software keystore. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
  11. Now create the auto-login keystore. 
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/Fortanix' IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
  12. Update the sqlnet.ora file to use the hardware security module location. Comment the previously configured wallet location (adjust DIRECTORY to the path where your wallet is stored). 
    ENCRYPTION_WALLET_LOCATION = (SOURCE = (METHOD=HSM)(METHOD_DATA=(DIRECTORY=/opt/oracle/admin/ORCLCDB/wallet/Fortanix)))
  13. Shutdown and restart the database for changes to pick up.
  14. Run the following command to verify that the wallet is auto-open. 
    SELECT * FROM V$ENCRYPTION_WALLET;
    This completes the auto-login steps for Oracle 12c and 18c.

7.3   Auto-Login in Oracle 19c

note_icon.svg NOTE: Complete the Steps for HSM Wallet as per Section 5.0, before proceeding for auto-login steps. The TDE master key needs to be created before auto-login can be set.

  1. Check if 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. 
    Select * from V$ENCRYPTION_WALLET
  2. Close the HSM keystore if it is open. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY "file:///etc/fortanix/pkcs11.conf" CONTAINER = ALL;
  3. Create directory for software wallet. 
    mkdir /opt/oracle/admin/ORCLCDB/wallet/Fortanix
    Where the wallet location should resemble $WALLET_ROOT/tde. See how WALLET_ROOT is set in Section 5.2.
  4. Change the keystore type to software wallet. 
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE"
  5. Create a software keystore. This keystore will store the password to the HSM wallet for the purpose of auto-login. 
    ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/tde' IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
    note_icon.svg NOTE:
    • Provide a password of at least 8 characters above. This will be your software wallet password. Remember it for future use.
    • From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For 12.2 database and above, it is also required to keep the wallet password the same as “<SDKMS_APP_PASSWORD>”.
  6. Open the software keystore. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
  7. Add Fortanix Self-Defending KMS App password as a secret in the software wallet using the client as HSM_PASSWORD. HSM_PASSWORD. This is an Oracle defined client name that is used to represent the HSM password as a secret in the software keystore. The app password can be fetched as per Section 4.4. 
    ADMINISTER KEY MANAGEMENT ADD SECRET '<SDKMS_APP_PASSWORD>' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY “<SDKMS_APP_PASSWORD>” WITH BACKUP;
    note_icon.svg NOTE: If certificate-based authentication is set (See Section 4.5), then the password is not needed to be set. In this case the location of pkcs#11 config file used as a placeholder password. 
    ADMINISTER KEY MANAGEMENT ADD SECRET 'file:///etc/fortanix/pkcs11.conf' FOR CLIENT 'HSM_PASSWORD' IDENTIFIED BY password WITH BACKUP;
  8. Edit the existing PKCS#11 file:
    • Remove API Key if exists in the file.
    • Add App Id. This value can be fetched from Section 4.4.
      The updated contents of pkcs11.conf is:
      api_endpoint = "https://sdkms.fortanix.com"
      app_id = "<App UUID>"
      prevent_duplicate_opaque_objects = true
      retry_timeout_millis = 3000
      [log]
      file = "<log filename>"

      note_icon.svg NOTE: The rest of the contents in pkcs11.conf file can be kept the same. E,g, ca_certs, cert, key, etc. This means the configuration is applicable for certificate-based authenticate mode too.

  9. Close the software keystore. 
    ADMINISTER KEY MANAGEMENT SET KEYSTORE CLOSE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
  10. Now create the auto-login keystore. 
    ADMINISTER KEY MANAGEMENT CREATE AUTO_LOGIN KEYSTORE FROM KEYSTORE '/opt/oracle/admin/ORCLCDB/wallet/tde IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;
  11. Set the wallet location to HSM backed by auto-login.
    ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=HSM|FILE"
  12. Shutdown and restart the database for changes to pick up.
  13. Run the following command to verify that the wallet is auto-open. 
    SELECT * FROM V$ENCRYPTION_WALLET;
    This completes the auto-login steps for Oracle 19c.

8.0   Oracle RAC Setup

Oracle RAC (Real Application Cluster) is a cluster database with a shared cache architecture that overcomes the limitations of traditional shared-nothing and shared-disk approaches to provide highly scalable and available database solutions for enterprises. Oracle RAC is a key component of Oracle's private cloud architecture.

For Oracle RAC Cluster setup, you can perform both direct hsm or auto-login hsm procedures mentioned in Section 5.0 and Section 7.0 for Fortanix Self-Defending KMS integration. You will need to additionally make sure of the following:

  1. The PKCS11 config file should be:
    • Either at a central location /etc/fortanix/pkcs11.conf
    • Or at a location pointed by env variable FORTANIX_PKCS11_CONFIG_PATH see Step 2 of Section 5.4 for more details.
  2. The PKCS11 library that you will use should be version 3.3 and above. The latest library can be downloaded from the URL:
    https://support.fortanix.com/hc/en-us/articles/360018312391-PKCS-11
  3. For autologin setup in Oracle 11g, the software wallet creation steps (Section 7.1, Step 3, and 4) can be skipped for the rest of the nodes.
    1. Complete the software keystore creation steps on node 1.
    2. Copy the software wallet files in the directory to the same location on other nodes (the .sso .p12 files)
    3. Rest steps remain the same on other nodes.
  4. For any other Oracle database version and integration type (auto-login etc.), all integration steps need to be executed on all the nodes in RAC cluster.

9.0  Master Key Rotation

Oracle database supports rotation of The TDE Master Key in Fortanix Self-Defending KMS.

  • Key Rotation activity is driven by Oracle database, and not to be performed at Fortanix Self-Defending KMS directly. Thus, this requires the involvement of DBA.
  • The Key rotation cannot be performed in Auto-login mode prior to Oracle database 12.2 versions.
  • From Oracle version 12.2 onwards you can use FORCE option for key rotation with auto-login enabled wallet. For example: 
    ADMINISTER KEY MANAGEMENT SET KEY FORCE KEYSTORE IDENTIFIED BY “<SDKMS_APP_PASSWORD>”;

On Key rotation, Oracle database re-encrypts the existing Data Encryption Keys, with the new rotated key.

  • For Oracle 11g, the key rotation command is 5.7.2
  • For Oracle 12c, 18c and 19c, the key rotation command is 5.8.2

Its recommended to not delete the older master keys in Fortanix Self-Defending KMS. Oracle database will require the other keys in case of restore of older backups of the database.

10.0  Perform the Hardware Keystore Migration

You now have the configuration file for PKCS11 library, containing the app_id , Oracle master key, and the Fortanix Self-Defending KMS application secret stored in Wallet.

You can use the ADMINISTER KEY MANAGEMENT SQL statement to perform a hardware keystore migration.

To migrate from the software keystore to hardware keystore, you must use the MIGRATE USING keystore_password clause in the ADMINISTER KEY MANAGEMENT SET KEY SQL statement to decrypt the existing TDE table keys and the tablespace encryption keys with the TDE master encryption key in the software keystore and then re-encrypt them with the newly created TDE master encryption key in the hardware keystore.

After you complete the migration, you do not need to restart the database, nor do you need to manually re-open the hardware keystore. The migration process automatically reloads the keystore keys in memory.

To perform the hardware keystore migration, follow the steps mentioned in the previous section (Section 7.0) before executing the below procedure.

  1. Use the following syntax when you run the ADMINISTER KEY MANAGEMENT SQL statement for migration. 
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "app_secret_value" MIGRATE USING software_keystore_password [WITH BACKUP [USING 'backup_identifier']];
    note_icon.svg NOTE: Here we need to use the App_secret that you set as HSM_PASSWORD after "IDENTIFIED BY", and then after MIGRATE USING you must use the software wallet password. For example, run the command as follows: 
    ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "V5iFE8LjFGk_p-pmhl74GVlqsp9JrdQ8fNEKeOY5VJ9XUibj18Ci9sLYCvIGY6og_Ql2sHSveoKi3WTHvvJ38w" MIGRATE USING password;
  2. You will receive the message “keystore altered”.
  3. Check if the appropriate keystores are opened, and contain the master key using the below command. 
    SELECT * FROM V$ENCRYPTION_WALLET;

11.0   Modify HSM Heartbeat Check Interval 

note_icon.svg NOTE: This section does not apply to Oracle 11G.

Oracle performs continuous HSM heartbeat checks by performing crypto operation with a key stored in HSM.

The default interval at which Oracle sends HSM Heartbeat check is 3 seconds. Fortanix recommends modifying this interval to a larger interval, as follows:

ALTER SYSTEM SET "_heartbeat_period_multiplier"= xx SCOPE=SPFILE;
ALTER SYSTEM SET "_heartbeat_config"=AUTOCONNECT SCOPE=SPFILE;

Where xx is used in the following way to determine the heartbeat interval:
xx + 3 (initial seconds) = yyy seconds.
For example, if you want to set the heartbeat interval to

  1. 2 minutes (120 seconds), the xx value will be 39.
    39x3 + 3 (initial seconds) = 120 seconds.
  2. 1 hour (3600 seconds), the xx value will be 1199. (This is recommended value by Fortanix).               1199x3 + 3 (initial seconds) = 3600 seconds.

12.0   Troubleshooting

The following table describes the possible reasons for errors and exceptions and provides information about resolving them.

PROBLEM

RESOLUTION

Issues while opening the HSM wallet

Ensure the following to troubleshoot:

  • The sqlnet.ora file you edited is the one being used by database.
  • The directory permissions of the folder where software wallet is stored is correct such that it is readable and writeable by 'oracle' user.
  • You have only one PKCS11 library under folder /opt/oracle/extapi/64/hsm/. Having multiple libraries under different sub-folders of this folder can cause Oracle to fail to load any library.

Failing to open HSM wallet (ORA-28353)

Look at PKCS11 log file to check if C_Login is failing. A failing entry for C_Login will have non-zero status as follows:

2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160

C_Login Failure

Verify the following information is correct:

  • API end point points to your instance of Fortanix Self-Defending KMS.
  • API key used by your setup is correct and corresponding app in Fortanix Self-Defending KMS in enabled.
  • Network connectivity from your database server to Fortanix Self-Defending KMS is working.

Encrypted Tablespace creation Failure

ERROR at line 1: ORA-00406: COMPATIBLE parameter needs to be 11.0.0.0.0 or greater ORA-00722: Feature "Tablespace Level Encryption"

In Oracle database 11g installation which have been upgraded from older version, the parameter COMPATIBLE needs to be set to increased to enable tablespace encryption. Run following command and restart database:

alter system set COMPATIBLE='11.2.0' scope=spfile;

HSM heartbeat Failure error

Look at the PKCS11 log file to find which PKCS11 function is failing. Oracle performs continuous HSM heartbeat checks by performing crypto operation with a key stored in HSM. To troubleshoot heartbeat check failure, please check the following:

  • Verify the information is correct as mentioned in the steps for troubleshooting C_Login failure.
  • Verify the Oracle TDE master key in Fortanix Self-Defending KMS is enabled and exists.

PKCS library fails to open the PKCS11  configuration file and uses default              configuration.

oracle[14045]: could not read  config file /root/.config/fortanix/pkcs11.conf, using default configuration...

  Look for the PKCS11 errors in the log file, for     

example:
 /var/log/mesages

 

 

 

API failures from the PKCS#11 service

Configure the error retry limit by setting retry_timeout_millis = xxxx in the config file. Where xxxx is the value of time in milliseconds. This is the maximum duration for which the PKCS#11 library will do any number of retries in case of API failures. For example, retry_timeout_millis = 6000 sets the retry limit to 6 secs. The default value is 3000, which is 3 secs.

Orcale DB crashes

Check if app is disabled in Fortanix Self-Defending KMS.

Network connection lost between Oracle and Fortanix Self-Defending KMS

Check firewall rules and IP table rules.

note_icon.svg NOTE: It is recommended that you configure your PKCS11 config file to store PKCS11 logs in a separate file. During TDE configuration or operation, if you get an error, please send the PKCS11 log file to Fortanix support team to troubleshoot the issue. Contents of PKCS11 log file will appear as follows:

2019-06-13T01:31:36.720632089-04:00 - Fortanix C_Login -> 160
2019-06-13T01:31:36.722161947-04:00 - Fortanix C_CloseSession -> 0
2019-06-13T01:31:36.722188512-04:00 - Fortanix C_Finalize -> 0

12.1   Rollback and Recovery

13.0   References

  1. Introduction to Transparent Data Encryption
    https://docs.oracle.com/en/database/oracle/oracle-database/12.2/asoag/introduction-to-transparent-data-encryption.html
  2. Fortanix Self-Defending KMS Getting started
    https://support.fortanix.com/hc/en-us/articles/360015809372-Getting-Started-with-SDKMS
  3. Oracle TDE and auto-login keystore
    https://docs.oracle.com/database/121/ASOAG/managing-keystore-and-tde-master-encryption-key.htm#ASOAG10434