Administration of platform services (nShield 5 HSMs)

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 protection 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>] [--dry-run] [--force] [--verbose] [--json] <NPKGFILE>

This command takes the following parameters:

Parameter Description

--verbose

Prints verbose logs.

--json

Prints metadata in JSON format.

--dry-run

Don’t load the package, just validate it.

--force

Ignore warnings and force upgrade to proceed.

--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 (nShield 5s HSMs) 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 manages the system logs of connected HSMs. These logs are separate from the ncoreapi logs. See Platform services and (nShield 5 HSMs) for more information about platform services and ncoreapi.

For more information about system logs, see System logging (nShield 5 HSMs).

For more information about managing ncoreapi logs, see Audit Logging.

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.

HSMs running firmware version 13.5 or later can produce logs in either a signed or unsigned format. This subcommand will retrieve unsigned logs. To retrieve logs in a signed format, use the export subcommand. 
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 system log can only be cleared using this command on firmware versions earlier than 13.5. The system log on HSMs running firmware version 13.5 or later is cleared using the expire command. See Logging, debugging, and diagnostics for more information. The init log can be cleared on all firmware versions using this command.

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

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 logs export

This subcommand retrieves and validates signed logs from a connected HSM.

The directory used for storing the log files must exist before running this command. 
hsmadmin logs export [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN>] [--saved] [--expire] [--json | --outdir <OUTDIR>]

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 export logs.

--json

Prints metadata in JSON format.

--outdir

Write logs to directory specified by OUTDIR

--verbose

Prints verbose logs.

--expire

Expire the log after exporting it

--saved

If not expired, re-export a previously saved log

hsmadmin logs expire

This subcommand expires saved system logs from a connected HSM.

hsmadmin logs expire [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN>] --seq <SEQ_NO> [--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 HSM from which to expire logs.

--json

Prints output in JSON format.

--seq

expire the log identified by <SEQ_NO>

--verbose

Prints verbose logs.

hsmadmin logs getkey

This subcommand retrieves the system log signing key from a connected HSM.

hsmadmin logs getkey [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN>] [--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 the log signing key

--json

Prints output in JSON format.

--out

Write key to file specified by <OUTFILE>.

--verbose

Prints verbose logs.

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.

hsmadmin settime

This command is used to synchronize the HSM system clock with the clock in the host PC.

See Setting the system clock for more information on managing the system clock.

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

To use this command without the --adjust parameter, the HSM must be in maintenance mode.

Setting the system date and time without the --adjust parameter automatically resets the HSM. 
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>

You can use the following subcommand with this command:

The following subcommands are only relevant to the nShield 5c. See CodeSafe setup for the nShield 5c for more detail about the subcommands.

  • clientinfo

  • genclientinfo

  • enroll

  • unenroll

  • list

hsmadmin cs5 stats

This subcommand gets statistics from active SEE machines.

hsmadmin cs5 stats [--timeout TIMEOUT] [-u UUID] [--esn ESN] [--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.

--u

UUID of SEE machine from which to obtain statistics.

If no UUID is specified, statistics will be retrieved for all running SEE machines.

--esn

Returns statistics for the HSM identified by <ESN>.

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

--json

Prints output in JSON format.