Client Software and module configuration
This chapter describes how to configure the internal security module of the nShield HSM and the client to communicate with each other, after you have installed the HSM and the Security World Software.
For more information about installing the HSM, see the Installation Guide. If you are configuring an HSM and client for the first time, or you want to complete a basic installation quickly, see the Installation Guide.
The nShield HSM provides significant performance improvements, and can be deployed successfully with existing nShield products. Customers wishing to take advantage of these performance improvements must update their client machines with the latest Security World Software. |
About user privileges
Cryptographic security does not depend on controlling user privileges or access but maintaining the integrity of your system from both deliberate or accidental acts can be enhanced by appropriate use of (OS) user privileges.
There are two levels of user in Windows:
-
Administrator access
-
Normal
Administrator access (an Administrator on Windows) is required for such tasks as:
-
Software installation, starting and stopping the hardserver and SNMP.
-
Typically, any operation that requires write access, such as the creation of Security Worlds, card sets and keys.
Typically, normal users can only carry out read only operations involving Security Worlds, card sets and keys.
For example, encrypted copies of keys are held in Key Management Data (C:\ProgramData\nCipher\Key Management Data
). The default permissions allow all users to read these files, enabling them to use keys but not create them.
File permissions can be altered to restrict access to specific keys to specific users/groups.
You should use the nt_privpipe_users option to define the name of the user who can carry out privileged operations, for example, using the nopclearfail utility. See nt_privpipe_users for more information.
|
About client configuration
You can add more HSMs to a client and more clients to an HSM at any time. |
The HSM and a client communicate by means of the hardserver, which handles secure transactions between the HSM and applications that run on the client. You must configure:
-
Each client hardserver to communicate with the HSM that the client needs to use
-
The HSM to communicate with clients that are allowed to use the HSM.
Information about the current configuration of the HSM or a client is stored in configuration files that are stored in specified file systems on the clients and on the HSM. For more information about the contents of configuration files, see HSM and client configuration files.
For information about configuring the HSM by importing an edited configuration file, see About user privileges.
Remote file system (RFS)
Each HSM must have a remote file system (RFS) configured. The RFS contains master copies of all the files that the HSM needs:
-
The HSM configuration file
-
Feature-enabling certificates
-
The encrypted Security World and key data for Security Worlds created on the HSM.
The RFS normally resides on a client computer, but it can be located on any computer that is accessible on the network.
For more information about setting up the remote file system, see Configuring the Remote File System (RFS).
HSM configuration
The data that defines the configuration of the HSM hardserver is stored in a file on the HSM. This file is automatically:
-
Updated when the HSM is configured from the front panel
-
Exported to the remote file system (RFS) directory.
Each HSM has separate configuration files on the RFS, stored in the directories with names of the form
%NFAST_KMDATA%\hsm-ESN\config
where ESN
represents the electronic serial number of the HSM from which the files were exported.
These directories can contain the following files:
Option | Description |
---|---|
|
The master configuration file. This contains the current configuration for the HSM. It is always present in the directory. |
|
An alternative configuration file saved by the system. |
|
A hand-edited configuration file that can be read by the HSM. |
You normally configure the HSM using the front panel controls. However, in some cases (for example, if you need to configure an HSM remotely, or if you are importing a number of clients), you may prefer to edit the exported configuration file and then re-import the file into the HSM. For more information, see:
Client configuration
The data that defines the configuration of the client hardserver is stored in a file on the client’s file system.
You must load the configuration file for the configuration to take effect. For information about loading a client configuration remotely, see Remote configuration of additional clients.
You can configure a client to use multiple HSMs. All the HSMs configured for use by a client can fail over if the application that uses them is set up appropriately.
For more information about the contents of the client configuration file, see HSM and client configuration files.
You can also configure the client’s hardserver by setting environment variables, as described in Setting environmental variables. Environment variable settings override settings in the client configuration files. |
Basic HSM and remote file system (RFS) configuration
After installing the HSM hardware and software, there are several HSM and RFS configuration tasks you must perform. You perform these RFS tasks before:
-
Creating the Security World and an Operator Card Set (OCS)
-
Completing the process of configuring the HSM and client to work together.
Configuring the Ethernet interfaces
The HSM communicates with one or more clients. Each client is an Ethernet connected computer that has the Security World Software installed and configured. You must supply Internet Protocol (IP) addresses for the HSM and the client. Contact your system administrator for this information if necessary.
To configure the Ethernet interfaces (IPv4 and IPv6), see the Installation Guide for your HSM.
Optionally configure hardserver interfaces
By default, the hardserver listens on all interfaces. However, you can alter the hardserver settings. Altering the hardserver settings would prove necessary, for example, if you wanted to connect one of the Ethernet interfaces to external hosts.
Ensure that you have configured the Ethernet interfaces on the HSM before attempting to configure the hardserver. See the Installation Guide for more information about configuring the Ethernet interfaces.
You can configure the following options to specify network interfaces on which the hardserver listens:
Option | Description |
---|---|
All interfaces |
This option (which is the default) specifies that the hardserver listens on all interfaces. |
IP address of interface #1 |
This option specifies that the hardserver listens only on interface 1. This option only appears if interface 1 has been configured. |
IP address of interface #2 |
This option specifies that the hardserver listens only on interface 2. This option only appears if interface 2 has been configured. |
Will not listen |
This option specifies that the hardserver does not listen on any interfaces. |
To define the interface and port on which the hardserver listens:
-
From the main menu, select System > System configuration > Hardserver config. The following screen appears:
Hardserver config Select network I/F hardserver listens on: All interfaces Select TCP port: 9004 CANCEL FINISH
-
Select the network interfaces on which the hardserver is to listen.
For security reasons, do not allow the hardserver to listen on any interface that is to connect to the public Internet. -
Press the Select button to move to the TCP port field, and set the port on which the hardserver is to listen. The default is 9004.
Make sure that your firewall settings are consistent with your port settings. See the Installation Guide for more about firewall settings. -
When the network interface and port are correct, press the right-hand navigation button.
-
Press the right-hand navigation button again to continue.
-
You are asked if you wish to reboot the system now or later. Press the right-hand navigation button to reboot now.
Configuring the Remote File System (RFS)
The RFS contains the master copy of the Security World data for backup purposes. The RFS can be located on either a client or another network-accessible computer where the Security World Software is installed. If the RFS is on a client, the same file structure also contains the configuration files for that client.
We recommend that you regularly back up the entire contents of the RFS.
The
%NFAST_KMDATA%
directory is required to restore the nShield HSM, or a replacement, to its current state, in case of failure.
|
You can specify a new remote file system, and modify or delete an existing remote file system configuration. To create or modify a remote file system configuration, specify the IP address of the computer on which the file system resides.
You must have created an RFS on the client computer before you specify the IP address of the client. |
For more information about the RFS and its contents, see:
The nShield HSM must be able to connect to TCP port 9004 of the RFS. If necessary, modify the firewall configuration to allow this connection on either the RFS itself or on a router between the RFS and the nShield HSM.
You can configure the connection to use secure authentication using software-based authentication or with an nToken (or local HSM) installed in the RFS. When enabled the nShield HSM not only examines the RFS’s IP address, but also requires the RFS to identify itself using a signing key.
If an nToken is installed in the RFS, it can be used to both generate and protect a key that is used for the impath communication between the nShield HSM and the RFS. Thus a strongly protected key is used at both ends of the impath. A local nShield PCIe or USB-attached HSM can also be used to perform the role of the nToken. |
Obtain the following information about the nShield HSM before you set up an RFS for the first time:
-
The IP address
-
The electronic serial number (ESN)
-
The hash of the
K
NETI key (HK
NETI). TheK
NETI key authenticates the nShield HSM to clients. It is generated when the nShield HSM is first initialized from factory state.
If your network is secure and you know the IP address of the nShield HSM, you can use the anonkneti
utility to obtain the ESN and hash of the K
NETI key by giving the following command on the client computer.
For guidance on network security, see the nShield Security Manual.
anonkneti <Unit IP>
In this command, <Unit IP> is the IP address of the nShield HSM, which could be one of the following:
-
An IPv4 address, for example
123.456.789.123
. -
An IPv6 address, for example
fc00::1
. -
A link-local IPv6 address, for example
fe80::1%eth0
. -
A hostname.
The command returns output in the following form:
A285-4F5A-7500 2418ec85c86027eb2d5959fef35edc5e1b3b698f
In this example output, A285-4F5A-7500
is the ESN and 2418ec85c86027eb2d5959fef35edc5e1b3b698f
is the hash of the K
NETI key.
Alternatively, you can find this information on the nShield HSM startup screen. Use the touch wheel to scroll to the appropriate information.
When you have the necessary information, set up an RFS as follows:
-
Prepare the RFS on the client computer (or another appropriate computer) by running the following command on that computer:
rfs-setup <Unit IP> <EEEE-SSSS-NNNN> <keyhash>
In this command:
-
<Unit IP> is the IP address of the nShield HSM.
-
<EEEE-SSSS-NNNN> is the ESN of the nShield HSM.
-
<keyhash> is the hash of the
K
NETI key.
-
-
On the nShield HSM display screen, use the right-hand navigation button to select System > System configuration > Remote file system, and enter the IP address of the client computer on which you set up the RFS:
Remote File System Enter IP address: CANCEL CONTINUE
-
The next screen asks for the port number on which the RFS is listening. Enter the port number and press the right-hand navigation button to continue:
Remote File System Enter port number: 9004 CANCEL CONTINUE
Leave the port number at the default setting of 9004. -
Select the config push mode and press the right-hand navigation button to continue:
Remote File System Set RFS config push mode to: AUTO CANCEL CONTINUE
Three options are available:
-
AUTO
: The RFS is only allowed to push configuration files to the nShield HSM if secure authentication is enabled. This is the default value. -
ON
: The RFS is allowed to push configuration files to the nShield HSM. -
OFF
: The RFS is not allowed to push configuration files to the nShield HSM.
-
-
You must confirm whether to enable or disable secure authentication when setting up the RFS. The following screen is displayed:
Remote File System Do you want secure authentication enabled on the RFS? YES CANCEL CONTINUE
-
Select
No
and press the right-hand navigation button to configure the RFS without secure authentication. The authentication of the RFS will be based on the IP address only. -
Select
Yes
and press the right-hand navigation button to configure the RFS with secure authentication.
-
-
Skip this step if you have not selected secure authentication.
If an nToken is installed in the RFS, you will be asked to choose which authentication key to use. Select the desired option and press the right-hand navigation button:
>0DA8-A5AE-BA0D Software Key BACK SELECT
-
The ESN of the nToken installed in the RFS.
-
"Software Key" for software-based authentication.
If no nToken is installed in the RFS, then software-based authentication is automatically selected.
-
-
Skip this step if you have not selected secure authentication.
At the next screen, verify that the key hash displayed by the nShield HSM matches the RFS key hash:
Remote 0DA8-A5AE-BA0D reported the key hash: 9e0020264af732933574 0cfe10446d33cea33f4a Is this EXACTLY right? CANCEL CONFIRM
The RFS key hash is obtained by running the commands described below. Take a copy of the returned key hash and compare it to the value reported on the nShield HSM display.
- With software-based authentication
-
Run the following command on the RFS:
enquiry -m0
This command returns the software key hash, tagged as
kneti hash
, as part of its output, for example:Server: enquiry reply flags none enquiry reply level Six ... kneti hash d4c3d757a67416cb9ba31f33febd6ead688629e5 ...
- With nToken authentication
-
Run the following command on the RFS:
ntokenenroll -H
This command produces output of the form:
nToken module #1 nToken ESN: 0DA8-A5AE-BA0D nToken key hash: 9e0020264af732933574 0cfe10446d33cea33f4a
Check that the ESN also matches the one reported on the nShield HSM display.
If the RFS key hash matches the one reported on the nShield HSM display, press the right-hand navigation button to continue the RFS configuration. Otherwise press the left-hand navigation button to cancel the operation.
-
The nShield HSM displays "Transferring files…" followed by a message reporting that the RFS has been set up. Press the right-hand navigation button again to exit.
After you have defined the RFS, the nShield HSM configuration files are exported automatically. See the User Guide for more about configuration files.
To modify the RFS at a later date, select System > System configuration > Remote file system, and then select the required action.
You can allow other clients to access the remote file system and share Security World and key data that is stored in the
%NFAST_KMDATA%
directory in the same way as the HSM.
Clients that access data in this way are described as cooperating clients.
To configure client cooperation, you need to know the details of each client including IP address and optionally their key hash and nToken ESN.
|
Configuring log file storage
You can choose to store log files on both the HSM and RFS or on the HSM only.
To configure log file storage, use the right-hand navigation button to select System > System configuration > Log config. Then select one of:
-
Log to store log files on the HSM only.
-
Append to store log files on both the HSM and remote file system.
We recommend selecting Append because if you select Log you can only view the log file from the nShield HSM front panel. Moreover, the log file stored on the HSM is cleared every time it is powered down.
You may also additionally configure the logs to be sent to a remote syslog server, see Configuring Remote Syslog.
Setting the time and date
If you do not intend to use NTP time synchronization, set the time and date as described in this section. If you configure the nShield HSM to use NTP time synchronization, then the time and date will be maintained by NTP.
To set the time and date on the HSM as UTC:
-
Use the right-hand navigation button to select and display the System menu:
1-1 System configuration System information Login settings Upgrade system Factory state Shutdown/Reboot BACK SELECT
-
Select System configuration to display the System configuration menu:
1-1-1 Network config Hardserver config Remote file system Client config Resilience config Config file options BACK SELECT
-
Use the touch wheel to move the arrow to Date/time setting, and press the right-hand navigation button to select it. The Set system date screen is displayed:
Set system date Please enter the current UTC date as DD/MM/YYYY: 27/ 5/2013 CANCEL NEXT
-
For each date field, use the touch wheel to set the value and move the cursor to the next field.
When you have completed all the fields, press the right-hand navigation button to confirm the date. The Set system time screen is displayed:
Set system time Please enter the current UTC time as hour/mins/seconds: 18:08:19 CANCEL FINISH
Setting the time and date of the HSM as UTC does not reset the value of the Real Time Clock (RTC) on the HSM. The UTC date and time settings are used only in log messages.
Keyboard layout
You can connect a keyboard to the USB connector on the nShield HSM front panel. This enables you to control the nShield HSM using a special set of keystrokes instead of the standard front panel controls.
You can connect either a US or a UK keyboard. To configure the nShield HSM for your keyboard type, select System > System configuration > Keyboard layout and then choose the keyboard type you require.
Configuring the nShield HSM to use the client
You must inform the HSM hardserver of the location of the client computer.
You can configure the connection to use secure authentication using software-based authentication or with an nToken (or local PCIe HSM) installed in the client. When enabled the nShield HSM not only examines the client IP address, but also requires the client to identify itself using a signing key.
If an nToken is installed in a client, it can be used to both generate and protect a key that is used for the impath communication between the nShield HSM and the client. Thus a strongly protected key is used at both ends of the impath. A local PCIe HSM can also be used to perform the role of the nToken. |
Software-based authentication is only supported from version 12.60. Previously enrolled clients using software-based authentication will need to be re-enrolled if an earlier version of Security World software is installed. |
The client configuration process varies slightly depending on whether you are enrolling the client with or without secure client authentication:
-
On the nShield HSM front panel, use the right-hand navigation button to select System > System configuration > Client config > New client.
The following screen is displayed:
Client configuration Please enter your client IP address: CANCEL NEXT
Enter the IP address of the client, and press the right-hand navigation button.
-
Use the touch wheel to confirm whether you want to save the IP or not, and press the right-hand navigation button.
Client configuration Do you want to save the IP in the config? (No for dynamic client IPs) No BACK NEXT
-
Use the touch wheel to select the connection type between the nShield HSM and the client.
Client configuration Please choose the client permissions Unprivileged BACK NEXT
The following options are available:
Option Description Unprivileged
Privileged connections are never allowed.
Priv. on low ports
Privileged connections are allowed only from ports numbered less than 1024. These ports are reserved for use by root on Linux.
Priv. on any ports
Privileged connections are allowed on all ports.
A privileged connection is required to administer the nShield HSM (for example, to initialize a Security World). If privileged connections are allowed, the client can issue commands that can interfere with the normal operation of the nShield HSM, such as clearing it. Entrust recommends that you allow only unprivileged connections unless you are performing administrative tasks. -
When you have selected a connection option, press the right-hand navigation button.
The following screen is displayed:
Client configuration Do you want secure authentication enabled on this client? Yes BACK NEXT
-
Select
No
and press the right-hand navigation button to configure the client without secure authentication. The authentication of the client will be based on the IP address only. -
Select
Yes
and press the right-hand navigation button to configure the client with secure authentication.
-
-
On the nShield HSM, enter the number of the port on which the client is listening (the default is 9004), and press the right-hand navigation button. The following screen is displayed:
Client configuration On what port is the client listening? 9004 CANCEL NEXT
-
Skip this step if you have not selected secure authentication.
If an nToken is installed in the client, you will be asked to choose which authentication key to use. Select the desired option and press the right-hand navigation button:
>3138-147F-2D64 Software Key BACK SELECT
-
The ESN of the nToken installed in the client.
-
"Software Key" for software-based authentication.
If no nToken is installed in the client, then software-based authentication is automatically selected.
Software-based authentication is only supported from version 12.60. -
-
Skip this step if you have not selected secure authentication.
The next screen asks you to verify that the key hash displayed by the nShield HSM matches the client key hash:
Remote 3138-147F-2D64 reported the key hash: 691be427bb125f387686 38a18bfd2eab75623320 Is this EXACTLY right? CANCEL CONFIRM
The client key hash is obtained by running the commands described below. Take a copy of the returned key hash and compare it to the value reported on the nShield HSM display.
- With software-based authentication
-
Run the following command on the client:
enquiry -m0
This command returns the software key hash, tagged as
kneti hash
, as part of its output, for example:Server: enquiry reply flags none enquiry reply level Six ... kneti hash f8222fc007be38b78ebf442697e244dabded38a8 ...
- With nToken authentication
-
Run the following command on the client:
ntokenenroll -H
This command produces output of the form:
nToken module #1 nToken ESN: 3138-147F-2D64 nToken key hash: 691be427bb125f387686 38a18bfd2eab75623320
Check that the ESN also matches the one reported on the nShield HSM display.
If the client key hash matches the one reported on the nShield HSM display, press the right-hand navigation button to continue the RFS configuration. Otherwise press the left-hand navigation button to cancel the operation.
-
The nShield HSM displays a message reporting that the client has been configured. Press the right-hand navigation button again.
To modify or delete an existing client, select System > System configuration > Client config and perform the appropriate procedure.
If you want to use multiple clients with the nShield HSM, you must enable additional client licenses (see Enabling optional features). When you have additional client licenses enabled, to configure more clients, repeat the appropriate steps of the procedure described in this section for each client.
Remote configuration of additional clients
Additional clients can be added remotely provided that config push is enabled. This can be done from the RFS or a client computer (see Pushing configuration files to the nShield HSM).
Before you can use multiple clients with the nShield HSM, you must enable the additional clients as described in Enabling optional features. |
To add clients remotely:
-
Copy the HSM configuration file
NFAST_KMDATA\hsm-ESN\config\config
toconfig.new
in the same directory.The path to the new file will be:
NFAST_KMDATA\hsm-ESN\config\config.new
. -
Add a new entry to
config.new
in thehs_clients
section to contain the details of the client to be added.The following two entries must exist in the configuration file:
addr=<client_IP> clientperm=permission_type
Where:
<client_IP>
can be either the IP address of the client or0.0.0.0
,::
, or blank if the HSM is to accept clients identified by their key hash instead of their IP address.0.0.0.0
or::
, and blank result in the same behavior. You can only use them in the configuration file, you cannot enter these values in the front-panel user interface.The default is blank.
If you set both the
<client_IP>
field (the client’s IP address) and the key hash, the HSM must identify clients from both of these fields.permission_type
defines the type of commands the client can issue (unpriv
,priv
orpriv_lowport
).-
If the client is using an nToken, two additional entries will need to be added to the configuration file:
esn=nToken_ESN keyhash=nToken_keyhash
Where
nToken_ESN
is the ESN of the client’s nToken andnToken_keyhash
is the hash of the key that the client’s nToken should authenticate itself with. -
If the client is using software-based authentication, one additional entry will need to be added to the configuration file:
keyhash=software_keyhash
Where
software_keyhash
is the hash of the software generated key that the client should authenticate itself with. TheESN
entry must be blank or omitted for software-based authentication.Each client entry after the first must be introduced by a line consisting of one or more hyphens.
-
-
Load the updated configuration file on to the nShield HSM. To do this, run the following command:
cfg-pushnethsm --address=<module_IP_address> <new_config_file>
In this command,
<module_IP_address>
is the IP address of the nShield HSM and<new_config_file>
is the location of the updated configuration file (config.new
).Alternatively, you can load the configuration file using the nShield HSM front panel without enabling config push. The configuration file (
config.new
) must be in the directory%NFAST_KMDATA%\hsm-ESN\config
on the remote file system. To do this, select System > System configuration > Config file options > Fetch configuration.An SEE machine cannot be installed or configured using the fetch configuration option from the front panel, the config push feature must be used for this. See Remotely loading and updating SEE machines for more information.
Changing the nShield HSM configuration from the Front Panel to use a client
From the Front Panel, you can change the settings that your nShield HSM stores about its client.
The Front Panel does not display all current properties for the client. Entrust recommends that you retrieve the current client settings before you start the update. See HSM and client configuration files. During the configuration update, check the current configuration file against the values displayed on the Front Panel. Check the values at each configuration step before proceeding to the next step and finally confirming the changes. |
Configuring client computers to use the nShield HSM
Each client computer must be configured to use the internal security module of your nShield HSM. There are two methods for achieving this:
-
Enrolling the client with the configuration file.
-
Enrolling the client with command-line utilities.
Enrolling the client with the client configuration file
The client configuration files are in the directory
%NFAST_KMDATA%\config
on the client computer’s file system.
For this release, you must generate a new client configuration file to take advantage of the new functionality.
To generate a new client configuration file, back up your existing configuration file and run the command cfg-mkdefault . This generates a template for the configuration file into which you can copy the settings from your old configuration file.
|
The nethsm_imports
section defines the network HSMs that the client imports (See nethsm_imports). It can also be set up by the nethsmenroll
utility.
-
Edit the following mandatory fields:
local_module
,remote_ip
,remote_esn
,remote_keyhash
andprivileged
. The default value forremote_keyhash
(40 zeros) specifies that no authentication should occur. -
The
ESN
andhash
of the HSM to import can be retrieved by running the commandanonkneti remote_ip
-
If the client is to be enrolled with an nToken, open a command line window, and run the command:
ntokenenroll --H
. This command produces output of the form:nToken module #1 nToken ESN: 3138-147F-2D64 nToken key hash: 691be427bb125f3876838a18bfd2eab75623320
-
Enter the nToken’s
ESN
in the fieldntoken_esn
in the config file. -
Each HSM entry after the first must be introduced by a line consisting of one or more hyphens, i.e.
---
. -
At the command line run the command
cfg-reread
, to reload the hardserver’s configuration. -
Verify that the client can use the nShield HSM by running
enquiry
, which reports the HSM’s status.
If the client is to be enrolled with either software-based authentication or no authentication, the ntoken_esn field must be left empty.
|
For information about configuration file contents, see HSM and client configuration files.
Enrolling the client from the command line
The nethsmenroll
command-line utility edits the client hardserver’s configuration file to add the specified nShield HSM.
For more information about the options available to use with nethsmenroll
, read the following section Client configuration utilities, or run the command:
nethsmenroll --help
To retrieve the nShield HSM’s ESN
and HKNETI
, run the command
anonkneti <Unit IP>
This command produces output of the form:
3138-147F-2D64 691be427bb125f38768638a18bfd2eab75623320
If the nShield HSM’s ESN
and HKNETI
are not specified, nethsmenroll
attempts to contact the HSM to determine what they are, and requests confirmation.
-
If you are enrolling the client with an nToken, run the command:
nethsmenroll --ntoken-esn <nToken ESN> [Options] --privileged <Unit IP> <Unit ESN> <Unit KNETI HASH>
-
If you are enrolling the client without an nToken, i.e. software-based authentication or no authentication, run the command:
nethsmenroll [Options] --privileged <Unit IP> <Unit ESN> <Unit KNETI HASH>
These commands produce output of the form:
OK configuring hardserver's nethsm imports.
Client configuration utilities
We provide the following utilities for client configuration:
Utility | Description |
---|---|
|
This utility is used to configure the client to communicate with the nShield HSM. |
|
This utility is used to configure the client’s hardserver to enable TCP sockets. |
nethsmenroll
The nethsmenroll
command-line utility edits the client hardserver’s configuration file to add the specified nShield HSM.
If the nShield HSM’s ESN
and HKNETI
are not specified, nethsmenroll
attempts to contact the nShield HSM to determine what they are, and requests confirmation.
Usage:
nethsmenroll [Options] --privileged <hsm-ip> <hsm-esn> <hsm-kneti-hash>
Options | Description | ||
---|---|---|---|
|
Specifies the local HSM number to use (default is |
||
|
Causes the hardserver to request a privileged connection to the nShield HSM (default |
||
|
The IP address of the nShield HSM, which could be one of the following:
|
||
|
Deconfigures the specified nShield HSM. |
||
|
Forces reconfiguration of an nShield HSM already known. |
||
|
Does not request confirmation when automatically determining the nShield HSM’s
|
||
|
When the |
||
|
Specifies the port to use when connecting to the given nShield HSM (default |
||
|
Specifies the |
config-serverstartup
The config-serverstartup
command-line utility automatically edits the [server_startup]
section in the local hardserver configuration file in order to enable TCP ports for Java and KeySafe.
Any fields for which values are not specified remain unchanged.
After making any changes you are prompted to restart the hardserver.
Run config-serverstartup
using commands of the form:
config-serverstartup [OPTIONS]
For more information about the options available to use with config-serverstartup
, run the command:
config-serverstartup --help
Configuring NTP in the nShield HSM
The nShield HSM has a standard NTP client that can be configured to support synchronization of system time on the HSM with one or more NTP servers. Network Time Protocol (NTP) is intended to synchronize all participating computers to within a few milliseconds of Coordinated Universal Time (UTC). System time on the nShield HSM is independent of the Real Time Clock (RTC) in the HSM and is used for log messages and front panel display.
Entrust recommends that the NTP Server(s) are trusted servers within your local network, not internet time servers. |
After configuring NTP the HSM has to be re-started for the configuration to take effect. When starting up after being configured, the NTP client can make a step change to the system time to bring it into line with that of the NTP server(s). At all other times, the NTP client will only slew (gradually change) the system time. When using NTP there should be no need to set the system time by setting time and date from the front panel of the nShield HSM.
Before configuring NTP you must ensure the following:
-
config push is enabled for the remote computer used to configuring NTP. See Pushing configuration files to the nShield HSM.
-
The client computer enabled for auto push is configured for Privileged connections, see Configuring the nShield HSM to use the client, so that the nShield HSM can be rebooted from the client computer.
Using the NTP configuration tool
NTP is configured using the cfg-pushntp
utility on a client computer.
Utility | Description | ||
---|---|---|---|
|
This tool enables or disables NTP time synchronization on the specified nShield HSM. When enabling NTP synchronization, the IP addresses of up to 3 NTP servers may be specified.
|
Usage:
cfg-pushntp -a ADDR [-p PORT -k -m MODULE] -1 ADDR [-2 ADDR -3 ADDR] enable
cfg-pushntp -a ADDR [-p PORT -k -m MODULE] disable
Options:
Field | Description |
---|---|
|
Enable or disable NTP service on the nShield HSM. |
|
IP address of nShield HSM to configure NTP on. This can be an IPv4 or an IPv6 address, or it can be a hostname that resolves to the HSM’s IP address. |
|
Set port to use to connect to the nShield HSM (default=9004). |
|
Use KNETI to authenticate ourselves. |
|
Set the HSM to use for KNETI authentication.
The default is HSM 1. This option can only be used with the - |
|
IP address of NTP server. This can be an IPv4 or an IPv6 address. |
|
IP address of NTP server. This can be an IPv4 or an IPv6 address. |
|
IP address of NTP server. This can be an IPv4 or an IPv6 address. |
For example, running the command:
cfg-pushntp.exe --address=192.30.100.150 --ntp1=192.23.24.256 enable
Returns:
The requested NTP configuration changes have been uploaded and will take effect when the target nShield HSM is restarted.
Restarting the nShield HSM
After configuring NTP, restart the nShield HSM, for example see Using nethsmadmin to reboot an nShield HSM. Once the HSM has rebooted and the syslog output is available, check that there are no NTP failures reported in the syslog output.
Enable NTP for IPv6
You can use HSM images that were built with buildroot from version 13 onwards with NTP over IPv6.
To run ntpd as a non-root user, start ntpd as root and use switch -u
on the command line to change to the "ntp:ntp" non-root user.
To set NTP up for IPv6:
-
Reset the HSM to factory state using the UI (menu: 1-5). See
-
Assign an IPv6 address to the HSM on interface #1 (eth0).
For example:
fd01:11::260:e0ff:fe81:4ac1
. -
Assign an IPv6 address on the same subnet to the RFS host machine that will act as the NTP server.
For example:
fd01:11::ae9f:98bc:e202:9941
. -
Enroll the HSM on the RFS using the following commands:
Ensure that the displayed kneti hash is not just a string of zeroes. If it is, reset the HSM to factory state.
opt/nfast/bin/anonketi <HSM IP> opt/nfast/bin anonketi <HSM IPv6 address> sudo /opt/nfast/bin/rfs-setup --force <HSM IPv6 address> `/opt/nfast/bin/anonketi <HSM IPv6 address>` sudo /opt/nfast/bin/nethsmenroll -fp <HSM IPv6 address>
-
Add the RFS IPv6 address to the HSM (menu: 1-1-3)
-
RFS IP address:
<RFS IPv6 address>
-
Set RFS config push mode to:
AUTO
-
Do you want secure authentication enabled on RFS?
YES
-
-
Add the RFS IPv6 address to the HSM as a client (menu: 1-1-4)
-
Client IP address:
<RFS IPv6 address>
-
Do you want to save IP in the config?
Yes
-
Client permissions:
Priv on any port
-
Do you want secure authentication enabled on this client?
No
-
-
Check that the RFS can detect the HSM. If any errors appear, such as
AccessDenied
, wait for one minute and then run the command again./opt/nfast/bin/enquiry
-
Ensure that auto-push is enabled on the HSM. If auto-push is not enabled,
cfg-pushntp
reports anUnknownHostVolume
error.-
Toggle auto-push on:
System > System configuration > Config file options > Setup auto push > Yes
-
Add the RFS IPv6 address:
System > System configuration > Config file options
-
-
Using the HSM front panel, set the date and time to be different from those on the RFS host machine. This will help you verify that HSM is updating from the RFS when completing this task.
You can view the HSM’s status, including the date and time, by scrolling through the front (top) menu on the front panel.
-
Install NTP on the RFS.
For an Ubuntu 18.04 host:
-
Run the following command:
sudo apt install ntp
-
Add the following lines to the
/etc/ntp.conf
file.0.au.pool.ntp.org 1.au.pool.ntp.org 2.au.pool.ntp.org 3.au.pool.ntp.org
-
Restart the NTP service:
sudo service ntp restart
-
Verify that the service successfully restarted and is running:
sudo service ntp status
-
Check that the firewall is not blocking UDP and TCP ports 123.
-
-
Push the NTP configuration to the HSM from the RFS host machine:
/opt/nfast/bin/cfg-pushntp --address=<HSM IPv6 address> --ntp1=<RFS IPv6 address> enable
-
Reboot the HSM from the RFS host machine. The HSM updates its system time from the NTP server by running the
/sbin/setostime
script when it starts up from the/etc/inittab
file.sudo opt/nfast/bin/nethsmadmin --reboot --module 1
-
When the HSM has rebooted, chack that the date and time in the front (top) menu match the date and time on the RFS host machine.
Configuring Remote Syslog
The nShield HSM can be configured to send logs directly to a remote syslog server, listening on a User Datagram Protocol (UDP) port, by editing the remote_sys_log
section of the config file.
This behavior can be configured in addition to storing the log files on the RFS (i.e. you can configure the logs to be sent to a remote syslog server regardless of whether the nShield HSM logs are configured to be stored on the HSM or the RFS). For further information see Configuring log file storage.
There is no additional formatting of log messages (the logs sent are the same log messages that will appear on the unit or the RFS). It is the responsibility of the remote syslog server / SIEM application to format, sort and aggregate the incoming log messages.
To configure an nShield HSM to send logs to a remote syslog server:
-
In the
remote_sys_log
section of the config file for the remote module, add the following settings:If your configuration file predates the functionality to send logs to a remote syslog server, you will need to manually create a new config file section called remote_sys_log
.remote_sys_log_ip=REMOTE_SYSLOG_SERVER_IP remote_sys_log_port=REMOTE_SYSLOG_SERVER_PORT
-
Run the following command to push the new config file to the module:
cfg-pushnethsm
If you are using an older version of the Security World software with a Connect image that supports remote syslog, you will see this error message: unrecognized section name: 'remote_sys_log'. Use the following command to push the updated configuration file: cfg-pushnethsh --force
If you are using a version of the Security World software that supports remote syslog with an image that does not support remote syslog, the configuration file will be pushed to the nShield HSM but will be rejected by it. You will see that the upgraded configuration file on the RFS is unchanged.
To turn off sending logs to a remote syslog server, remove the entries from the remote_sys_log
section of the configuration file and push the updated configuration file.
Setting up client cooperation
If you do not need to allow multiple clients access to your remote file system (RFS), you only need to follow the instructions provided in Configuring the Remote File System (RFS) to initialize your RFS. If you need to allow other clients to access your RFS (that is, able to access the RFS to share key data), complete the following steps:
-
Configure the RFS to accept access by cooperating clients:
-
For every authenticated client (with write access and KNETI authorization) that needs to be a client of this remote file system, run the command:
rfs-setup --gang-client <client_IP_address> <EEEE-SSSS-NNNN> <keyhash>
In this command:
-
<client_IP_address>
is the IP address of the client. -
<EEEE-SSSS-NNNN>
is the ESN of the nToken used by the client when using a nTokenK
NETI key to authenticate itself. When using software-based authentication, it must be empty (i.e. "") or can be omitted altogether. -
<keyhash>
is the hash of the software or moduleK
NETI key used by the client.
-
-
For every unauthenticated client (with write access but without
K
NETI authorization), run the command:rfs-setup.exe --gang-client --write-noauth <client_IP_address>
The --write-noauth
option should be used only if you believe your network is secure. This option allows the client you are configuring to access the RFS withoutK
NETI authorization.To limit a gang-client to read-only, use the
--readonly
flag.
-
-
On each client that is to be a cooperating client, you must run the
rfs-sync
command-line utility with appropriate options:-
for clients using a software
K
NETI key to authenticate themselves to the RFS, run the command with the default options:rfs-sync --setup <RFS_IP_ADDRESS>
-
for clients using a module
K
NETI key to authenticate themselves to the RFS, run the command:rfs-sync --setup --authenticate --module=<MODULE> <RFS_IP_ADDRESS>
In this command:
-
<RFS_IP_ADDRESS>
is the IP address of the RFS. -
<MODULE>
is the local module to use for authentication.
-
-
for clients to authenticate the RFS using software-based authentication, use the
--rfs-hkneti=HKNETI
option to specify the hash of the softwareKNETI
key of the RFS. -
for clients to authenticate the RFS using nToken authentication, use the
--rfs-esn=ESN
and--rfs-hkneti=HKNETI
options to specify theESN
and hash of theKNETI
key of the nToken installed in the RFS.
-
The rfs-sync
utility uses lock files to ensure that updates are made in a consistent fashion.
If an rfs-sync
--commit
operation (the operation that writes data to the remote file system) fails due to a crash or other problem, it is possible for a lock file to be left behind.
This would cause all subsequent operations to fail with a lock time-out error.
The rfs-sync
utility has options for querying the current state of the lock file, and for deleting the lock file; however, we recommend that you do not use these options unless they are necessary to resolve this problem.
Clients without write access cannot delete the lock file.
For more information about the rfs-sync
utility, see rfs-sync.
To remove a cooperating client so the RFS no longer recognizes it, you must:
-
Know the IP address of the cooperating client that you want to remove
-
Manually update the
remote_file_system
section of the hardserver configuration file by removing the following entries for that particular client:remote_ip=client_IP_address remote_esn=keyhash=0000000000000000000000000000000000000000 native_path=%NFAST_KMDATA%\local volume=kmdata-local allow_read=yes allow_write=yes allow_list=yes is_directory=yes is_text=no
and
remote_ip=client_IP_address remote_esn=keyhash=0000000000000000000000000000000000000000 native_path=%NFAST_KMDATA%\local\sync-store volume=kmdata-backup allow_read=yes allow_write=yes allow_list=yes is_directory=yes is_text=no
Useful utilities
anonkneti
To find out the ESN and the hash of the K
NETI key for a given IP address, use the anonkneti
command-line utility.
A manual double-check is recommended for security.
The IP address could be one of the following:
-
An IPv4 address, for example
123.456.789.123
. -
An IPv6 address, for example
fc00::1
. -
A link-local IPv6 address, for example
fe80::1%eth0
. -
A hostname.
rfs-sync
This utility synchronises the
%NFAST_KMDATA%\local
folder between a cooperating client and the remote file system it is configured to access.
It should be run when a cooperating client is initialised in order to retrieve data from the remote file system and also whenever a client needs to update its local copy of the data or, if the client has write access, to commit changes to the data.
Usage
rfs-sync [-U|--update] [-c|--commit] [-s|--show] [--remove] [--setup [setup_options] ip_address]
Options
-U
|--update
-
These options update local key-management data from the remote file system.
If a cooperating client has keys in its kmdata\local
directory that are also on the remote file system, if these keys are deleted from the remote file system and thenrfs-sync --update
is run on the client, these keys remain on the client until manually removed. -c
|--commit
-
These options commit local key-management data changes to the remote file system, and update the client from the remote file system.
-s
|--show
-
These options display the current synchronisation configuration.
--setup
-
This option sets up a new synchronisation configuration. Specifics of the configuration can be altered using
setup_options
as follows: -a
|--authenticate
-
This set-up option specifies the use of a module KNETI key to authenticate this client to the RFS. By default the software KNETI key is used instead.
-m
|--module=module
-
This option selects the local module to use for authentication. The default is 1. This option can only be used with the
--authenticate
option. -p
|--port=port
-
These options specify the port on which to connect to the remote file system. The default is 9004.
--rfs-hkneti=HNETI
-
This option specifies the hash of the
KNETI
key to use for nToken or software-based authentication of the RFS. --rfs-esn=ESN
-
This options specifes the
ESN
of the nToken to use for authentication of the RFS. ip_address
-
This option specifies the IP address of the remote file system, which could be one of the following:
-
An IPv4 address, for example
123.456.789.123
. -
An IPv6 address, for example
fc00::1
. -
A link-local IPv6 address, for example
fe80::1%eth0
. -
A hostname.
-
--remove
-
This option removes the synchronisation configuration.
A client can use rfs-sync
--show
to display the current configuration, or rfs-sync
--remove
to revert to a standalone configuration.
Reverting to a standalone configuration leaves the current contents of the Key Management Data directory in place.
The rfs-sync
command also has additional administrative options for examining and removing lock files that have been left behind by failed rfs-sync --commit
operations.
Using the --who-has-lock
option displays the task ID of the lock owner.
As a last resort, you can use the rfs-sync
command-line utility to remove lock files. In such a case, the --kill-lock
option forcibly removes the lock file.
The lock file can also be removed via menu item 3-3-2, Remove RFS Lock: this executes the rfs-sync --kill-lock command.
|
Setting environmental variables
This section describes how to set Security World Software-specific environment variables. You can find detailed information about the environment variables used by Security World Software in Environment variables. Environment variables
You can set Security World Software-specific environment variables as follows:
-
Open the System dialog by clicking System in the control panel menu.
-
Select the Advanced tab and click the Environment Variables button.
-
To add a variable, click New. Alternatively, to edit an existing variable select an entry in the System Variables list and click Edit.
-
In the Variable Name field, type or edit the name of the environment variable (for example, NFAST_HOME).
-
In the Variable Value field, type or edit the value to use.
-
Click the OK button to set the value, and then click the OK button to close the dialog.
-
Open the Administrative Tools dialog by clicking the Administrative Tools icon in the Control Panel
-
Open the Services console by clicking the Services icon.
-
From the displayed list of services, select the nFast Server icon, and select Restart the service.
Logging and debugging
The nShield HSM and applications that use it generate log files. You can view the logs using the unit front panel. Application log messages are handled on the client.
The Security World Software generates logging information that is configured through a set of four environment variables:
-
NFLOG_FILE
-
NFLOG_SEVERITY
-
NFLOG_DETAIL
-
NFLOG_CATEGORIES
If none of these logging environment variables are set, the default behavior is to log nothing, unless this is overridden by any individual library. If any of the four logging variables are set, all unset variables are given default values. |
Detailed information about controlling logging information by means of these environment variables is supplied in Logging, debugging, and diagnostics.
Some components of the Security World Software generate separate debugging information which you can manage differently. Debugging information for applications is handled on the client. If you are setting up the unit to develop software that uses it, you should configure debugging before commencing software development.
Configuring Java support for KeySafe
To use KeySafe, follow the instructions in Using KeySafe.
Routing
If you have configured only one network interface, you do not need to configure a static route for the unit, although you can do so if you wish. If you have configured a second network interface, you can choose to configure a static route.
If the unit is to connect to a remote host or network that is unreachable through the default gateway, you must set up extra static routes in the system routing table.
To set up the Ethernet interfaces (IPv4 and IPv6), see the Installation Guide for your HSM.
After you have defined static routes, you should test them as described in Testing routes.
If you define, edit, or delete a route, you must reboot the unit before the route can be used and the routing table is updated. |
Testing routes
When you have set up or edited a route, you should test the route.
Testing a route between the unit and the client
When you have installed the unit in its final location, you should test the connection between the unit and the client. You can do this from the client, as described in this section, or by using the Ping remote host option on the unit. To do this from the unit, select System > System configuration > Network config > Ping remote host.
You can also use the method described in this section to test the route between the client and a remote computer.
To test the route from the client to the unit, issue a ping
command from the client for the IP address that you specified for the unit. (The format of the command and results may vary according to the platform that you are using.)
ping <xxx.xxx.xxx.xxx>
If the ping
operation is successful, a message similar to the following is displayed:
Pinging xxx.xxx.xxx.xxx with 32 bytes of data
Reply from xxx.xxx.xxx.xxx: bytes=32 time=10ms TTL=125
Reply from xxx.xxx.xxx.xxx: bytes=32 time=10ms TTL=125
Reply from xxx.xxx.xxx.xxx10ms TTL=125
Reply from xxx.xxx.xxx.xxx10ms TTL=125
Testing a route between the unit and a remote host
When you have defined or edited a route from the unit to a remote computer, you should test it.
To do this you can issue a ping
command from the unit to the IP address of the host.
You can also use this method to test the connection between the unit and the client.
To test a route from the unit to a host:
-
Select System > System configuration > Network config > Ping remote host. The following screen appears:
Ping remote host Select IP address: 0. 0. 0. 0 RESET FINISH
-
Enter the IP address of the remote host.
-
Press FINISH to issue the ping. The following message appears:
Please wait, running ping
-
After a short wait, a display similar to the following should appear, showing that the unit has managed to communicate with the host:
Ping xxx.xxx.xxx.xxx: #0: rtt=0.0503 ms #1: rtt=0.0503 ms #2: rtt=0.0503 ms #3: rtt=0.0503 ms 4 of 4 packets back. min avg max SD 0.29 0.36 0.50 0.09 ms
If not all of the information is visible onscreen, use the touch wheel to scroll up and down the page.
-
Press the left-hand navigation button to return to the Network config menu.
Tracing network routes
You can trace network routes from the unit and from clients.
Tracing the route from the unit
You can trace the route taken from the unit to a remote computer. You can also use this method to trace the route from the unit to the client.
-
Select System > System configuration > Network config > Trace route to host. The following screen appears:
Trace route Select IP address: 0. 0. 0. 0 CANCEL FINISH
-
Press the right-hand navigation button to issue the
traceroute
. The following message appears:Please wait, running traceroute.
-
After a short wait, a display similar to the following should appear, showing the IP addresses encountered along the route:
1: xxx.xx.xxx.x 0.40 ms 2: * 3: xx.xxx.xx.xxx 2.1 ms 4: xxx.xx.xxx.xxx 2.4 ms BACK
If not all of the information is visible onscreen, use the touch wheel to scroll up and down the page.
-
Press the left-hand navigation button to return to the Network config menu.
Tracing the route from the client
You can trace the route from the client to the unit or (if the client is connected to the public Internet) to a remote computer.
To trace the route from the client to the unit, issue a traceroute
command from the client for the IP address of the unit. (The format of the command, and results, may vary depending upon the platform that you are using.)
tracert <xxx.xxx.xxx.xxx>
After a short wait, a display similar to the following should appear, showing the IP addresses encountered along the route:
Tracing route to modulename (xxx.xxx.xxx.xxx)/ over a maximum of 30 hops:
1 xxx.xxx.xxx.xxx (xxx.xxx.xxx.xxx) 1.457 ms 0.513 ms 0.311 ms
2 xxx.xxx.xxx.xxx (xxx.xxx.xxx.xxx) 0.773 ms 0.523 ms 1.615 ms
Displaying the routing table
You can view details of all the IP addresses for which the internal security module has a route stored. The routing table includes entries for static routes (which are stored permanently) and local hosts to which the module has set up temporary routing entries.
To view the routing table:
-
Select System > System configuration > Network config > Show routing table. A display similar to the following appears:
Dest Gateway Flg 1 xxx.xxx.xxx.xxx xxx.xxx.xxx.xxx UG 2 xxx.xx.xx.x xxx.x.x.xxx UG BACK
If not all of the information is visible on the unit display screen, use the touch wheel to scroll up and down the page.
-
Press the left-hand navigation button to return to the Network config menu.
Configuring an nShield HSM using the Serial Console
On supported hardware variants (see Model numbers in the nShield 5c v13.3 User Guide (Windows)) there is an RJ45 serial port connector at the rear of the nShield HSM marked Console. The serial port provides access to a serial console command line interface that enables remote configuration of the unit whilst also facilitating status monitoring. Tasks which would typically require a physical presence in front of the HSM, including setting IP addresses, can be done remotely using the serial console.
This functionality can help provide separation of duty between the data center technician installing the nShield HSM and the administrator configuring and using the HSM.
The only required local activity is to connect the nShield HSM to power and to serial and Ethernet ports.
Everything that can be configured using the front panel can then be configured remotely either over the serial interface, by using the nethsmadmin
utility (see nethsmadmin) or by pushing an updated configuration file to the nShield HSM (see Configuring the nShield HSM with configuration files).
The Serial Console supports IPv4 and IPv6 addresses.
Serial port configuration
The RJ45 connector can be directly connected to your client machine or connected to a serial port aggregator for remote access.
To access the serial console command line interface, first determine the device name of the serial connection once it is connected to your client machine. Then configure the serial port connection in your serial port communication software with the following parameters:
-
Line Speed (baud): 115200
This is the default baud rate. If you have manually changed the baud rate to 9600 (see here), enter this value instead.
-
Data bits: 8
-
Parity: None
-
Stop bits: 1.
Once the connection is established, press Return until a login prompt is displayed. The login prompt should look like:
nethsm login:
Change the baud rate
To change the baud rate using the front panel, navigate to System > System configuration > Remote config options > Serial Console > Serial baud rate and select the required baud rate.
to change the baud rate remotely:
-
Copy the config file to
config.new
. -
If the
config.new
file does not already contain the following section, add it to the file.[cli] # Start of the cli section # The serial CLI baud rate configuration. Restart your CLI connection after # changing. # Each entry has the following fields: # # Set to "115200" or "9600" to select the relevant baud rate for the serial # CLI connection. Note active CLI serial connections are broken upon the # setting of a new baud rate. baud_map=BAUDRATE
-
Edit the
baud_map
value. -
Push
config.new
to the HSM usingcfg_pushnethsm
.
Changing the baud rate using the front panel creates the [cli] section in the config file if it does not already exist.
|
Troubleshooting
Error | Action |
---|---|
Nothing on the screen |
Press Enter a few times. Make sure that the RJ45 connector is properly connected and that remote configuration is enabled on the nShield HSM, see Enabling and disabling the serial console. |
Miscellaneous characters displayed on the screen |
Make sure the serial port connection is configured correctly, see Serial port configuration. |
Creating a serial console session
The username for accessing the serial console is cli
and the default password is admin
.
On first login you will be prompted to change the password for the cli
user.
The minimum length of the new password is 5 characters.
You must enter a new password.
You cannot reuse admin
the first time you change the password.
For guidance on selecting a password, see the nShield Security Manual.
Once you are successfully logged in to a serial console session you will see the welcome message:
Welcome to the nShield 5c Serial Console. Type help or ? to list commands.
(cli)
The serial console session will automatically logout after 180 seconds of inactivity. To manually end a session, use the logout command.
Enabling and disabling the serial console
The serial console interface can be enabled and disabled using the nShield HSM front panel.
-
To enable the serial console interface, navigate to System > System configuration > Remote config options > Serial Console and set to On.
-
To disable the serial console interface, set Serial Console to Off.
The serial interface is enabled by default and will turn back on with the default password if the unit is reset to its factory state. This means if you do not want the serial console enabled you will need to disable it after each factory state.
If you do not see the menu option System > System configuration > Remote config options > Serial Console on the front panel then this means that your nShield HSM does not support the serial console feature (the hardware does not support serial access).
The availability of the serial console feature can also be checked remotely from an enrolled client by running the enquiry utility.
Feature availability | Enquiry output |
---|---|
Serial console available |
… level six flags SerialConsoleAvailable … |
Serial console not available |
… level six flags none … |
Serial console commands
The serial console command line interface provides the following commands:
Command | Description | ||
---|---|---|---|
|
Get/set the HSM system time |
||
|
Prints enquiry data from the HSM |
||
|
Show the Electronic Serial Number (ESN) of the HSM |
||
|
Reset unit to its original (factory) state
|
||
|
Get/set the default IPv4 gateway address |
||
|
Get/set the default IPv6 gateway address |
||
|
Get the real time clock (RTC) of the nShield 5c Only available on the nShield 5c |
||
|
List available commands with |
||
|
Show the (hash of) Kneti (used for enrolling the HSM with clients) |
||
|
Print nShield 5c diagnostic logs Only available on the nShield 5c |
||
|
Log out of the nShield HSM Serial Console |
||
|
Enable/disable maintenance mode Only available on the nShield 5c |
||
|
Get/set the IPv4 network interface configuration |
||
|
Get/set the IPv6 network interface configuration |
||
|
Print network interface statistics |
||
|
Enable IPv6 |
||
|
Get/set the network interface link, get the network interface MAC address |
||
|
Get/set the HSM bond interface configuration |
||
|
Get/set the bond interface link |
||
|
Set the serial console password |
||
|
Ping a remote host |
||
|
Get/set the config push setting |
||
|
Reboot the HSM |
||
|
Get/set the RFS IP address, port, optional secure authentication and push mode |
||
|
Get/set IPv4 network routes |
||
|
Get/set IPv6 network routes |
||
|
Show the IPv4 routing table |
||
|
Show the IPv6 routing table |
||
|
Set the RTC on the nShield 5c Only available on the nShield 5c Before you can use this command, you must put the nShield 5c into maintenance mode with |
||
|
Run the |
||
|
Check for any Security World data on the HSM |
||
|
Show the nShield HSM tamper log |
||
|
Show how long the nShield HSM has been running (since last boot) |
||
|
Show nShield HSM Serial Console version information |
For additional help on a command, run help
command to see additional guidance on command usage, syntax and parameter documentation.
Using multiple modules
The hardserver can communicate with multiple modules connected to the host. By default, the server accepts requests from applications and submits each request to the first available module. The server can share load across buses, which includes the ability to share load across more than one module.
If your application is multi-threaded, you can add additional modules and expect performance to increase proportionally until you reach the point where cryptography no longer forms a bottleneck in the system.
Identifying modules
Modules are identified in two ways:
-
By serial number
-
By
ModuleID
.
You can obtain the ModuleID
's and serial numbers of all your modules by running the enquiry
command-line utility.
Electronic Serial Number (ESN)
The serial number is a unique 12-digit number that is permanently encoded into each module. Quote this number in any correspondence with Support.
ModuleID
The ModuleID
is an integer assigned to the module by the server when it starts.
The first module it finds is given a ModuleID
of 1, the next is given a ModuleID
of 2, and this pattern of assigning ModuleID
numbers continues for additional modules.
The order in which buses are searched and the order of modules on a bus depends on the exact configuration of the host. If you add or remove a module, this can change the allocation of ModuleIDs to all the modules on your system.
You can use the enquiry
command-line utility to identify the PCI bus and slot number associated with a module.
All commands sent to nShield modules require a ModuleID
. Many Security World Software commands, including all acceleration-only commands, can be called with a ModuleID
of 0. Such a call causes the hardserver to send the command to the first available module.
If you purchased a developer kit, you can refer to the developer documentation for information about the commands that are available on nShield modules.
In general, the hardserver determines which modules can perform a given command. If no module contains all the objects that are referred to in a given command, the server returns an error status.
However, some key-management operations must be performed together on the same module.
In such cases, your application must specify the ModuleID
.
To be able to share OCSs and keys between modules, the modules must be in the same Security World.
Adding a module
If you have a module installed, you can add further modules without reinstalling the server software.
However, we recommend that you always upgrade to the latest server software and upgrade the firmware in existing modules to the latest firmware.
-
Install the module hardware. Refer to the Installation Guide for information on installing nShield hardware.
-
Add the module to the Security World. Refer to Adding or restoring an HSM to the Security World.
Module fail-over
The Security World Software supports fail-over: if a module fails, its processing can be transferred automatically to another module provided the necessary keys have been loaded. Depending on the mode of failure, however, the underlying bus and operating system may not be able to recover and continue operating with the remaining devices.
To maximize uptime, we recommend that you fit any additional nShield modules for failover on a bus that is physically separate from that of the primary modules.
Stopping and restarting the hardserver
If necessary, you can stop the hardserver on the client, and where applicable the Remote Administration Service, by running the following command in a command window with administrative privileges:
net stop "nfast server"
If the Remote Administration Service is running, you will be warned and given the option of continuing or not.
Similarly, you can start the hardserver on the client, and where applicable the Remote Administration Service, by running the following command in a command window with administrative privileges
net start "nfast server"
net start "nfast Remote Administration Service"
You can also stop, start, or restart the hardserver, and where applicable the Remote Administration Service, from the Windows Control Panel:
-
From the Windows Start menu, open the Windows Control Panel.
-
Double-click Administrative Tools.
-
Double-click Services.
-
Locate nFast Server or nFast Remote Administration Service in the list of services, and from the Action menu, select Stop, Start, or Restart as required.
The nFast Remote Administration Service, where applicable, is dependent on the nFast Server so should be started or restarted after the nFast Server.
Resetting and testing the nShield HSM
Default configuration
To reset the unit to its default configuration, select System > System configuration > Default config and confirm that you want to set the default configuration.
This removes the configuration of the module but does not change its K
NETI.
Factory state
To reset the unit to its original (factory) state, select Factory state from the main menu and confirm that you want to return the unit to its factory state.
This gives a new K
NETI to the unit, which means that you must update the keyhash field of the unit’s entry in the nethsm_imports
section of the configuration file of all the clients that use it.
After a factory reset, ensure you re-enable any dynamic features. See Remotely enabling dynamic feature certificates including nShield HSM client licenses.
For more information about:
-
The contents of the configuration files, see Module and client configuration files
-
Configuring a new remote file system for the unit, see Configuring the Remote File System (RFS).
Testing the installation
To test the installation and configuration, follow these steps:
-
Log in on the client computer as a regular user, and open a command window.
-
Run the command:
enquiry
A successful
enquiry
command returns an output of the following form:Server: enquiry reply flags none enquiry reply level Six serial number ####-####-#### mode operational version #-#-# speed index ###### rec. queue ####..#### --- version serial # remote port (PV4) #### Module ##: enquiry reply flags none enquiry reply level Six serial number ####-####-#### mode operational version #-#-# speed index ##### rec. queue ##..### --- rec. LongJobs queue ## SEE machine type PowerPCELF supported KML types DSAp1024s160 DSAp3072s256 hardware status OK
If the mode is
operational
, the unit is installed correctly.If the
enquiry
command says that the unit is not found:-
Restart the client computer.
-
Re-run the
enquiry
command.
-