Vendor Instructions for Integrating an HSM as the Root of Trust for Oracle Key Vault

HSM vendors are responsible for documenting and testing instructions to integrate their HSM with Oracle Key Vault.

About Integrating an HSM as a Root of Trust for Oracle Key Vault

This type of integration enables Oracle Key Vault to use HSMs other than Thales Luna Network HSM version 7000, Entrust nShield Connect + and XC models, or Utimaco’s SecurityServer 4.31.1.

You, the vendor, need to work with the Oracle Key Vault administrator to complete the integration. Oracle Key Vault provides files to enable the setting of parameters and environment variables, as well as scripts to help with the upgrade process. The Oracle Key Vault administrator will need to configure these scripts. You will need to provide documentation on how to use and configure them, and be responsible for updating this documentation for subsequent releases.

In the general, you will need to perform the following steps:

  1. Ensure that your HSM meets the requirements for performing the integration, which include the ability to install the HSM client software, verifying the required functionality of the PKCS#11 library, and the ability to enroll the Oracle Key Vault as a client of the HSM.

  2. Provide documentation for managing the configuration and environment variable files, and the upgrade scripts. Ensure that you update this documentation as the HSM’s needs change. Oracle Key Vault provides the following files: okv_hsm.conf, okv_hsm_env, and okv_hsm_mid_upgrade.

  3. After you document the necessary steps to integrate Oracle Key Vault with the HSM, confirm the success of the integration. This includes enabling the HSM, and performing tasks such as upgrades, backups, and restore operations.

  4. Validate the HSM as a Root of Trust (RoT) in standalone, multi-master cluster, and primary-standby environments.

Requirements Before Starting the Integration

The vendor of the HSM to be integrated with Oracle Key Vault must meet certain requirements, such as providing instructions on how to install the client software and ensuring the PKCS#11 library provides the required functionality.

Requirements for the Vendor’s HSM Client Installation Software

The HSM client software installation process must fulfill requirements such as installing the HSM client software into its own directory

As the vendor, you must do the following:

Requirements for the PKCS#11 Library

As the vendor, ensure that your library supports all of the necessary PKCS#11 functionality.

The PKCS#11 library must supply the following functions:

Configuration Requirements for Enrolling Oracle Key Vault as the HSM Client

HSMs typically require additional configuration for enrolling Oracle Key Vault as a client of the HSM.

This enrollment enables the communication between Oracle Key Vault and the HSM.

As the vendor, you must document and maintain these detailed instructions. The requirements are as follows:

Integrating the HSM

The integration process includes setting up configuration files and scripts.

okv_hsm.conf Parameters

Oracle Key Vault provides a configuration file to enable Oracle Key Vault administrators to define information such as the vendor name.

The okv_hsm.conf file is located in the /usr/local/okv/hsm/generic/ directory. As the vendor, ensure that you document the correct way to complete the okv_hsm.conf configuration file, including updating this documentation for subsequent releases.

The okv_hsm.conf file contains the following settings:

okv_hsm_env Environment File

Oracle Key Vault provides an environment file so that Oracle Key Vault administrators can specify environment variables that are needed when Oracle Key Vault uses the PKCS#11 library.

If the HSM’s PKCS#11 library requires special environment variables, then the Oracle Key Vault administrator can include these variables in the okv_hsm_env file. Ensure that you document the correct way to complete the okv_hsm_env file, including updating this documentation for subsequent releases.

okv_hsm_mid_upgrade Script

Oracle Key Vault provides a script that can help to reapply configurations that may be lost during an upgrade.

As the vendor, ensure that you document the correct way to complete the okv_hsm_mid_upgrade script, including updating this documentation for subsequent releases.

This script is necessary during upgrades, particularly a major version that upgrades the operating system version, to ensure that information such as user accounts are recreated in the newer Oracle Key Vault version. Because Oracle Key Vault will need access to the Root of Trust (RoT) key in the HSM after the appliance restarts with the newer operating system version, these changes must be executed mid-upgrade.

As the vendor, you must address any configurations that need to be modified during the upgrade. The script must perform the following actions:

For example, if your HSM installation includes a service as a part of the HSM client software setup, and the service is needed for Oracle Key Vault to connect to the HSM, then in the mid-upgrade script, you should check and enforce that both the service exists and is running. If you created a user, in the mid-upgrade script, then you should check both that the user exists and that it continues to own any HSM-related files that it owned before the upgrade was started (or recreate the user and chown any files as appropriate). Anything that is not a preserved file or directory as specified in the parameter file is liable to be removed, so ideally this script would check and fix all vendor-owned files and directories (and their permissions) on the Oracle Key Vault server itself in detail.

