Client software and module configuration: PCIe and USB HSMs

This chapter describes software and module configuration tasks that you can choose to perform after the initial installation of Security World Software and hardware.

You must determine whether particular configuration options are necessary or appropriate for your installation. The additional configuration options described in this chapter can be performed either before or after the creation of a Security World (as described in Create a new Security World) and an OCS (as described in Creating Operator Card Sets (OCSs)).

About user privileges

Cryptographic security does not depend on controlling user privileges or access but maintaining the integrity of your system from both deliberate or accidental acts can be enhanced by appropriate use of (OS) user privileges.

Set up client cooperation

You can allow an nShield HSM to automatically access the remote file system (RFS) belonging to another nShield HSM and share the Security World and key data stored in the Key Management Data directory. Client hardware security modules that access data in this way are described as cooperating clients.

To configure client cooperation for other clients or hardware security modules that are not nShield HSMs, see Client cooperation.

Useful utilities

Setting environmental variables

This section describes how to set Security World Software-specific environment variables. You can find detailed information about the environment variables used by Security World Software in Environment variables.

Linux

You can set Security World Software-specific environment variables in the file /etc/nfast.conf. This file is not created by the installation process: you must create it yourself. /etc/nfast.conf is executed by the start-up scripts of nShield HSM services as the root user. This file should only contain shell commands that can safely be run in this context. /etc/nfast.conf should be created with access permissions that allow only the root user to write to the file.

Ensure that all variables are exported as well as set.
Windows

You can set Security World Software-specific environment variables as follows:

  1. Open the System dialog by clicking System in the control panel menu.

  2. Select the Advanced tab and click the Environment Variables button.

  3. To add a variable, click New. Alternatively, to edit an existing variable select an entry in the System Variables list and click Edit.

  4. In the Variable Name field, type or edit the name of the environment variable (for example, NFAST_HOME).

  5. In the Variable Value field, type or edit the value to use.

  6. Click the OK button to set the value, and then click the OK button to close the dialog.

  7. Open the Administrative Tools dialog by clicking the Administrative Tools icon in the Control Panel

  8. Open the Services console by clicking the Services icon.

  9. From the displayed list of services, select the nFast Server icon, and select Restart the service.

Logging and debugging

Network-attached HSMs: You can view logs generated by the nShield HSM and applications that use it on the unit front panel. Application log messages are handled on the client.

The Security World Software generates logging information that is configured through a set of four environment variables:

  • NFLOG_FILE

  • NFLOG_SEVERITY

  • NFLOG_DETAIL

  • NFLOG_CATEGORIES

If none of these logging environment variables are set, the default behavior is to log nothing, unless this is overridden by any individual library. If any of the four logging variables are set, all unset variables are given default values.

Detailed information about controlling logging information by means of these environment variables is supplied in Logging, debugging, and diagnostics.

Some components of the Security World Software generate separate debugging information which you can manage differently. On network-attached HSMs, debugging information for applications is handled on the client.

If you are setting up the unit or the client to develop software that uses it, you should configure debugging before commencing software development.

Configuring Java support for KeySafe

To use KeySafe, follow the instructions in Using KeySafe.

Configuring the hardserver

The hardserver handles secure transactions between the HSMs connected to the host computer and applications that run on the host computer. In addition, the hardserver, for example:

  • Controls any Remote Operator slots that the HSM uses

  • Loads any SEE (Secure Execution Engine) machines that are to run on the HSM

  • Enables Remote Administration and provides the communication channel between the Remote Administration Service and the HSM

The hardserver can handle transactions for multiple HSMs. This does not require configuration of the hardserver. For more information, see Using multiple modules.

The hardserver must be configured to control:

  • The way the hardserver communicates with remote HSMs

  • The way the hardserver communicates with local HSMs

  • The import and export of Remote Operator slots

  • The loading of SEE machines on to the HSM when the hardserver starts up

  • The number of Dynamic Slots available on the HSM

  • The port used to connect to the Remote Administration Service

  • Whether a Dynamic Slot needs to be exchanged with slot 0 of an HSM

  • Timeout values for nShield Remote Administration Card presence assurance

  • Configuring the audit logging destination.

