1.0 Introduction

This article describes the steps to integrate Fortanix Data Security Manager (DSM) with Oracle Key Vault (OKV).

The Oracle Key Vault (OKV) uses an Oracle Database to store the client/endpoint keys. This Oracle DB repository inside OKV uses Transparent Data Encryption (TDE) and the TDE master key is stored in a local file wallet on the OKV server. In a standard OKV configuration, the OKV TDE key is stored inside a password-protected wallet. With Fortanix HSM integration, the OKV wallet password will be encrypted using a key that will be stored in Fortanix HSM as a root of trust.

2.0 Prerequisites

• Fortanix DSM minimum version - 4.2
• Fortanix PKCS#11 library
• Oracle Key Vault 21.3
• Oracle Key Vault should be able to reach Fortanix DSM

Sign up with Fortanix DSM and create a group, create an app, and add the app to the group. Refer to Section 3.3 for more details.

3.0 Fortanix Data Security Manager Integration with Oracle Key Vault

3.1 Create Fortanix Directories

1. Log in to Oracle Key Vault Server and switch to the root directory.
2. Create the following directory structures under /opt.

   #mkdir -p /opt/fortanix/bin /opt/fortanix/conf /opt/fortanix/log

   NOTE

   Oracle recommends creating the client installation directory in a new subdirectory under /opt.

3.2 Change the Ownership and Permission of Fortanix DSM Directories

Now change the ownership and permission of Fortanix DSM client installation directories using the following commands:

#chown -R oracle:oinstall /opt/fortanix
#chmod -R 755 oracle:oinstall

3.3 Copy the Fortanix DSM App UUID

1. Log in to Fortanix DSM account for OKV and create a group and an app.
   Figure 1: Create an app
2. Copy the app UUID and Password.
   
                                        Figure 2: App UUID and Password

3.4 Upload Fortanix PKCS#11 Library

1. Download and install the Fortanix PKCS#11 library by following the instructions provided in the URL:
   https://support.fortanix.com/hc/en-us/articles/360016160451-Clients-PKCS-11-Library
2. Upload the Fortanix PKCS#11 library to /opt/fortanix/bin location in the OKV server.
3. Rename the library to libpkcs11.so.

3.5 Create PKCS#11 Config File

Create the pkcs11.conf file in the /opt/fortanix/conf folder with the following parameters:

api_endpoint = "https://sdkms.fortanix.com"
app_id="<Fortanix_DSM_APP_ID>"
prevent_duplicate_opaque_objects = true
retry_timeout_millis = 60000

[log]
file = "/opt/fortanix/log/pkcs11.log"

3.6 Modify HSM Config Parameters

Modify okv_hsm.conf parameters and add the parameters as below:

#cd /usr/local/okv/hsm/generic
In okv_hsm.conf add the below paths 
VENDOR_NAME="Fortanix"
PKCS11_LIB_LOC= “/opt/fortanix/bin/libpkcs11.so”
PRESEVED_FILES=”/opt/fortanix/bin:/opt/fortanix/conf:/opt/fortanix/conf/pkcs11.conf: /opt/fortanix/bin/libpkcs11.so”

3.7 Add Environment Variable

Add the following environment variable in okv_hsm_env file under /usr/local/okv/hsm/generic.

FORTANIX_PKCS11_CONFIG_PATH=”/opt/fortanix/conf/pkcs11.conf”

3.8 Verify Fortanix DSM Endpoint Connectivity

Verify that the Fortanix DSM endpoint is reachable from the OKV server.

1. Run the following curl command to verify the SSL certificate.

   #curl -v <endpoint_url>
   

   NOTE

   If the SSL verification is failing, you should upload the endpoint rootCA certificate to /opt/fortanix/conf directory and add the following parameter to the pkcs11.conf file.

   ca_certs_file = "/opt/fortanix/conf/rootCA.pem"
   

2. You can verify the certificate check using the following command.

   # curl --cacert /opt/fortanix/conf/rootCA.pem <endpoint_url> -v
   

3.9 Initialize HSM

For the rest of the activity, use the OKV UI console.

1. Log in to Oracle Key Vault SYSADMIN. 
2. Go to the System tab and click Hardware Security Module. 
3. Click the Initialize button to initialize the HSM and enter the HSM Credential and OKV Recovery Passphrase.
   • HSM Credential: APP_PASSWORD
   • Re-enter HSM Credential: APP_PASSWORD
   • Recovery Password: <the OKV recovery password>
   
   Figure 3: Initialize HSM
4. The HSM is initialized.
   Figure 4: HSM initialized

3.10 Set HSM Credentials

1. If you want to change the APP_CREDENTIALS (HSM credentials) at any point, you can follow the process below:
   1. Change the secret size and regenerate the App password by clicking the REGENERATE button.
      Figure 5: Regeneratre API key
2. Click the Set Credential button on OKV SYSADMIN-> Hardware Security Module. This will pop up a prompt asking to fill the new password.
   Figure 6: Set credential
   • HSM Credential: <New APP_ID>
   • Re-enter HSM Credential: <New APP_ID>

3.11 Reverse Migration of HSM

NOTE

At times when you need to revert the Fortanix DSM integration for some reason, you can perform the following procedure:
Figure 7: HSM reverse migration

• HSM Credential: <APP_PASSWORD>
• Old Recovery Passphrase: <APP_PASSWORD>
• New Recovery Passphrase: <New OKV Recovery Passphrase>
• Re-enter New Recovery Passphrase: <New OKV Recovery Passphrase>

After successful reverse migration, check the status as below:
Figure 8: Reverse migration complete

4.0 OKV Backup and Restoration with Root of Trust in Fortanix DSM

The following are the steps for the OKV backup and restore:

1. Manage the backup location to a remote server.
2. Take a backup.
   NOTE

   Make sure the HSM integration status is green (enabled) before taking the backup.
3. Install and configure a fresh OKV instance.
4. Follow all the process as described in Section 3.1 to 3.8 and make sure Fortanix DSM integration prerequisites are configured.
5. Configure the manage backup location to the same remote server where backup files are available, taken in Step 2 above.
6. Set the HSM credentials and restore the backup on the new instance of OKV.
   Figure 9: Available backups
   Figure 10: Restore details
   Figure 11: OKV restored
   For more details, refer to the Oracle Key Vault Backup and Restoration (Section 2.4.2)