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
- Log in to Oracle Key Vault Server and switch to the root directory.
- Create the following directory structures under /opt.
#mkdir -p /opt/fortanix/bin /opt/fortanix/conf /opt/fortanix/log
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
- Log in to Fortanix DSM account for OKV and create a group and an app.
Figure 1: Create an app - Copy the app UUID and Password.
Figure 2: App UUID and Password
3.4 Upload Fortanix PKCS#11 Library
- 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 - Upload the Fortanix PKCS#11 library to
/opt/fortanix/bin
location in the OKV server. - 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.
- Run the following curl command to verify the SSL certificate.
#curl -v <endpoint_url>
- 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.
- Log in to Oracle Key Vault SYSADMIN.
- Go to the System tab and click Hardware Security Module.
- 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 - HSM Credential:
- The HSM is initialized.
Figure 4: HSM initialized
3.10 Set HSM Credentials
- If you want to change the
APP_CREDENTIALS
(HSM credentials) at any point, you can follow the process below:- Change the secret size and regenerate the App password by clicking the REGENERATE button.
Figure 5: Regeneratre API key
- Change the secret size and regenerate the App password by clicking the REGENERATE button.
- 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
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:
- Manage the backup location to a remote server.
- Take a backup.
- Install and configure a fresh OKV instance.
- Follow all the process as described in Section 3.1 to 3.8 and make sure Fortanix DSM integration prerequisites are configured.
- Configure the manage backup location to the same remote server where backup files are available, taken in Step 2 above.
- 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)
Comments
Please sign in to leave a comment.