nShield 5s platform modes
This chapter describes the nShield 5s platform modes of operation:
Modes of operation
The status of the nShield 5s HSM can only be one of the following:
| Status | Description |
|---|---|
Primary mode |
The nShield 5s HSM is running on the primary firmware image. This is the normal operational mode. |
Recovery mode |
The nShield 5s HSM is running on the recovery image instead of the primary image. See Recovery mode. |
Factory state |
The nShield 5s HSM is in a factory state. See Return to factory state. |
Normal operation
In normal operation the nShield 5s HSM will be running the primary firmware
image. In a multi-tenant system there will be ncoeapi service running at platform level.
The ncoreapi service runs only inside a VCM and it will be necessary to create at least
one VCM in order to have access to ncoreapi services.
Return to factory state
nShield 5s HSMs that are delivered from the factory contain no data relating to the ncoreapi service.
A small amount of 'lifetime' data, which is used by the platform services, is pre-installed.
This data is for personalisation and identification of the individual HSM, such as its ESN.
You can perform a reset operation that returns the data stored in an HSM to the state it was in when it left the factory. This erases user credentials and information, leaving only the 'lifetime' data.
When an HSM is in this state it will not support any user commands other than hsmadmin enroll and it will be necessary to follow the process described in Installation of SSH keys before any further actions can be taken.
| Returning to factory state will erase any optional features that were not installed at the factory. See, Optional features. |
| Returning to factory state will change the key used to sign system logs. You should make a record of the new log verification key as soon as possible after returning an HSM to factory state. See Verifying Signed Logs for more information. Signed system logs are only available from firmware version 13.5 onwards so this is not necessary for HSMs running older firmware. |
Purpose of factory state
The main reason for returning an nShield 5s HSM to factory state is to securely erase all user secrets. This is important when, for example:
-
The HSM is being taken out of service.
-
The HSM is being moved from one domain to another, where it is important to ensure that there is no possibility of secrets being leaked between domains.
-
The HSM is being returned to Entrust for servicing or warranty.
-
You have lost the SSH keys used to communicate with the HSM, see Recovery from loss of SSH keys
Recovery from loss of SSH keys
Returning a unit to factory state will be necessary if you have lost possession of the SSH keys used to communicate with the HSM and you have not
previously made a backup of those keys with hsmadmin keys backup (or hsmadmin keys backup --passphrase if the HSM is being re-installed in a different machine).
If this happens, returning the HSM to factory state will allow hsmadmin enroll to successfully create new keys and re-establish communication with the HSM.
Enter and exit the factory state
The nShield 5s HSM can be returned to factory state in one of two ways. Either by use of hsmadmin factorystate or by placing the HSM in Recovery mode.
If the SSH keys used to communicate with the HSM have been lost, only the Recovery mode option is possible. Both of the above methods include a reboot of the HSM.
| The command hsmadmin factorystate is prohibited if the system logs have exceeded a maximum size, see maximum log size or if the system clock is invalid, see System interaction with the system clock. In these situations you can only return to factory state by placing the HSM in Recovery mode. |
The HSM is taken out of factory state by use of hsmadmin enroll.
Recovery mode
nShield 5s HSMs are loaded with two different firmware images:
-
The Primary image.
-
The Recovery image.
During normal operation, the HSM is running firmware that is loaded from the Primary image.
If required, the HSM can be forced into recovery mode to run firmware loaded from the Recovery image.
Entry into recovery mode performs the same actions as hsmadmin factorystate
Recovery mode is useful in the following cases:
-
To return the HSM to a known good state for disaster recovery.
-
To retrieve the
initlog if the HSM fails to boot into primary mode, see Retrieving the init log -
To clear the system log if the HSM is prohibiting actions because it has exceeded the maximum log size, see Maximum log size
-
To restore communication with the HSM if the SSH keys have been lost and no backup is available, see Set up communication between host and module (nShield 5s HSMs).
-
To restore communication with the HSM if an invalid system clock is preventing you from modifying the SSH keys in primary mode. See System interaction with the system clock.
Restrictions in recovery mode
The main purpose of recovery mode is to allow essential maintenance activities that are not possible in when the nShield 5s is running the primary image firmware.
The ncoreapi and launcher services don’t run when the nShield 5s is in recovery mode.
Only the platform services are available, meaning that only the commands described in Administration of platform services (nShield 5 HSMs) are available.
If you run hsmadmin enroll in recovery mode, a warning will appear.
This is because the certificates for the SSH keys described in Set up communication between host and module (nShield 5s HSMs) are not created in recovery mode.
You can ignore this warning.
Commands that use ncoreapi or launcher service do not run and may show error messages.
Entry into recovery mode
Boot the nShield 5s HSM into recovery mode by holding down the recovery mode button on the back panel of the HSM and then rebooting the HSM. You must continue holding down the button for 60 seconds after initiating the reboot. The button is non-latching.
| You must hold down the recovery mode button while the HSM is rebooting. If you reboot the HSM and then press and hold down the button, you will miss the part of the reboot process in which you can change the mode of the HSM. |
See Install a PCIe HSM for the location of the recovery mode button.
You can trigger a reboot with hsmadmin reset or by power cycling the host machine containing the HSM.
If you cannot reach the recovery mode button and enter the reboot command simultaneously, you might need to connect a keyboard, mouse, and monitor to the back of the server hosting the HSM. If this is not possible, you need a second person to pass the command to the HSM while you hold down the button, or to hold down the button while you pass the command.
Entering and exiting recovery mode return the HSM to factory state.
You must run hsmadmin enroll after the boot has completed before any further actions can be performed.
Run hsmadmin status to verify that the HSM is in recovery mode.
If you are still in primary mode, try the process again, making sure that the recovery mode button is pressed down before or as soon as the reboot command is passed, and that it is held for the allotted time.
Exit from recovery mode
Exit recovery mode by booting the nShield 5s HSM without the recovery mode button held down.
If the firmware is changed whilst in recovery mode using hsmadmin upgrade, the unit automatically reboots.
When the unit next boots into primary mode it will be in factory state.
You must run hsmadmin enroll again before any further actions can be performed.
If you exited recovery mode using hsmadmin reset, or as part of a firmware upgrade, you must restart the hardserver/nFast server after running hsmadmin enroll.
Run hsmadmin status to verify that the HSM is in the correct mode.