nShield v13.6.5 HSM User Guide
Introduction
The nShield HSM User Guide provides useful information about your nShield HSMs. You should consult it before and while using a new HSM.
It contains a section for each type of HSM (network-attached, PCIe, and USB). There is also a section that contains information that applies to all types of HSM.
Read this guide if …
Read this guide if you need to configure or manage an Entrust Hardware Security Module (HSM).
nShield hardware security modules use the Security World paradigm to provide a secure environment for all your HSM and key management operations. Guides are also available to help with the following tasks:
nShield network-attached HSMs are connected to a network by an Ethernet connection. Each network-attached HSM is configured to communicate with one or more client computers on the network. You can also configure clients to make use of any other network-connected HSMs on the network, as well as locally connected HSMs.
All nShield HSMs support standard cryptography frameworks and integrate with many standards based products.
This guide assumes that:
-
You are familiar with the basic concepts of cryptography and Public Key Infrastructure (PKI)
-
You have read the relevant Security world and HSM documentation.
-
You have installed your nShield HSM.
Terminology
Some information only applies to a specific HSM or HSM type. Where this is the case, the relevant HSM or HSM type is mentioned by name, otherwise the terms nShield "HSM", "hardware security module", or "module" are used interchangeably.
nShield HSMs | nShield HSM type |
---|---|
Connect, Connect +, Connect XC, 5c |
Network-attached HSMs |
Solo, Solo +, Solo XC, 5s |
PCIe HSMs |
Edge |
USB-attached HSMs |
Model numbers
Details
Model numbering conventions are used to distinguish different nShield hardware security devices.
Model number | Used for |
---|---|
NH2047 |
nShield Connect 6000 |
NH2040 |
nShield Connect 1500 |
NH2033 |
nShield Connect 500 |
NH2068 |
nShield Connect 6000+ |
NH2061 |
nShield Connect 1500+ |
NH2054 |
nShield Connect 500+ |
NH2075-B |
nShield Connect XC Base |
NH2075-M |
nShield Connect XC Medium |
NH2075-H |
nShield Connect XC High |
NH2082 |
nShield Connect XC SCAP |
NH2089-B |
nShield Connect XC Base - Serial Console |
NH2089-M |
nShield Connect XC Mid - Serial Console |
NH2089-H |
nShield Connect XC High - Serial Console |
NH3003-B |
nShield Connect CLX Base - Serial Console |
NH3003-M |
nShield Connect CLX Mid - Serial Console |
NH3003-H |
nShield Connect CLX High - Serial Console |
NH2096-B |
nShield 5c Base |
NH2096-M |
nShield 5c Medium |
NH2096-H |
nShield 5c High |
nC3nnnE-nnn, nC4nnnE-nnn |
nShield Solo PCIe |
nC30n5E-nnn, nC40n5E-nnn |
nShield Solo XC PCIe |
NC5536E-B |
nShield 5s Base |
NC5536E-M |
nShield 5s Medium |
NC5536E-H |
nShield 5s High |
nC30nnU-10, nC40nnU-10 |
nShield Edge |
Security World Software
PCIe and USB HSMS The hardserver software controls communication between applications and Entrust nShield product line HSMs, which may be installed locally or remotely. It runs as a daemon (Linux) or a service (Windows) on the host computer. |
The Security World for nShield is a collection of programs and utilities, including the hardserver, supplied by Entrust to install and maintain your nShield security system. The Security World Software includes the following:
-
The appropriate installer for the client platform
-
The client hardserver
-
A set of utilities for configuring the nShield HSM
-
A set of utilities and the KeySafe application for performing key management tasks on nShield HSMs.
Entrust provides the firmware that runs on the nShield HSM, and software to run on each client computer. The nShield HSM is supplied with the latest version of the HSM firmware installed. For more information about:
-
Upgrading the firmware, see
-
Upgrade firmware: nShield Solo, Solo XC, and Edge HSMs (Solo and Edge models).
-
Upgrade firmware: nShield 5s nShield 5s.
-
Upgrading the image file and associated firmware: network-attached HSMs (network-attached HSMs).
-
-
Installing and configuring the software on each client computer, see nShield Security World Software v13.6.5 Installation Guide and Client software and module configuration: PCIe and USB HSMs (PCIe and USB HSMs) or Client software and module configuration: network-attached HSMs (network-attached HSMs).
-
The supplied utilities, see nShield v13.6.5 Utilities Reference.
-
Maintenance of your nShield hardware, see Maintenance of nShield Hardware.
Software architecture
The software, firmware, and utilities have version numbers and there is also a version number for the World which refers to the World data that is stored in encrypted form on the client computer, typically in the opt/nfast/kmdata
(Linux) or C:\ProgramData\nCipher\Key Management Data
(Windows) directory or on the RFS.
This data includes information concerning the World itself and also concerning each key that was created within that World.
The World version created is determined by the version numbers of the software and firmware used when it was first created, see nShield Security World v13.6.5 Management Guide.
The latest World version is version 3.
You can query the version of the World loaded on your system by using the command kmfile-dump
.
Hardserver (network-attached HSMs)
The hardserver software controls communication between the internal security module and applications on the network.
Separate instances of the hardserver run on the unit and each client that is configured to work with the unit. There is a secure channel, known as the impath, between the two software instances, which forms a single secure entity for transferring data between the unit and the clients. See also Compatibility issues.
The unit’s hardserver is configured using the front panel on the unit, or by means of uploaded configuration data. Configuration data is stored on the unit and in files in a specially configured file system on each client computer. For more information about using:
-
The front panel to configure the unit, see Front panel controls
-
The specially configured file system to configure the unit and the client, see Client software and module configuration: network-attached HSMs.
Remote file system (RFS) (network-attached HSMs)
Each unit uses a remote file system (RFS). You can configure the RFS on any computer, but it is normally located on the first client that is configured. The RFS contains:
-
The master configuration information for the unit
-
The Security World files
-
The key data.
Do not copy the master configuration to file systems on other clients. You can copy Security World files and key data to other clients to allow you to manage the unit from more than one client. To make it available to the unit, copy to the RFS the data for Security Worlds, cards or keys that you create on a client that does not contain the RFS.
Default directories
The default locations for Security World Software and program data directories on English-language systems are summarized in the following table:
Directory name | Default path (Linux) | Environment variable (Windows) | Default path (Windows) |
---|---|---|---|
nShield Installation |
|
|
|
Key Management Data |
|
|
|
Dynamic Feature Certificates |
|
|
|
Static Feature Certificates |
|
|
|
Log Files |
|
|
|
User Log Files |
|
|
|
Remote Static Feature Certificates |
|
|
|
Remote Dynamic Feature Certificates |
|
|
By default, the Windows C:\ProgramData\ directory is a hidden directory.
To see this directory and its contents, you must enable the display of hidden files and directories in the View settings of the Folder Options.
|
Dynamic feature certificates must be stored in the directory stated above. The directory shown for static feature certificates is an example location. You can store those certificates in any directory and provide the appropriate path when using the Feature Enable Tool. However, you must not store static feature certificates in the dynamic features certificates directory. |
On Windows, the absolute paths to the Security World Software installation directory and program data directories are stored in the indicated nShield environment variables at the time of installation. If you are unsure of the location of any of these directories, check the path set in the environment variable.
The instructions in this guide refer to the locations of the software installation and program data directories as follows:
-
By name (for example, Key Management Data).
-
Linux: By absolute path (for example,
/opt/nfast/kmdata
). -
Windows: By nShield environment variable names enclosed with percent signs (for example,
%NFAST_KMDATA%
).
If the software has been installed into a non-default location:
-
Linux: Create a symbolic link from
/opt/nfast/
to the directory where the software is actually installed. -
Windows: Ensure that the associated nShield environment variables are re-set with the correct paths for your installation. For more information about creating symbolic links, see your operating system’s documentation.
Utility help options
Unless noted, all the executable utilities provided in the bin
subdirectory of your nShield installation 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.
Setting the PATH for nShield utilities
It is recommended that the PATH environment variable be changed to include opt/nfast/bin
(Linux) or <%NFAST_HOME%\bin>
, which is usually C:\Program Files\nCipher\nfast\bin
(Windows).
This is the directory in the nShield installation that contains the nShield command-line utilities and some DLLs.
This will allow all the nShield command-line utilities to be run without the need to type the full path, for example running enquiry
instead of opt/nfast/bin/enquiry>
(Linux) or <%NFAST_HOME%\bin\enquiry>
(Windows).
opt/nfast/bin
(Linux) or <%NFAST_HOME%\bin>
(Windows) must be set in the PATH in order to use the OpenSSL module in the Python that is bundled with nShield.
The Python bundled with nShield is located in opt/nfast/python3/bin
(Linux) or %NFAST_HOME\python3\bin
, which is usually C:\Program Files\nCipher\nfast\python3\bin
(Windows).
If using the nShield Python, you may additionally want to add this directory to the PATH environment variable so that you can run the nShield python as just the python command.
You may not want to do this if you are also using other Python installations on the same machine.
Further information
This guide forms one part of the information and support provided by Entrust.
If you have installed the Java Developer component, the Java Generic Stub classes, nCipherKM JCA/JCE provider classes, and Java Key Management classes are supplied with HTML documentation in standard Javadoc
format, which is installed in the appropriate nfast/java
directory when you install these classes.
Security advisories
If Entrust becomes aware of a security issue affecting nShield HSMs, Entrust will publish a security advisory to customers. The security advisory will describe the issue and provide recommended actions. In some circumstances the advisory may recommend you upgrade the nShield firmware and or image file. In this situation you will need to re-present a quorum of administrator smart cards to the HSM to reload a Security World. As such, deployment and maintenance of your HSMs should consider the procedures and actions required to upgrade devices in the field.
The Remote Administration feature supports remote firmware upgrade of nShield HSMs, and remote ACS card presentation. |
We recommend that you monitor the Announcements & Security Notices section on Entrust nShield, https://nshieldsupport.entrust.com, where any announcement of nShield Security Advisories will be made.