HSM and client configuration files

This appendix describes the configuration files that store the current configuration of an nShield HSM or client.

The module configuration files are stored on the internal file system of the nShield HSM. They are updated automatically when the nShield HSM is configured from the front panel. The configuration files are also exported automatically to the remote file system, where they can be edited manually and reloaded on the nShield HSM, if required. For more information, see Client Software and module configuration.

The client configuration files are stored in the client’s file system. The client’s hardserver can also be set up using environment variables. Environment variable settings override settings in the client configuration files. For more information, see Setting environment variables.

Location of client configuration files

The client configuration files are in opt/nfast/kmdata/config/ (Linux) or %NFAST_KMDATA%\config (Windows) on the client computer’s file system. This directory can contain the following files:

File Description

config

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

config-default

The default configuration file. This can be used to restore factory settings for the client. It is created by the cfg-mkdefault utility.

You can also save backup copies of configuration files in this directory.

Location of module configuration files

When you configure the nShield HSM from the front panel, the configuration files are exported automatically to the remote file system defined in the rfs_client section of the module configuration. The exported files are in /opt/nfast/kmdata/hsm-ESN/config (Linux) or %NFAST_KMDATA%\hsm-ESN\config (Windows).

In this path, ESN is the electronic serial number of the network nShield HSM from which the files were exported. This directory contains the master configuration file config, which specifies the current configuration for the nShield HSM. It is always present in the directory.

The remote file system information is also contained in the client configuration file section remote_file_system.

Structure of configuration files

The configuration files are text files. They must contain only characters with ASCII values between 32 and 127, and the tab, line break, and return characters.

