Supplied utilities

This appendix describes the executable command-line utilities (utilities) that you can use for performing various configuration and administrative tasks related to your module.

These utilities exist in the bin subdirectory of your Security World Software installation. Unless noted, all utilities have the following standard help options:

  • -h|--help displays help for the utility.

  • -v|--version displays the version number of the utility.

  • -u|--usage displays a brief usage summary for the utility.

Utilities for general operations

Use the utilities described in this section to:

  • Check the module configuration and verify that it functions as expected.

  • Obtain statistics for checking the performance of the module.

enquiry

Obtain information about the hardserver (Security World Software server) and the modules connected to it.

  • Check if the software has been installed correctly

  • Check the firmware version

  • Check if the Remote Operator feature is enabled

  • Check if the Serial Console feature is available

  • Check the hardware status of internal security modules

See Testing the installation for more information.

checkmod

Check modulo exponentiations performed on the module against the test data located in opt/nfast/testdata (Linux) or %NFAST_HOME%\testdata (Windows).

cfg-mkdefault

Create a default client configuration file for the hardserver configuration sections.

cfg-reread

Load the hardserver configuration from the configuration file.

fet

  • Activate features

  • View the status of features

  • Verify that a feature has been successfully enabled on a connected module

To view the status of features, run the tool without a smart card. If a FEM card is not present, or if any of the features are not enabled successfully, the utility prompts you to indicate what to do next.

To enable features, and view the status of or verify features on an nShield HSM, use the front panel rather than the fet utility.

For more information, see Enabling optional features

ncdate

View, set, and update the time on a module’s real-time clock.

ncversions

Obtain and verify the versions of the Security World Software components that are installed. This utility lists the following information:

  • Versions of all components, irrespective of whether they are installed individually or as part of a component bundle

  • Version of each component bundle

nfdiag

Obtain information about the module and the host on which it is installed. This diagnostic utility can save information to either a ZIP file or a text file.

For more information, see nfdiag: diagnostics utility.

Run this utility only if requested to do so by Support.

nopclearfail

Clear an HSM, put an HSM into the error state, retry a failed HSM, or change the HSM mode.

You must use a privileged connection to use this utility with the following parameters:

  • change the mode of the HSM (nopclearfail -I/M/O)

  • Clear the module (nopclearfail -c)

nvram-backup

Copy files between a module’s NVRAM and a smart card, allowing files to be backed up and restored.

nvram-sw

View and modify information about NVRAM areas.

pubkey-find

Obtain information of the public key from a certificate or certificate request (in a Base-64 encoded PEM file).

randchk

Run a universal statistical test on random numbers returned by the module.

rtc

View and set the module’s real-time clock.

By default, rtc reads the real-time clock of module 1.

  • --adjust: The module uses the difference between its idea of the current time and the new time, together with how long it’s been since the clock was last set, to compute how much its clock is drifting.

  • --set-clock: The module’s clock is set to either TIME, if it is provided as a list of six integers separated by non-digit characters, or to the host’s current time.

slotinfo

  • Obtain information about tokens in a module

  • Format a smart card

snmpbulkwalk snmpget snmpgetnext snmptable snmpset snmptest snmptranslate snmpwalk

Obtain system, module, connection and software information from the SNMP agent.

For more information, see Using the SNMP command-line utilities.

stattree

Obtain statistics gathered by the Security World Software server and modules.

For more information, see stattree: information utility.

Linux

Archive the existing hardserver log from /opt/nfast/log/hardserver.log and re-open as a fresh log file.

When run with no arguments, it will automatically archive the existing log to /opt/nfast/log/archive/hardserver.DATETIME.log (where DATETIME is the current date and time). The directory /opt/nfast/log/archive/ is created if it does not already exist.

Optionally, a single argument can be provided with the full file name to archive the existing hardserver log to.

This script must be run as root.

Windows

Extract Windows event log entries and output them to the console or a text file.

As required, specify:

  • -s \| --source: The event log source. The default is the nCipherlog

  • -c \| --count: The number of records read from the event log. The default is 10000

  • -f \| --file: The output filename.

Hardware utilities

Use the following utilities to manage the firmware installed on an nShield HSM.

fwcheck

Verify the firmware installed on a module.

nfloadmon

