3 Upgrade Considerations When Using HSMs in Oracle Key Vault

When you upgrade an Oracle Key Vault deployment that has HSMs, you should consider factors such as the release being upgraded from, Entrust, and tokens.

• 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 described in Oracle Key Vault Administrator's Guide 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 select Primary-Standby from the left side bar.
   3. 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 as described in Oracle Key Vault Administrator's Guide 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.

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

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.

1. 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 steps to upgrade as described in Oracle Key Vault Administrator's Guide, up to and including the command where you run the following command:

   root# /usr/bin/ruby /images/upgrade.rb --confirm

3. After running /usr/bin/ruby /images/upgrade.rb --confirm but before you execute the reboot operation, execute the following commands:

   root# usermod -a -G nfast oracle
   root# cd /etc/rc.d/rc5.d
   root# mv S50nc_hardserver S40nc_hardserver
   root# cd /etc/rc.d/rc3.d
   root# mv S50nc_hardserver S41nc_hardserver

4. Continue with the upgrade process as described in Oracle Key Vault Administrator's Guide.
5. Remake the hardserver changes, as they may have been undone during the upgrade.

   root# /usr/bin/test -e /etc/rc.d/rc5.d/S50nc_hardserver && /bin/mv /etc/rc.d/rc5.d/S50nc_hardserver /etc/rc.d/rc5.d/S40nc_hardserver
   root# /usr/bin/test -e /etc/rc.d/rc3.d/S50nc_hardserver && /bin/mv /etc/rc.d/rc3.d/S50nc_hardserver /etc/rc.d/rc3.d/S41nc_hardserver

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, 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.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, and then click Hardware Security Module in the left sidebar. Navigate to the Hardware Security Module page. For example, the token label in the following example is myPartition1:
      
      Description of the illustration hsm_enabled.png
      
   3. Select the Set Credential button.
   4. In the Prepare for HSM Restore dialog box, enter the HSM credential in the HSM Credential and Re-enter HSM Credential fields, and the recovery passphrase that you are currently using in the Recovery Passphrase field. 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.