Lines starting with one or more number sign characters (#) are comments and are ignored. Some comments that document the configuration options are generated by the configuration process. You can add your own comments, but in some cases they may later be overwritten.

A configuration file begins with a single line that specifies the version of the file syntax. This syntax-version line has the format:

syntax-version=n

In this syntax-version line example, n represents the version of the syntax in which the file is written. The system can process a file with a lower syntax version than the one it uses, but not one with a higher version.

After the syntax-version line, the rest of the configuration file consists of sections that can be edited to control different aspects of nShield HSM or client behavior. Each section begins with its name in square brackets, as in this example:

[slot_imports]

Module configuration files and client configuration files have some sections in common, and some specific to the type of file:

Both Module file only Client file only

server_settings

nethsm_settings

module_settings

server_remotecomms

server_remotecomms_ipv6

nethsm_eth

nethsm_eth_ipv6

server_performance

server_startup

nethsm_gateway

nethsm_gateway_ipv6

nethsm_imports

load_seemachine

nethsm_bond

rfs_sync_client

slot_imports

nethsm_route

nethsm_route_ipv6

remote_file_system

slot_exports

nethsm_eth1_enable

remote_administration_service_startup

dynamic_slots

nethsm_bond_enable

slot_mapping

nethsm_enable

dynamic_slot_timeouts

cosmod

auditlog_settings

hs_clients

rfs_client

sys_log

remote_sys_log

config_op

ui_lockout

You can update the parameters defined in most of these sections to configure the way that the hardserver handles secure transactions between the nShield HSM and applications that run on the client.

Some sections are updated automatically and should not be edited manually. For more information, see the descriptions of individual sections.

In each section, the bracketed name is followed by a specified set of fields. Each field is on a separate line. Each field begins with its name, followed by an equals sign (=) and a value of the appropriate type. White space can be included at either end of the line (for example, in order to indent lines as an aid to clarity).

Some types of field are grouped into entries. An entry is a set of fields of different types that define an instance of an object (for example, a particular client as distinct from other clients). Entries in the same section are separated by a line that contains one or more hyphens (-). Blank lines and comments are allowed between the fields in an entry.

Strings are case sensitive in the section names and field names.

Multiple clients can be added to one configuration file by separating each client entry from the next with a line consisting of one or more hyphens.

If a particular section is not present in the configuration file, it is assumed to have no entries.

Sections only in module configuration files

nethsm_settings

The nethsm_settings section defines settings specific to the nShield HSM. The section contains the following fields:

Field Description

enable_impath_resilience

When set to the default yes value, this field enables impath resilience for the module. Setting this field to no disables impath resilience.

impath_resilience_timeout

This field specifies the interval of time that must pass for a resumable impath resilience session to expire. In the event of network errors, clients can reconnect and resume use of keys and other loaded objects until the specified interval has passed (after which all previously loaded objects must be reloaded).

Specify this interval either in the form N t, where N is an integer and t is s for seconds, m for minutes, h for hours, d for days, or w for weeks, or as never (in which case sessions never expire). If you specify N but not t, the seconds are assumed. The default setting is 3600 for 3,600 seconds.

expose_nic_status

When set to the yes value, this field enables NIC details in the stattree output. Setting this field to default no disables NIC details.

expose_nic_addresses

When set to the yes value, this field enables NIC addresses in the stattree output, only if expose_nic_status is enabled. Setting this field to default no disables NIC addresses.

nethsm_eth

The nethsm_eth section defines the Ethernet interfaces for IPv4 for the nShield HSM. Each interface is defined by an entry as follows:

Field Description

iface

The identifier for the interface. This value must be 1 or 0.

addr

The IP address of the nShield HSM. The default is 0.0.0.0.

netmask

The net mask for the nShield HSM. The default is 0.0.0.0.

gateway

This field is retained for backwards compatibility only. The IP address of the gateway is stored in the nethsm_gateway section and this field is set to 0.0.0.0.

linkspeed

This field specifies the link speed setting. It can be one of auto/1Gb (nShield 5s only), 10BaseT, 10BaseT-FDX, 100BaseTX, or 100BaseTX-FDX.

We recommend that you accept the default auto/1Gb or auto setting. On the nShield HSM, this setting can auto-negotiate 1Gb Ethernet.

nethsm_eth_ipv6

The nethsm_eth_ipv6 section defines the Ethernet interfaces for IPv6 for the nShield HSM. Each interface is defined by an entry as follows:

Field Description

iface

The identifier for the interface. This value must be 1 or 0.

addr

The static IPv6 address for this interface. The default is ::. If SLAAC is enabled, this address is ignored.

netmask

The subnet prefix length of the static IPv6 address for the interface. The default is 64.

nethsm_gateway

The nethsm_gateway section defines the default IPv4 Ethernet gateway for the nShield HSM. There is one field, as follows:

Field Description

gateway

The IPv4 address of the gateway for the nShield HSM. The default is 0.0.0.0.

nethsm_gateway_ipv6

The nethsm_gateway_ipv6 section defines the default IPv6 Ethernet gateway for the nShield HSM. There is one field, as follows:

Field Description

gateway

The IPv6 address of the gateway for the nShield HSM. The default is ::.

linklocal_if

The ethernet interface (0 or 1) to use if the IPv6 default gateway address is a link-local address. The information is not used if the IPv6 default gateway is not a link-local address (default 0).

nethsm_bond

The nethsm_bond section defines the HSM bond interface, used for network bonding. The bond interface’s address and netmask configuration are inherited from the eth0 (iface=0) configuration. Each entry has the following fields:

Field Description

mode

Possible values:

  • 802.3ad

  • active-backup Default: 802.3ad.

miimon

The MII link monitoring frequency in milliseconds.

Range: 0 - 10000.

Default: 100.

primary

Primary device. The specified device will always be the active slave while it is available.

Possible values:

  • eth0

  • eth1

Default: eth0.

Only valid for active-backup mode.

resend_igmp

The number of IGMP membership reports to be issued after a failover event.

Range: 0 - 255.

Default: 1.

A value of 0 prevents the IGMP membership report from being issued in response to the failover event.

Only valid for active-backup mode.

lacp_rate

The rate in which the Ethernet interface asks the link partner to transmit LACPDU packets in 802.3ad mode.

Possible values:

  • slow

  • fast

Default: slow.

Only valid for 802.3ad mode.

xmit_hash_policy

The transmit hash policy to use for slave selection in 802.3ad mode.

Possible values:

  • layer2

  • layer2+3

  • encap2+3

Default: layer2.

The process of network bonding, including all the fields above, are described in https://www.kernel.org/doc/Documentation/networking/bonding.txt.

nethsm_route

The nethsm_route section defines the static IPv4 routes for the nShield HSM. Each route is defined by an entry as follows:

Field Description

addr

The IPv4 address of the route destination. The default is 0.0.0.0.

masklen

The length to mask for the route.

gateway

The IPv4 address of the gateway for the route. The default is 0.0.0.0.

nethsm_route_ipv6

The nethsm_route_ipv6 section defines the static IPv6 routes for the nShield HSM. Each route is defined by an entry as follows:

Field Description

addr

Routable IPv6 address block. The default is ::.

masklen

The number of bits to mask for the subnet address prefix, that is, the number in the range of 1 to 128) after the / of an address in CIDR format. The default is 64.

gateway

Route gateway. The default is ::.

linklocal_if

