Oracle Key Vault 21.3: nShield HSM Integration Guide

Entrust has successfully tested nshield HSM integration with Oracle Key Vault in the following configurations:

Entrust has successfully tested with the following nshield hardware and software versions:

Connect XC

Connect +

Before installing these products, read the associated documentation:

• For the nshield HSM: Installation Guide and User Guide .

• If nshield Remote Administration is to be used: [.cite]nshield Remote Administration User Guide_.

• Oracle Key Vault documentation ( https://docs.oracle.com/en/database/oracle/key-vault ).

In addition, the integration between nshield HSMs and Oracle Key Vault requires:

• A separate non-HSM machine on the network to use as the Remote File System for the HSM. The RFS machine can also be used as a client to the HSM, to allow presentation of Java Cards using nshield Remote Administration. See the [.cite]nshield Remote Administration User Guide_.

• PKCS #11 support in the HSM.

• A correct quorum for the Administrator Card Set (ACS).

• Operator Card Set (OCS), Softcard, or Module-Only protection.

  If OCS protection is to be used, a 1-of-N quorum must be used.

• Firewall configuration with usable ports:

  • 9004 for the HSM (hardserver).

  • 8200 for Key Vault.

Furthermore, the following design decisions have an impact on how the HSM is installed and configured:

• Whether your Security World must comply with FIPS 140-2 Level 3 standards.

  If using FIPS Restricted mode, it is advisable to create an OCS for FIPS authorization. The OCS can also provide key protection for the Vault master key. For information about limitations on FIPS authorization, see the Installation Guide of the nshield HSM.

• Whether to instantiate the Security World as recoverable or not.

For more information about OS support, contact your Oracle Key Vault sales representative or Entrust nshield Support, https://nshieldsupport.entrust.com .

Perform these steps on the Oracle Key Vault server.

If you have a high availability Oracle Key Vault environment, perform these steps:

• In a primary-standby architecture, on both the primary and the standby.

• In a cluster architecture, on each Key Vault instance to be added to the cluster.

To install HSM client software on the Key Vault server:

1. Log into the Oracle Key Vault server as the support user using SSH:

   $ ssh support@<okv_instance>
   <Enter the support user password when prompted>

2. Switch to root:

   $ su root

3. Install the latest version of the Security World software as described in the Installation Guide for the HSM.

   Note	Entrust recommends that you uninstall any existing nshield software before installing the new nshield software.

4. Create the Security World as described in the User Guide , creating the ACS and OCS that you require.

5. As root on the Key Vault server, add the nfast group to the oracle user:

   root# usermod -a -G nfast oracle

6. Switch to the oracle user, and verify the installation:

   root# su oracle
   oracle$ PATH=/opt/nfast/bin:$PATH
   oracle$ export PATH
   oracle$ enquiry

   The mode should say operational in the output. For example:

   Server:
   enquiry reply flags  none
   enquiry reply level  Six
   serial number        nnnn-nnnn-nnnn
   mode                 operational
   version              12.60.7
   speed index          15843

7. Restart the Oracle Key Vault server for the group change to take effect.

   Note	To restart or restore Key Vault in HSM mode when OCS protection is used, the OCS for the HSM must be in slot 0 of the HSM.

8. As the root user, set firewall rules to enable port 9004 for the hardserver (the client process in the nshield Security World software that communicates with the HSM).

1. Add the Key Vault server IP address to the client list on the HSM using the front panel or via an update to the Connect configuration file. For instructions, see the User Guide for your HSM.

   • Select privileged on any port.

   • If you have a high availability Oracle Key Vault environment, add the IP addresses of all Key Vault servers to the client list on all HSMs.

2. Switch to the oracle user:

   root# su oracle
   oracle$ PATH=/opt/nfast/bin:$PATH
   oracle$ export PATH

3. To obtain the ESN and keyhash for the nethsmenroll command in the next step, run the anonkneti command:

   anonkneti <HSM IP address>

4. On the Key Vault server, enroll with the HSM:

   oracle$ nethsmenroll --privileged <HSM IP address> <HSM ESN> <HSM keyhash>

5. Run the following command:

   enquiry

   Verify that the HSM mode is operational and the hardware status is OK.

6. Configure TCP sockets:

   oracle$ config-serverstartup --enable-tcp --enable-privileged-tcp

7. Switch to root and restart the hardserver:

   oracle$ su root
   root# /opt/nfast/sbin/init.d-ncipher restart

8. On the Remote File System machine, run the following command:

   rfs-setup --gang-client --write-noauth <IP address of your Key Vault server>

9. If OCS protection is intended to be used but the Security World has not been created yet, edit the cardlist file to enable Java Cards for use through dynamic slots. If the Security World has been created with this RFS, this configuration is already enabled.

   1. Go to the following directory on the RFS:

      #/opt/nfast/kmdata/config

   2. Open the cardlist file in a text editor.

   3. Add an asterisk (*) to authorize all Java Cards for dynamic slots.

      If only certain Java Cards are authorized for this use, list them by their serial number. For example:

      4286005559064791
      4286005559064792
      4286005559064793

   4. Copy the updated cardlist file from the RFS to all clients.

10. On the Key Vault server as the oracle user, run the following commands:

    oracle$ rfs-sync --setup <IP address of Remote File System machine>
    oracle$ rfs-sync --update

11. As the root user, create the /opt/nfast/cknfastrc configuration file for PKCS#11 variables. For information on these variables, see the User Guide for your HSM.

    1. OCS protection.

       If you are using OCS or Module protection, cknfastrc needs the following set:

       CKNFAST_NO_ACCELERATOR_SLOTS=1
       CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness;tokenkeys;longterm

    2. Softcard Protection.

       If you are using Softcard protection, then CKNFAST_LOADSHARING must be set. This is not supported alongside the Module-only Key protection settings. See also [{xref_known-issues}] .

       CKNFAST_LOADSHARING=1
       CKNFAST_NO_ACCELERATOR_SLOTS=1
       CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness;tokenkeys;longterm

    3. Module Protection.

       If you are using Module-Only protection, cknfastrc needs the following set:

       CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness;tokenkeys;longterm
       CKNFAST_FAKE_ACCELERATOR_LOGIN=1

12. On the Key Vault Server, test PKCS#11 access as follows:

    oracle$ /opt/nfast/bin/ckcheckinst

    Select a slot number to run a library test. Various slots are displayed, depending on your configuration.

    Example 1:

    0 Fixed token "accelerator"
    1 Operator card "OKV_OCS"

    Example 2:

    0  Operator card     "OKV_OCS"
    1  Soft token        "OKV_Softcard"

    Test execution:

    Test                      Pass/Failed
    ----                      -----------
    
    1 Generate RSA key pair   Pass
    2 Generate DSA key pair   Pass
    3 Encryption/Decryption   Pass
    4 Signing/Verification    Pass
    
    Deleting test keys         ok
    
    PKCS#11 library test successful.

After installing HSM software and enrolling Key Vault as an HSM client, you can enable HSM mode with nshield HSM(s) from the Key Vault web user interface. This will protect the Oracle Key Vault Root of Trust key with the HSM.

1. Log into the Oracle Key Vault web user interface as a Key Administrator.

   The Oracle Key Vault Home page appears.

2. Select the System tab.

   The Status page appears.

3. Select Settings on the Left menu and then Select HSM under Network Services .

   The Hardware Security Module page appears.

   The red downward arrow shows the non-initialized Status . The Type field displays None .

4. Select Initialize .

   The Initialize HSM dialog appears.

5. From the Vendor list, select Entrust .

6. Enter a password two times: first in HSM Credential and second in Re-enter HSM Credential .

   • If you are using OCS protection, then your OCS passphrase needs to be entered in twice with your card presented in slot 0.

   • If you are using Softcard protection, then the Softcard passphrase needs to be entered twice.

   • If you are using Module-Only protection, enter a password that you set up for this credential check.

     Note	The password will be needed in the future, for example for reverse migration.

7. Enter the recovery passphrase for Oracle Key Vault.

8. If you are using token labels, used for OCS protection and Softcards for instance, check the Use Token Label checkbox and enter the name of the token.

9. Select Initialize .

   At the end of a successful initialize operation, the Hardware Security Module page appears. The initialized status is indicated by an green upward arrow. The Type field shows details of the HSM in use.

   Note	The Token label is accelerator if Module-Only protection is used.

   Note	Only the first two numbers of the firmware are included.

10. After a successful initialize operation of the nshield HSM, run the following command as the oracle user on the Key Vault server:

    oracle$ /opt/nfast/bin/rfs-sync --commit

In a high availability Oracle Key Vault installation, you must enable the HSM(s) separately on the servers that you plan to designate as primary and standby before pairing them in a high availability configuration. On the primary server, the HSM(s) will be enabled through the Oracle Key Vault web user interface. On the standby server, the command line interface with ssh will be used to enable the HSM(s).

1. Install Oracle Key Vault on two servers that you mean to designate as primary and standby.

2. Install the nshield Security World software on each Oracle Key Vault server, see Install HSM client software on the Key Vault server .

3. Enroll the primary and standby nodes as clients of the HSM, see Enroll Key Vault as a client of the HSM .

4. From the Oracle Key Vault web user interface, initialize the intended primary server for HSM mode with nshield HSM(s), see Enable HSM mode in Key Vault .

5. On the primary server, run the following commands as the oracle user:

   $ ssh support@<okv_primary_instance>
   <Enter password when prompted>
   $ su root
   root# su oracle
   oracle$ rfs-sync --commit
   oracle$ cd /usr/local/okv/hsm/wallet
   oracle$ scp cwallet.sso support@<okv_standby_instance>:/tmp
   oracle$ scp enctdepwd support@<okv_standby_instance>:/tmp
   oracle$ cd /usr/local/okv/hsm/restore
   oracle$ scp ewallet.p12 support@<okv_standby_instance>:/tmp

6. On the standby server, run the following commands as the root user:

   $ ssh support@<okv_standby_instance>
   <Enter password when prompted>
   $ su root
   root# cd /usr/local/okv/hsm/wallet
   root# mv /tmp/enctdepwd .
   root# mv /tmp/cwallet.sso .
   root# chown oracle *
   root# chgrp oinstall *
   root# cd /usr/local/okv/hsm/restore
   root# mv /tmp/ewallet.p12 .
   root# chown oracle *
   root# chgrp oinstall *

7. Continuing as the root user, open the okv_security.conf file for writing:

   root# vi /usr/local/okv/etc/okv_security.conf

   A sample okv_security.conf file before enabling HSM mode:

   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="0"
   HSM_FIPS_ENABLED="1"
   OKV_OCI_INSTALL="DISABLED"
   HSM_TOKEN_LABEL=""
   HSM_KEY_EXTRACTABLE="0"
   OKVAG_LINK_UI="https://docs.oracle.com/en/database/oracle/key-vault/21.3/okvag/"
   LDAP_TRACE_LEVEL="1"

8. Make updates to the okv_security.conf file as follows:

   1. Set the variable HSM_ENABLED to 1. If the variable does not exist, add it and set its value to 1.

      HSM_ENABLED="1"

   2. Add the following line:

      HSM_PROVIDER="2"

   3. If using Softcards or OCS cards, enter the name of the card set:

      HSM_TOKEN_LABEL="card_set_name"

9. On the standby server, run the rfs-sync --update command as the oracle user:

   root# su oracle
   oracle$ /opt/nfast/bin/rfs-sync --update

10. Without restarting the Oracle Key Vault instances, navigate to the web user interfaces of the primary and standby servers, and configure primary-standby via the Oracle Key Vault web user interface. For information on the configuration and settings, see the Oracle documentation.

You can configure HSMs in a multi-master cluster with a single node or multiple nodes. 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 (recovery passwords), RoT keys, and HSM credentials.

This guide will set up the cluster from scratch. If you already have a cluster in place, read the documentation above.

To use an HSM within a cluster, you should start with a single node and add additional nodes as needed.

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

1. Convert an Oracle Key Vault server into the first node (the controller node) of the cluster.

   1. Create the cluster by configuring the first node of the cluster.

   2. Select the Cluster tab.

   3. On the left menu, select Configure .

      The Configure as a Candidate Node page appears. For example:

      • For Current Server IP , enter the server IP address.

      • For First Node of Cluster , select Yes if this is the first node, otherwise set it to No .

      • Node Name should be pre-populated with the host name of the OKV server.

      • For Cluster Name , enter the name for the cluster.

      • For Cluster SubGroup , enter the name of the group.

        Note	If any node in the cluster is already HSM-enabled, you cannot add a new node that is not HSM-enabled.

   4. Select Convert Candidate Node . The Cluster Information page appears.

2. If using multiple nodes, add the candidate nodes to the cluster using the controller node.

   Refer to https://docs.oracle.com/en/database/oracle/key-vault/21.3/okvag/managing_multimaster.html for details on how to add a candidate node to the cluster.

3. HSM-enable the controller node (first node).

   Follow instructions to enable HSM mode on the first node of the cluster. See Enable HSM mode in Key Vault section on how to do this.

4. If multiple nodes are being used in the cluster, create an HSM bundle from the controller node and apply it to the candidate node(s).

   You can configure HSM for the other nodes by copying information from the HSM-enabled controller node in the cluster. You do that by creating a bundle and applying the bundle to the candidate nodes in the cluster.

   • On the contoller node of the cluster (first node), log into the Oracle Key Vault web user interface as a Key Administrator

   • Select the System tab.

   • On the left side of the System page, select Settings .

   • Select HSM under the Network Services section. The Hardware Security Module page appears.

     Note	The controller node must be HSM enabled first.

   • Select Create Bundle .

   • Enter the HSM Credentials.

   • Enter the recovery passphrase.

   • Select Create Bundle .

     A message indicating the bundle was created successfully appears.

   • Log into the controller (first node) HSM-enabled node through SSH as the support user.

     % ssh support@HSMENABLEDNODEIP

   • Copy the bundle to the candidate node using the node IP addresses:

     % sudo scp /usr/local/okv/hsm/hsmbundle support@CANDIDATENODEIPADDRESS:/tmp

   • Log into the candidate node in the cluster, except the original HSM-enabled node, using the node IP address:

     % ssh support@CANDIDATENODEIPADDRESS

   • Perform the following steps to copy the bundle to the /usr/local/okv/hsm location and apply user and group ownership:

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

   • On the candidate node, select Apply Bundle on the Hardware Security Module page in the Web interface. Enter the recovery passphrase.

     Note	If you plan on reverse-migrating the original HSM-enabled node, you must apply the bundle immediately on all nodes first.

5. HSM-enable the candidate node.

   Follow instructions to enable HSM mode on the candidate node of the cluster when using multiple nodes. See Enable HSM mode in Key Vault section on how to do this.

6. Verify that each HSM is enabled in the cluster.

   • In the Oracle Key Vault web user interface, select the Cluster tab.

   • Select Monitoring in the left sidebar.

   • Check that the Cluster Settings State has all green ticks for HSM:

     Note	An enabled HSM does not mean that the HSM is active. The status only indicates whether the HSM is enabled for these nodes. To check whether the HSM is active, use the status information on the Hardware Security Module page of the web user interface.

   • After you have HSM-enabled all nodes and verified the replication between all nodes, remove the hsmbundle file from all of the nodes.

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 web user interface.

• Reverse migrating a primary-standby deployment

  To reverse migrate a primary-standby deployment, use both the Oracle Key Vault web user interface and the command line.

• Reverse migrating a multi-master cluster

  You can reverse migrate a multi-master cluster by using the Oracle Key Vault web user interface.

Reverse migrate a standalone deployment

Reverse migrate a primary-standby deployment

Reverse migrate a multi-master cluster

1. Log into the Oracle Key Vault web user interface as a Key Administrator.

   The Oracle Key Vault Home page appears.

2. Select the System tab.

   The Status page appears.

3. On the left side of the System page, select Settings .

4. Select Backup and Restore under the System Configuration section.

5. Add the backup destination on the System Backup page, just as you would in non-HSM mode.

6. Perform a backup as usual from the user interface on the web user interface.

Only backups taken in HSM mode can be restored onto an HSM-enabled Oracle Key Vault. Before you restore a backup onto a system, you must ensure that the system can access both the:

• HSM.

• Root of Trust used to take the backup. You must therefore have installed the HSM on the Oracle Key Vault server and enrolled Oracle Key Vault as a client of the HSM prior to this step.

  1. If OCS protection is used, present the OCS card to the HSM.

  2. Log into the Oracle Key Vault web user interface as a user with system administrative privileges.

     The Oracle Key Vault Home page appears.

  3. Select the System tab.

     The Status page appears.

  4. On the left side of the System page, select Settings .

  5. Select HSM under the under the Network Services section.

     The Hardware Security Module page appears. On restore, the Status is disabled first, then enabled after the restore completes.

  6. Select Set Credential .

     The Prepare for HSM Restore screen appears.

  7. From the Vendor list, select Entrust and enter the HSM credential twice as requested.

  8. Select Set Credential .

     The HSM credential will be stored in the system. This HSM credential must be entered manually to do an HSM restore because it is not stored in the backup itself.

  9. On the left side of the page, select Settings .

  10. Select Backup and Restore under the System Configuration section.

  11. Select Restore and restore the Key Vault backup.

To restart or restore Key Vault in HSM mode when OCS protection is used, the OCS for the HSM must be in slot 0 of the HSM.

The raserv package of nshield software is only available on the nshield RFS machine, it is not supported on Oracle Key Vault servers. When the Oracle Key Vault server restarts or restores from a backup and Java Cards cannot be presented to the HSMs that are enrolled to that server, the restart or restore will fail.

If the HSM is also enrolled to the RFS, you can present Java Cards there when the RFS is operational. As a result, when the Oracle Key Vault server comes back up, it can still access the keys from the HSM using the OCS in slot 0.