Upgrading firmware

This section describes how to upgrade firmware on your nShield HSM hardware security module.

Primary, recovery and bootloader firmware

HSM firmware consists of three major components:

  • Primary image firmware

  • Recovery image firmware

  • Bootloader firmware

Upgrade packages may contain updates for any of these components. The same upgrade method is used in all cases. The system will automatically detect which components are included in the update package and will load the firmware 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 performs as expected and then upgrade the Recovery firmware at a later date.

Firmware version control

The version of Primary and Recovery image firmware that can be installed on an HSM is controlled by the Version Security Number, see Version Security Number.

Bootloader firmware version control is described in Bootloader version.

Version Security Number (VSN)

Entrust supply several versions of the module firmware. Primary and Recovery image firmware includes a Version Security Number (VSN). This number is increased whenever Entrust improve the security of the firmware. Ensuring you use firmware with the highest available VSN allows you to benefit from these security improvements.

However, if you have a regulatory requirement to use certified firmware such as that approved by FIPS or Common Criteria, you should only install the latest available firmware that has been certified by the relevant certification authority. This firmware may not have the highest VSN available.

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.

You can upgrade to a firmware version with a higher VSN than the HSM’s current firmware, without committing yourself to the upgrade, by installing the newer firmware without altering the HSM’s minimum VSN requirement. The older firmware can be reinstalled at any time provided the HSM’s minimum VSN has not been altered.

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.

Configuring the minimum VSN

To increase the HSM’s minimum VSN requirement, use the command hsmadmin setminvsn. 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.

It is 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. This prevents future downgrades of the firmware that could potentially weaken security.

Bootloader version

Bootloader firmware does not have a VSN. The Bootloader version number is included in the filename of the upgrade package. Entrust recommend that you always install the latest version available.

For security reasons some Bootloader firmware upgrades are irreversible. These Bootloader upgrades revoke the signing key used to sign previous Bootloader firmware and thus it is not possible to revert back to previous Bootloader firmware after such an upgrade.

Refer to the release notes accompanying the firmware release to identify whether the Bootloader upgrade is reversible or not.

It is only possible to update the Bootloader when running firmware version 13.4 or later.

Firmware on the installation media

Your Firmware installation media may contain several sets of firmware for each supplied product. These can include the:

  • latest FIPS approved firmware

  • latest Common Criteria approved firmware

  • latest firmware available

You should ensure you are using the latest firmware available, unless you have a regulatory requirement to use firmware that has been certified by a specific certification authority.

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 Primary or Recovery image 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:

Linux
hsmadmin npkginfo /disc-name/firmware/nShield5s/status/firmware_file.npkg

In this command, disc-name is the directory on which you mounted the installation media, status is the certification status, and firmware_file is the file name.

Windows
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.
If the HSM to be upgraded is part of an audit logging Security World you will need to finalize the audit log before starting the upgrade. See audit logging and firmware upgrade for information on how to do this.
You should always check that the system clock is correct before upgrading the firmware and adjust it if necessary, see Manage the system clock of an nShield 5s.

  1. Put the module in Maintenance mode.

    See Check and change the mode of operation.

  2. Check the version of the firmware currently loaded, see hsmadmin status.

  3. View information about the firmware in the upgrade file including the version and the VSN, see hsmadmin npkginfo.

  4. Optionally make a dry-run of the upgrade by using hsmadmin upgrade with the --dry-run option. This will check that everything is in place for the upgrade to succeed but will not upgrade the firmware. If any errors are reported fix these before continuing to the next step.

  5. Upgrade the firmware, see hsmadmin upgrade.

    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.

  6. Check the version of the firmware now loaded, see hsmadmin status.

  7. Put the module in initialization mode.

    See Check and change the mode of operation.

  8. Restore the HSM to the Security World, see Adding or restoring an HSM to the Security World

    If the HSM is not part of a Security World you can use the command initunit instead of this step.

  9. Put the module in Operational mode.

    See Check and change the mode of operation.

  10. 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 loaded. This is the version field listed per module.