The ethernet interface (0 or 1) to use if the IPv6 default gateway address is a link-local address. The information is not used if the IPv6 default gateway is not a link-local address (default 0).

nethsm_eth1_enable

The nethsm_eth1_enable section defines if the eth1 interface is enabled.

Field Description

enable

The indicator of whether the eth1 interface is enabled or disabled (default 'no').

nethsm_bond_enable

The nethsm_bond_enable section defines if the bond interface is enabled.

Field Description

enable

The indicator of whether the bond interface is enabled or disabled (default 'no').

nethsm_enable

The nethsm_enable section defines whether IPv4 and or IPv6 are enabled or disabled for the interfaces of the unit. The enable fields are:

Field Description

iface

The ethernet interface (0 or 1) to which the following fields apply.

enable_ipv4

Indicator of whether the IPv4 protocol on the interface is enabled (default: yes).

enable_ipv6

Indicator of whether the IPv6 protocol on the interface is enabled (default: no).

ipv6_conf_addr

Indicator of whether the interface uses IPv6 static addresses (static) or SLAAC (slaac). The default is static.

cosmod

The cosmod section defines the input configuration for the nShield HSM. The configuration is defined by an entry as follows:

Field Description

keymap

The selected layout for the keyboard connected to the nShield HSM front panel. This value is either UK or US.

rfs_client

The rfs_client section defines the remote file system where the module configuration is backed up and the master copy of the Security World data is located, as follows:

Field Description

remote_ip

The IP address of the RFS.

remote_port

The port number on which the RFS hardserver is listening.

remote_keyhash

Software or module KNETI hash used to authenticate the RFS, or 40 zeroes to indicate no authentication required (default is 40 zeroes).

remote_esn

ESN of the remote module used to authenticate the RFS, or empty when using software KNETI authentication or no authentication required (default is empty).

push

Whether to allow the RFS to push configuration files to the nShield HSM:

  • ON: This effectively allows the RFS to remotely configure the nShield HSM, and also to act as an additional privileged cryptographic client above the client licence limit.

  • OFF: This does not allow the RFS to remotely configure the nShield HSM.

  • AUTO (default): If the remote_keyhash field is set to a non-zero hash, behaviour shall be as though ON was set. If the remote_keyhash field is the all-zeroes hash, behaviour shall be as though OFF was set.

sys_log

The sys_log section defines how the nShield HSM logging works:

Field Description

behaviour

The way the log is written. How the log is written is decided by setting either of the following:

  • log

  • push

If log is set, the log is written only to the file system of the nShield HSM. It is lost if the nShield HSM is rebooted. Logging stops when the file system is full. If push is set, the log is automatically appended to the log file in the RFS or remote syslog server at the interval specified in push_interval.

push_interval

The number of minutes between the log being appended when behaviour is set to push. The default is 60. The minimum is 1.

remote_sys_log

The remote_sys_log section defines a remote syslog server to send the nShield HSM logging (system.log and hardserver.log) to. It can be an IPv4 or an IPv6 address.

Field Description

remote_syslog_ip

The IP address of the remote syslog server to send logs to. The default is 0.0.0.0.

remote_sys_log_port

The UDP port of the remote syslog server to send logs to. The default is 514.

config_op

The config_op section defines whether a client computer is allowed to update the module configuration automatically (to push a configuration) from files on the client:

Field Description

push

Whether the client is allowed to push configuration files to the nShield HSM. This is decided by setting one of the following:

  • ON

  • OFF

If on, the client specified in the remote_ip section is allowed to update the configuration of the nShield HSM remotely.

remote_ip

The IP address of the client that is allowed to push config files. If no value is set, or if it is set to 0.0.0.0 or ::, any IP address can push on a new config file.

remote_keyhash

The hash of the key with which the authorized client is to authenticate itself, or (as the default) 40 zeros to indicate no key authentication required.
The default value for remote_keyhash (40 zeros) specifies that no authentication should occur. We recommend specifying a key hash in place of this default.

ui_lockout

The ui_lockout section defines whether you can lock the nShield HSM using login settings.

To be compatible with UI lockout, the OCS card(s):

  • Must be persistent.

  • Must not be remoteable.

  • Do not need a passphrase, but if a passphrase is configured, it has to be used.

Field Description

lockout_mode

Controls front panel access to the nShield HSM. Set to:

  • locked

    Enables UI lockout without requiring a logical token.

  • locked_lt

    Enables UI lockout with a logical token (OCS) (requires a valid ltui_hash to be set).

  • unlocked

    No UI lockout (default).

ltui_hash

