Upgrading the image file and associated firmware

Version Security Number (VSN)

Each Connect image file has a Version Security Number (VSN). In addition, the internal module (HSM) 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.

The Version Security Number (VSN) stands as a safeguard to prevent earlier and potentially less secure images and accompanying firmware from being loaded onto the nShield Connect. It prevents the loading of an image file with a lower VSN than the existing VSN. The VSN is not incremented with every release, but only in the event of a significant security enhancement to the nShield Connect and / or its internal module.

The Connect image VSN is only available from the nShield Connect Front Panel UI.

Key data

During an upgrade Security World and key data are preserved on the RFS host computer. Once you have upgraded the Connect image 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 nShield HSM image file, client licenses and features activations on the HSM will persist. However, if you factory state the unit dynamic features are lost and must be re-enabled.

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

Ensure you have a quorum of the ACS and that the ACS is available and operating correctly prior to commencing any firmware upgrade. If you do not, you will not be able to reload your Security World on your nShield Connect and you will not be able to use any of your keys.

Upgrading the Connect image

The Connect image (identified by the file extension .nff) is located on the .iso or DVD in the nethsm-firmware directory. The image file contains all necessary components required to upgrade the nShield Connect.

Before upgrading, copy the directory containing the .nff file from the .iso or DVD to the nethsm-firmware directory on the Remote File System of the nShield Connect.

The following sections describe how to load this firmware package onto your nShield Connect.

Upgrading the Connect image using the front panel

Before upgrading your Connect image ensure that you have a working quorum of Administrator Cards from the ACS. You need these together with the files in /local to restore your Security World on your nShield Connect after the upgrade.

To upgrade the Connect image:

Ensure that the Connect image file is named nCx3N.nff and located in the following directory:
- Windows: %NFAST_HOME%\nethsm-firmware\<version>\nCx3N.nff.
- Linux: /opt/nfast/nethsm-firmware/<version>/nCx3N.nff.
  
  Where <version> is a subfolder containing the firmware image to be used for the upgrade. There can be more than one <version> subfolder.

The directory <version> should match the image version string identified on the firmware ISO. If you are not sure on the details, contact Entrust nShield Support, https://nshieldsupport.entrust.com.

From the main menu on the unit, select System > Upgrade system.
Confirm that you want to upgrade the image file.
Select the directory that contains the image file or firmware that you require. If multiple Connect image directories are displayed, scroll to the relevant directory and select it.

You are informed that the files are being transferred. The nShield Connect will disconnect from the network during the upgrade procedure and reconnect once the upgrade is complete.
Verify the image version, HSM (firmware) version, and image VSN that are displayed, and confirm the upgrade when prompted.

Upgrading the nShield Connect from a privileged client

The following description assumes the RFS and Client are separate machines which an nShield HSM 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 HSM.

The image upgrade file may be supplied as a separate item that must be copied into the subfolder for its respective version. The default file name is nCx3N.nff.

Ensure that the new 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 image for the respective version. There can be more than one <version> subfolder. The string <version> should 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.
List the image file(s) available on the RFS, run the following command from the Client:
```
>nethsmadmin –m<n> -s <RFS_IP> -l
```
Where:
- <n> is the module number for the target nShield HSM
- <RFS_IP> is the IP address of the RFS.
- Additionally the --rfs-hkneti=<RFS_HKNETI> and --rfs-esn=<RFS_ESN> options can be set to enable secure authentication of the RFS. There are three possible cases:
  - Without secure authentication: The authentication of the RFS will be based on the IP address only if the --rfs-hkneti and --rfs-esn options are not specified.
  - Software-based authentication: The --rfs-hkneti option specifies the software KNETI hash of the RFS. The --rfs-esn option shall not be specified.
    
    <RFS_HKNETI> can be obtained by running anonkneti -m0 localhost on the RFS.
  - nToken authentication: Only if an nToken (or local HSM) is installed in the RFS. The --rfs-hkneti and --rfs-esn options specify the KNETI hash and ESN of the nToken.
    
    <RFS_HKNETI> and <RFS_ESN> can be obtained by running ntokenenroll -H on the RFS.
    
    For example, when the image file is located in the appropriately named <version> folder:
    
    >nethsmadmin -m1 -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:
    
    >nethsmadmin -m1 -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).

In order to load (or upgrade) the Connect image run the following command from the Client:

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

Where:

<n> is the module number for the target nShield HSM
<selected-image-version> specifies the version subfolder on the RFS containing the firmware image you wish to load (upgrade) onto the nShield HSM.

<RFS_IP> specifies the IP address of the RFS using the -s argument. For example

>nethsmadmin -m1 -s 194.28.158.14 --upgrade-image=nethsm-firmware/VersionName/nCx3N.nff

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.

>nethsmadmin -m1 -s 194.28.158.14 --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

The notification appears because the RFS/client cannot contact the nShield Connect. Once the image is copied across, the nShield Connect will disconnect from the network for the duration of the upgrade and reconnect once the upgrade is completed.

If the nShield HSM 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.

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

Enabling and disabling remote upgrade

You can enable or disable upgrading an nShield HSM remotely, see Enabling and disabling remote mode changes. Once you have enabled remote upgrade, you can upgrade an nShield HSM 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.