Hardserver configuration files
The default location of the hardserver configuration file is
%NFAST_KMDATA%\config\config
.
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 | ||
---|---|---|---|
|
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 module has failed, this field specifies the number of seconds the hardserver should wait before failing commands directed to that module 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_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 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. |
|
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 |
---|---|
|
This field specifies the electronic serial number of the module. |
|
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 |
---|---|
|
This field specifies the port on which the hardserver listens for incoming impath connections.
The default is 9004.
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 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 |
|
This field specifies the port on which the hardserver listens for local privileged TCP connections.
The value |
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 | ||
---|---|---|---|
|
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. |
||
|
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 |
||
|
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 modules that will be available to the local computer.
Each slot is defined by the following fields:
Field | Description |
---|---|
|
This field specifies the ESN of the local module 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 HSM. |
|
This field specifies the ESN of the remote module from which to import the slot. |
|
This field specifies the |
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 |
---|---|
|
This field specifies the ESN of the local module whose slot can be imported by a network module. |
|
This field specifies the |
|
This field specifies the IP address of the module that is allowed to import the slot.
Use |
|
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 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 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 of the HSM to which the mapping is applied. |
|
The slot number to be swapped with slot 0, so that:
|
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. |
audit_logging
The audit_logging
section defines the settings for for the syslog infrastructure used by the audit logging capability.
These values require a restart of the hardserver to be recognized.
Field | Description |
---|---|
|
This field specifies the UDP port to which audit log syslog messages should be delivered. The default is 514. |
|
This field specifies the IP address of the machine that hosts the syslog server to which audit logging syslog messages shoud be sent. |
|
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. |
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 |
---|---|
|
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. |
|
This field specifies the IP address of the module to import. |
|
This field specifies the port for connecting to the nShield HSM. |
|
This field specifies the ESN of the imported module. |
|
This field specifies the hash of the key that the module should use to authenticate itself. |
|
The value in this field specifies whether the client can make a privileged connection to the module.
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 RFS against which to synchronize. |
|
This field specifies the port for connecting to the RFS. |
|
Setting this option to |
|
This is only required if |
|
Software or module KNETI hash used to authenticate the RFS, or 40 zeroes to indicate no authentication required (default is 40 zeroes). |
|
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 |
---|---|
|
This field specifies the IP address of the remote module that is allowed to access the file system on this client. |
|
This field specifies the ESN of the remote module 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 module. 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. |
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 |
---|---|
|
Which port to use to connect to the Dynamic Slot Server. The default is 9005. |