The hash of the logical token (LTUI) required to authorize access to the nShield HSM menu structure when lockout_mode is set to locked_lt.

panel_poweroff

This controls the function of the Power button on the nShield HSM front panel when it is in operational mode. The default setting of yes enables the Power button. When set to no, the Power button is disabled.

Sections in both module and client configuration files

server_settings

The server_settings section defines the settings for the client hardserver you can modify while the hardserver is running.

These flags are used by the NFLOG_DETAIL environment variable (see Environment variables to control logging).

The section contains the following fields:

Field Description

loglevel

This field specifies the level of logging performed by the hardserver.

See hardserver loglevel and Logging, debugging, and diagnostics.

logdetail

This field specifies the level of detail logged by the hardserver. You can supply one or more flags in a space-separated list. For more information about the flags, see the table below.

connect_retry

This field specifies the number of seconds to wait before retrying a remote connection to a client hardserver. The default is 10.

connect_maxqueue

This field specifies the maximum number of jobs which can be queued on the hardserver. The default is 4096: this is also the maximum value. Setting connect_maxqueue to a high value allows high throughput, but may cause long latency if the hardserver goes down.

connect_broken

This field specifies the number of seconds of inactivity allowed before a connection to a client hardserver is declared broken. The default is 90.

connect_keepalive

This field specifies the number of seconds between keepalive packets for remote connections to a client hardserver. The default is 10.

accept_keepidle

This field specifies the number of seconds before the first keepalive packet for remote incoming connections. The default is 30. Ideally, accept_keepalive should be at least twice the value of the connect_keepalive setting on the unattended machines.

accept_keepalive

This field specifies the number of seconds between keepalive packets for remote incoming connections. The socket will be closed after up to ten consecutive probe failures. The default is 10.

Ideally, accept_keepalive should be a value such that (10 * accept_keepalive) > connect_broken on the unattended machine. Using the default values for both these fields will fulfil this requirement.

connect_command_block

When the nShield HSM has failed, this field specifies the number of seconds the hardserver should wait before failing commands directed to that HSM with a NetworkError message. For commands to have a chance of succeeding after the nShield HSM has failed this value should be greater than that of connect_retry. If it is set to 0, commands to an nShield HSM are failed with NetworkError immediately. The default is 35.

max_pci_if_vers

This field specifies the maximum PCI interface version number. If max_pci_if_vers is set to 0 (the default), there is no limit.

enable_remote_mode

If this field is set to yes (the default value) in the module configuration file, nShield HSM mode changing using the nopclearfail utility is enabled. If set to no, mode changing using the nopclearfail utility is disabled.

Do not set enable_remote_mode in the client configuration file.

enable_remote_reboot

If this field is set to yes (the default value) in the module configuration file, the nShield HSM remote reboot using the nethsmadmin utility is enabled. If set to no, remote reboot using the nethsmadmin utility is disabled. Run cfg-pushnethsm to push the new config file to the module.

enable_remote_upgrade

If this field is set to yes (the default value) in the module configuration file, the nShield HSM remote upgrade using the nethsmadmin utility is enabled. If set to no, remote upgrade using the nethsmadmin utility is disabled. Run cfg-pushnethsm to push the new config file to the module.

These flags are those used by the NFLOG_DETAIL environment variable (see Environment variables to control logging).

You can supply a number of flags with the logdetail field, which specifies the level of detail logged by the hardserver (see the table above). Supply the flags in a space separated list:

Flag Description

external_time

This flag specifies the external time (that is, the time according to your machine’s local clock) with the log entry.

external_date

This flag specifies the external date (that is, the date according to your machine’s local clock) with the log entry.

external_tid

This flag specifies the external thread ID with the log entry.

external_time_t

This flag specifies the external time_ti (that is, the time in machine clock ticks rather than local time) with the log entry.

stack_backtrace

This flag specifies the stack backtrace with the log entry.

stack_file

This flag specifies the stack file with the log entry.

stack_line

This flag specifies the message line number in the original library. This flag is likely to be most useful in conjunction with example code we have supplied that has been written to take advantage of this flag.

msg_severity

This flag specifies the message severity (a severity level as used by the NFLOG_SEVERITY environment variable) with the log entry.

msg_categories

This flag specifies the message category (a category as used by the NFLOG_CATEGORIES environment variable) with the log entry.

msg_writeable

This flag specifies message writeables, and extra information that can be written to the log entry, if any such exist.

msg_file

This flag specifies the message file in the original library. This flag is likely to be most useful in conjunction with example code we have supplied that has been written to take advantage of this flag.

