Configuring an HSM for Oracle Key Vault

2 Configuring an HSM for Oracle Key Vault

The HSM can be configured to protect keys, or work in a classic primary-standby configuration or in a multi-master cluster.

Protecting the Oracle Key Vault TDE Master Key with the HSM
You can use the Oracle Key Vault management console to configure protection for the TDE master encryption key.
Enabling HSM in a High Availability Key Vault Installation
In a primary-standby Oracle Key Vault installation, you must enable the HSM separately on the primary and standby servers.
HSMs in a Multi-Master Cluster
You can configure HSMs in a multi-master cluster with a single node or multiple nodes.
Backup and Restore Operations in an HSM-Enabled Oracle Key Vault Instance
You can back up and restore an HSM-enabled Oracle Key Vault instance.
Reverse Migration Operations to a Local Wallet
Reverse migrating an HSM-enabled Oracle Key Vault server reverts the Key Vault server to using the recovery passphrase to protect the TDE wallet.

2.1 Protecting the Oracle Key Vault TDE Master Key with the HSM

You can use the Oracle Key Vault management console to configure protection for the TDE master encryption key.

If you plan to use a multi-master cluster, then Oracle recommends that you perform this procedure before you configure the cluster environment. Ensure that you complete the following steps on this server before you perform these steps on another Oracle Key Vault server.

If you have implemented nCipher Hardware Security Module (HSM), then run the following command as user oracle:
```
oracle$ /opt/nfast/bin/rfs-sync --update
```
Log into the Oracle Key Vault management console as a user with the System Administrator role.
If you are using a multi-master cluster environment, then log into the Oracle Key Vault node that you want to HSM-enable.
Click the System tab.
The Status page appears.
Click Hardware Security Module in the left sidebar.
The Hardware Security Module page appears. The red downward arrow shows the non-initialized Status. The Type field displays None.

Description of the illustration hsm_page.png
Click Initialize.
The Initialize HSM dialog box appears.

Description of the illustration hsm_init_bp3.png
Enter the HSM credential two times: first in HSM Credential and second in Re-enter HSM Credential.
Consult the HSM documentation for this credential. The HSM credential for SafeNet is the SafeNet partition password. For nCipher, the credential is the Operator Card Set password.
Enter the Recovery Passphrase for Oracle Key Vault.
Click Initialize.
At the end of a successful initialize operation, the Hardware Security Module page appears. The initialized Status is indicated by an upward green arrow. The Type field displays details of the HSM in use.

Description of the illustration hsm_post_init.png
If you have implemented nCipher HSM, then run the following command as user oracle:
```
oracle$ /opt/nfast/bin/rfs-sync --commit 
```
If you do not perform this step after each initialization when using nCipher, then multiple features will break, including restoring backups and using the primary-standby configuration.
Verify that the operation was successful by checking the most recent initialization log files in the /var/okv/log/hsm/ directory.

If the initialize operation fails, then you will be redirected to the Hardware Security Module page with non-initialized Status and Type None.

Note:

If you change the HSM credential on the HSM after initialization, then you must also update the HSM credential on the Oracle Key Vault server using the Set Credential command.

Parent topic: Configuring an HSM for Oracle Key Vault

2.2 Enabling HSM in a High Availability Key Vault Installation

In a primary-standby Oracle Key Vault installation, you must enable the HSM separately on the primary and standby servers.

You must perform this task before pairing these two servers in a primary-standby configuration. If you have already HSM-enabled either the primary or the standby server, or both, but do not follow these steps and then do a primary-standby pairing, then the configuration will fail. If the servers are already paired but neither are HSM-enabled, then you must unpair them, reinstall the standby server, and the follow these steps.

Install two separate Oracle Key Vault instances.
Choose one to be the primary node and the other to be the standby node.
Install the HSM client software on both the primary and the standby node.
Enroll the primary and standby nodes as clients of HSM.
Initialize HSM use on the primary.
Log in to the designated primary server through SSH as user support, switch user (su) to root, then switch user (su) to oracle.
```
$ ssh support@okv_primary_instance_IP_address
$ su root
root# su oracle
```

