nShield HSM configuration files

Introduction

There are two types of HSM configuration file:

  • Connect configuration files.
    These are used in network-attached (nShield Connect and 5c HSM) HSMs to configure the physical HSM.

  • Client configuration files
    These are used to configure a client’s hardserver. They are also referred to as "hardserver configuration files" within the documentation.

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]

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 or between modules connected to a 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.

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.

Location of configuration files

Client

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.

The default location of the client configuration file in the client computer’s file system is:

  • Linux: /opt/nfast/kmdata/config/config

  • Windows: %NFAST_KMDATA%\config\config

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 with the cfg-mkdefault utility.

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

Connect

Connect 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: network-attached HSMs.

When you configure the nShield HSM from the front panel, the configuration files are exported to the following location on the Remote File System (RFS) that was defined in the rfs_client section of the module configuration:

  • Linux: /opt/nfast/kmdata/hsm-<ESN>/config

  • Windows: %NFAST_KMDATA%\hsm-<ESN>\config

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.

Configuration file sections reference lists

Sections that appear in both client and Connect configuration files

Sections that only appear in client configuration files

Sections that only appear in Connect configuration files

Apply configuration file changes

When you change a configuration section, you need to either run cfg-reread, for client configuration files, or push the Connect configuration file to the HSM. Many settings can be updated dynamically, meaning that running cfg-reread or pushing the configuration file is enough to apply the settings.

Where a configuration file section is not applied dynamically, additional actions are required following the cfg-reread or configuration file push, such as a system reboot. Additional information is provided under the following section headings for those that are not dynamically applied.

Configuration file sections

auditdb_settings

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

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.

auditlog_settings

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires a hardserver restart (the nFast Server service on Windows) if the settings are changed in the client configuration file or an HSM reboot if they are changed in the Connect configuration file.

Both

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

cli

Maximum number of entries Application mode more info Client/Connect configuration file

1

Restart your CLI connection after changing.

Connect

This section configures the serial CLI baud rate.

Field Description

baud_map

Set to the relevant baud rate for the serial CLI connection, either 115200 or 9600.

Setting a new baud rate breaks any active serial CLI connections.

codesafe

Maximum number of entries Application mode more info Client/Connect configuration file

516

After you run cfg-read, you need to clear the applicable module before the settings take effect.

Client

The codesafe section defines the CodeSafe 5 applications to load and start on an nShield 5s.

For pre-nShield 5 HSMs, see load_seemachine.
Field Description

esn

The ESN of the module that the CodeSafe 5 application is being loaded onto.

enabled

Enables or disables the entry:

  • yes: Enabled (default)

  • no: Disabled

image_file

The filename of the CodeSafe 5 image the module is to host.

seejobs_port

The port in the CodeSafe 5 application configured for SEEJobs communication. An SSH tunnel is automatically created between the hardserver and this port.

The default is 8888. Set to 0 to disable it.

enable_ncoreapi

Enables or disables ncoreapi access for the CodeSafe application with Cmd_CreateSEEConnection. The image file identities are automatically passed.

Set to either:

  • yes: Enabled (default)

  • no: Disabled

worldid_pubname

The PublishedObject name name to use for publishing the KeyID of the started CodeSafe 5 application.

auto_enroll

Enables auto-enrollment of the client with nShield 5c HSMs:

  • yes: Enabled (default)

  • no: Disabled

This setting does not apply to nShield 5s or unprivileged clients of nShield 5c HSMs.

logging

Enables logging for the CodeSafe 5 application:

  • yes: Enabled (default)

  • no: Disabled

Retrieve logs using csadmin log get -u UUID.

force_reload

Force reloads the CodeSafe 5 image even if a matching image appears to already be loaded.

Set to either:

  • yes: Enabled

  • no: Disabled (default)

identities

The key names of CodeSafe 5 application identities to pass to Cmd_CreateSEEConnection. This is only applicable if enable_ncoreapi is also enabled.

If the identity is only signed with the Application Signing Key (ASK), then the specified identity is passed. If the identity is signed with the ASK and one extra signature (csadmin image signextra), then by default only the extra identity is passed. If there are multiple extra signers, then all identities are supplied.

The override the default, for example to supply both the ASK and the signextra when the identity is signed with the ASK and one extra signature, specify the key names as a space-separated list.

This setting controls what is reported by Cmd_GetWorldSigners instead of the CodeSafe 5 application.

config_op

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

The config_op section defines whether a client computer is allowed to update the HSM 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.

cosmod

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

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.

dynamic_slot_timeouts

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

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.

dynamic_slots

Maximum number of entries Application mode more info Client/Connect configuration file

1,000

Dynamic

