Administration of platform services

nShield 5s platform services are administered through the unified utility hsmadmin, which directs the command to the service that implements the command.

Some commands require elevated privileges by default because both the permissions and the protection settings have an impact on the usability of the keys by non-administrative users. Commands that create keys or modify configuration always require elevated privileges. Elevated privileges mean root on Linux, and the built-in local Administrators group (running in an elevated shell) on Windows. If a command requires elevated privileges, this is indicated in the command description.

You can modify the permissions and protection options on service keys to allow particular groups of users to execute commands that require the private key for a given service. See Permissions on SSH keys and Setting Protections on SSH keys.

All of the platform services are administered by a unified utility called hsmadmin

hsmadmin

The hsmadmin utility manages the administration of nShield HSMs using different subcommands.

hsmadmin <subcommand>

You can use one of the following subcommands each time you run hsmadmin:

hsmadmin factorystate

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w.

This command returns an HSM to the state it was in when it left the factory. This securely erases all user credentials and information. It resets the sshadmin SSH credential to the default.

hsmadmin factorystate [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose]

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Resets specific modules to factory state.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin factorystate --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If no ESNs are specified, the command resets all connected modules.

--verbose

Prints verbose logs.

hsmadmin status

This command displays the ESN and currently loaded firmware version for discovered HSMs. It also displays whether the current image is a primary or a recovery image. When used with the --json option it displays primary firmware version, recovery firmware version, and uboot version.

hsmadmin status [-h] [--esn <ESN>] [--timeout <TIMEOUT>] [--verbose] [--json]

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints the HSM firmware version and image version in JSON format.

--esn

Displays information for specified HSMs.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin status --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If you do not specify any ESNs, the command displays information for all connected HSMs.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

hsmadmin npkginfo

This command inspects the npkg file and displays the metadata.

hsmadmin npkginfo [--json] <NPKGFILE>

This command takes the following parameters:

Parameter Description

--json

Prints metadata in JSON format.

<NPKGFILE>

Specifies the NPKG-format file to inspect.

hsmadmin upgrade

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w.

This command installs firmware packages in npkg format. The command can install both primary and recovery firmware.

hsmadmin upgrade [-h] --esn <ESN> [--timeout <TIMEOUT>] [--verbose] [--json] <NPKGFILE>

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints metadata in JSON format.

--esn

Specifies the HSMs in which to load the NPKG file.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin upgrade --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321 <NPKGFILE>

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

<NPKGFILE>

Specifies the npkg file to load in to the HSMs.

hsmadmin reset

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w. If you run the command while in operational mode, it creates a failed state and you will need to run nopclearfail -r -m <MODULEID> to correct it.

This command resets the nShield HSM.

hsmadmin reset [-h] [--esn <ESN>]

This command takes the following parameters:

Parameter Description

--esn

Specifies the HSMs to reset.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin reset --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If you do not specify any ESNs, all connected HSMs will be reset.

hsmadmin enroll

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w.

This command configures the SSH keys for the nShield HSM.

Linux-only

The install script calls this command automatically as hsmadmin enroll --sshadmin-key /root/.ssh/id_nshield5_sshadmin. This will generate SSH client keys and register them with the units if they have not been previously set up. If the sshadmin key is not found in its usual location under /opt/nfast then /root/.ssh/id_nshield5_sshadmin will be tried instead, so it is convenient to use hsmadmin keys backup to backup the key to this location.

If hsmadmin enroll is called after install to change the installed units, the hardserver will need to be restarted in order to pick up the configuration changes, for example, by running /opt/nfast/sbin/init.d-ncipher restart.

 
hsmadmin enroll [--timeout <TIMEOUT>] [--verbose] [--sshadmin-key <SSHADMIN_KEY>]

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--verbose

Prints verbose logs.

--sshadmin-key

Path to backup of sshadmin key to use if not present in the standard location.

hsmadmin keys

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w.

This command is used to manage the SSH keys currently loaded on a module.

hsmadmin keys [--timeout <TIMEOUT>] <subcommand>

This command takes the following parameter:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

You can use one of the following subcommands with this command:

hsmadmin keys show

This subcommand displays the public client and server keys used to communicate with the HSMs. For client keys, it also displays the time stamp held on the associated key file in the host file system.