Upgrade the module monitor and firmware of nShield PCIe and network-attached HSMs.

Test analysis tools

Use the following utilities to test the cryptographic operational behavior of a module.

All the listed utilities, except the floodtest utility, are supported only on FIPS 140 Level 2 Security Worlds.
Utility Enables you to…​

cryptest

Test all defined symmetric cryptographic mechanisms.

des_kat

Perform DES known-answer tests. This utility indicates if any of them fail.

floodtest

Perform hardware speed-testing by using modular exponentiation.

kptest

Test the consistency of encryption and decryption, or of signature and verification, with the RSA and DSA algorithms.

ncthread-test

Stress test modules and test nCore API concurrent connection support.

perfcheck

Run various tests to measure the cryptographic performance of a module. For more information, see perfcheck: performance measurement checking tool.

sigtest

Measure module speed using RSA or DSA signatures or signature verifications.

ncperftest

Test the performance of various crypto commands using attached nShield hardware. Available since v12.10 it contains all the functionality in sigtest and floodtest as well as several new features and greater accuracy and throughput capability in performance management.

Security World utilities

Use the utilities described in this section to:

  • Set up and manage Security Worlds.

  • Create and manage card sets and passphrases.

  • Generate keys and transfer keys between Security Worlds.

Utility Enables you to…​

bulkerase

Erase multiple smart cards including Administrator Cards, Operator Cards, and FEM activation cards, in the same session.

Do not use the bulkerase utility to erase Administrator Cards from the current Security World.

cardpp

Change, verify, and recover a passphrase of an Operator Card. For more information, see:

createocs

Create and erase an OCS. For more information, see:

initunit

Initialize an nShield module.

For more information, see Erasing a module with initunit.

generatekey

Generate, import, or retarget keys. This utility is included in the Core Tools bundle, which contains all the Security World Software utilities. For more information, see:

kmfile-dump

Obtain key management information from a Security World’s key management data file.

migrate-world

Migrate existing keys to a destination Security World. For more information, see Security World migration.

mkaclx

Generate non-standard cryptographic keys that can be used to perform specific functions, for example, to wrap keys and derive mechanisms. This utility includes options that are not available with the generate-key utility.

Ensure that you run the mkaclx utility with the options that are appropriate for your security infrastructure. If the appropriate options are not chosen, the security of existing keys might potentially be compromised.

new-world

Create and manage Security Worlds on nShield modules.

You must use a privileged connection to use this utility with the following parameter:

  • Initialize the HSM (new-world -e/i/l)

nfkmcheck

Check Security World data for consistency.

nfkminfo

Obtain information about a Security World and its associated cards and keys. For more information, see:

nfkmverify

Perform Security World verification.

For more information, see Verifying Key Generation Certificates with nfkmverify.

postrocs

Transfer PKCS #11 keys to a new card set in the new Security World. When transferring keys by using either the key-xfer-im utility or the migrate-world utility, run the postrocs utility if there are any PKCS #11 keys that are protected by OCSs.

PKCS #11 keys either have keys_pkcs_um or key_pkcs_uc as the prefix.

ppmk

  • Create and manage softcards. Use this utility to:

  • View details of a softcard

  • Create and delete a softcard

  • View, change, and recover the passphrase of a softcard

For more information, see:

preload

Load keys into a module before an application is run in another session.

racs

Create a new ACS to replace an existing ACS.

For more information, see Replacing an Administrator Card Set using racs.

rocs

  • Restore an OCS from a quorum of its cards

  • Restore softcards

For more information, see:

CodeSafe utilities

Use the following helper utilities to develop and sign SEE machines. For more information about these utilities, see the CodeSafe Developer Guide.

Utility Enables you to…​

elftool

Convert ELF format executables into a format suitable for loading as an SEE machine.

hsc_loadseemachine

Load an SEE machine into each module that is configured to receive one, then publishes a newly created SEE World, if appropriate.

loadsee-setup

Set up the configuration of auto-loaded SEE machines.

modstate

View the signed module state.

see-sock-serv

see-stdioe-serv

see-stdioesock-serv

see-stdoe-serv

Activate or enable standard IO and socket connections for SEE machines using the bsdlib architecture.

tct2 (Trusted Code Tool)

