Hardserver configuration files

This guide applies to both PCIe and USB HSMs.

The default location of the hardserver configuration file is /opt/nfast/kmdata/config/config (Linux) or %NFAST_KMDATA%\config\config (Windows).

The hardserver configuration file has the following sections that you can update to configure the hardserver on an nShield module. If a section is not present, it is assumed to have no entries.

Hardserver configuration files

Hardserver 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 a # character 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 hardserver 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 hardserver behavior. Each section begins with its name in square brackets, as in this example:

[slot_imports]

You can update the parameters defined in most of these sections to configure the way that the hardserver handles secure transactions between modules connected to the host computer and applications that run on the host computer.

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.

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

General hardserver configuration settings

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 module has failed, this field specifies the number of seconds the hardserver should wait before failing commands directed to that module with a NetworkError message. For commands to have a chance of succeeding after the module has failed this value should be greater than that of connect_retry. If it is set to 0, commands to a module are failed with NetworkError immediately, as soon as the module. 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 nopclearfail 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 nopclearfail is enabled. If set to no, remote reboot using nopclearfail 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 nopclearfail is enabled. If set to no, remote upgrade using nopclearfail 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 ensure 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_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.

module_settings

The module_settings section defines the settings for the module 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 module.

priority

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

server_remotecomms

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

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. Ensure that firewall settings are consistent with port settings. See Before you install the software for more information about firewall settings.

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

The section contains the following fields:

Field Description (Linux) Description (Windows)

unix_socket_name

This field specifies the name of the socket to use for non-privileged connections on Linux. 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.

This field is not used on Windows.

unix_privsocket_name

This field specifies the name of the socket to use for privileged connections on Linux. 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.

This field is not used on Windows.

nt_pipe_name

This field is not used on Linux.

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.

nt_pipe_users

This field is not used on Linux.

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

nt_privpipe_name

This field is not used on Linux.

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.

nt_privpipe_users

This field is not used on Linux.

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

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. Java clients default to connecting to port 9000. Ensure that your network firewall settings are correct. See Before you install the software for more information 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 module 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 module on to which to load the SEE machine. The value must be an integer. A module 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 0: set to 1 to pull the SEE machine and userdata from the RFS before loading on the remote module.

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 modules that will be available to the local computer. Each slot is defined by the following fields:

Field Description

local_esn

This field specifies the ESN of the local module importing the slot.

local_slotid

This field specifies the SlotID to use to refer to the slot when it is imported on the local module. The default is 0, and provides automatic assignment to the lowest available slotID after any configured dynamic slots.

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 module from which to import the slot.

remote_slotid

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

slot_exports

The slot_exports section defines the slots on local modules that the local hardserver should allow network modules to import. Each local slot has an entry for each remote module that can import it, consisting of the following fields:

Field Description

local_esn

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

local_slotid

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

remote_ip

This field specifies the IP address of the module that is allowed to import the slot. Use 0.0.0.0 to allow all machines. The default is 0.0.0.0

remote_esn

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

dynamic_slots

The dynamic_slots section defines the number of Dynamic Slots that each HSM is to support for the Remote Administration Service.

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 the Remote Administration Service.

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 and/or Remote Slot and the local slot becomes the specified slot number. This enables applications and utilities that only support slot 0 to use Remote Administration and Remote Operator.

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 and/or Remote 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.

audit_logging

The audit_logging section defines the settings for the syslog infrastructure used by the audit logging capability. These values require a restart of the hardserver to be recognized.

Field Description

auditlog_port

This field specifies the UDP port to which audit log syslog messages should be delivered. The default is 514.

auditlog_addr

This field specifies the IP address of the machine that hosts the syslog server to which audit logging syslog messages shoud be sent.

auditlog_copy_hslog

This field specifies if audit logging sylog entries should be copied into the hardserver log as well as being transmitted to the syslog server. The default is off. It can be turned by setting to yes, true, on or 1. Care should be taken when setting this field as this can cause the hardserver log to grow significantly.

It should never be set on a nShield network-attached HSM.

auditdb_settings

The auditdb_settings section defines the settings for the nCore audit logging database used by the nShield Audit Log Service. to learn more about this service, see nShield Audit Log Service

Field Description

free_space_min_mb

This field specifies the minimum available megabytes of free-space for audit DB to operate. The default is 0.

db_size_max_mb

This field specifies the maximum available megabytes of free-space for audit DB to operate. The default is 0 for no limit.

audit_indexes_max

This field specifies the maximum number of audit indexes in audit DB. The default is 0 for no limit.

Sections only in client configuration files

nethsm_imports

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

Field Description

local_module

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

remote_ip

This field specifies the IP address of the module 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 module.

keyhash

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

privileged

The value in this field specifies whether the client can make a privileged connection to the module. 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 modules allowed to access the file system on this client. Each module is defined by an entry consisting of the following fields:

Field Description

remote_ip

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

remote_esn

This field specifies the ESN of the remote module 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 module. 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_service_slot_server_startup

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

Field Description

port

Which port to use to connect to the Dynamic Slot Server. The default is 9005.