Perform the following manual steps on the primary server as user oracle:

oracle$ cd /usr/local/okv/hsm/wallet
oracle$ scp cwallet.sso support@okv_standby_instance_IP_address:/tmp
oracle$ scp enctdepwd support@okv_standby_instance_IP_address:/tmp
oracle$ cd /usr/local/okv/hsm/restore
oracle$ scp ewallet.p12 support@okv_standby_instance_IP_address:/tmp

Log in to the designated standby server through SSH as user support, then switch user (su) to root.
```
$ ssh support@okv_standby_instance_IP_address
$ su root
```
Open the okv_security.conf file.
A sample okv_security.conf file before enabling HSM in the node appears as follows:
```
SNMP_ENCRYPTION_PWD="snmp_encryption_password" 
SNMP_AUTHENTICATION_PWD="snmp_auth_password" 
SNMP_USERNAME="snmpuser" 
SMTP_TRUSTSTORE_PWD="smtp_truststore_password" 
HSM_ENABLED="0" 
FIPS_ENABLED="fips_value" 
HSM_FIPS_ENABLED="1"
```
Versions of Oracle Key Vault earlier than release 18 may not contain the FIPS_ENABLED or the HSM_FIPS_ENABLED parameter in the okv_security.conf file. Consult the documentation for earlier releases for more information.
Set up the HSM-related files and in the okv_security.conf file, set the HSM_ENABLED and HSM_PROVIDER parameters.
```
$ cd /usr/local/okv/hsm/wallet
$ mv /tmp/enctdepwd .
$ mv /tmp/cwallet.sso .
$ chown oracle *
$ chgrp oinstall *
$ cd /usr/local/okv/hsm/restore
$ mv /tmp/ewallet.p12 .
$ chown oracle *
$ chgrp oinstall *
$ vi /usr/local/okv/etc/okv_security.conf
   Set HSM_ENABLED="1"
   Set HSM_PROVIDER="provider_value"
```
In this specification:
- HSM_ENABLED is set in this example to 1 to enable the HSM for this node. Setting it to 0 disables the HSM.
- HSM_PROVIDER refers to the HSM provider. For SafeNet, set this value to 1. For nCipher, set it to 2.
Save and quit by entering the following sequence of characters in the vi file: :wq!
After you enable the HSM, the okv_security.conf file will be similar to the following:
```
SNMP_ENCRYPTION_PWD="snmp_encryption_password" 
SNMP_AUTHENTICATION_PWD="snmp_auth_password" 
SNMP_USERNAME="snmpuser" 
SMTP_TRUSTSTORE_PWD="smtp_truststore_password" 
HSM_ENABLED="1" 
FIPS_ENABLED="fips_value"
HSM_PROVIDER="2"
```
Versions of Oracle Key Vault earlier than release 18 may not contain the FIPS_ENABLED or the HSM_FIPS_ENABLED parameter in the okv_security.conf file. Consult the documentation for earlier releases for more information.
Without restarting the Oracle Key Vault instances, navigate to the primary and standby Oracle Key Vault management consoles and configure primary-standby environment.

Related Topics

Oracle Key Vault Administrator's Guide

Parent topic: Configuring an HSM for Oracle Key Vault

2.3 HSMs in a Multi-Master Cluster

You can configure HSMs in a multi-master cluster with a single node or multiple nodes.

About HSMs in a Multi-Master Cluster
An HSM in Oracle Key Vault stores a top level master encryption key that acts as a Root of Trust (RoT).
Configuring an HSM for a Multi-Master Cluster with a Single Node
To use an HSM with a multi-master cluster, you should start with a single HSM-enabled node and add additional HSM-enabled nodes.
Configuring an HSM for a Multi-Master Cluster with Multiple Nodes
You can configure HSM for multiple nodes by copying information from an HSM-enabled node to the non-enabled nodes.

