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 platform services are administered through a unified utility called hsmadmin.

hsmadmin

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

hsmadmin <subcommand> [-h] [-v] [--no-reset]

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

You can use the following options with hsmadmin:

  • Reset options:

    • --no-reset: Does not trigger an immediate reset of any HSM. If a reset is required you must reboot the host system.

  • Help options:

    • -h, --help: Displays help for hsmadmin.

    • -v, --version: Displays the version number of the Security World Software

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.

--all

Resets all modules without prompting for confirmation.

--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. The command will prompt you to confirm this action unless the --all parameter is specified.

--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 installs firmware packages in npkg format. The command can install both primary and recovery firmware.

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

Before running this command, place the module to be upgraded in maintenance mode using nopclearfail -M -m <MODULEID> -w. This requirement can be overridden by using the --force option.

In a multi-tenant system all VCMs running on the HSM to be upgraded must be stopped for this command to succeed. This cannot be overridden using the --force option.

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.

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. A warning about this restriction to the local machine will be printed if the --passphrase option is omitted (add --local to indicate that this is the explicit choice in order to prevent the warning).

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 (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

CodeSafe 5 is not supported in multi-tenant systems (v14.1 firmware).

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.

hsmadmin select

This command is used to select configuration options that are not controlled by licenses.

This command can only be used when the unit is in maintenance mode. It requires root privileges on Linux and the privileges of the built-in local Administrators group on Windows.

hsmadmin select <option> [--esn ESN] [--json] [--timeout]

All select <option> commands support the following parameters:

Parameter Description

--esn

Select this option on the HSM identified by <ESN>.

If no ESNs are specified, the selection is applied to all connected modules.

--json

Prints output in JSON format.

You can use the following options with this command:

--timeout

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

hsmadmin select acceleration

This option selects which algorithms will be accelerated.

hsmadmin select acceleration [--set ID | --show]

This option takes the following parameters:

Parameter Description

--set

Set the accelerator to use.

The module must be reset for the change to take effect.

--show

Show the available, and the currently selected accelerators.

hsmadmin vcm

This command allows the tenants to manage their VCMs.

hsmadmin vcm <subcommand>

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

hsmadmin vcm create

This subcommand generates a request to create a VCM. The request will be written to the file specified in the command. This file should be sent to your service provider.

The file is signed by a signing key unique to you. This key is automatically generated when you create your first request and will then be used for all subsequent requests. 
hsmadmin vcm create [-h] [--verbose] --request-file <REQUEST_FILE> [--request-validity <REQUEST_VALIDITY>] [--restrict-startup | --autostart] [--serial-cardreader] [--features] [--name <NAME>]

This subcommand takes the following parameters:

Parameter Description

--request-file

Specifies the name of the file to which the creation request will be written

--verbose

Prints verbose logs.

--request-validity

The time period in seconds for which the request is valid

--restrict-startup

If this option is chosen, the service provider will be unable to start the VCM without a valid start request

--autostart

A VCM with this option will automatically start after a reboot of the HSM on which it is hosted. The service provider may choose to ignore this request when creating the VCM if, for example, more tenants request this option than the service provider has a license for.

--serial-cardreader

A VCM with this option will have access to the serial card reader attached to the HSM. Only one VCM can have access to the card reader at any one time so the service provider may choose to ignore this request.

--features

The ncoreapi features you would like your VCM to have, expressed as a 32 bit hexadecimal word. The service provider may choose to provision a different set of features

--name

The name you would like the VCM to have. This name is only visible to the service provider so this option is mainly for use where the service provider is part of your own organisation

hsmadmin vcm start

This subcommand generates an authorization to start a VCM. This is needed if the VCM was created with the --restrict-startup option. The subcommand will write the authorization to a file specified in the command. This file must be sent to the service provider. There is an option to specify the validity period for the authorization and if this is selected the service provider must action the request before the end of the validity period and if not a new authorization must be generated.

hsmadmin vcm start [-h] --request-file <REQUEST_FILE> [--request-validity <REQUEST_VALIDITY>] [--uuid <UUID>]

This subcommand takes the following parameters:

Parameter Description

--request-file

Specifies the name of the file to which the start authorization will be written

--request-validity

The time period in seconds for which the authorization is valid

--uuid

The UUID of the VCM for which the request is valid. A VCMs UUID is contained in the configuration file that was received from the service provider when the VCM was created and can also be seen in the enquiry command as part of the device name.

hsmadmin vcm enroll

This subcommand enrolls a VCM using the configuration file received from the service provider.

hsmadmin vcm enroll [-h] [--verbose] --config <CONFIG_FILE> [--no-service-restart]

This subcommand takes the following parameters:

Parameter Description

--config

Specifies the configuration file that was received from the service provider

--no-service-restart

If this option is specified the hardserver and other services will not be restarted during enrollment

--verbose

Prints verbose logs.

hsmadmin vcm unenroll

This subcommand removes details of an enrolled VCM from the host file system.

hsmadmin vcm unenroll [-h] [--no-service-restart] [--verbose] uuid

This subcommand takes the following parameters:

Parameter Description

uuid

Specifies the uuid of the VCM to unenroll

--no-service-restart

If this option is specified the hardserver and other services will not be restarted during enrollment

--verbose

Prints verbose logs.

hsmadmin vcm setproperties

This subcommand generates a request to change the properties of a VCM. The request is written to a file specified in the command and should be sent to the service provider. There is an option to specify the validity period for the request and if this is selected the service provider must action the request before the end of the validity period and if not a new request must be generated.

hsmadmin vcm setproperties [-h] --request-file <REQUEST_FILE> [--request-validity <REQUEST_VALIDITY>] [--uuid <UUID>] [--restrict-startup | --no-restrict-startup] [--autostart | --no-autostart] [--serial-cardreader | --no-serial-cardreader] [--features <FEATURES>] [--name <NAME>]

This subcommand takes the following parameters:

Parameter Description

--request-file

Specifies the name of the file to which the request will be written

--request-validity

The time period in seconds for which the request is valid

--uuid

The UUID of the VCM for which the request is valid. A VCMs UUID is contained in the configuration file that was received from the service provider when the VCM was created and can also be seen in the enquiry command as part of the device name.

--restrict-startup

Enable the restrict-startup property

--no-restrict-startup

Disable the restrict-startup property

--autostart

Enable the autostart property

--no-autostart

Disable the autostart property

--serial-cardreader

Enable the serial-cardreader property

--no-serial-cardreader

Disable the serial-cardreader property

--features

Modify the VCM features. The new value is expressed as a 32 bit hexadecimal word.

--name

Modify the VCM name

hsmadmin vcm inspect-request

This subcommand displays the contents of a request or authorization file.

hsmadmin vcm inspect-request [--verify] [--key-file <KEY_FILE>] <REQUEST_FILE>

This subcommand takes the following parameters:

Parameter Description

--verify

Verify the request signature

--key-file

The public key file for verifying the request signature

hsmadmin vcm info

This subcommand retrieves information about the HSM on which the VCM is hosted.

hsmadmin vcm info [-h] [--timeout <TIMEOUT>] [--uuid <UUID>] [--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.

--uuid

Specifies the UUID of the VCM to retrieve info for. If omitted, information will be retrieved for all enrolled VCMs.

--json

Prints output in JSON format.

hsmadmin vcm getenvstats

This subcommand retrieves some statistics for a VCM, including the system time.

Times are reported in seconds using 'Unix time', also known as 'Epoch time'. There are readily available converters that can convert Unix time to other time formats.

hsmadmin vcm getenvstats [-h] [--verbose] [--timeout <TIMEOUT>] [--uuid <UUID>] [--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.

--uuid

Specifies the UUID of the VCM from which to retrieve statistics.

--json

Prints output in JSON format.

--verbose

Prints verbose logs.

hsmadmin vcm single-setup

This subcommand will automatically create, start and enroll a single VCM hosted on the same machine as the HSM host.

hsmadmin vcm single-setup [-h] [--verbose] [--timeout <TIMEOUT>] [--esn <ESN>] [--json] [--name <NAME>]

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 on which to create the VCM

--json

Prints output in JSON format.

--name

The name of the VCM which will be created

--verbose

Prints verbose logs.

hsmadmin vcm logs

This command manages the VCM system logs.

hsmadmin vcm logs <subcommand>

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

hsmadmin vcm logs export

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

The directory used for storing the log files must exist before running this command. 
hsmadmin vcm logs export [-h] [--verbose] [--timeout <TIMEOUT>] --uuid <UUID> [--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.

--uuid

Specifies the uuid of the VCM 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 vcm logs expire

This subcommand expires saved system logs from a connected VCM.

hsmadmin vcm logs expire [-h] [--verbose] [--timeout <TIMEOUT>] --uuid <UUID> --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 uuid of the VCM from which to expire logs.

--json

Prints output in JSON format.

--seq

Expire the log identified by <SEQ_NO>

--verbose

Prints verbose logs.

hsmadmin vcm logs getkey

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

hsmadmin vcm logs getkey [-h] [--verbose] [--timeout <TIMEOUT>] --uuid <UUID> [--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 uuid of the VCM 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 fet

This subcommand applies a feature licence to the HSM.

hsmadmin fet [--timeout TIMEOUT] [--verbose] [--esn ESN] [--json] <FILENAME>

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

ESN of the HSM on which to apply the license

This must match the ESN contained in the license.

--json

Prints output in JSON format.

FILENAME

Certificate file containing licence to be applied

hsmadmin setnetwork

This command allows you to specify the subnetwork for this HSM on which VCMs will be created.

After applying this command, you must reset your HSM using hsadmin reset for the settings to take effect. 
hsmadmin setnetwork <subcommand>

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

hsmadmin setnetwork default

This subcommand sets the network to use IPv6 link local addresses, which is the default setting. The main use of this is where all tenants are on the same machine as the HSM. For example when the HSM is used for single tenant operation or if multiple tenants are hosted in containers on the same machine.

hsmadmin setnetwork default [-h]

This subcommand takes no parameters.

hsmadmin vcm setnetwork ipv4static

This subcommand sets the IPv4 subnetwork on which VCMs will be created.

hsmadmin setnetwork ipv4static --address <ADDRESS> --gateway <GATEWAY>

This subcommand takes the following parameters:

Parameter Description

address

IPv4 address and network mask in CIDR format

gateway

IPv4 address of network gateway

hsmadmin vcm setnetwork ipv6static

This subcommand sets the IPv6 subnetwork on which VCMs will be created.

hsmadmin setnetwork ipv6static --address <ADDRESS> --gateway <GATEWAY>

This subcommand takes the following parameters:

Parameter Description

address

IPv6 address and network mask in CIDR format

gateway

IPv6 address of network gateway