You can rely on host name resolution to work during this step, provided that DNS servers were saved in Oracle Key Vault’s settings before upgrading.

Pre- or Post-Upgrade Validation Scripts

You can provide pre- or post-upgrade scripts that the Oracle Key Vault administrator can run before and after the upgrade process to ensure that the HSM configuration is correct.

These scripts are useful for Oracle Key Vault administrators to ensure that all HSM-related configurations are as expected either before the upgrade begins or after the upgrade completes.

As the vendor, ensure that you document the correct way to configure these scripts, including updating this documentation for subsequent releases.

Confirming the Success of the HSM Configuration

Testing operations such as HSM-enabling, upgrading, backing up, and restoring Oracle Key Vault while integrated with an HSM is essential to confirming a successful integration.

Enabling the HSM in a Standalone Environment

The HSM should be enabled as a Root of Trust (RoT) for a standalone Oracle Key Vault environment in much the same way that any of the standard HSMs, such as Thales Luna Network HSM version 7000, Entrust nShield Connect + and XC models, or Utimaco’s SecurityServer 4.31.1, can be enabled.

The HSM vendor must provide instructions on how to specify the token label. Oracle recommends that a token label is specified.

The following behavior indicates that the HSM-enable operation is successful:

Check the log files in the /var/okv/log/hsm directory.

This operation creates a RoT key and creates or updates a key number object in the HSM. The key number object is used to associate a unique key number with each RoT key that is created in the HSM. The key number starts at 1 and is incremented by 1 with each successive HSM-enable operation. To increment the number, the current value is fetched and updated. It is possible the key number object’s value could change before the update operation completes. The HSM vendor must take special care to document any additional steps that may be necessary to prevent conflicts (for example, two RoT keys created with the same key number). Failure to do so may render an Oracle Key Vault unable to create the auto-login wallet when the Oracle Key Vault server is restarted, and will require manual intervention. You can find the key number in the generated log files in the /var/okv/log/hsm directory.

Related Topics

Performing an Upgrade of an HSM-Enabled Oracle Key Vault Server

The vendor should be able to upgrade an Oracle Key Vault server that is integrated with other HSMs in much the same way that Oracle Key Vault is normally upgraded.

Perform the Oracle Key Vault upgrade, and include any additional steps that the HSM vendor’s documentation requires.

When an Oracle Key Vault server is configured with an HSM, the following activities indicate that the upgrade was successful:

Related Topics

Performing a Backup of an HSM-Enabled Oracle Key Vault Server

The vendor should be able to perform a backup of an HSM-enabled Oracle Key Vault server in the Oracle Key Vault management console.

Perform the Oracle Key Vault backup operation.

The following behavior indicates that the backup operation is successful:

Check the log files in the /var/okv/log/hsm directory.

Related Topics

Performing a Restore of an HSM-Enabled Oracle Key Vault Server

The vendor should be able to perform a restore of an HSM-enabled Oracle Key Vault server from the Oracle Key Vault management console.

Perform the Oracle Key Vault restore operation.

The following behavior indicates that the restore operation is successful:

Related Topics

Confirming the Success of the HSM Configuration in a Multi-Master Cluster

To confirm the HSM configuration in a multi-master cluster environment, the vendor must be able to HSM-enable a multi-master cluster starting with a single node or an entire cluster.

Starting with an HSM-Enabled Single Node

The vendor should be able to build a multi-master cluster, starting with a single HSM-enabled node, and then add other HSM-enabled nodes to the cluster.

  1. HSM-enable one node, and then add a second HSM-enabled node as a read-write peer of the first node.

    After the pairing completes, the Oracle Key Vault management console Cluster Management page on both nodes must show both nodes in the ACTIVE state.

  2. Restart both nodes, as described in Oracle Key Vault Administrator’s Guide.

  3. After Oracle Key Vault restarts, ensure that the Oracle Key Vault management console is accessible to both of the nodes.

  4. Add a third HSM-enabled node to the cluster, using either the first or the second node as the controller node.

    After the pairing completes, the Oracle Key Vault management console Cluster Management page on all three nodes must show that these nodes are in the ACTIVE state.

  5. Restart the third node, and then ensure that the Oracle Key Vault management console is accessible to this node.

  6. Create a wallet on both of the read-write nodes.

  7. Ensure that the status for both of the wallets goes from PENDING to ACTIVE.

    To do so, check the wallets’ name status on all three nodes.

