Procedures

The high-level procedure to install and configure one or more Oracle Key Vault servers with one or more nShield HSMs is as follows:

  1. Install the required number of instances of Oracle Key Vault. For instructions, see the Oracle Key Vault documentation.

  2. Install and configure the required number of HSMs and the Security World software, including setting up the Remote File System (RFS) or Remote Administration. For instructions, see the Installation Guide for your HSM.

    • nShield HSMs require a separate non-HSM machine on the network to use as the RFS. You must set up this machine and copy the nShield Security World Software files to it before you install the HSM client software on Oracle Key Vault servers.

    • All enrolled HSMs must be in the same Security World and must have access to the OCS in slot 0 if OCS-protection is used. If the HSM whose slot 0 is used is enrolled on each of the Key Vault servers, the Key Vault web user interface has access to all of the HSMs, as long as they are in the same Security World.

    • If dynamic slots are to be used on the HSMs, set up Remote Administration and configure slot mapping.

  3. Install the HSM client software on the Oracle Key Vault server(s).

  4. Enroll the Key Vault(s) as client(s) of the HSM(s).

  5. Enable HSM mode in the Oracle Key Vault web user interface.

  6. If you have a high availability Oracle Key Vault environment, enroll your HSM and configure initialization of the HSM in each of the nodes.

Install HSM client software on the Key Vault server

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 in to 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.

      We recommend 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, perform additional edits on the Key Vault server:

      1. 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
 mode                 operational

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

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

Enroll Key Vault as a client of 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. To obtain the ESN and keyhash for the nethsmenroll command in the next step, run the anonkneti command:

    anonkneti <HSM IP address>

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

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

  4. Run the enquiry command:

    enquiry

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

  5. Configure TCP sockets:

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

  6. Switch to root and restart the hardserver:

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

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

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

  8. 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 folder 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.

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

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

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

    oracle$ /opt/nfast/bin/ckcheckinst

    Select slot number to run 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.

Enable HSM mode in Key Vault

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.

    okv interface

  3. Select 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.

    okv interface 2

  4. Select Initialize.

    The Initialize HSM screen appears.

  5. From the Vendor list, select nCipher:

    hsm initialize ncipher

  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.

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

  7. Enter the recovery passphrase for Oracle Key Vault.

  8. Select 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.

    hsm initialize okv
    The Token label is accelerator if Module-Only protection is used.
    Only the first two numbers of the firmware are displayed.

  9. 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
If you change the HSM credential on the HSM after initialization, you must also update the HSM credential on the Oracle Key Vault server: In the Vendor list select nCipher, then select the Set Credential button.
set credentials

Enable the HSM in a primary-standby high availability deployment

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.

  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$ 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"

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

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

    HSM_ENABLED="1"

    Add the following line:

    HSM_PROVIDER="2"

    If using softcards or OCS cards, enter the name of the cardset:

    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.

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

You can reverse migrate a standalone deployment by using the Oracle Key Vault web user interface.

  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 Hardware Security Module in the left sidebar.

    The Hardware Security Module page appears.

  4. Select Reverse Migrate.

    The HSM Reverse Migrate dialog box is displayed.

    reverse migrate standalone

  5. On the HSM Reverse Migrate dialog box, enter the following details:

    1. Enter the HSM credential in the HSM Credential field. For nShield HSMs, the credential is what you use for OCS, Softcard, or Module-Only protection.

    2. Enter the old recovery passphrase in the Old Recovery Passphrase field.

    3. Enter the new recovery passphrase in the New Recovery Passphrase and Re-enter New Recovery Passphrase fields.

  6. Select Reverse Migrate.

  7. The Hardware Security Module page appears. The red downward arrow indicates the Status.