msg_line

This flag specifies the message line number in the original library. This flag is likely to be most useful in conjunction with example code we have supplied that has been written to take advantage of this flag.

options_utc

This flag showing the date and time in UTC (Coordinated Universal Time) instead of local time.

unix_file_descriptor_max

This field sets the number of file descriptors the hardserver must be capable of having open concurrently on Linux. The value must be an integer. If unix_file_descriptor_max is set to 0 (the default), the value will be ignored by the hardserver. If it is set to a positive value, the hardserver will refuse to start if the file descriptor hard limit on the system is less than that value. This configuration entry can be used to make sure that the hardserver is capable of satisfying the maximum number of hardserver connections that applications may make use of.

hardserver loglevel

The table in this section describes the loglevels in increasing order of severity. If you set a custom [server_settings]/loglevel, you will get that level and all the more severe levels.

If the legacy NFAST_SERVERLOGLEVEL debug environment variable is set, it overrides any loglevel value set in the configuration file.

[server_settings]/loglevel value Appears in the hardserver log as Description

info

Information

Report about the hardserver start-up configuration, connections that have been established or closed. General information for nShield Support for debugging.

notice

Notice

Report about certain start-up events, some non-fatal and routine errors that the hardserver can handle internally.

client

Detected error in client behaviour

Malformed or invalid messages are received from a client, typically from a local client.

remoteserver

Remote server error

Malformed messages or protocol errors are received while communicating with remote peers over the nCipher Secure Transport/Impath protocol.

error

Nonfatal error

Unexpected but handled errors from system calls, for example for device or TCP I/O.

serious

Serious error, trying to continue

Unexpected errors from system calls, but they are more serious and likely to indicate an issue somewhere in the system.

internal

Serious internal error, trying to continue

Possible bug in the hardserver, but it might also be an issue in the environment the hardserver is running in.

startup

Fatal error during startup

The hardserver could not start, for example because of an invalid configuration file or because it cannot bind to a TCP socket which is already in use. The hardserver will abort.

fatal

Fatal runtime error

Fatal error usually referring to a non-ignorable error that has occurred after startup such as out of memory errors in certain contexts. Rarely used. The hardserver will abort.

fatalinternal

Fatal internal error

A non-recoverable failure occurred, for example certain internal self-consistency checks to detect program logic errors. The hardserver will abort.

server_remotecomms

The server_remotecomms section defines the remote IPv4 communication settings for the client hardserver. These are read only at hardserver start-up.

Any changes made to these fields in the HSM config file should be followed by a reboot of the nShield HSM.

It is not recommended that the port number be changed. If it is changed, the port number must match in the configuration of peers. For example, if the port number is changed in the nShield HSM configuration, the remote_port field of the nethsm_imports section of the client-side hardserver config file must be updated to match. The port number can also be specified with the -P parameter when running nethsmenroll.

This section contains the following fields:

Field Description

impath_port

This field specifies the port on which the hardserver listens for incoming impath connections. The default is 9004. Setting this field to 0 specifies that the hardserver does not listen for incoming connections (do not set to 0 on an nShield HSM).

Make sure that firewall settings are consistent with port settings.

If you change this field you will need to re-enroll your client with the new port value, see Enrolling the client from the command line.

impath_addr

This field specifies the IPv4 address at which the hardserver listens for incoming impath connections. If this field is set to inaddr_any (which is the default), the hardserver listens on all IP addresses.

impath_interface

This field specifies a string representing the name of the Ethernet interface on which the hardserver listens. This field is only examined if impath_addr is set to inaddr_any.

By default, the impath_interface field is empty, which means that the hardserver listens on all interfaces. If the string is not recognized as the name of one of the interfaces of the nShield HSM, the hardserver does not listen.

server_remotecomms_ipv6

The server_remotecomms_ipv6 section defines the remote IPv6 communication settings for the client hardserver. These are read only at hardserver start-up.

Any changes made to these fields in the HSM config file should be followed by a reboot of the nShield HSM.

It is not recommended that the port number be changed. If it is changed, the port number must match in the configuration of peers. For example, if the port number is changed in the nShield HSM configuration, the remote_port field of the nethsm_imports section of the client-side hardserver config file must be updated to match. The port number can also be specified with the -P parameter when running nethsmenroll.

This section contains the following fields:

Field Description

impath_port

This field specifies the port on which the hardserver listens for incoming impath connections. The default is 9004. Setting this field to 0 specifies that the hardserver does not listen for incoming connections (do not set to 0 on an nShield HSM).

