Client software and module configuration: network-attached HSMs

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

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 (for example, root) is required for such tasks as software installation, starting and stopping the hardserver and SNMP.

Windows

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

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 (Linux) or %NFAST_KMDATA%\hsm-ESN\config (Windows) 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 (Linux) or %NFAST_KMDATA% (Windows) 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 HSM, you can use the anonkneti utility to obtain the ESN and 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 (Linux) or %NFAST_KMDATA% (Windows) 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 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 (refer to the nShield Remote Administration User Guide for more information.).

Before you can use multiple clients with the nShield HSM, you must enable the additional clients as described in Optional features.

To add clients remotely:

  1. Copy the HSM configuration file, NFAST_KMDATA/hsm-ESN/config/config (Linux) or NFAST_KMDATA\hsm-ESN\config\config (Windows), to config.new in the same directory.

    The path to the new file will be NFAST_KMDATA/hsm-ESN/config/config.new (Linux) or NFAST_KMDATA\hsm-ESN\config\config.new (Windows).

  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 /opt/nfast/kmdata/hsm-ESN/config (Linux) or %NFAST_KMDATA%\hsm-ESN\config (Windows) directory 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 /opt/nfast/kmdata/config (Linux) or %NFAST_KMDATA%\config (Windows) directory 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 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 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 ESN and HKNETI of the HSM, run the command

anonkneti <ip-address>

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

  • an IPv6 address, including a link-local IPv6 address

  • 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

Client Session Resumption (Impath Resilience)

Client Session Resumption (Impath Resilience) is a mechanism which mitigates brief network disruption between the nShield HSM and the client. When the hardserver on the nShield HSM detects that the client connection is lost, it will "park" the client session for a limited time enabling it to be resumed when the network recovers. The parked session (resumable session) holds state such as the loaded keys so that applications on the client machine can resume automatically when network recovers, without the need to re-load keys or other objects.

From v13.6 of the nShield HSM image, clients that share the same IP address, for example those behind NAT (Network Address Translation), or which share the same KNETI (network authentication key) will be treated as distinct sessions and will all benefit from Client Session Resumption. This supports scenarios such as dynamically spun-up clients running in VMs or containers. Prior to v13.6, only one client session for a given client "identity" was parked and benefited from session resumption.

Client Licensing

The license model, from v13.6 of the nShield HSM image, is based on the number of concurrent client connections rather than the number of clients configured in the hs_clients section in the nShield HSM configuration file. Prior to v13.6, licenses were enforced based on the number of clients configured; from v13.6 onwards, any number of clients may be configured in the nShield HSM configuration file, independently of the license limit.

The behavior in v13.6 onwards means that clients count towards the license limit only when they are actually running.

A licensable client (also referred to as a crypto client) is a client hardserver that creates a privileged or unprivileged nCore client connection to the nShield HSM. This is typically configured by running nethsmenroll on the client machine, or editing the nethsm_imports section of the client configuration file.

The license utilization can be queried using the stattree tool. The MaxCryptoClients field reports the number of crypto clients permitted by the license. The CryptoClientCount field reports the current usage, that is the number of currently live network connections from crypto clients plus any parked sessions.

+#RemoteServers:
   +#1:
      +#ServerGlobals:
         -Uptime               1805
         -CmdCount             1604
         -CmdBytes             65724
         -CmdMarshalErrors     0
         -ReplyCount           1604
         -ReplyBytes           81512
         -ReplyMarshalErrors   0
         -ClientCount          2
         -MaxClients           2
         -DeviceFails          0
         -DeviceRestarts       0
         -CryptoClientCount    2
         -MaxCryptoClients     3

When a client session has been parked as a result of Client Session Resumption (Impath Resilience), the parked session will hold the license until either the parked session expires or a new client requires a license. If there is otherwise no license slot available for the new client, the oldest parked session will be evicted and the recovered license is given to the new client.

Sharing KNETI (network authentication key)

Sharing the KNETI key may be useful in scenarios where multiple instances of the same client configuration are spun-up such as in containers or virtual environments. For security, it is recommended to always require KNETI authentication for clients even if the IP address is static, and even if multiple instances of the same client configuration are being spun-up.

Each crypto client that connects to the nShield HSM will occupy a license, even if it shares an IP address and/or KNETI with another crypto client.

A shared KNETI network authentication key is configured in the hs_clients section of the configuration by setting the keyhash field. If the client IP address is dynamic, the addr is configured as 0.0.0.0, ::, blank or omitted. If the clients share the same IP address, for example those behind NAT (Network Address Translation), then the addr is configured with the shared IP address.

For example, clients are in containers (or virtual machines), connected to a NAT virtual network on a host, the host’s IP address is 192.30.100.100. The addr is configured with the hosts IP address as it is shared with the clients. The keyhash field is added with the client’s kneti hash, found in the response of the enquiry -m0 command, executed on the client.

