nShield Connect and client configuration files
This appendix describes the configuration files that store the current configuration of an nShield Connect or client.
The module configuration files are stored on the internal file system of the nShield Connect. They are updated automatically when the nShield Connect 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 Connect, 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 the directory
%NFAST_KMDATA%
\config
on the client computer’s file system.
This directory can contain the following files:
File | Description |
---|---|
|
The master configuration file. This contains the current configuration for the client. It is always present in the directory. |
|
The default configuration file.
This can be used to restore factory settings for the client.
It is created by the |
You can also save backup copies of configuration files in this directory.
Location of module configuration files
When you configure the nShield Connect 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 the directory
%NFAST_KMDATA%
\hsm-ESN\config
.
In this path, ESN is the electronic serial number of the network nShield Connect from which the files were exported.
This directory contains the master configuration file config
, which specifies the current configuration for the nShield Connect.
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 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 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 Connect 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 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
||
|
||
|
||
|
||
|
You can update the parameters defined in most of these sections to configure the way that the hardserver handles secure transactions between the nShield Connect 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 Connect.
The section contains the following fields:
Field | Description |
---|---|
|
When set to the default |
|
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 |
nethsm_eth
The nethsm_eth
section defines the Ethernet interfaces for IPv4 for the nShield Connect.
Each interface is defined by an entry as follows:
Field | Description |
---|---|
|
The identifier for the interface.
This value must be |
|
The IP address of the nShield Connect.
The default is |
|
The net mask for the nShield Connect.
The default is |
|
This field is retained for backwards compatibility only.
The IP address of the gateway is stored in the |
|
This field specifies the link speed setting.
It can be one of We recommend that you accept the default |
nethsm_eth_ipv6
The nethsm_eth_ipv6
section defines the Ethernet interfaces for IPv6 for the nShield Connect.
Each interface is defined by an entry as follows:
Field | Description |
---|---|
|
The identifier for the interface.
This value must be |
|
The static IPv6 address for this interface.
The default is |
|
The subnet prefix length of the static IPv6 address for the interface.
The default is |
nethsm_gateway
The nethsm_gateway
section defines the default IPv4 Ethernet gateway for the nShield Connect.
There is one field, as follows:
Field | Description |
---|---|
|
The IPv4 address of the gateway for the nShield Connect.
The default is |
nethsm_gateway_ipv6
The nethsm_gateway_ipv6
section defines the default IPv6 Ethernet gateway for the nShield Connect.
There is one field, as follows:
Field | Description |
---|---|
|
The IPv6 address of the gateway for the nShield Connect.
The default is |
|
The ethernet interface ( |
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 |
---|---|
|
Possible values:
|
|
The MII link monitoring frequency in milliseconds. Range: Default: |
|
Primary device. The specified device will always be the active slave while it is available. Possible values:
Default: Only valid for |
|
The number of IGMP membership reports to be issued after a failover event. Range: Default: A value of Only valid for |
|
The rate in which the Ethernet interface asks the link partner to transmit LACPDU packets in Possible values:
Default: Only valid for |
|
The transmit hash policy to use for slave selection in Possible values:
Default: |
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 Connect.
Each route is defined by an entry as follows:
Field | Description |
---|---|
|
The IPv4 address of the route destination.
The default is |
|
The length to mask for the route. |
|
The IPv4 address of the gateway for the route.
The default is |
nethsm_route_ipv6
The nethsm_route_ipv6
section defines the static IPv6 routes for the nShield Connect.
Each route is defined by an entry as follows:
Field | Description |
---|---|
|
Routable IPv6 address block.
The default is |
|
The number of bits to mask for the subnet address prefix, that is, the number in the range of |
|
Route gateway.
The default is |
|
The ethernet interface ( |
nethsm_eth1_enable
The nethsm_eth1_enable
section defines if the eth1 interface is enabled.
Field | Description |
---|---|
|
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 |
---|---|
|
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 |
---|---|
|
The ethernet interface ( |
|
Indicator of whether the IPv4 protocol on the interface is enabled (default: |
|
Indicator of whether the IPv6 protocol on the interface is enabled (default: |
|
Indicator of whether the interface uses IPv6 static addresses ( |
cosmod
The cosmod
section defines the input configuration for the nShield Connect.
The configuration is defined by an entry as follows:
Field | Description |
---|---|
|
The selected layout for the keyboard connected to the nShield Connect front panel.
This value is either |
hs_clients
The hs_clients
section defines the clients that are allowed to connect to the nShield Connect.
Each client is defined by an entry as follows:
Field | Description |
---|---|
|
Either the IP address of the client or If no value is set (the field is blank), or if it is set to The default is blank.
|
|
The type of connection permitted from the client. This is one of the following:
The default is |
|
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 The default is 40 zeros, which means that no key authentication is required. |
|
The ESN of the client’s nToken. (Only applicable if nToken authentication is used.) |
|
Obsolete.
This should be set to |
|
Obsolete.
This should be set to |
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 |
---|---|
|
The IP address of the computer on which the remote file system resides. |
|
The port number on which the remote hardserver is listening. |
sys_log
The sys_log
section defines how the nShield Connect logging works:
Field | Description |
---|---|
|
The way the log is written. How the log is written is decided by setting either of the following:
If |
|
The number of minutes between the log being appended when |
remote_sys_log
The remote_sys_log
section defines a remote syslog server to send the nShield Connect logging (system.log and hardserver.log) to.
Field | Description |
---|---|
|
The IP address of the remote syslog server to send logs to.
The default is |
|
The UDP port of the remote syslog server to send logs to.
The default is |
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 |
---|---|
|
Whether the client is allowed to push configuration files to the nShield Connect. This is decided by setting one of the following:
If |
|
The IP address of the client that is allowed to push config files.
If no value is set, or if it is set to |
|
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 Connect 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 |
---|---|
|
Controls front panel access to the nShield Connect. Set to:
|
|
The hash of the logical token ( |
|
This controls the function of the Power button on the nShield Connect front panel when it is in operational mode.
The default setting of |
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 | ||
---|---|---|---|
|
This field specifies the level of logging performed by the hardserver. It takes a value that is one of the following:
The default is
|
||
|
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. |
||
|
This field specifies the number of seconds to wait before retrying a remote connection to a client hardserver. The default is 10. |
||
|
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 |
||
|
This field specifies the number of seconds of inactivity allowed before a connection to a client hardserver is declared broken. The default is 90. |
||
|
This field specifies the number of seconds between |
||
|
This field specifies the number of seconds before the first keepalive packet for remote incoming connections.
The default is 30.
Ideally, |
||
|
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, |
||
|
When the nShield Connect has failed, this field specifies the number of seconds the hardserver should wait before failing commands directed to that HSM with a |
||
|
This field specifies the maximum PCI interface version number.
If |
||
|
If this field is set to
|
||
|
If this field is set to |
||
|
If this field is set to |
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 |
---|---|
|
This flag specifies the external time (that is, the time according to your machine’s local clock) with the log entry. |
|
This flag specifies the external date (that is, the date according to your machine’s local clock) with the log entry. |
|
This flag specifies the external thread ID with the log entry. |
|
This flag specifies the external |
|
This flag specifies the stack backtrace with the log entry. |
|
This flag specifies the stack file with the log entry. |
|
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. |
|
This flag specifies the message severity (a severity level as used by the |
|
This flag specifies the message category (a category as used by the |
|
This flag specifies message writeables, and extra information that can be written to the log entry, if any such exist. |
|
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. |
|
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. |
|
This flag showing the date and time in UTC (Coordinated Universal Time) instead of local time. |
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 Connect module config file should be followed by a reboot of the nShield Connect.
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 Connect 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 |
---|---|
|
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 Connect). 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. |
|
This field specifies the IPv4 address at which the hardserver listens for incoming impath connections.
If this field is set to |
|
This field specifies a string representing the name of the Ethernet interface on which the hardserver listens.
This field is only examined if By default, the |
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 Connect module config file should be followed by a reboot of the nShield Connect.
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 Connect 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 |
---|---|
|
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 Connect). 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. |
|
This field specifies the IPv6 address at which the hardserver listens for incoming impath connections.
If this field is set to |
|
This field specifies a string representing the name of the Ethernet interface on which the hardserver listens.
This field is only examined if By default, the Setting this field to |
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 |
---|---|
|
This field is not used on Windows. |
|
This field is not used on 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 If the |
|
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 (e.g. bob not MYDOMAIN\bob or bob@MYDOMAIN ). |
|
This field specifies the name of the pipe to use for privileged connections on Windows.
An empty string specifies none.
The default is If the |
|
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 (e.g. bob not MYDOMAIN\bob or bob@MYDOMAIN ). |
|
This field specifies the port on which the hardserver listens for local non-privileged TCP connections.
The value Make sure that your network firewall settings are correct. See the Installation Guide for more about firewall settings. If the |
|
This field specifies the port on which the hardserver listens for local privileged TCP connections.
The value If the |
load_seemachine
The load_seemachine
section of the hardserver configuration file defines SEE machines that the nShield Connects 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 | ||
---|---|---|---|
|
This field specifies the nShield Connect on to which to load the SEE machine. The value must be an integer. A nShield Connect with this ID must be configured on the client computer. |
||
|
This field specifies the file name of the SEE machine. |
||
|
This field specifies the |
||
|
This field specifies the |
||
|
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 To run |
||
|
This field specifies arguments to pass to the program specified by the To run |
||
|
This field specifies whether the SEE machine name and userdata should be pulled from the RFS.
The default is This field will be ignored if set on client machine configurations.
|
slot_imports
The slot_imports
section defines slots from remote nShield Connects that will be available to the client.
Each slot is defined by the following fields:
Field | Description |
---|---|
|
This field specifies the ESN of the local nShield Connect importing the slot. |
|
This field specifies the |
|
This field specifies the IP address of the machine that hosts the slot to import. |
|
This field specifies the port for connecting to the nShield Connect. |
|
This field specifies the ESN of the remote nShield Connect from which to import the slot. |
|
This field specifies the |
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 Connect that can import it, consisting of the following fields:
Field | Description |
---|---|
|
This field specifies the ESN of the local nShield Connect whose slot can be imported by a network nShield Connect. |
|
This field specifies the |
|
This field specifies the IP address of the nShield Connect that is allowed to import the slot. Keep this field blank to allow all machines. The default is blank. |
|
This field specifies the ESN of the nShield Connect allowed to import the slot. Leave the value blank to allow all permitted nShield Connects 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 of the HSM to be configured with Dynamic Slots. |
|
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 of the HSM to which the mapping is applied. |
|
The slot number to be swapped with slot 0, so that:
If |
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 (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. |
|
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 Connect that can be changed while the hardserver is running.
The section contains the following fields:
Field | Description |
---|---|
|
This field specifies the electronic serial number of the nShield Connect. |
|
This field specifies the priority of the nShield Connect. 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 |
---|---|
|
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 nShield Connects, for which scaling is currently optimized, and disabled if using nShield Solos or any other local devices). It can explicitly be enabled by setting to yes, and explicitly disabled by setting to no. |
|
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 Connects that the client imports.
It can also be set up by the nethsmenroll
utility.
Each nShield Connect is defined by the following fields:
Field | Description |
---|---|
|
This field specifies the ModuleID to assign to the imported nShield Connect. The value must be an integer. An nShield Connect with this ID must not be already configured on the client computer. |
|
This field specifies the IP address of the nShield Connect to import. |
|
This field specifies the port for connecting to the nShield Connect. |
|
This field specifies the ESN of the imported nShield Connect. |
|
This field specifies the hash of the key that the nShield Connect should use to authenticate itself. |
|
Obsolete.
This should be set to |
|
Obsolete.
This should be set to |
|
The value in this field specifies whether the client can make a privileged connection to the nShield Connect.
The default is |
|
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 |
---|---|
|
The IP address of the remote server against which to synchronize. |
|
This field specifies the port for connecting to the nShield Connect. |
|
Setting this option to |
|
This is only required if |
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 Connects allowed to access the file system on this client.
Each nShield Connect is defined by an entry consisting of the following fields:
Field | Description |
---|---|
|
This field specifies the IP address of the remote nShield Connect that is allowed to access the file system on this client. |
|
This field specifies the ESN of the remote nShield Connect allowed to access the file system on this client. |
|
This field specifies the hash of the key with which the client must authenticate itself to the nShield Connect. The default is 40 zeros, which means that no key authentication is required. |
|
This field specifies the local file name for the volume to which this entry corresponds. |
|
This field specifies the volume that the remote host would access to use this entry. |
|
If this field is set to |
|
If this field is set to |
|
If this field is set to |
|
If this field is set to |
|
If this field is set to |
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. |