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 three levels of user:

  • Superuser

  • nfast group user

  • normal

Typically, normal users can carry out operations involving Security Worlds, cardsets and keys, but not create Security Worlds, keys and cardsets. nfast group users have enhanced access, enabling them to create Security Worlds, cardsets and keys. For example, encrypted copies of keys are held in kmdata (/opt/nfast/kmdata). Normal users only have read access to the files, whereas nfast group users have read and write access, enabling them to create and use keys. nfast group users can also change the mode of an HSM remotely.

Superuser access (e.g., root) is required for such tasks as software installation, starting and stopping the hardserver and SNMP

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 /opt/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

config

The master configuration file. This contains the current configuration for the HSM. It is always present in the directory.

config-name

An alternative configuration file saved by the system.

config.new

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:

  1. 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

  2. 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.

  3. 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.

  4. When the network interface and port are correct, press the right-hand navigation button.

  5. Press the right-hand navigation button again to continue.

  6. 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 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 KNETI key (HKNETI). The KNETI 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 KNETI 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 KNETI 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:

  1. 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 KNETI key.

  2. 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

  3. 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.

  4. 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.

  5. 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

    1. 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.

    2. Select Yes and press the right-hand navigation button to configure the RFS with secure authentication.

  6. 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

    1. The ESN of the nToken installed in the RFS.

    2. "Software Key" for software-based authentication.

    If no nToken is installed in the RFS, then software-based authentication is automatically selected.

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

  8. 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 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:

  1. Log to store log files on the HSM only.

  2. 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:

  1. 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

  2. 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

  3. 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

  4. 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:

  1. 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.

  2. 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

  3. 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.

  4. 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

    1. 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.

    2. Select Yes and press the right-hand navigation button to configure the client with secure authentication.

  5. 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

  6. 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

    1. The ESN of the nToken installed in the client.

    2. "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.

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

  8. 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:

  1. Copy the HSM configuration file NFAST_KMDATA/hsm-ESN/config/config to config.new in the same directory.

    The path to the new file will be: NFAST_KMDATA/hsm-ESN/config/config.new .

  2. Add a new entry to config.new in the hs_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 or 0.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 or priv_lowport).

    1. 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 and nToken_keyhash is the hash of the key that the client’s nToken should authenticate itself with.

    2. 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. The ESN 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.

  3. 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 /opt/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 /opt/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 and privileged. The default value for remote_keyhash (40 zeros) specifies that no authentication should occur.

  • The ESN and hash of the HSM to import can be retrieved by running the command

    anonkneti 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 field ntoken_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.

  1. 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>

  2. 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

nethsmenroll

This utility is used to configure the client to communicate with the nShield HSM.

config-serverstartup

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

-m|--module=MODULE

Specifies the local HSM number to use (default is 0 for dynamic configuration by hardserver).

-p|--privileged

Causes the hardserver to request a privileged connection to the nShield HSM (default unprivileged).

-<hsm-ip>

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.

-r|--remove

Deconfigures the specified nShield HSM.

-f|--force

Forces reconfiguration of an nShield HSM already known.

--no-hkneti-confirmation

Does not request confirmation when automatically determining the nShield HSM’s ESN and HKNETI

This option is potentially insecure and should only be used on secure networks where there is no possibility of a man-in-the-middle attack. For guidance on network security, see the nShield Security Manual.

-V|--verify-nethsm-details

When the ESN and HKNETI have been provided on the command line, verifies that the selected HSM is alive, reachable and matches those details.

-P|--port=PORT

Specifies the port to use when connecting to the given nShield HSM (default 9004).

-n|--ntoken-esn=ESN

Specifies the ESN of the nToken to be used to authenticate this client. If the option is omitted, then software authentication will be used instead.

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:

Using the NTP configuration tool

NTP is configured using the cfg-pushntp utility on a client computer.

Utility Description

cfg-pushntp

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.

The new NTP settings will take effect the next time the target nShield HSM is restarted.

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

Enable or disable NTP service on the nShield HSM.

-a|--address=ADDR

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.

-p|--port=PORT

Set port to use to connect to the nShield HSM (default=9004).

-k|--use-kneti

Use KNETI to authenticate ourselves.

-m|--module=MODULE

Set the HSM to use for KNETI authentication. The default is HSM 1. This option can only be used with the --use-kneti option

-1|--ntp1=ADDR

IP address of NTP server. This can be an IPv4 or an IPv6 address.

-2|--ntp2=ADDR

IP address of NTP server. This can be an IPv4 or an IPv6 address.

-3|--ntp2=ADDR

IP address of NTP server. This can be an IPv4 or an IPv6 address.

For example, running the command:

