Utilities command reference
This section provides command reference details for the Unix Installation Utility (safeNet-install.sh), hsmstate, hsmreset, hsmfactoryreset and hsmtrace.
Unix Installation Utility (safeNet-install.sh)
This utility provides a simple menu-driven interface and is used on Unix systems to complete the following tasks:
-
Install packages.
Whenever the utility installs a package, it also installs itself on the host system's hard disk (in /usr/bin/safeNet-install.sh). This copy can be used to uninstall or configure the software.
-
Uninstall packages.
-
List installed packages.
-
List directory contents for the current platform or all platforms.
-
Install a package from the directory.
-
Change the default operating mode (hardware or software-only).
Syntax
safeNet-install.sh [-h] [-p] [-s <size>] [-v]
| Option | Description |
|---|---|
| -h | Show help. |
| -p | Plain mode. In this mode the ‘tput’ is not used for video enhancements. |
| -s<size> | Override the screen size (default = ‘tput lines/cols’ or 24x80). |
| -v | Print the version of this script. |
These options listed in the table above are useful for troubleshooting. To troubleshoot an issue you are experiencing while using the installation utility, refer to ProtectToolkit 7 installation issues.
hsmstate
This utility is installed during the ProtectServer 3 PCIe and ProtectServer 3 External Access Provider installations and is used to display the current status of the HSM(s). By default, it reports all HSMs found in the system. The states reported may include:
HSM in NORMAL MODE.
HSM is responding to tamper.
HSM is initializing performing POST.
Syntax
hsmstate [-d<devicenum>] [-h] [-?] [-v] [-q]
| Option | Description |
|---|---|
| -d<devicenum> | The utility reports only on the present device specified. To list the available devices, run hsmstate without any options included. |
| -h, -? | Show help. |
| -v | Verbose flag. This will display a more detailed report about the HSM. |
| -q | Quick mode. Prints the state of the HSM and then exits (does not send any requests). |
Examples
The command hsmstate will show all devices found in the system. For example:
HSM device 0: HSM in NORMAL MODE. RESPONDING
HSM device 1: HSM in NORMAL MODE. RESPONDING
HSM device 2: HSM in NORMAL MODE. RESPONDING
The command hsmstate -d1 -v will show a report with full details about device 1. For example:
HSM device 1: HSM in NORMAL MODE. RESPONDING to requests.
State = (0x8000, 0x41403)
I2O_INBOARD_MF_OFFSET = 0kb Reserved memory at beginning of PCI Window
I2O_FRAME_LENGTH = 4kb Length of an I2O Message Frame in KiloBytes
I2O_NUM_FRAMES = 20 Number of message frames in one direction
Host Interface version = V0.3
Note
The information presented with the -v option may only be required when contacting technical support.
hsmreset
This utility is installed during the ProtectServer 3 PCIe and ProtectServer 3 External Access Provider installations and is used to clear the HSM of any outstanding requests and prepare it to continue normal operation. It can be used when the HSM is in a normal or halt state.
Syntax
hsmreset [-d<instance>] [-f] [-h] [-?] [-v]
| Option | Description |
|---|---|
| -d<instance> | This option will reset only the device specified. To list the available devices, run hsmstate without any options included. |
| -f | Force an HSM reset without prompting for confirmation. |
| -h, -? | Show help. |
| -v | Verbose flag. This will display a more detailed report about the HSM. |
Example
The command hsmreset will reset the first HSM. Upon execution, the following message displays:
HSM is in normal mode. Resetting it might disturb other applications.
Continue [N/Y]:
Enter Y to complete the operation.
hsmfactoryreset
Note
This utility is only available with ProtectToolkit 7.3.0 or newer.
This utility is installed during the ProtectServer 3 PCIe Access Provider installation and is used to reset the HSM to factory settings by erasing all cryptographic objects, ProtectServer identity keys and certificates, and FMs.
Syntax
hsmfactoryreset [-b] [-h] <device>
| Option | Description |
|---|---|
| -b | Do not display program banner and do not prompt for confirmation. |
| -h | Show help. |
| <device> | HSM index (0-based). |
Example
The command hsmfactoryreset <device> restarts the HSM while erasing all cryptographic objects, ProtectServer identity keys and certificates, and FMs.
PTK K7 Factory Reset tool Copyright (c) Safenet, Inc. 2009-2022 Ver 7.3.0
Warning: This command will Factory Reset the HSM.
All user keys, Identity Keys/Certs, FM Images and SMFS will be erased.
Continue [y/N]:
Enter y to complete the operation.
hsmtrace
This utility is installed during the ProtectServer 3 PCIe Access Provider installation. hsmtrace is a useful tool for functionality module (FM) developers that need to view debug messages from an FM during development, and for general troubleshooting.
Syntax
hsmtrace
