Upgrading the nShield Connect image file and associated firmware

The nShield image file package for the nShield Connect is a single software bundle that consists of the following components:

  • The internal module firmware

  • The unit operating system image and host side software.

The image file package is installed on the remote file system when you install the client software. The following sections describe how to load this firmware package onto your nShield module.

Version Security Number (VSN)

Each nShield image file has a Version Security Number (VSN). In addition, the module firmware has its own individual VSN. This number is increased whenever we improve the security of the image file and/or firmware.

We supply several versions of the module firmware. You can always upgrade to firmware with an equal or higher VSN than that currently installed on your module.

You can never load an image file with a lower VSN than the currently installed version.
You can never load module firmware with a lower VSN than the currently installed firmware.

Ensuring you use an image file package with the highest available VSN allows you to benefit from security improvements and enhanced functionality. It also prevents future downgrades of the image file and/or that could potentially weaken security. However, you may choose to install an image file or 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 package, which may not have the highest VSN. Similarly, if you want to install a version with enhanced features without committing yourself to the upgrade, you can do so providing you upgrade only to firmware with a VSN equal to that currently installed on your module.

Key data

Security Worlds and key data are preserved on the RFS host computer only when you upgrade the unit image and/or firmware. You must restore the unit to the Security World if you wish to continue using the key data.

Adding or restoring a module will require authorisation from a quorum of Administrator cards.
When upgrading the Connect image file, client licenses and features activations on the nShield Connect will persist unless you deliberately factory state the unit (from the front panel menu).

For more information, see Adding or restoring an HSM to the Security World.

Upgrading the nShield Connect image file and firmware using the front panel

Before you upgrade the image file or firmware, ensure that you have installed the latest Security World Software on the client computer and that the remote file system has an up-to-date set of Security World files.

The nShield Connect image file contains both the Connect image and the firmware.

To upgrade the nShield Connect image file and firmware:

  1. Ensure that the nShield Connect image file that you require has been copied to the following directory:

    • Windows: %NFAST_HOME%\nethsm-firmware\<version>.

    • Linux: /opt/nfast/nethsm-firmware/<version>.

      Where <version> is a subfolder containing a firmware image for the respective version. There can be more than one <version> subfolder. The string <version> must match the name of the version folder in which the image is located on the version’s firmware ISO.

  2. From the main menu on the unit, select System > Upgrade system.

  3. Confirm that you want to upgrade the nShield Connect image file.

  4. Select the directory that contains the image file or firmware that you require. You are informed that the files are being transferred.

  5. Verify the image version, HSM (firmware) version, and image VSN that are displayed, and confirm the upgrade when prompted.

Remotely enabling dynamic feature certificates including nShield Connect client licenses

Feature certificates contained on the remote file system (RFS) can be applied to the nShield Connect. The main use case for applying feature certificates is for enabling the client licenses dynamic feature which have been purchased after the initial nShield Connect purchase, although both static and other dynamic feature certificates can be applied.

To apply a dynamic feature certificate, e.g. nShield Connect client license, do the following:

Feature certificates must be present on the RFS in the folder $NFAST_KMDATA/hsm-ESN/features.

  1. Use the nethsmadmin utility to list the nShield Connect feature files on the RFS. Run the command:

    nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --list-features

    In this command:

    • <MODULE> specifies the HSM to use, by its ModuleID (default = 1).

    • <RFS_IP> specifies the IP address of the RFS.

  2. Use the nethsmadmin utility to make the nShield Connect use a specific feature file from the RFS. Run the command:

    nethsmadmin --module=<MODULE> --rfs=<RFS_IP> --apply-feature=<feature_file>

    In this command:

    • <feature_file> must be the path to the feature file that is displayed when you run the nethsmadmin command with the --list-features option. Errors are reported if you use either just the feature name, or the full path. The file must be alphanumeric, and no longer than 150 characters.

      The following is an example of the output expected when applying a dynamic feature:

      Applying feature <DYNAMIC_FEATURE> to module <MODULE_NO> ...
Feature <DYNAMIC_FEATURE> application process started on module <MODULE_NO>
*DYNAMIC_FEATURE DETECTED*
Please restart you clientside hardserver and check the enquiry output to ensure the dynamic feature has been applied correctly!
For the client licences feature check the 'max exported modules' section in enquiry to see if the new client number has been applied correctly.

      The following is an example of the output expected when applying a static feature:

      Applying feature <STATIC_FEATURE> to module <MODULE_NO> ...