Both

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.

hs_clients

Maximum number of entries Application mode more info Client/Connect configuration file

Over 2 billion

Dynamic

Both

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

load_seemachine

Maximum number of entries Application mode more info Client/Connect configuration file

500

After you run cfg-read or push the configuration file to the module, you need to clear the applicable module before the settings take effect.

Both

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/0: set to yes/1 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.

module_settings

Maximum number of entries Application mode more info Client/Connect configuration file

Over 2 billion

Dynamic

Both

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.

nethsm_bond

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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_bond_enable

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

The nethsm_bond_enable section defines if the bond interface is enabled. The section contains the following fields:

Field Description

enable

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

nethsm_codesafe5

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires reboot of HSM if set in configuration file. Can be set dynamically either using the Serial CLI or, remotely, using appliance-cli.

Connect

The nethsm_codesafe5 section defines settings for CodeSafe 5 SEE. The section contains the following fields:

Field Description

enable_ports

Enables or disables the CodeSafe 5 ports:

  • yes: Enabled (default)

  • no: Disabled

address

The IPv4 or IPv6 address of the nShield 5c where the CodeSafe 5 ports are to be enabled.

The default is ::.

nethsm_enable

Maximum number of entries Application mode more info Client/Connect configuration file

One entry per HSM Ethernet interface

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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.

nethsm_eth

Maximum number of entries Application mode more info Client/Connect configuration file

One entry per HSM Ethernet interface

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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

Maximum number of entries Application mode more info Client/Connect configuration file

One entry per HSM Ethernet interface

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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_eth1_enable

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

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_gateway

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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_imports

Maximum number of entries Application mode more info Client/Connect configuration file

500

Dynamic

Both

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.

nethsm_route

Maximum number of entries Application mode more info Client/Connect configuration file

10

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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

Maximum number of entries Application mode more info Client/Connect configuration file

10

Requires reboot of HSM if set in configuration file. Can be set dynamically from the Front Panel UI or the Serial CLI.

Connect

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_settings

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

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 1800 for 1,800 seconds.

impath_resilience_max_sessions

This field specifies the maximum number of sessions that can be parked. A value of 0 means that there is no limit and all elligible sessions will be parked. The default is 0.

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_watchdog

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

The nethsm_watchdog section enables or disables the Connect watchdog and defines whether it can be remotely configured. The section contains the following fields:

Field Description

push

Allows clients to remotely configure the nethsm_watchdog by pushing new watchdog configuration files to the netHSM.

Set to either:

  • on

  • off (default)

remote_ip

The IP address of the client that is allowed to push new watchdog configuration files. If this is not set, or is set to 0.0.0.0, new configuration files can be pushed from any IP address.

remote_keyhash

The hash of the key that the authorised client should use to authenticate itself. If this is set to 40 zeros, which is the default, no key authentication is required.

enable_watchdog

Enables or disables the Connect watchdog:

  • yes: Enabled

  • no: Disabled (default)

remote_administration_service_startup

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires the restart of raserv service (nFast Remote Administration Service on Windows).

Client

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

remote_file_system

Maximum number of entries Application mode more info Client/Connect configuration file

10,000

Dynamic

Client
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_sys_log

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

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.

rfs_client

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

The rfs_client section defines the remote file system where the HSM 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.

rfs_sync_client

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

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

server_performance

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires a hardserver restart (the nFast Server service on Windows).

Client

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.

server_remotecomms

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

The server_remotecomms section defines the remote IPv4 communication settings for the hardserver’s impath port. 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

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

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_settings

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

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 server_settings: 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 Connect 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 Connect 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 Connect 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.

server_settings: hardserver loglevel

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Both

This section describes the available options for the loglevel field in the [server_settings] section in increasing order of severity. If you set a custom 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.

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_startup

Maximum number of entries Application mode more info Client/Connect configuration file

1

Requires a hardserver restart (the nFast Server service on Windows).

Client

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

Linux

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

Linux

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

Windows

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

Windows

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

Windows

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

Windows

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

Make sure that your network firewall settings are correct. See Before you install the software 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.

slot_exports

Maximum number of entries Application mode more info Client/Connect configuration file

1,000

Dynamic

Both

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 or use 0.0.0.0 to allow all machines. The default is blank or 0.0.0.0.

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.

slot_imports

Maximum number of entries Application mode more info Client/Connect configuration file

1,000

Dynamic

Both

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_mapping

Maximum number of entries Application mode more info Client/Connect configuration file

1,000

Dynamic

Both

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.

sys_log

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

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.

ui_lockout

Maximum number of entries Application mode more info Client/Connect configuration file

1

Dynamic

Connect

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.