Reverse migrate a primary-standby deployment

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

  1. On the primary server, 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 Hardware Security Module in the left sidebar.

    The Hardware Security Module page appears.

  4. Select Reverse Migrate.

    The HSM Reverse Migrate dialog box is displayed.

    reverse migrate standalone

  5. On the HSM Reverse Migrate dialog box, enter the following details:

    1. Enter the HSM credential in the HSM Credential field. For nShield HSMs, the credential is what you use for OCS, Softcard, or Module-Only protection.

    2. Enter the old recovery passphrase in the Old Recovery Passphrase field.

    3. Enter the new recovery passphrase in the New Recovery Passphrase and Re-enter New Recovery Passphrase fields.

  6. Select Reverse Migrate.

    The Hardware Security Module page appears. The red downward arrow indicates the Status.

  7. On the standby server, log in through SSH as the support user, then, with the su command, switch to the root user.

    $ 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="2".

    • Change the value of the parameter HSM_ENABLED to 0.

    • Check that the parameter HSM_TOKEN_LABEL is set to "".

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

  9. Switch user (su) to oracle:

    $ su oracle

  10. Run the following command:

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

  11. Enter the new recovery passphrase that you specified in Step 5.

    Enter wallet password:
Operation is successfully completed.

The primary-standby deployment is successfully reverse migrated.

Reverse migrate a multi-master cluster

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

  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 Hardware Security Module in the left sidebar.

    The Hardware Security Module page appears.

  4. Select Reverse Migrate.

    The HSM Reverse Migrate dialog box is displayed.

    reverse migrate cluster

  5. In the HSM Reverse Migrate dialog box, enter the following details:

    1. Enter the HSM credential. For nShield HSMs, the credential is what you use for OCS, Softcard, or Module-Only protection.

    2. Enter the recovery passphrase.

  6. Select Reverse Migrate.

    The Hardware Security Module page appears. The red downward arrow indicates the Status.

Configure an HSM for a multi-master cluster

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.

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

Configure 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:

  1. Configure the first node of the cluster.

  2. Configure the 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. See Configure an HSM for a multi-master cluster with multiple nodes.

  3. HSM-enable the candidate node before adding it to the cluster.

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

  5. Verify that the HSM is enabled:

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

    2. Select Monitoring in the left sidebar.

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

      cluster settings
      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.

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

For instructions to configure an HSM for a multi-master cluster, see Configure an HSM for a multi-master cluster with a single node. 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.

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

  2. Select the System tab.

  3. On the left side of the System page, select Hardware Secure Module.

  4. On the HSM-enabled node, select Create Bundle on the Hardware Security Module page.

  5. Enter the recovery passphrase.

    create bundle

  6. Log in to the HSM-enabled node through SSH as the support user.

    ssh support@<hsm_enabled_node>

  7. Switch to the root user.

    su root

  8. Copy the bundle to each node using the node IP addresses:

    scp /usr/local/okv/hsm/hsmbundle support@<ip_address>:/tmp

  9. Log in to each node in the cluster, except the original HSM-enabled node, using the node IP address:

    ssh support@<ip_address>

  10. Switch to the root user.

    su root

  11. Perform the following steps on each node to copy the bundle to the /usr/local/okv/hsm location and apply user and group ownership:

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

  12. On each node except the original HSM-enabled node, select Apply Bundle on the Hardware Security Module page. Enter the recovery passphrase.

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

  13. Proceed to HSM-enable each of these nodes in the same way that you HSM-enabled the first node. Also verify that each HSM is enabled:

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

    2. Select Monitoring in the left sidebar.

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

      cluster settings
      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.

  14. After HSM-enabling a node in a cluster, the rfs-sync --update command must be run on all other nodes to ensure that all nodes have up-to-date Security World files.

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

Configure backup of the Key Vault server in HSM mode

  1. Install a new Key Vault server.

  2. Install the nShield Security World Software as described in Install HSM client software on the Key Vault server.

  3. From the Key Vault web user interface, add the backup destination on the System Backup page, just as you would in non-HSM mode.

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

Restore from a Key Vault backup in HSM mode

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.

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

    5. Select Set Credential.

      The Prepare for HSM Restore screen appears.

    6. From the Vendor list, select nCipher and enter the HSM credential twice as requested.

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

    8. Go to the Restore page via the Key Vault web user interface and restore the Key Vault backup.

Restart or restore in HSM mode using nShield Remote Administration

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. This way, when the Oracle Key Vault server comes back up, it can still access the keys from the HSM using the OCS in slot 0.