Using Data Security Manager With Oracle Key Vault

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.

It also contains the information that a user requires to:

• Configure Fortanix DSM

• Initialize HSM

• Set credential

• Perform HSM reverse migration

• Perform OKV backup and restoration

2.0 Prerequisites

Ensure the following:

• 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

3.0 Configure Fortanix DSM

A Fortanix DSM service must be configured, and the URL must be accessible. To create a Fortanix DSM account and group, refer to the following sections:

3.1 Signing Up

To get started with the Fortanix DSM cloud service, you must register an account at <Your_DSM_Service_URL>. For example, https://eu.smartkey.io.

For detailed steps on how to set up the Fortanix DSM, refer to the User's Guide: Sign Up for Fortanix Data Security Manager SaaS documentation.

3.2 Creating an Account

Access <Your_DSM_Service_URL> in a web browser and enter your credentials to log in to Fortanix DSM.

For more information on how to set up an account in Fortanix DSM, refer to the User's Guide: Getting Started with Fortanix Data Security Manager - UI.

3.3 Creating a Group

Perform the following steps to create a group in the Fortanix DSM:

1. In the DSM left navigation panel, click the Groups menu item, and then click the + button to create a new group.

   

2. On the Adding new group page, do the following:

   1. Title: Enter a name for your group.

   2. Description (optional): Enter a short description of the group.

3. Click SAVE to create the new group.

The new group is added to the Fortanix DSM successfully.

3.4 Creating an Application

Perform the following steps to create an application (app) in the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the + button to create a new app.

   

2. On the Adding new app page, do the following:

   1. App name: Enter the name for your application.

   2. ADD DESCRIPTION (optional): Enter a short description of the application.

   3. Authentication method: Select the default API Key as the authentication method from the drop down menu. For more information on these authentication methods, refer to the User's Guide: Authentication.

   4. Assigning the new app to groups: Select the group created in Section 3.3: Creating a Group from the list.

3. Click SAVE to add the new application.

The new application is added to the Fortanix DSM successfully.

3.5 Copying the App UUID

Perform the following steps to copy the app UUID from the Fortanix DSM:

1. In the DSM left navigation panel, click the Apps menu item, and then click the app created in Section 3.4: Creating an Application to go to the detailed view of the app.

2. On the INFO tab, click VIEW API KEY DETAILS.

3. Click the USERNAME/PASSWORD tab.

4. From the Credentials Details dialog box, copy the Username (app UUID) and Password as it will be used in the PKCS#11 configuration file.

4.0 Create Fortanix Directories

Perform the following steps to create the Fortanix DSM 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.

5.0 Change the Ownership and Permissions

Run the following commands to change the ownership and permissions of the Fortanix DSM client installation directories:

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

6.0 Upload Fortanix PKCS#11 Library

Perform the following steps to download Fortanix PKCS#11 library and then upload it to OKV server:

1. Download and install the Fortanix PKCS#11 library. For more information, refer to the 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.

7.0 Create PKCS#11 Configuration 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"

8.0 Modify HSM Configuration 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”

9.0 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”

10.0 Verify Fortanix DSM Endpoint Connectivity

Perform the following steps to 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. Run the following command to verify the certificate check:

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

11.0 Initialize HSM

For the rest of the activity, use the OKV user interface (UI) console.

1. Log in to Oracle Key Vault SYSADMIN. 

2. Go to the System tab and click Hardware Security Module. 

3. Click Initialize 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>

   

4. The HSM is initialized.

   

12.0 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 REGENERATE.

      

2. Click Set Credential on OKV SYSADMIN → Hardware Security Module. This will pop up a prompt asking to fill the new password.

   

   • HSM Credential: <New APP_ID>

   • Re-enter HSM Credential: <New APP_ID>

13.0 Reverse Migration of HSM

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

• HSM Credential: <APP_PASSWORD>

• Old Recovery Passphrase: <OKV Recovery Passphrase>

• 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:

14.0 OKV Backup and Restoration

Perform the following steps to back and restore the OKV with root of trust in Fortanix DSM:

1. Manage the backup location to a remote server.

2. Take a backup.

   NOTE

   Ensure 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 4.0: Create Fortanix Directories to Section 11.0: Initialize HSM and ensure that 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.

6. Set the HSM credentials and restore the backup on the new instance of OKV.

   

   

   

   For more information, refer to the Section 2.4.2 in Oracle Key Vault Backup and Restoration.