Upgrading firmware

This appendix describes how to load firmware onto your nShield HSM hardware security module.

Version Security Number (VSN)

The firmware includes a Version Security Number (VSN). This number is increased whenever Entrust improve the security of the firmware.

Entrust supply several versions of the module firmware. Every HSM records the minimum firmware VSN that it will accept. You can always upgrade to firmware with an equal or higher VSN than the minimum VSN set on your module, even if the firmware currently installed on the module has a higher VSN than the firmware to which you are upgrading. firmware currently installed on the module has a higher VSN than the firmware to which you are upgrading.

You can never load firmware with a lower VSN than the target HSM’s minimum VSN requirement.

For example, if the HSM has a minimum VSN requirement of 3 and the currently installed firmware has a VSN of 4, you can install firmware with a VSN of 3 or above to the HSM. You cannot install firmware with a VSN of 1 or 2 to this HSM.

To increase the HSM’as minimum VSN requirement, use the hsmadmin setminvsn command. The new VSN must be greater than or equal to the HSM’s current minimum required VSN, and cannot be greater than the VSN of the firmware currently installed on the HSM.

Therefore it is possible to upgrade to a firmware version with a higher VSN that the HSM’s current firmware without committing yourself to the upgrade by installing the newer firmware without using the hsmadmin setminvsn command. The older firmware can be reinstalled at any time provided the hsmadmin setminvsn command has not been run.

Ensuring you use firmware with the highest available VSN allows you to benefit from security improvements and enhanced functionality. It also prevents future downgrades of the firmware that could potentially weaken security. It is therefore recommended that the hsmadmin setminvsn command always be used as soon as the decision has been made not to return to the older version of the firmware.

However, you may choose to install an associated firmware that does not have the highest available VSN. For example, if you have a regulatory requirement to use FIPS-approved firmware, you should install the latest available FIPS-validated firmware, which may not have the highest VSN.

Firmware on the installation media

Your Firmware installation media contains several sets of firmware for each supplied product. These can include the latest available:

  • FIPS-approved firmware with the base VSN

  • FIPS-approved firmware with a higher VSN

  • Firmware awaiting FIPS approval with the base VSN

  • Firmware awaiting FIPS approval with a higher VSN.

You should ensure you are using the latest firmware, unless you have a regulatory requirement to use firmware that has been FIPS validated. In the latter case, you should ensure that you are using the latest available FIPS validated firmware.

Primary and recovery firmware

Upgrade packages may contain updates for either the primary firmware or the recovery firmware. The same upgrade method is used in both cases. The system will automatically detect whether the firmware is primary or recovery and will load it to the correct location.

If upgrade packages are available for both primary and recovery firmware it is not recommended to upgrade them both at the same time. The recommended procedure is to always upgrade the primary firmware first. Test that the system the performs as expected and then upgrade the recovery firmware at a later date.

Recognising firmware files

The firmware files are stored in subdirectories within the firmware directory on the installation media. The subdirectories are named by product and then certification status, which can be latest, fips-pending, fips, or cc.

Firmware files for nShield HSM modules have a .npkg filename suffix.

The VSN of a firmware file is incorporated into its filename and is denoted by a dash and the letters "vsn" followed by the digits of the VSN. For example, -vsn24 means the VSN is 24.

To display information about a firmware file on the installation media, enter the following command:

hsmadmin npkginfo E:\firmware\nShield5s\status\firmware_file.npkg

In this command, E is the drive letter of your installation media, status is the certification status, and firmware_file is the file name.

Firmware installation overview

Normal procedure is to install firmware when the HSM is running in primary mode. If the HSM is running in recovery mode, as described in Recovery mode the procedure is identical except that the reboot caused by hsmadmin upgrade will cause the module to factory state and it will be necessary to run hsmadmin enroll before continuing with the rest of the installation.

If you are upgrading a module which has SEE program data or NVRAM-stored keys in its nonvolatile memory, use the nvram-backup utility to backup your data first.

  1. Put the module in Maintenance mode.

    See Checking and changing the mode on an nShield 5s module for more about changing the mode.

  2. Run the hsmadmin status command-line utility and check the version of the firmware currently loaded.

    By default the command only displays the version of the current primary firmware. If you wish to also see the current recovery firmware version use the command line option --json

  3. Run the hsmadmin npkginfo command-line utility to view information about the firmware in the upgrade file including the version and the VSN.

  4. Run the hsmadmin upgrade command-line utility to upgrade the firmware.

    The current firmware version and the firmware version being loaded will be displayed automatically.

    The module will be programmed with the new firmware and will be automatically rebooted.

    If the installation is being run from recovery mode this reboot will factory state the HSM and hsmadmin enroll must be run before continuing.
    The module will report which internal components of the firmware have been updated. These components are pre-determined by the individual upgrade file and the internal names are intended for use by Entrust support staff only.

  5. Run the hsmadmin status command-line utility and check the version of the firmware now loaded.

  6. Put the module in initialization mode.

    See Checking and changing the mode on an nShield 5s module for more about changing the mode.

  7. Initialize the module by running the command initunit

  8. Put the module in Operational mode.

    See Checking and changing the mode on an nShield 5s module for more about changing the mode.

  9. Run the enquiry command to verify the module is in operational state and has the correct firmware version.

    In Operational mode, the enquiry command shows the version number of the firmware.

After firmware installation

After you have installed new firmware and initialized the HSM, you can create a new Security World with the HSM or reinitialize the HSM into an existing Security World.

If you are initializing the HSM into a new Security World, see Creating a Security World.

If you are re-initializing the HSM into an existing Security World, see Adding or restoring an HSM to the Security World