Feature <STATIC_FEATURE> application process started on module <MODULE_NO>
*STATIC_FEATURE DETECTED*
To be able to use the static feature please clear module MODULE_NO.
Use the fet utility to verify the feature was applied correctly.

      In the output examples:

    • <DYNAMIC_FEATURE> specifies the name of the dynamic feature file applied.

    • <STATIC_FEATURE> specifies the name of the static feature file applied.

    • <MODULE_NO> specifies the HSM that the feature was applied to.

Upgrading the nShield Connect image file and firmware from a privileged client

Before you upgrade the nShield Connect firmware, ensure you have installed the latest Security World software on the RFS and Client. However, an actual Security World is not required for this operation.

The following description assumes the RFS and Client are separate machines which an nShield Connect has already been configured to use. If you are using a combined RFS/Client, then apply the following instructions to the same machine. The Client must have privileged access to the nShield Connect.

The image upgrade file may be supplied as a separate item that must be copied into the subfolder for its respective version. The file must always be named nCx3N.nff irrespective of its version.

  1. Ensure that the new nShield Connect image file is in the following folder on the RFS:

    • Windows: %NFAST_HOME%\nethsm-firmware\<version>

    • Linux: /opt/nfast/nethsm-firmware/<version>

      Where <version> is a subfolder containing the nShield Connect image for the respective version. There can be more than one <version> subfolder. The string <version> must match the name of the version folder in which the image is located on the version’s firmware ISO.

      If the <version> subfolder does not already exist on the RFS, it must be created by a user with the necessary privileges.

  2. List the image file(s) available on the RFS, run the following command from the Client:

    Client:>>nethsmadmin –m<n> -s <RFS_IP> -l

    Where:

    • <n> is the module number for the target nShield Connect

    • <RFS_IP> is the IP address of the RFS.

    For example, when the image file is located in the appropriately named <version> folder:

    client:>>nethsmadmin -m2 -s 194.28.158.146 -l
Initiating RFS nethsm image check on 194.28.158.146...

Checking the nethsm-firmware directory on the RFS.
nethsm-firmware/VersionName/nCx3N.nff
nethsm-firmware/AnotherVersionName/nCx3N.nff

Images were successfully found on the RFS (194.28.158.146).

    For example, if the version folder does not exist or its name is not correct, the nethsmadmin command cannot find the image:

    client:>>nethsmadmin -m2 -s 194.28.158.146 -l
Initiating RFS nethsm image check on 194.28.158.146...

Checking the nethsm-firmware directory on the RFS.
No images found on the RFS (194.28.158.146).

  3. In order to load (or upgrade) the firmware image onto the nShield Connect, run the following command from the Client:

    Client:>>nethsmadmin –m<n> --upgrade-image=nethsm-firmware/<selected-image-version>/nCx3N.nff

    Where:

    • <n> is the module number for the target nShield Connect

    • <selected-image-version> specifies the version subfolder on the RFS containing the firmware image you wish to load (upgrade) onto the nShield Connect.

      Copy the path to the required image file as provided by the available image list above. (Linux style path separators are used irrespective of whether the Client or RFS are Windows or Linux based).

      e.g.

      client:>>nethsmadmin -m2 --upgrade-image=nethsm-firmware/VersionName/nCx3N.nff
Initiating appliance image upgrade using file nethsm-firmware/VersionName/nCx3N.nff...
Upgrade operation state changed to: Image Transfer Initiated
Upgrade operation state changed to: Image Transferred
Upgrade operation state changed to: Image Verified
Not able to contact appliance because of reason(23): CrossModule,#1-ExplicitRequest,#2-Mode
Upgrade operation final state: Image Verified
Image upgrade completed.
Please wait for appliance to reboot.
Please wait for approximately half an hour for the appliance to internally upgrade.

      The following line is expected and requires no action:

      Not able to contact appliance because of reason(23): CrossModule,#1-ExplicitRequest,#2-Mode
      If the nShield Connect suffers a loss of power while you are upgrading the image file or internal module firmware, exit the nethsmadmin utility, wait until power is restored to the HSM, then try to restart the process as shown above.

  4. After the image upgrade has completed, run the enquiry utility to check the image version of the target nShield Connect is as expected.

Enabling and disabling remote upgrade

You can enable or disable the ability to remotely upgrade an nShield Connect, see Enabling and disabling remote mode changes.

Once you have enabled remote upgrade, you can upgrade an nShield Connect from a computer using the nethsmadmin command, without accessing the unit itself.

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.