hsmadmin keys show [--json] [--verbose]

This subcommand takes the following parameters:

Parameter Description

--json

Prints output in JSON format.

--verbose

Prints verbose logs.

hsmadmin keys migrate

This subcommand changes the SSHAdmin client key on all connected modules to match a public key. The public key is derived from the private key specified in the subcommand.

hsmadmin keys migrate --privkeyfile <PRIVKEYFILE> [--json] [--verbose]

This subcommand takes the following parameters:

Parameter Description

--json

Prints output in JSON format.

--verbose

Prints verbose logs.

--privkeyfile

Specifies the file containing the private key to be migrated to.

hsmadmin keys roll

This subcommand changes the client keys for all services.

See SSH Client Key Protection for information about protection options that can be set on keys during generation.

hsmadmin keys roll [--json] [--verbose]

This subcommand takes the following parameters:

Parameter Description

--json

Prints output in JSON format.

--verbose

Prints verbose logs.

On Linux, the hardserver must be restarted in order to be able to use the new ncoreapi SSH client key after performing this operation, for example, with /opt/nfast/sbin/init.d-ncipher restart.

hsmadmin keys backup

This subcommand makes a backup of the private client key for the sshadmin service.

The backup key should be protected against unauthorized access. Refer to your security procedures for information on how to store the backup file. 
hsmadmin keys backup [--passphrase] <FILE>

This subcommand takes the following parameters:

Parameter Description

--passphrase, -p

Replace host key protection with passphrase protection.

<FILE>

Path to file in which to store backup.

If the --passphrase option is not supplied, then the existing sshadmin key file will be copied verbatim with whatever existing protections it has. By default, the sshadmin key is tied to the host machine and OS install, and will not be usable on another machine.

If the --passphrase option is used, then the sshadmin key will be loaded and re-encrypted using a user passphrase that must be supplied at the prompt. If the existing sshadmin key was also protected with a user passphrase (this is not the case by default), then there will be a prompt for that key’s passphrase too. The backup key will not be tied to the host machine in this case, and can be used to re-install the HSM on another machine.

On Linux, the backup file will be generated with owner and group matching the directory in which it is created, and readable by owner only.

hsmadmin keys restore

This subcommand restores the private client key for the sshadmin service from a backup file that has previously been created with the hsmadmin keys backup command.

Once the private client key for the sshadmin service has been successfully restored, this command will automatically configure all other SSH keys for the HSM.

hsmadmin keys restore <FILE>

This subcommand takes the following parameter:

Parameter Description

<FILE>

Path to file previously created by hsmadmin keys backup

hsmadmin keys remote-set

This subcommand installs a specific SSH public key for remote access to one HSM service.

hsmadmin keys remote-set <SERVICE> <KEYTYPE> <KEYDATA>

This subcommand takes the following parameters:

Parameter Description

<SERVICE>

HSM service to be accessed remotely

<KEYTYPE>

SSH public key type

<KEYDATA>

SSH public key

hsmadmin keys remote-remove

This subcommand removes a specific SSH public key that had previously been set for remote access and restores the local client key.

hsmadmin keys remote-remove <SERVICE>

This subcommand takes the following parameter:

Parameter Description

<SERVICE>

HSM service from which to remove remote access

hsmadmin logs

This command retrieves or clears logs from connected HSMs.

hsmadmin logs <subcommand>

You can use one of the following subcommands with this command:

hsmadmin logs get

This subcommand retrieves logs from a connected HSM. The information in these logs is primarily intended for use by nShield Support.

If primary mode fails to boot, boot into recovery mode and retrieve the init log, then send the information it contains to nShield Support.

hsmadmin logs get [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN>] --log <LOG> [--json | --out <OUTFILE>]

This subcommand takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Specifies the HSM from which to retrieve logs.+ Only one ESN can be used in the command to retrieve the logs of one specific HSM.

--json

Prints output in JSON format.

--out

Write logs to file specified by OUTFILE

--verbose

Prints verbose logs.

--log

Selects log to be retrieved. Options are system, init

hsmadmin logs clear

This subcommand clears logs from connected HSMs. The HSM must be in maintenance mode for clearing logs.

hsmadmin logs clear [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN] --log <LOG> [--json]