The hardserver configuration file defines the configuration of the hardserver. By default, it is stored in /opt/nfast/kmdata/config/ (Linux) or %NFAST_KMDATA%\config (Windows), and a default version of this file is created when the Security World Software is installed. See Overview of hardserver configuration file sections for an overview of the hardserver configuration file, and see "Hardserver configuration files" for detailed information about the various options available through it.

In some previous releases of the Security World Software, hardserver configuration was controlled by environment variables. The use of these variables has been deprecated. If any of these environment variables are still set, they override the settings in the configuration file.

You must load the configuration file for the changes to the configuration to take effect.

To configure the hardserver, follow these steps:

  1. Save a copy of the configuration file, /opt/nfast/kmdata/config/ (Linux) or %NFAST_KMDATA%\config\config (Windows), so that the configuration can be restored if necessary.

  2. Edit the configuration file to contain the required configuration. (See "Hardserver configuration files" for descriptions of the options in the configuration file.)

  3. Run cfg-reread to load the new configuration.

    If you changed the server_startup section of the hardserver configuration file, you must restart the hardserver instead of running cfg-reread. For more information, see Stopping and restarting the hardserver.

  4. Test that the hardserver is configured correctly by running the enquiry command-line utility.

    Check that an HSM with the correct characteristics appears in the output.

  5. Test that the client has access to the Security World data by running the nfkminfo command-line utility.

    Check that an HSM with the correct ESN appears in the output and has the state 0x2 Usable.

Overview of hardserver configuration file sections

Configure remote HSM connections

You configure the hardserver’s communications with remote HSMs in the server_remotecomms section of the hardserver configuration file. This section defines the port on which the hardserver listens for communications from remote HSMs. You need to edit this section only if the default port (9004) is not available.

For detailed descriptions of the options in this section, see server_remotecomms.

For information about configuring the Remote Operator feature (Remote Operator slots), as opposed to remote HSMs, see Remote Operator.

Hardserver settings

You configure the hardserver’s settings in the server_settings section of the configuration file.

This section defines how connections and hardserver logging are handled. These settings can be changed while the hardserver is running.

For detailed descriptions of the options in this section, see server_settings.

Hardserver performance settings

You configure the hardserver performance settings in the server_performance section of the configuration file.

This section determines whether multi-threaded performance scaling is enabled or not. By default, scaling is not enabled. Any changes you make to the settings in this section do not take effect until after you restart the hardserver.

For detailed descriptions of the options in this section, see server_performance.

HSM settings

You configure the HSM’s settings in the module_settings section of the configuration file.

This section defines the settings for the HSM that can be changed while the hardserver is running.

For detailed descriptions of the options in this section, see module_settings.

Hardserver start-up settings

You configure the hardserver’s start-up settings in the server_startup section of the configuration file.

This section defines the sockets and ports used by the hardserver. You need to change this section only if the default ports for privileged or unprivileged connections (9000 and 9001) are not available.

Windows only

You should use the nt_privpipe_users option to define the name of the user who is allowed to carry out privileged operations, for example, using the nopclearfail utility. See nt_privpipe_users for more information.

For detailed descriptions of the options in this section, see server_startup.

SEE machines

You configure the hardserver to load SEE machines on start-up in the load_seemachine section of the configuration file. The SEE Activation feature must be enabled on the HSM, as described in Optional features.

This section defines the SEE machines and optional user data to be loaded, as well any other applications to be run in order to initialize the machine after it is loaded.

For detailed descriptions of the options in this section, see load_seemachine.

For information about SEE machines, see CodeSafe applications.

Remote Operator slots

You configure Remote Operator slots in the slot_imports and slot_exports sections of the configuration file. These sections define the slots that are imported to or exported from the HSM. This applies to the Remote Operator feature only.

For detailed descriptions of the options in these sections, see slot_imports and slot_exports.

The Remote Operator feature must be enabled on the HSM, as described in Optional features.

Remote file system

Each client’s remote file system is defined separately in the remote_file_system section of the configuration file with a list of HSMs that are allowed to access the file system on the given client. For information about setting up client cooperation, see Client cooperation.

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