Parent topic: Configuring an HSM for Oracle Key Vault

2.3.1 About HSMs in a Multi-Master Cluster

An HSM in Oracle Key Vault stores a top level master encryption key that acts as a Root of Trust (RoT).

This RoT protects master encryption keys that Oracle Key Vault uses. HSMs are built with specialized tamper-resistant hardware which is harder to access than normal servers. This protects the RoT and makes it difficult to extract encrypted data, lowering the risk of compromise. In addition, you can use HSMs in FIPS 140-2 level 3 mode, which enables you to meet certain compliance requirements.

Note:

An existing Oracle Key Vault deployment cannot be migrated to use an HSM as a RoT.

In a multi-master Oracle Key Vault installation, any Key Vault node in the cluster can use any HSM. The nodes in the multi-master cluster can use different TDE wallet passwords, RoT keys, and HSM credentials.

Note:

To ensure complete security, you must HSM-enable all Oracle Key Vault nodes in the cluster.

Parent topic: HSMs in a Multi-Master Cluster

2.3.2 Configuring an HSM for a Multi-Master Cluster with a Single Node

To use an HSM with a multi-master cluster, you should start with a single HSM-enabled node and add additional HSM-enabled nodes.

Oracle recommends the following steps to configure an HSM for a multi-master cluster with a single node:

Configure the first node of the cluster.
Configure HSM on the first node before adding any new nodes. If there is already more than one node in the cluster, then configure the HSM for a multi-master cluster with multiple nodes.
HSM-enable the candidate node before adding it to the cluster.
Add the HSM-enabled candidate node to the cluster using a controller node that is also HSM-enabled. If any node in the cluster is already HSM-enabled, you cannot add a new node that is not HSM-enabled.

Related Topics

Configuring an HSM for a Multi-Master Cluster with Multiple Nodes

Parent topic: HSMs in a Multi-Master Cluster

2.3.3 Configuring an HSM for a Multi-Master Cluster with Multiple Nodes

You can configure HSM for multiple nodes by copying information from an HSM-enabled node to the non-enabled nodes.

Configuring an HSM for a Multi-Master Cluster with a Single Node explains how to configure an HSM for a multi-master cluster. If the first node to be HSM-enabled is in a cluster that already has multiple nodes, then you must manually copy information from that HSM-enabled Oracle Key Vault to the other Oracle Key Vault installations in the cluster before you can enable HSM in any other nodes. If the first node to be HSM-enabled has a read-write peer, then the read-write peer will not be able to decrypt the information from the HSM-enabled node until the bundle is copied and applied successfully to the read-write peer.

Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
Click the System tab.
On the left side of the System page, click Hardware Secure Module.
On the HSM-enabled node, click Create Bundle on the HSM page.
Log in to the HSM-enabled node through SSH as user support.
```
ssh support@hsm_enabled_node
```
Switch to the root user.
```
su root
```
To copy the bundle to the /usr/local/okv/hsm location on each of the other nodes using the IP address:
```
scp /usr/local/okv/hsm/hsmbundle support@ip_address:/tmp
```
Log in to each node in the cluster using the IP address (except the original HSM-enabled node):
```
ssh support@ip_address
```
Switch to the root user.
```
su root
```

Perform the following steps on each node:

cp /tmp/hsmbundle /usr/local/okv/hsm/
chown oracle:oinstall /usr/local/okv/hsm/hsmbundle

On each node except the original HSM-enabled node, click Apply Bundle on the HSM page.

You must apply the bundle immediately on all nodes before you reverse-migrate the original HSM-enabled node.
Proceed to HSM-enable each of these nodes in the same way that you HSM-enabled the first node.
After you have HSM-enabled all nodes and verified the replication between all nodes, remove the hsmbundle file from all of the nodes.

Parent topic: HSMs in a Multi-Master Cluster

2.4 Backup and Restore Operations in an HSM-Enabled Oracle Key Vault Instance

You can back up and restore an HSM-enabled Oracle Key Vault instance.