Make sure that firewall settings are consistent with port settings.

If you change this field you will need to re-enroll your client with the new port value, see Enrolling the client from the command line.

impath_addr

This field specifies the IPv6 address at which the hardserver listens for incoming impath connections. If this field is set to :: (which is the default), the hardserver listens on all IP addresses.

impath_interface

This field specifies a string representing the name of the Ethernet interface on which the hardserver listens. This field is only examined if impath_addr is set to ::.

By default, the impath_interface field is empty, which means that the hardserver listens on all interfaces. If the string is not recognized as the name of one of the interfaces of the nShield HSM, the hardserver does not listen.

Setting this field to 0 will disable IPv6 in the hardserver.

server_startup

The server_startup section defines the settings for the hardserver that are loaded at start-up. Any changes you make to the settings in this section do not take effect until after you restart the hardserver. For more information, see Stopping and restarting the client hardserver.

The section contains the following fields:

Field Description

unix_socket_name

This field is not used on Windows.

On Linux, this field specifies the name of the socket to use for non-privileged connections. The default is /dev/nfast/nserver. If the NFAST_SERVER environment variable is set, it overrides any value set for unix_socket_name in the hardserver configuration file. For more information about environment variables, see Environment variables.

unix_privsocket_name

This field is not used on Windows.

On Linux, this field specifies the name of the socket to use for privileged connections. The default is /dev/nfast/privnserver. If the NFAST_PRIVSERVER environment variable is set, it overrides any value set for unix_privsocket_name in the hardserver configuration file.

nt_pipe_name

This field specifies the name of the pipe to use for non-privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\crypto.

If the NFAST_SERVER environment variable is set, it overrides any value set for nt_pipe_name in the hardserver configuration file.

This field is not used on Linux.

nt_pipe_users

This field specifies the name of the user or group who is allowed to issue non-privileged connections on Windows. If this field is empty (which is the default), any user can make non-privileged connections. User or group names must be specified unqualified (for example, bob not MYDOMAIN\bob or bob@MYDOMAIN ).

This field is not used on Linux.

nt_privpipe_name

This field specifies the name of the pipe to use for privileged connections on Windows. An empty string specifies none. The default is \\.\pipe\privcrypto.

If the NFAST_PRIVSERVER environment variable is set, it overrides any value set for nt_privpipe_name in the hardserver configuration file.

This field is not used on Linux.

nt_privpipe_users

This field specifies the name of the user or group who is allowed to make privileged connections on Windows. If this field is empty (which is the default), only processes running with local administrator privilege can make privileged connections. User or group names must be specified unqualified (for example, bob not MYDOMAIN\bob or bob@MYDOMAIN ).

This field is not used on Linux.

nonpriv_port

This field specifies the port on which the hardserver listens for local non-privileged TCP connections. The value 0 (which is the default) specifies none.

Make sure that your network firewall settings are correct. See the Installation Guide for more about firewall settings.

If the NFAST_SERVER_PORT environment variable is set, it overrides any value set for nonpriv_port in the hardserver configuration file.

priv_port

This field specifies the port on which the hardserver listens for local privileged TCP connections. The value 0 (which is the default) specifies none. Java clients default to connecting to port 9001.

If the NFAST_SERVER_PRIVPORT environment variable is set, it overrides any value set for priv_port in the hardserver configuration file.

load_seemachine

The load_seemachine section of the hardserver configuration file defines SEE machines that the nShield HSMs connected to the client should load and, if required, start for use by other clients. Each SEE machine is defined by the following fields:

Field Description

module

This field specifies the nShield HSM on to which to load the SEE machine. The value must be an integer. A nShield HSM with this ID must be configured on the client computer.

machine_file

This field specifies the file name of the SEE machine.

userdata

This field specifies the userdata file name to pass to the SEE machine on start-up. If this field is blank (" "), the SEE machine is loaded but not started. By default, this field is blank.

worldid_pubname

This field specifies the PublishedObject name to use for publishing the KeyID of the started SEE machine. If this field is blank (" "), the KeyID is not published. This field is ignored if the value of the userdata field is blank.

postload_prog

This field specifies the program to run after loading the SEE machine in order to perform any initialization required by the SEE machine or its clients. The specified program must accept an argument of the form -m module#.

To run see-sock-serv directly on the nShield HSM, set this field to sockserv.

postload_args

This field specifies arguments to pass to the program specified by the postload_prog field. The argument -m module# is automatically passed as the first argument. The postload_args field is ignored if postload_prog is not specified or is blank.