cfg-pushntp --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:

  1. Reset the HSM to factory state using the UI (menu: 1-5). See

  2. Assign an IPv6 address to the HSM on interface #1 (eth0).

    For example: fd01:11::260:e0ff:fe81:4ac1.

  3. 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.

  4. 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>

  5. 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

  6. 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

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

  8. Ensure that auto-push is enabled on the HSM. If auto-push is not enabled, cfg-pushntp reports an UnknownHostVolume error.

    1. Toggle auto-push on:

      System > System configuration > Config file options > Setup auto push > Yes

    2. Add the RFS IPv6 address:

      System > System configuration > Config file options

  9. 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.

  10. Install NTP on the RFS.

    For an Ubuntu 18.04 host:

    1. Run the following command:

      sudo apt install ntp

    2. 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

    3. Restart the NTP service:

      sudo service ntp restart

    4. Verify that the service successfully restarted and is running:

      sudo service ntp status

    5. Check that the firewall is not blocking UDP and TCP ports 123.

  11. 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

  12. 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

  13. 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:

  1. 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

  2. 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:

  1. 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 nToken KNETI 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 module KNETI key used by the client.

    • For every unauthenticated client (with write access but without KNETI authorization), run the command:

      rfs-setup --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 without KNETI authorization.

      To limit a gang-client to read-only, use the --readonly flag.

  2. 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 KNETI 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 KNETI 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 software KNETI 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 the ESN and hash of the KNETI 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=/opt/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=/opt/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 KNETI 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 opt/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 then rfs-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 in the file /etc/nfast.conf. This file is not created by the installation process: you must create it yourself. /etc/nfast.conf is executed by the start-up scripts of nShield HSM services as the root user. This file should only contain shell commands that can safely be run in this context. /etc/nfast.conf should be created with access permissions that allow only the root user to write to the file.

Ensure that all variables are exported as well as set.

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:

  1. 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

  2. Enter the IP address of the remote host.

  3. Press FINISH to issue the ping. The following message appears:

    Please wait, running ping

  4. 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.

  5. 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.

  1. 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

  2. Press the right-hand navigation button to issue the traceroute. The following message appears:

    Please wait, running traceroute.

  3. 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.

  4. 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:

  1. 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.

  2. 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 (Linux)) 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.

Console serial port

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:

  1. Copy the config file to config.new.

  2. 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

  3. Edit the baud_map value.

  4. Push config.new to the HSM using cfg_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

date

Get/set the HSM system time

enquiry

Prints enquiry data from the HSM

esn

Show the Electronic Serial Number (ESN) of the HSM

factorystate

Reset unit to its original (factory) state

This will reset the IP and serial console settings

gateway

Get/set the default IPv4 gateway address

gateway6

Get/set the default IPv6 gateway address

getrtc

Get the real time clock (RTC) of the nShield 5c

Only available on the nShield 5c

help or ?

List available commands with help or detailed help with help cmd

kneti

Show the (hash of) Kneti (used for enrolling the HSM with clients)

logs

Print nShield 5c diagnostic logs

Only available on the nShield 5c

logout

Log out of the nShield HSM Serial Console

maintmode

Enable/disable maintenance mode

Only available on the nShield 5c

netcfg

Get/set the IPv4 network interface configuration

netcfg6

Get/set the IPv6 network interface configuration

netdiagnose

Print network interface statistics

netenable

Enable IPv6

netlink

Get/set the network interface link, get the network interface MAC address

bondcfg

Get/set the HSM bond interface configuration

bondlink

Get/set the bond interface link

passwd

Set the serial console password

ping

Ping a remote host

push

Get/set the config push setting

reboot

Reboot the HSM

rfsaddr

Get/set the RFS IP address, port, optional secure authentication and push mode

route

Get/set IPv4 network routes

route6

Get/set IPv6 network routes

routing

Show the IPv4 routing table

routing6

Show the IPv6 routing table

setrtc

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 maintmode

stattree

Run the stattree command

sworldcheck

Check for any Security World data on the HSM

tamperlog

Show the nShield HSM tamper log

uptime

Show how long the nShield HSM has been running (since last boot)

version

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.

  1. Install the module hardware. Refer to the Installation Guide for information on installing nShield hardware.

  1. Run the script /opt/nfast/sbin/install.

  2. 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:

/opt/nfast/sbin/init.d-ncipher stop

Similarly, you can start the hardserver on the client, and where applicable the Remote Administration Service, by running the following command

/opt/nfast/sbin/init.d-ncipher start

You can also restart the hardserver on the client, and where applicable the Remote Administration Service, by running the following command:

/opt/nfast/sbin/init.d-ncipher restart

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 KNETI.

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 KNETI 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:

Testing the installation

To test the installation and configuration, follow these steps:

  1. Log in on the client computer as a regular user, and open a command window.

  2. Run the command:

    opt/nfast/bin/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:

    1. Restart the client computer.

    2. Re-run the enquiry command.