3 Upgrade Considerations When Using HSMs in Oracle Key Vault

When you upgrade an Oracle Key Vault deployment that is integrated with an HSM, consider factors such as the version of Oracle Key Vault.

• Upgrades from Oracle Key Vault Release 12.2
  Upgrading from a standalone or a primary-standby Oracle Key Vault release 12.2 environment has special considerations for HSMs.
• Upgrade Considerations for Entrust
  When you upgrade while HSM-enabled and using an Entrust HSM, you must remake hardserver changes and consider changes to overriding security assurances.
• Using a Token Label After Upgrading Oracle Key Vault without Reverse-Migrating
  Starting in release 18.4, Oracle Key Vault can use a token label when you choose a slot while connecting to an HSM.

3.1 Upgrades from Oracle Key Vault Release 12.2

Upgrading from a standalone or a primary-standby Oracle Key Vault release 12.2 environment has special considerations for HSMs.

• Upgrading from an Oracle Key Vault Release 12.2 Standalone Deployment
  You can upgrade from an Oracle Key Vault standalone deployment by reverse-migrating before the upgrade, and after the upgrade completes, re-HSM-enabling Oracle Key Vault.
• Upgrading from an Oracle Key Vault Release 12.2 Primary-Standby Deployment
  You can upgrade from an Oracle Key Vault release 12.2 primary-standby deployment by reverse-migrating before the upgrade, and after the upgrade completes, re-HSM-enabling Oracle Key Vault.

3.1.1 Upgrading from an Oracle Key Vault Release 12.2 Standalone Deployment

You can upgrade from an Oracle Key Vault standalone deployment by reverse-migrating before the upgrade, and after the upgrade completes, re-HSM-enabling Oracle Key Vault.

1. Make a one-time backup of the Oracle Key Vault server to a remote backup destination.
2. Make a copy of the /mnt/okvram/cwallet.sso wallet file.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root
   root# /bin/cp /mnt/okvram/cwallet.sso /var/lib/oracle/cwallet_hsm_upgrade.sso

3. Reverse migrate so that Oracle Key Vault is no longer using an HSM as the RoT.
   You can verify the success of this operation by checking the audit record in the audit trail.
   If this step fails despite using the correct HSM credential and recovery passphrase, then do not continue with the rest of these steps. Contact Oracle Support.
4. Make another one-time backup of the Oracle Key Vault server to a remote backup destination.
5. Proceed with the rest of the upgrade steps as for a standalone Oracle Key Vault server, including taking a one-time backup after the upgrade completes.
6. After the upgrade successfully completes, optionally HSM-enable your Oracle Key Vault server.
7. Remove the copied wallet in Step 2.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root
   root# /bin/rm /var/lib/oracle/cwallet_hsm_upgrade.sso

3.1.2 Upgrading from an Oracle Key Vault Release 12.2 Primary-Standby Deployment

You can upgrade from an Oracle Key Vault release 12.2 primary-standby deployment by reverse-migrating before the upgrade, and after the upgrade completes, re-HSM-enabling Oracle Key Vault.

1. On the current primary, make a one-time backup of the Oracle Key Vault server to a remote backup destination.
2. On the current primary, make a copy of the /mnt/okvram/cwallet.sso wallet file.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root
   root# /bin/cp /mnt/okvram/cwallet.sso /var/lib/oracle/cwallet_hsm_upgrade.sso

3. Unpair the primary and the standby servers.
   1. Log in to the primary server's management console as a user with the System Administrator role.
   2. Select the System tab, then Settings in the left navigation bar.
   3. In the System Configuration area, click Primary-Standby.
   4. Click Unpair.
      The unpair operation takes about 10 minutes to complete. After the unpair operation is complete, the standby will no longer be usable.
4. Reverse migrate so that Oracle Key Vault is no longer using an HSM as the RoT.
   You can verify the success of this operation by checking the audit record in the audit trail.
   If this step fails despite using the correct HSM credential and recovery passphrase, then do not continue with the rest of these steps. Contact Oracle Support.
5. Make another one-time backup of the Oracle Key Vault server to a remote backup destination.
6. Proceed with the rest of the upgrade steps for a primary-standby Oracle Key Vault server, including taking a one-time backup after the upgrade completes.
7. After the upgrade successfully completes, optionally HSM-enable a new primary-standby configuration using the upgraded Oracle Key Vault server as the primary and a fresh installation of the same version as the standby.
8. Remove the copied wallet in Step 2.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root
   root# /bin/rm /var/lib/oracle/cwallet_hsm_upgrade.sso

3.2 Upgrade Considerations for Entrust

When you upgrade while HSM-enabled and using an Entrust HSM, you must remake hardserver changes and consider changes to overriding security assurances.

Note:

Starting Oracle Key Vault 21.8, usage of Thales, Entrust, and Utimaco vendor specific configuration and notes is deprecated. It is recommended to check with the HSM vendor to see if there are any additional instructions to follow while upgrading an HSM enabled Oracle Key Vault server.

• Remaking Hardserver Changes While Upgrading Oracle Key Vault
  Because HSM configurations can vary, it is your responsibility to run test upgrades on non-production environments to ensure that the upgrade will work with your HSM configuration.