To run see-sock-serv directly on the nShield HSM, set this field to -p pubname.

pull_rfs

This field specifies whether the SEE machine name and userdata should be pulled from the RFS. The default is no: set to yes to pull the SEE machine and userdata from the RFS before loading on the remote nShield HSM.

This field will be ignored if set on client machine configurations.

This field will not be added to existing configuration files if you are upgrading an image. If you require the new functionality enabled by this field, you can add the field to the load_seemachine section of your existing configuration file.

slot_imports

The slot_imports section defines slots from remote nShield HSMs that will be available to the client. Each slot is defined by the following fields:

Field Description

local_esn

This field specifies the ESN of the local nShield HSM importing the slot.

local_slotid

This field specifies the SlotID to use to refer to the slot when it is imported on the local nShield HSM. The default is 2.

remote_ip

This field specifies the IP address of the machine that hosts the slot to import.

remote_port

This field specifies the port for connecting to the nShield HSM.

remote_esn

This field specifies the ESN of the remote nShield HSM from which to import the slot.

remote_slotid

This field specifies the SlotID of the slot to import on the remote nShield HSM. The value of this field must be an integer. The default is 0.

slot_exports

The slot_exports section defines the slots on the HSMs connected directly to the client that the client hardserver should export for other network HSMs to import. Each local slot has an entry for each network nShield HSM that can import it, consisting of the following fields:

Field Description

local_esn

This field specifies the ESN of the local nShield HSM whose slot can be imported by a network nShield HSM.

local_slotid

This field specifies the SlotID of the slot that is allowed to be exported. The value must be an integer. The default is 0.

remote_ip

This field specifies the IP address of the nShield HSM that is allowed to import the slot. Keep this field blank to allow all machines. The default is blank.

remote_esn

This field specifies the ESN of the nShield HSM allowed to import the slot. Leave the value blank to allow all permitted nShield HSMs in the Security World. The default is blank.

dynamic_slots

The dynamic_slots section defines the number of Dynamic Slots that each HSM supports.

Field Description

esn

ESN of the HSM to be configured with Dynamic Slots.

slotcount

The number of Dynamic Slots that the HSM is to support. If set to 0 (default) the HSM does not support Remote Administration.

slot_mapping

The slot_mapping section defines, for each specified HSM, a slot that is exchanged with slot 0 of the HSM. Slot 0 becomes a Dynamic Slot and the local slot becomes the specified slot number. This enables applications and utilities that only support slot 0 to use Remote Administration.

Field Description

esn

ESN of the HSM to which the mapping is applied.

slot

The slot number to be swapped with slot 0, so that:

  • Slot 0 refers to a Dynamic Slot

  • The specified slot number refers to the local slot of the HSM.

If slot is set to 0 (default) there is no slot mapping.

dynamic_slot_timeouts

The dynamic_slot_timeouts section defines timeout values that are used to specify expected smartcard responsiveness for all HSMs associated with the relevant host or client, when using the Remote Administration.

Field Description

round_trip_time_limit

round_trip_time_limit > 5s + network latency time

Round trip (HSM to smartcard and back) time limit in seconds. The card is regarded as removed, if no response has been received within the allowed time. Expected network delays need to be taken into account when setting this. The default is ten seconds.

card_remove_detect_time_limit

card_remove_detect_time_limit >= round_trip_time_limit *2

Maximum number of seconds that can pass without a response from the smartcard, before it is regarded as removed and all the keys that it protects are unloaded. Lower values increase network traffic. The default is 30 seconds.

Sections only in client configuration files

module_settings

The module_settings section defines the settings for the nShield HSM that can be changed while the hardserver is running. The section contains the following fields:

Field Description

esn

This field specifies the electronic serial number of the nShield HSM.

priority

This field specifies the priority of the nShield HSM. The value for this field can be an integer from 1 (highest) to 100 (lowest). The default is 100.

server_performance

The server_performance section defines the performance settings for the client hardserver. These are read only at hardserver start-up. This section contains the following fields:

Field Description

enable_scaling

This field determines whether multi-threaded performance scaling is enabled or not. If this field is set to auto (or not set), the hardserver automatically chooses the best option for the available hardware (enabled when using an nShield network-attached HSM, for which scaling is currently optimized, and disabled if using an nShield PCIe or USB-attached HSM). It can explicitly be enabled by setting to yes, and explicitly disabled by setting to no.

target_concurrency

This field allows the level of concurrency to be tuned. The value must be an integer and will only come into effect when multi-threaded performance scaling is enabled. If target_concurrency is set to 0 (the default), the value will be automatically configured by the hardserver based on the available number of physical CPU cores. The target concurrency configured is written to the hardserver log.