Backup Operations in an HSM-Enabled Oracle Key Vault Instance
Backing up Oracle Key Vault data in an HSM-enabled instance is the same as backing up an instance that has not been HSM enabled.
Restore Operations in an HSM-Enabled Oracle Key Vault Instance
Only backups made to an HSM-enabled Oracle Key Vault instance can be restored onto an HSM-enabled Oracle Key Vault instance.

Parent topic: Configuring an HSM for Oracle Key Vault

2.4.1 Backup Operations in an HSM-Enabled Oracle Key Vault Instance

Backing up Oracle Key Vault data in an HSM-enabled instance is the same as backing up an instance that has not been HSM enabled.

You can use the Oracle Key Vault management console to perform a backup operation.

Related Topics

Oracle Key Vault Administrator's Guide

Parent topic: Backup and Restore Operations in an HSM-Enabled Oracle Key Vault Instance

2.4.2 Restore Operations in an HSM-Enabled Oracle Key Vault Instance

Only backups made to an HSM-enabled Oracle Key Vault instance can be restored onto an HSM-enabled Oracle Key Vault instance.

Before you restore a backup onto a system, you must ensure that the system can access both the HSM and the Root of Trust (RoT) that was used to make the backup. You must therefore have installed the HSM on the Oracle Key Vault server and enrolled Oracle Key Vault as a client of HSM before this step. If the backup was taken on an HSM-enabled cluster node, then when you restore the backup to a standalone server, you must ensure that the server has access to the same HSM as the node on which the backup was taken.

Log into the Oracle Key Vault management console as a user with the System Administrator role.
The Oracle Key Vault Home page appears.
Click the System tab.
The Status page appears.
Click Hardware Security Module in the left sidebar.
The Hardware Security Module page appears. On restore, the Status is disabled first, then enabled after the restore completes.
Click Set Credential.
The Prepare for HSM Restore screen appears.

Description of the illustration hsm_set_cred_bp3.png
Enter the HSM credential two times: first in HSM Credential and second in Re-enter HSM Credential.
Consult the HSM documentation for this credential. The HSM credential for SafeNet is the SafeNet partition password. For nCipher, the credential is the Operator Card Set password.
Click Set Credential.

Caution:

If you enter an incorrect credential for the HSM, the previous credential will continue to be stored and used. If the node is not HSM enabled, and you enter an incorrect credential for the HSM, the incorrect credential is not stored.

The HSM credential will be stored in the system. You must manually enter this HSM credential to perform an HSM restore because it is not stored in the backup itself.
In the Oracle Key Vault management console, go to the Restore page and then restore the backup.

Related Topics

Oracle Key Vault Administrator's Guide

Parent topic: Backup and Restore Operations in an HSM-Enabled Oracle Key Vault Instance

2.5 Reverse Migration Operations to a Local Wallet

Reverse migrating an HSM-enabled Oracle Key Vault server reverts the Key Vault server to using the recovery passphrase to protect the TDE wallet.

This operation is necessary if the HSM that protects Oracle Key Vault must be decommissioned.

Reverse Migrating a Standalone Deployment
You can reverse migrate a standalone deployment by using the Oracle Key Vault management console.
Reverse Migrating a Primary-Standby Deployment
To reverse migrate a primary-standby deployment, use both the Oracle Key Vault management console and the command line.
Reverse Migrating a Multi-Master Cluster
You can reverse migrate a multi-master cluster by using the Oracle Key Vault management console.

Parent topic: Configuring an HSM for Oracle Key Vault

2.5.1 Reverse Migrating a Standalone Deployment

You can reverse migrate a standalone deployment by using the Oracle Key Vault management console.

Log into the Oracle Key Vault management console as a user with the System Administrator role.
The Oracle Key Vault Home page appears.
Click the System tab.
The Status page appears.
Click Hardware Security Module in the left sidebar.
The Hardware Security Module page appears.
Click Reverse Migrate.
The HSM Reverse Migrate screen is displayed.