This subcommand takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Specifies the HSMs from which to clear logs.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin logs clear --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321 --log <LOG>

If you do not specify any ESNs, logs will be cleared from all connected HSMs.

--json

Prints output in JSON format.

--verbose

Prints verbose logs.

--log

Selects log to be cleared. Options are system, init

hsmadmin info

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

This command returns information that was loaded in the HSM during manufacturing. This information is persistent even after returning the HSM to factory state.

hsmadmin info [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose] [--json]

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Returns information for the HSM identified by <ESN>.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin info --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If no ESNs are specified, the command returns information for all connected modules.

--verbose

Prints verbose logs.

--json

Prints output in JSON format.

Manage the system clock of an nShield 5s

Ensuring that an HSM’s system clock is closely synchronized with an external time source, such as the HSM’s host clock, is critical for maintaining robust security and audit capabilities. The HSM’s date and time are used to validate security certificate expiry dates and to provide accurate timestamps for security and audit logs, which are essential for official traceability. However, due to environmental differences and differences between the hardware devices responsible for keeping time on the HSM and host sides, their time can drift apart over time if at least one of them is not periodically adjusted. hsmadmin has commands for managing system clock settings and synchronization. The first step in managing the HSM’s system clock is to set the initial HSM time correctly. See settime.

Make sure that the date and time on the host machine are set correctly according to the documentation for the operating system on the host machine.
To prevent malicious actors from tampering with the HSM’s system clock by moving it backward, the HSM is designed to prevent the setting of a time and date that is earlier than a previously set time and date. Only hsmadmin factorystate can reset the HSM’s clock to an earlier time and date. This ensures that the HSM’s system clock remains secure and accurate and helps prevent unauthorized access that could occur if the system clock were tampered with.

The second critical step in maintaining minimal drift between an HSM’s host clock and its own clock is to periodically use the settime command with the adjust parameter. When the nShield 5s receives this command, it will work to gradually reduce any difference in time between the host and the HSM’s clocks, preventing large jumps or discontinuities in time. The frequency at which the HSM’s administrator should issue hsmadmin settime --adjust depends on multiple factors, for example the precision of the internal clock of the host of the HSM and the extent of drift between the host’s clock and the HSM’s clock. The recommended starting point for most systems would be to issue the command once per day. Experimentation is required to find the optimal frequency.

The settime command uses UTC date and time format.

hsmadmin settime

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Without the adjust parameter, hsmadmin settime obtains the host local clock time in UTC format and sets the system date and time of the HSM.

To set system date and time, the HSM must be in maintenance mode.

Setting the system date and time automatically resets the HSM.

If the adjust parameter is used with hsmadmin settime, the HSM system clock drift will be calibrated.

You can calibrate the clock drift when the HSM is in operational mode, but calibration will gradually converge the clocks at a few seconds per day. This means that it may take several days to correct the clock. When you execute hsmadmin settime adjust, the command immediately returns HSM system time calibration in progress to acknowledge that the calibration process has started. There is no notification when the calibration is complete.

hsmadmin settime [-h] [--adjust <adjust>] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose]

This command takes the following parameters:

Parameter Description

--adjust

Optional parameter. If specified an HSM System clock drift calibration is executed.

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Sets the system date and time of specific modules.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin settime --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If no ESNs are specified, the command resets all connected modules. If the adjust parameter is specified, a module reset is not required.

--verbose

Prints verbose logs.

hsmadmin gettime

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

It returns the system date and time of the HSM.

hsmadmin gettime [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose] [--json]

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Returns information for the HSM identified by <ESN>.

You need to add --esn before each ESN you include in the command, for example:

hsmadmin gettime --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If no ESNs are specified, the command returns the HSM system date and time for all connected modules.

--verbose

Prints verbose logs.

--json

Prints output in JSON format.

hsmadmin setminvsn

This command requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

Before running this command, place the unit in maintenance mode using nopclearfail -M -m <MODULEID> -w.

This command sets the minimum VSN number of the firmware which the HSM will in the future accept as an upgrade.

hsmadmin setminvsn [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose] [--json] <VSN>

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Sets the minimum VSN on the HSM identified by <ESN>.

You need to add --esn before each ESN you include in the command, for example:

>hsmadmin setminvsn --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321 2