Sign, pack, and encrypt file archives so that they can be loaded onto an SEE-ready nShield module.

PKCS #11

Do not use PKCS #11 to perform any task that requires an Administrator Card. Use the equivalent nShield utilities instead.

Use the following utilities to manage the interfaces between the PKCS #11 library and the module.

Utility Enables you to…​

ckcerttool

Import a certificate as a PKCS #11 CKO_CERTIFICATE object of type CKC_X_509, and optionally, associate it with the corresponding private key.

ckcheckinst

Verify the installation of the nShield PKCS #11 libraries. For more information, see Checking the installation of the nCipher PKCS #11 library.

ckimportbackend

Generate keys for use with PKCS #11 applications. When you run the generatekey utility to generate PKCS #11 keys, the ckimportbackend utility is executed in the background.

Do not run this utility unless directed to do so by Support.

cknfkmid

View values of attributes of PKCS #11 objects.

ckshahmac

Perform a PKCS #11 test for vendor-defined SHA1_HMAC key signing and verification capabilities.

cksigtest

Measure module signing or encryption speed when used with nShield PKCS #11 library calls.

The Security World software enables you to use the following additional PKCS #11 utilities. For more information about these utilities, see the Cryptographic API Integration Guide.

Utility Enables you to…​

ckinfo

View PKCS #11 library, slot, and token information. Use this utility to verify that the library is functioning correctly.

cklist

View details of objects on all slots. If invoked with a PIN argument, the utility lists public and private objects. If invoked with the -n (--nopin) option, the utility lists only the public objects.

This utility does not output any potentially sensitive attributes, even if the object has CKA_SENSITIVE set to FALSE.

ckmechinfo

View details of the supported PKCS #11 mechanisms provided by the module.

ckrsagen

Test RSA key generation. You can use specific PKCS #11 attributes for generating RSA keys.

cksotool

Create a PKCS #11 Security Officer role, and manage its PIN.

Utilities for network-attached HSMs

The utilities described in this section are used with nShield network-attached HSMs only. Use these utilities to:

  • Create and manage client configuration files.

  • Enroll nTokens with an nShield HSM.

  • Set up a Remote File System (RFS) and synchronize Security World data between an nShield HSM and the RFS.

  • Administer an nShield HSM without using the front panel

  • Configure NTP.

Utility Enables you to…​

anonkneti

View the ESN and HKNETI key hash from a module identified by its IP address.

For more information, see Configuring the remote file system (RFS).

cfg-pushnethsm

Copy a specified configuration file from a remote file system to the file system on a specified module.

Some changes propagated with cfg-pushnethsm need further actions. For example, you have to clear the module after changing the dynamic slot configuration. For more information, see:

cfg-pushntp

Configure time synchronisation on the nShield HSM, using NTP.

For more information, see Configuring NTP in the nShield HSM.

config-serverstartup

Edit the [server_startup] section of the configuration file for the client’s hardserver to enable or disable TCP sockets.

For more information, see:

nethsmadmin

Administer an nShield HSM without using the front panel. Options include:

  • Check the Security World files on a specified nShield HSM.

  • Copy Security World files from the RFS to the nShield HSM.

  • Command the specified nShield HSM to reboot. This restarts the hardserver.

  • Command the nShield HSM to upgrade using the specified image file from its RFS.

  • Retrieve a list of image files available on the RFS.

  • Retrieve a list of feature certificates available on the RFS for a specified nShield HSM.

  • Command the nShield HSM to apply a specified feature certificate from the RFS.

  • Erase the Security World on the nShield HSM and re-initialize the HSM.

  • Get the date and time on the nShield HSM.

  • Set the date and time on the nShield HSM.

  • Enable dynamic features, including client licenses remotely.

You must use a privileged connection to use this utility with the following parameters:

  • Reboot the HSM (nethsmadmin -r)

  • Erase the Security World (nethsmadmin -e)

  • Upgrade the HSM firmware (nethsmadmin -i)

For more information, see:

nethsmenroll

Edit the local hardserver configuration file to add the specified nShield HSM unit. As an alternative to hand-editing a client’s configuration file, you can run this utility on a client to configure it to access an nShield HSM. For example:

  • Enroll an HSM, without needing to restart the hardserver

  • Unenroll an HSM (nethsmenroll -r), then restart the hardserver to update the information about the HSM estate