nethsm_imports

The nethsm_imports section defines the network nShield HSMs that the client imports. It can also be set up by the nethsmenroll utility. Each nShield HSM is defined by the following fields:

Field Description

local_module

This field specifies the ModuleID to assign to the imported nShield HSM. The value must be an integer. An nShield HSM with this ID must not be already configured on the client computer.

remote_ip

This field specifies the IP address of the nShield HSM to import.

remote_port

This field specifies the port for connecting to the nShield HSM.

remote_esn

This field specifies the ESN of the imported nShield HSM.

keyhash

This field specifies the hash of the key that the nShield HSM should use to authenticate itself.

privileged

The value in this field specifies whether the client can make a privileged connection to the nShield HSM. The default is 0, which specifies no privileged connections. Any other value specifies privileged connections.

ntoken_esn

This field specifies the ESN of this client’s nToken, if an nToken is installed.
The default value for remote_keyhash (40 zeros) specifies that no authentication should occur. We recommend that you set a specific key hash in place of this default.

rfs_sync_client

This section defines which remote file system the client should use to synchronize its key management data:

Field Description

remote_ip

The IP address of the RFS against which to synchronize.

remote_port

This field specifies the port for connecting to the RFS.

use_kneti

Setting this option to yes to use a local module KNETI instead of the default hardserver’s software KNETI to authenticate this client to the RFS.

local_esn

This is only required if use_kneti is set to yes. It is the ESN of the local module used for authentication.

remote_keyhash

Software or module KNETI hash used to authenticate the RFS, or 40 zeroes to indicate no authentication required (default is 40 zeroes).

remote_esn

ESN of the remote module used to authenticate the RFS, or empty when using software KNETI authentication or no authentication required (default is empty).

remote_file_system

This section is updated automatically when the rfs-setup utility is run. Do not edit it manually.

The remote_file_system section defines a remote file system on the client by listing the nShield HSMs allowed to access the file system on this client. Each nShield HSM is defined by an entry consisting of the following fields:

Field Description

remote_ip

This field specifies the IP address of the remote nShield HSM that is allowed to access the file system on this client.

remote_esn

This field specifies the ESN of the remote nShield HSM allowed to access the file system on this client.

keyhash

This field specifies the hash of the key with which the client must authenticate itself to the nShield HSM. The default is 40 zeros, which means that no key authentication is required.

native_path

This field specifies the local file name for the volume to which this entry corresponds.

volume

This field specifies the volume that the remote host would access to use this entry.

allow_read

If this field is set to yes, it means that a remote server is allowed to read the contents of the file. The default is no.

allow_write

If this field is set to yes, it means that a remote server is allowed to write to the file. The default is no.

allow_list

If this field is set to yes, it means that a remote server is allowed to list the contents of the file. The default is no.

is_directory

If this field is set to yes, it means that this entry represents a directory. The default is no.

is_text

If this field is set to yes, it means that line endings should be converted to and from the Linux convention for transfers.
If you upgrade from an earlier software version to v12 and are using Remote Administration, you need to manually add the following sections to your configuration file.

remote_administration_slot_server_startup

The remote_administration_slot_server_startup section defines the communication settings that are applied at start-up to the Remote Administration.

Field Description

port

Which port to use to connect to the Remote Administration. The default is 9005.

hs_clients

The hs_clients section defines the clients that are allowed to connect to the nShield HSM. Each client is defined by an entry as follows:

Field Description

addr

Either the IP address of the client or 0.0.0.0, ::, or blank if the HSM is to accept clients identified by their keyhash instead of their IP address.

If no value is set (the field is blank), or if it is set to 0.0.0.0 or ::, only HKNETI identification is allowed.

The default is blank.

0.0.0.0 or ::, and blank result in the same behavior. You cannot enter these values in the front-panel user interface. You can only use them in the configuration file and you will have to use the correct key hash for identification if no IP address is configured.

clientperm

The type of connection permitted from the client.

This is one of the following:

  • unpriv (non-privileged connections)

  • priv (privileged connections)

  • priv_lowport (privileged connections on ports lower than 1024)

The default is unpriv.

keyhash

The hash of the KNETI key that the client should present to authenticate itself.

Both software based authentication and nToken authentication are supported,

For nToken authentication, a value must also be provided for the esn field.

The default is 40 zeros, which means that no key authentication is required.

esn

The ESN of the client’s nToken. (Only applicable if nToken authentication is used.)