Related Topics

HSM-Enabling a Cluster with Multiple Nodes

The vendor must first build the multi-master cluster with no HSM-enabled nodes. From there, the vendor HSM-enables each node one at a time.

  1. Create or use an existing multi-master cluster that has at least three nodes, in which two are read-write peer nodes and one is a read-only node.

  2. HSM-enable one node in this cluster.

  3. Create the HSM bundle on the HSM-enabled node and apply the HSM bundle to the other two nodes in the cluster.

  4. Restart all nodes, as described in Oracle Key Vault Administrator’s Guide.

  5. After Oracle Key Vault restarts, confirm that the Oracle Key Vault management console is accessible to these nodes and that replication works between all three nodes.

  6. HSM-enable the other two nodes.

  7. Restart the three nodes.

  8. After Oracle Key Vault restarts, ensure that the Oracle Key Vault management console is accessible to all three nodes.

  9. Create a wallet on both of the read-write nodes.

  10. Ensure that the status for both of the wallets goes from PENDING to ACTIVE.

    To do so, check the wallets’ name status on all three nodes.

Related Topics

Confirming the Success of the HSM Configuration in a Primary-Standby Environment

To confirm the HSM configuration in a primary-standby environment, the vendor should perform switchover and reverse migration operations.

Creating an HSM-Enabled Primary Standby Configuration

The vendor should be able to configure both the primary and standby Oracle Key Vault servers to use an HSM as a Root of Trust (RoT).

After you complete the configuration, in the Oracle Key Vault management console of the primary server Primary-Standby Status page, you should see Primary-Standby mode is enabled, and the Switchover Status should be TO STANDBY.

Check the log files in the /var/okv/log/hsm directories of both the primary and standby servers.

Related Topics

Performing an HSM-Enabled Primary-Standby Switchover Operation

The vendor should be able to execute a switchover operation between a pair of HSM-enabled primary and standby Oracle Key Vault servers, as described in Oracle Key Vault Administrator’s Guide.

After you complete the switchover operation, the Oracle Key Vault management console Primary-Standby Status page for the new primary should show Primary-Standby mode is enabled, and the Switchover Status should be TO STANDBY.

Check the log files in the /var/okv/log/hsm directories of both the primary and standby servers.

Related Topics

Performing a Reverse Migration of an HSM-Enabled Primary-Standby Configuration

The vendor should be able to perform a reverse migration of both the primary and standby HSM-enabled Oracle Key Vault servers.

After you complete the reverse migration operation on the primary Oracle Key Vault server, there should be a green success message, and there should be a red downward status arrow.

Next, do the following:

  1. Reverse migrate the standby Oracle Key Vault server.

  2. Perform a switchover operation as described in Oracle Key Vault Administrator’s Guide, and then verify the operation’s success.

  3. Restart both the primary and standby Oracle Key Vault servers, as described in as described in Oracle Key Vault Administrator’s Guide.

  4. Verify that the primary server can access the Oracle Key Vault management console.

Related Topics

Performing a Reverse Migration Operation

In this operation, the vendor removes the HSM as a Root of Trust (RoT) configuration by reverse migrating an Oracle Key Vault server.

Perform the reverse migration operation as is normally done in Oracle Key Vault.

The following behavior indicates that the reverse migration operation is successful:

Check the log files in the /var/okv/log/hsm directory.

Related Topics

Validating the HSM as a Root of Trust for Oracle Key Vault

After the vendor creates instructions on how to integrate their HSM with Oracle Key Vault, they should also validate the integration.

Test Cases for Standalone Configurations

For a standalone Oracle Key Vault server, the vendor should be able to HSM-enable a server (initialize) and perform backup and restore operations.

Test Cases for Multi-Master Cluster Configurations

For Oracle Key Vault servers in a multi-master cluster environment, the vendor should be able to HSM-enable nodes, perform backup and restore operations, reverse migrate a cluster, and upgrade a cluster.

As the vendor, perform the following tests:

Test Cases for Primary-Standby Configurations

For Oracle Key Vault servers in a primary-standby configuration, the vendor should be able to create the HSM-enabled primary-standby, and perform standard primary-standby operations.

These operations include switchovers, reverse migrations, backups and restores, and upgrades.