[hs_clients]
addr=192.30.100.100
clientperm=permission_type
keyhash=software_keyhash

In another case, clients have dynamic IP addresses on the same network as the nShield HSM. The addr field can be removed from the hs_clients section as it is not needed. The keyhash field is required and can be shared between multiple clients.

[hs_clients]
clientperm=permission_type
keyhash=software_keyhash

For multiple clients to share the same KNETI (specified via its keyhash), they must share the same kneti-hardserver key file. This key could be from an already enrolled client and can be copied from (and to) the /opt/nfast/hardserver.d directory (Linux) or %NFAST_DATA_HOME%\hardserver.d directory (Windows, C:\ProgramData\nCipher\hardserver.d by default). The existing permissions (ACLs on Windows) and file ownership must be preserved when copying the KNETI file. If updating an existing client hardserver to use a shared kneti-hardserver file it would have to be restated; details can be found in the Stopping and restarting the hardserver section. The clients can be enrolled using nethsmenroll or by editing the nethsm_imports section of the client config file as usual; if deploying a shared configuration to a container, this configuration is likely to be prepared in advance and then included as part of the container image or mounted from the host.

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. Refer to the nShield Remote Administration User Guide for more information.

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

Restarting the nShield HSM

After configuring NTP, restart the nShield HSM, for example using nethsmadmin --module=<MODULE> --reboot (see nethsmadmin). 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 (nShield 5c)

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: remote_syslog_ip can be an IPv4 or IPv6 address.

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 HSM to send logs to a remote syslog server:

  1. Configure the remote host to receive logs from the HSM.

    For instructions, see the documentation for the operating system of the remote host.

  2. Make sure that the HSM can communicate with an RFS host so that you can push the new configuration file to the HSM. See Basic HSM, RFS and client configuration in the Installation Guide for your HSM.

  3. If your HSM configuration file predates the functionality to send logs to a remote syslog server, manually create the remote_sys_log section in the config file for the remote module.

  4. In the remote_sys_log section, add the following settings:

    remote_sys_log_ip=REMOTE_SYSLOG_SERVER_IP
    remote_sys_log_port=REMOTE_SYSLOG_SERVER_PORT
  5. Run the following command to push the new config file to the HSM:

    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 an 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 HSM but the HSM will reject 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.

Set 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), see Client cooperation.

Useful utilities

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.

Linux

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

You can set Security World Software-specific environment variables as follows:

  1. Open the System dialog by clicking System in the control panel menu.

  2. Select the Advanced tab and click the Environment Variables button.

  3. To add a variable, click New. Alternatively, to edit an existing variable select an entry in the System Variables list and click Edit.

  4. In the Variable Name field, type or edit the name of the environment variable (for example, NFAST_HOME).

  5. In the Variable Value field, type or edit the value to use.

  6. Click the OK button to set the value, and then click the OK button to close the dialog.

  7. Open the Administrative Tools dialog by clicking the Administrative Tools icon in the Control Panel

  8. Open the Services console by clicking the Services icon.

  9. From the displayed list of services, select the nFast Server icon, and select Restart the service.

Logging and debugging

Network-attached HSMs: You can view logs generated by the nShield HSM and applications that use it on 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. On network-attached HSMs, debugging information for applications is handled on the client.

If you are setting up the unit or the client 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 v13.6.3 HSM User Guide) 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 (refer to the nShield Remote Administration User Guide for more information.).

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.

For guidance on selecting a password, see the nShield Security Manual.

nShield 5c: You must enter a new password. You cannot reuse admin the first time you change the password.

Once you are successfully logged in to a serial console session you will see the welcome message:

Welcome to the nShield HSM 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

cs5

Configures CodeSafe functionality on the nShield 5c

date

Get/set the HSM system time

enquiry

Prints enquiry data from the HSM

esn

Show the Electronic Serial Number (ESN) of the HSM

expose

Get/set the expose NIC nethsm_settings configuration

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

hsmdiagnose

Runs hsmdiagnose on the embedded HSM

kneti

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

ks5agent

Manage the KeySafe 5 agent

Configure and enable a KeySafe 5 agent on this Connect to report to a central KeySafe 5 management platform

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

watchdog

Get/set the nethsm_watchdog configuration

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.

  2. (Linux) Run the script /opt/nfast/sbin/install.

  3. 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. On Windows, this must be a command window with administrative privileges.

Linux
/opt/nfast/sbin/init.d-ncipher stop
Windows
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. On Windows, this must be a command window with administrative privileges.

Linux
/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
Windows
net start "nfast server"
net start "nfast Remote Administration Service"

On Windows, you can also stop, start, or restart the hardserver, and where applicable the Remote Administration Service, from the Windows Control Panel:

  1. From the Windows Start menu, open the Windows Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Services.

  4. 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 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. sign in to the client computer as a regular user, and open a command window.

  2. Run the command:

    Linux
    opt/nfast/bin/enquiry
    Windows
    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.