• Overriding Security Assurances for the Oracle Key Vault Upgrade
  You can configure how the Oracle Key Vault security assurance attributes are set for future initialization operations.
• Re-installation of Entrust Software While Upgrading Oracle Key Vault from 18.x to 21.x
  During the upgrade from Oracle Key Vault 18.x to 21.x, the operating system is upgraded from Oracle Linux 6 to Oracle Linux 7.

3.2.1 Remaking Hardserver Changes While Upgrading Oracle Key Vault

Because HSM configurations can vary, it is your responsibility to run test upgrades on non-production environments to ensure that the upgrade will work with your HSM configuration.

Upgrading Oracle Key Vault can undo changes that had been made before the upgrade to accommodate the installed HSM software. After the upgrade, perform the following steps and then ensure that Oracle Key Vault has all of the necessary changes to support integration with your HSM.

1. After you execute the steps to upgrade, and if the upgrade completed successfully, connect to the Oracle Key Vault server as the root user.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root

2. Execute the following command as the root user:

   root# usermod -a -G nfast oracle

3.2.2 Overriding Security Assurances for the Oracle Key Vault Upgrade

You can configure how the Oracle Key Vault security assurance attributes are set for future initialization operations.

As of Oracle Key Vault release 18.4.0.0.0, the Root of Trust (RoT) key that is created will have its CKA_EXTRACTABLE attribute set to CK_FALSE by default. However, in release 18.3.0.0.0 and earlier, CKA_EXTRACTABLE was set to CK_TRUE. This meant that the file /opt/nfast/cknfastrc used to require the following additional line:

CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness;tokenkeys;longterm

If you are upgrading Oracle Key Vault from release 18.3.0.0.0 or earlier, then these parameters will continue to be needed until you have reverse-migrated and re-initialized in a higher version, which will create a new RoT key with the CKA_EXTRACTABLE attribute set to CK_FALSE. If you prefer that future initialize operations continue have CKA_EXTRACTABLE set to CK_TRUE in release 18.4.0.0.0 and later, then perform the following steps before initializing.

1. Connect to the Oracle Key Vault server as the root user.

   $ ssh support@Oracle_Key_Vault_server_IP_address
   support$ su - root

2. Open the file okv_security.conf:

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

3. Set the HSM_KEY_EXTRACTABLE parameter in okv_security.conf as follows:

   HSM_KEY_EXTRACTABLE="1"

4. Save and exit the okv_security.conf file.

   :wq

5. Open the /opt/nfast/cknfastrc file.

   root# vi /opt/nfast/cknfastrc

6. Add the following line to /opt/nfast/cknfastrc:

   CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness;tokenkeys;longterm

Future initialize operations on this Oracle Key Vault server will now create Root of Trust keys with the CKA_EXTRACTABLE attribute set to CK_TRUE.

3.2.3 Re-installation of Entrust Software While Upgrading Oracle Key Vault from 18.x to 21.x

During the upgrade from Oracle Key Vault 18.x to 21.x, the operating system is upgraded from Oracle Linux 6 to Oracle Linux 7.

In order to preserve HSM integration functionality after the upgrade, the following steps are performed automatically during the upgrade:

/opt/nfast/sbin/install
/sbin/usermod -a -G nfast oracle
Edits to the /etc/systemd/system/nc_hardserver.service file

No action is required unless these steps are insufficient to set up the Entrust HSM in your environment. Oracle recommends that you run a test upgrade on a non-production environment to ensure that the upgrade will work with your HSM configuration.

3.3 Using a Token Label After Upgrading Oracle Key Vault without Reverse-Migrating

Starting in release 18.4, Oracle Key Vault can use a token label when you choose a slot while connecting to an HSM.

If you are upgrading an HSM-enabled Oracle Key Vault from a previous version, then you can begin using a token label after successfully upgrading without reverse-migrating.

1. Perform the upgrade to Oracle Key Vault release 18.4 or later.
2. Locate the token label of the token that Oracle Key Vault is currently using.
   1. Log into the Oracle Key Vault management console as a user who has the System Administrator role.
   2. Select the System tab, then Settings in the left navigation bar.
   3. In the Network Services area, click HSM to display the Hardware Security Module page.
      If the HSM is configured and running, then the Type label indicates the token label. For example:

      Token label: myPartition1

      Manufacturer ID: Safenet, Inc.

      Firmware version: 6.109

   4. Select the Set Credential button.
   5. In the Prepare for HSM Restore window, select from the Vendor menu, enter the HSM credential in the HSM Credential and Re-enter HSM Credential fields. Check the Use Token Label check box and enter the token label that you found (for example, myPartition1) in the Token Label field. Then click Set Credential.
   If this operation is successful, then Oracle Key Vault will begin to use the given token label when choosing a slot. If the operation fails, then your settings (token label, vendor, and HSM credential) are returned to what they were previously.

After this operation completes, if the green status arrow changes to a red arrow, this means that you have entered the wrong HSM credential, token label, vendor, or some combination of the three, and Oracle Key Vault was unable to revert the values to what they were previously. Oracle recommends that you try another set credential operation using the former HSM credential, token label, and vendor settings and do not restart Oracle Key Vault until the status arrow is again green. For more information about why the status arrow is red, check the most recent log files under the /var/okv/log/hsm directory.