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

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

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

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 Data Security Manager (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 the <Your_DSM_Service_URL> on the web browser and enter your credentials to log in to the Fortanix DSM.

3.3 Creating a Group

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

1. Click the Groups menu item in the DSM left navigation bar and click the + button on the Groups page to add a new group.

   

2. On the Adding new group page, enter the following details:

   • Title: Enter a title for your group.

   • Description (optional): Enter a short description for the group.

3. Click the SAVE button to create the new group.

The new group has been 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. Click the Apps menu item in the DSM left navigation bar and click the + button on the Apps page to add a new app.

   

2. On the Adding new app page, enter the following details:

   • App name: Enter the name of your application.

   • ADD DESCRIPTION (optional): Enter a short description for the application.

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

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

3. Click the SAVE button to add the new application. 

The new application has been 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. Click the Apps menu item in the DSM left navigation bar and 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 the VIEW API KEY DETAILS button.

3. Click the USERNAME/PASSOWORD tab.

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

   

4.0 Create Fortanix Directories

Perform the following steps:

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 Permission of Fortanix DSM Directories

Run the following command to change the ownership and permission of 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:

1. Download and install the Fortanix PKCS#11 library by following the instructions provided in the URL:
   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 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"

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

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. You can verify the certificate check using the following command.

   # 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 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>

   

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 the REGENERATE button.  

      

2. Click the Set Credential button 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

After successful reverse migration, check the status as below:

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

Perform the following steps for the OKV backup and restore:

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 the previous sections 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 above.

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

   

   

   

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