As a reference, for detailed descriptions of the options in this section, see remote_file_system.

Audit logging

You configure the hardserver’s audit logging in the auditlog_settings section of the configuration file.

This section defines the host IP address and port used as the destination for the syslog output of the audit logging capability. Optionally, the audit logging messages can be copied to the hardserver’s log file.

For further details see Audit Logging.

The hardserver needs to be restarted for these settings to take effect.

Using multiple modules

The hardserver can communicate with multiple modules connected to the host. By default, the server accepts requests from applications and submits each request to the first available module. The server can share load across buses, which includes the ability to share load across more than one module.

If your application is multi-threaded, you can add additional modules and expect performance to increase proportionally until you reach the point where cryptography no longer forms a bottleneck in the system.

Identifying modules

Modules are identified in two ways:

  • By serial number

  • By ModuleID.

You can obtain the ModuleID 's and serial numbers of all your modules by running the enquiry command-line utility.

Electronic Serial Number (ESN)

The serial number is a unique 12-digit number that is permanently encoded into each module. Quote this number in any correspondence with Support.

ModuleID

The ModuleID is an integer assigned to the module by the server when it starts. The first module it finds is given a ModuleID of 1, the next is given a ModuleID of 2, and this pattern of assigning ModuleID numbers continues for additional modules.

The order in which buses are searched and the order of modules on a bus depends on the exact configuration of the host. If you add or remove a module, this can change the allocation of ModuleIDs to all the modules on your system.

You can use the enquiry command-line utility to identify the PCI bus and slot number associated with a module.

All commands sent to nShield modules require a ModuleID. Many Security World Software commands, including all acceleration-only commands, can be called with a ModuleID of 0. Such a call causes the hardserver to send the command to the first available module. If you purchased a developer kit, you can refer to the developer documentation for information about the commands that are available on nShield modules.

In general, the hardserver determines which modules can perform a given command. If no module contains all the objects that are referred to in a given command, the server returns an error status.

However, some key-management operations must be performed together on the same module. In such cases, your application must specify the ModuleID.

To be able to share OCSs and keys between modules, the modules must be in the same Security World.

Adding a module

If you have a module installed, you can add further modules without reinstalling the server software.

However, we recommend that you always upgrade to the latest server software and upgrade the firmware in existing modules to the latest firmware.

  1. Install the module hardware.

  2. (Linux) Run the script /opt/nfast/sbin/install.

  3. Add the module to the Security World. Refer to Adding or restoring an HSM to the Security World.

Module fail-over

The Security World Software supports fail-over: if a module fails, its processing can be transferred automatically to another module provided the necessary keys have been loaded. Depending on the mode of failure, however, the underlying bus and operating system may not be able to recover and continue operating with the remaining devices.

To maximize uptime, we recommend that you fit any additional nShield modules for failover on a bus that is physically separate from that of the primary modules.

Stopping and restarting the hardserver

If necessary, you can stop the hardserver on the client, and where applicable the Remote Administration Service, by running the following command. On Windows, this must be a command window with administrative privileges.

Linux
/opt/nfast/sbin/init.d-ncipher stop
Windows
net stop "nfast server"

If the Remote Administration Service is running, you will be warned and given the option of continuing or not.

Similarly, you can start the hardserver on the client, and where applicable the Remote Administration Service, by running the following command. On Windows, this must be a command window with administrative privileges.

Linux
/opt/nfast/sbin/init.d-ncipher start

You can also restart the hardserver on the client, and where applicable the Remote Administration Service, by running the following command:

/opt/nfast/sbin/init.d-ncipher restart
Windows
net start "nfast server"
net start "nfast Remote Administration Service"

On Windows, you can also stop, start, or restart the hardserver, and where applicable the Remote Administration Service, from the Windows Control Panel:

  1. From the Windows Start menu, open the Windows Control Panel.

  2. Double-click Administrative Tools.

  3. Double-click Services.

  4. Locate nFast Server or nFast Remote Administration Service in the list of services, and from the Action menu, select Stop, Start, or Restart as required.

    The nFast Remote Administration Service, where applicable, is dependent on the nFast Server so should be started or restarted after the nFast Server.