If no ESNs are specified, the command sets the minimum VSN on all connected HSMs.

--verbose

Prints verbose logs.

--json

Prints output in JSON format.

<VSN>

The minimum VSN to set.

Once this command is executed, the HSM will no longer accept a command to upgrade to a firmware with a VSN lower than <VSN>.

The new minimum VSN cannot be lower than the HSM’s current VSN, and cannot be higher than the VSN of the firmware currently installed on the HSM.

hsmadmin getenvstats

This command returns the environmental monitoring statistics of the HSM.

Environmental monitoring statistics available depend on the model of the HSM, the hardware revision and the version of the firmware installed on the HSM.

For the nShield5 with firmware version 13.3 the available statistics are:

uptime

The time since the HSM was last rebooted, in seconds.

current_time

The current system time of the HSM.

mem_total

Total amount of physical RAM, in kilobytes.

msp_temp

Temperature recorded by the MSP sensor, in degrees C.

cpu_temp

Temperature recorded by the CPU sensor, in degrees C.

crypto_co_proc_temp

Temperature recorded by the cryptographic co-processor sensor, in degrees C.

voltage_t1022_core

Voltage drawn by the T1022 core chip.

voltage_t1022_ifc_io

Voltage drawn by the T1022 IFC I/O chip.

voltage_t1022_serdes

Voltage drawn by the T1022 SERDES chip.

voltage_t1022_serdes_io

Voltage drawn by the T1022 SERDES I/O chip.

voltage_c292_serdes

Voltage drawn by the C292 SERDES chip.

voltage_fpga_serdes

Voltage drawn by the FPGA SERDES chip.

voltage_c292_serdes_io

Voltage drawn by the C292 SERDES I/O chip.

voltage_fpga_serdes_io

Voltage drawn by the FPGA SERDES I/O chip.

voltage_msp_avcc

MSP Analogue Vcc.

voltage_ddr4_io_access

Voltage drawn by the DDR4 I/O access chip.

voltage_ddr4_io

Voltage drawn by the DDR4 I/O chip.

voltage_battery

Voltage supplied by the on-board battery.

voltage_pci_bus

Voltage drawn by the PCI bus.

max_temp

Highest temperature recorded by any temperature sensor since statistics were reset.

min_temp

Lowest temperature recorded by any temperature sensor since statistics were reset.

ais31_preliminary_alarm_count

AIS31 (RNG) preliminary alarm count.

spi_retries

SPI protocol failure count.

sp_i2c_total_failures

MSP430 I2C total failures.

sp_i2c_slave_failures

MSP430 I2C slave failures.

sp_temp_failures

MSP430 temperature failures.

sp_voltage_failures

MSP430 voltage failures.

host_bus_exceptions

PCI0 (Host) NPE and PE error count.

crypto_bus_exceptions

PCI1 (Crypto) NPE error count.

sp_sensor_cmd_failures

Read security processor handshake line failure count.

nvm_free_space

Free space on user NVRAM.

nvm_wear_level

Wear level on user NVRAM.

nvm_worn_blocks

Worn block count on user NVRAM.

bios_code

Not used; always reports 'None'

dfs_throttling

Whether CPU performance is currently degraded due to excessive heat.

 
hsmadmin getenvstats [-h] [--timeout <TIMEOUT>] [--esn <ESN>] [--verbose] [--json]

This command takes the following parameters:

Parameter Description

--timeout

Time to wait for service response, in seconds. Default 30 seconds, minimum 3s, maximum 120s.

--esn

Returns information for the HSM identified by <ESN>.

You need to add --esn before each ESN you include in the command, for example:

>hsmadmin getenvstats --esn 1A23-BC45-6789 --esn 9Z87-YX65-4321

If no ESNs are specified, the command returns the environmental monitoring statistics of all connected modules.

--verbose

Prints verbose logs.

--json

Prints output in JSON format.

hsmadmin cs5

This command is used to manage some aspects of CodeSafe SEE machines running on the HSM.

See also csadmin for additional commands related to managing CodeSafe SEE machines.

hsmadmin cs5 <subcommand>

The following subcommands are only relevant to the nShield 5c. For information on their usage refer to the nShield 5c User Guide

  • clientinfo

  • genclientinfo

  • enroll

  • unenroll

  • list