For more information, see:

ntokenenroll

Enroll a locally attached nToken with an nShield HSM. This utility installs the Electronic Serial Number (ESN) of the nToken within the client configuration file and displays the module’s ESN and the hash of the key to be used in nToken authentication.

For more information, see Configuring the unit to use the client.

rfs-setup

Create a default RFS hardserver configuration. Run this utility when you first configure the RFS.

For more information, see:

rfs-sync

Synchronize the Security World data between a cooperating client and the RFS. This utility is run on the client.

For more information, see:

You can use this utility with nShield modules if an nShield HSM is present.

MSCAPI utilities (Windows)

Use the following utilities to migrate from Windows registry-based CSP container storage to the new CSP formats. These utilities also enable you to manage the interfaces between the MSCAPI library and the module.

For more information about these utilities, see Utilities for the CAPI CSP.

Utility names that end with 64 run only on 64-bit version of Microsoft Windows. All other utilities run on both 32-bit and 64-bit versions of Microsoft Windows.
Utility Enables you to…​

cspcheck

cspcheck64

Check that CSP container files and keys in the %NFAST_KMDATA% directory are intact and uncorrupted and that the referenced key files exist.

cspimport

cspimport64

Insert keys manually into existing CSP containers.

For more information, see Installing the CAPI CSP.

cspmigrate

cspmigrate64

Move CSP container information for an existing Security World from the registry into the Security World.

cspnvfix

cspnvfix64

Regenerate the NVRAM key counter area for a specified nShield CSP key.

csptest

csptest64

Test the installed Cryptographic Service Providers.

csputils

csputils64

Obtain detailed information about CSP containers.

You must have Administrator privileges to view or delete machine containers or containers that belong to other users.

keytst

keytst64

Create, test, and display information about keys and CSP key containers.

configure-csp-poolmode

configure-csp-poolmode64

Configure HSM Pool mode for the nShield CAPI CSP.

CNG (Windows)

Use the following helper utilities to manage keys and the interfaces between the CNG library and the HSM. For a list of utilities specific to the nShield CNG CSP, see Utilities for the CAPI CSP.

Utility names that end with 64 run only on 64-bit version of Microsoft Windows. All other utilities run on both 32-bit and 64-bit versions of Microsoft Windows.
Utility Enables you to…​

cngimport

Migrate Security World, CAPI and CNG keys to the Security World Key Storage Provider.

For more information, see:

cnginstall32

cnginstall

(nShield CNG provider installer utility)

Remove or reinstall the provider DLLs and associated registry entries manually.

For more information, see cnginstall.

cnglist32

cnglist

View information about CNG providers.

For more information, see:

cngregister (nShield CNG provider registration utility)

Unregister and re-register the nShield providers manually.

For more information, see:

cngsoak

cngsoak64

(nShield CNG soak tool)

Evaluate the performance of signing, key exchange, and key generation by using a user-defined number of threads.

For more information, see cngsoak.

ncsvcdep (nShield Service dependency tool)

Configure service-based applications such as Microsoft Certificate Services and IIS to use the nShield CNG CSP. Use this tool to add the nFast Server to the dependency list of such services.

For more information, see:

configure-csp-poolmode

configure-csp-poolmode64

Configure HSM Pool mode for the nShield CNG CSP. For more information, see configure-csp-poolmode.

Developer-specific utilities

Use the following utilities to ensure that the HSMs are functioning as expected and to test the cryptographic functionality at the nCore level.

Utility Enables you to…​

pollbare

Obtain information about state changes. The functionality of this test utility depends on whether the server or an HSM supports nCore API poll commands.

To know if your server or HSM supports nCore API poll commands, run the enquiry utility.

trial

Test the nCore API commands. You can use this utility interactively or from a script file.

Utilities that require a privileged connection

You must be a privileged user, that is, use a privileged connection to the HSM, to run certain utilities with certain parameters.

Utility Use case

nopclearfail -I/M/O

Change the mode of the HSM

nopclearfail -c

Clear the module

nethsmadmin -r

Reboot the HSM

nethsmadmin -e

Erase the Security World

nethsmadmin -i

Upgrade the HSM firmware

new-world -e/i/l

Initialize the HSM