Description of the illustration hsm_reverse_migrate.png
On the HSM Reverse Migrate screen, enter the following details:
- Enter the HSM credential in the HSM Credential field. Consult the HSM documentation for this credential. The HSM credential for SafeNet is the SafeNet partition password. For nCipher, the credential is the Operator Card Set password.
- Enter the old recovery passphrase in the Old Recovery Passphrase field.
- Enter the new recovery passphrase in the New Recovery Passphrase and Re-enter New Recovery Passphrase fields.
Click Reverse Migrate
The Hardware Security Module page appears. The red downward arrow indicates the Status.

Parent topic: Reverse Migration Operations to a Local Wallet

2.5.2 Reverse Migrating a Primary-Standby Deployment

To reverse migrate a primary-standby deployment, use both the Oracle Key Vault management console and the command line.

On the primary server, log into the Oracle Key Vault management console as a user with system administrative privileges.
The Oracle Key Vault Home page appears.
Click the System tab.
The Status page appears.
Click Hardware Security Module in the left sidebar.
The Hardware Security Module page appears.
Click Reverse Migrate.
The HSM Reverse Migrate screen is displayed.

Description of the illustration hsm_reverse_migrate.png
On the HSM Reverse Migrate screen, enter the following details:
- Enter the HSM credential in the HSM Credential field. Consult the HSM documentation for this credential. The HSM credential for SafeNet is the SafeNet partition password. For nCipher, the credential is the Operator Card Set password.
- Enter the old recovery passphrase in the Old Recovery Passphrase field.
- Enter the new recovery passphrase in the New Recovery Passphrase and Re-enter New Recovery Passphrase fields.
Click Reverse Migrate
The Hardware Security Module page appears. The red downward arrow indicates the Status.
On the standby server, log in to the Oracle Key Vault Server through SSH as user support, then switch user (su) to root.
```
$ ssh support@okv_standby_instance
$ su root
```
Modify the okv_security.conf file.
```
$ vi /usr/local/okv/etc/okv_security.conf
```
- Delete the line HSM_PROVIDER="provider_value".
- Change the value of the parameter HSM_ENABLED to "0".
Save and quit by entering the following sequence of characters in the vi file: :wq!

On the standby server, remove the following files:

$ cd /usr/local/okv/hsm/wallet
$ rm -f cwallet.sso enctdepwd
$ cd /usr/local/okv/hsm/restore
$ rm -f cwallet.sso ewallet.p12
$ cd /mnt/okvram
$ rm -f cwallet.sso ewallet.p12
$ cd /mnt/okvram/restore
$ rm -f cwallet.sso ewallet.p12
$ cd /usr/local/okv/tde
$ rm -f cwallet.sso

Switch user (su) to oracle:
```
$ su oracle
```

Run the following command:

/var/lib/oracle/dbfw/bin/orapki wallet create -wallet /usr/local/okv/tde -auto_login

Enter the new recovery passphrase that you specified in Step 4.

The primary-standby deployment is successfully reverse migrated.

Parent topic: Reverse Migration Operations to a Local Wallet

2.5.3 Reverse Migrating a Multi-Master Cluster

You can reverse migrate a multi-master cluster by using the Oracle Key Vault management console.

Log into the Oracle Key Vault management console as a user with the System Administrator role.
The Oracle Key Vault Home page appears.
Click the System tab.
The Status page appears.
Click Hardware Security Module in the left sidebar.
The Hardware Security Module page appears.
Click Reverse Migrate.
The HSM Reverse Migrate dialog box is displayed.

Description of the illustration hsm_reverse_migrate_mmc.png
In the HSM Reverse Migrate dialog box, enter the following details:
- Enter the HSM credential. Consult the HSM documentation for this credential. The HSM credential for SafeNet is the SafeNet partition password. For nCipher, the credential is the Operator Card Set password.
- Enter the recovery passphrase.
Click Reverse Migrate
The Hardware Security Module page appears. The red downward arrow indicates the Status.

Parent topic: Reverse Migration Operations to a Local Wallet