Security World Remote Administration

Gathering a quorum of card holders to carry out card holder duties in a remote datacenter can be expensive and inconvenient. Remote Administration enables Administrators and Operators to present their cards remotely to authorize HSM operations without being physically present at the HSM.

When presenting a card, a secure channel is formed directly between the Remote Administration smart card and the target HSM before any token shares are read from or written to the smart card.

Remote Administration enables Administrators to use their remote access solution to perform administration operations and extends the operations that can be performed in this way.

Remote Administration enables:

  • Card holders to present smart cards to an HSM without being physically present at the HSM (e.g. the card holder may be in an office, while the HSM is in a datacenter)

  • All Administrator and Operator card operations to be carried out remotely

  • Security World programs and utilities to be run remotely when used in combination with a standard remote access solution

  • Full remote administration of Security Worlds and their HSMs including:

    • Remote mode change

    • Create/load/unload Security World

    • Firmware upgrade

    • Module status (SOS) reporting

    • nShield HSM reboot

    • nShield HSM front panel lock out

Once the software has been installed and the hardware security modules have been configured, Remote Administration enables full remote administration of Security Worlds and their HSMs.

Remote Administration components

Remote Administration consists of a number of components:

Remote Administration software

The following software is needed to allow remote card readers to be associated with an HSM:

  • nShield Remote Administration Client software
    Must be installed on the computer that has the card reader attached. See Remote Administration Client for more information.

  • nShield Remote Administration Service software
    Must be installed where it can access the appropriate HSM to provide communications between the card in the card reader and the HSM. See the Installation Guide for your nShield HSM for more about where to install Remote Administration Service software.

    The Remote Administration Service should be installed on a client machine of the HSMs in your Security World that you can make accessible to Remote Administration Clients.

    See Remote Administration Service for more information.

When a card is inserted in a reader that is associated with an HSM, the nShield Remote Administration Client and the Remote Administration Service convey messages between the card and the HSM, allowing a secure channel of communications to be established.

Security World programs and utilities

The Security World programs and utilities are typically installed on a computer within your datacentre. In such cases the Remote Administration feature assumes you will use your preferred remote access solution, e.g. SSH or Remote Desktop, to run the Security World programs and utilities remotely. This means you can run a utility like creatocs from a remote location and present the OCS to be created using a Remote Administration Client. The Remote Administration feature includes the ability to change the mode of HSMs remotely using the nopclearfail utility. This means it is possible to create a Security World remotely and perform firmware upgrades.

The nethsmadmin tool provides many of the Remote Administration capabilities for an nShield HSM without accessing the front panel.

For more information, see nethsmadmin.

nShield Remote Administration smart cards

You must use nShield Remote Administration Cards with Remote Administration. These are smart cards that are capable of negotiating cryptographically secure connections with an HSM, using warrants as the root of trust. nShield Remote Administration Cards can also be used in the local slot of an HSM if required.

The nShield Remote Administration smart cards provide:

  • Storage and retrieval of logical token fragments, similar to the smart cards used with previous releases

  • Security mechanisms to ensure authentication and confidentiality of data transferred between itself and the HSM

The nShield Remote Administration smart cards are FIPS 140 Level 3 certified devices, supporting execution of a custom Java Applet developed by Entrust. The smart cards used with previous versions of Security World software and nShield HSMs are still useable but, as previously, only in an HSM’s local slot. Remote Administration smart cards can be used both remotely and in an HSM’s local slot.

The use of nShield Remote Administration Cards is controlled by an Authorized Card List. If a card does not appear in the list, it cannot be used. See Authorized Card List for more information.

smart cards

Existing Administrator smart cards can be migrated to new Remote Administration smart cards using the racs (replace administrator card set) utility.

When using the racs utility, you cannot redefine the quantities in a K of N relationship for an ACS. The K of N relationship defined in the original ACS persists in the new ACS.

Similarly, existing OCS can be migrated using the rocs (replace operator card set) utility, provided the Security World has recovery enabled and the keys protected by that OCS are recovery enabled.

Migrating Card Sets

Authorized Card List

The use of nShield Remote Administration smart cards, both remotely and in an HSM’s local slot, is controlled by an Authorized Card List. If the serial number of a card does not appear in the Authorized Card List, it cannot be used by the system. The list only applies to Remote Administration smart cards.

By default, the Authorized Card List is empty following software installation. The serial numbers of Remote Administration smart cards must be added to the list using a text editor before they can be used.

For more information on the Authorized Card List, see Authorized Card List.

When administrative operations involving Remote Administration smart cards are initiated from an nShield HSM Front Panel, the HSM fetches the Authorized Card List from the RFS.
It is necessary to keep the Authorized Card List in sync by copying the file between the RFS and clients manually.

Remote Administration Client

The Remote Administration Client (RAC) is a utility that enables you to select an HSM located elsewhere from a list provided by the Remote Administration Service (RAS), and associate an nShield Trusted Verification Device attached to your computer with the HSM.

The RAC GUI (usually running on a laptop or workstation) communicates with the RAS (in a datacenter) over a standard TCP/IP connection. If the RAC computer is not on the same local network as the RAS computer, Entrust recommend that the connection is made over a VPN.

choose hsm

In the example screen shown, an HSM will not be Remote Administration (RA) Ready until it has the appropriate firmware, and has one or more dynamic Slots configured.

For users who want to script the card presentation process, there is also a command line utility, raccmd.

See the nShield Remote Administration Client User Guide for more information on deploying and using the Remote Administration GUI or command line utility.

Windows 8.1 + only

If you disconnect the TVD while you are on the Use Card Reader screen the Windows Smart Card service SCardSvr displays an error and terminates.

Remote Administration Service

The Remote Administration Service (RAS) provides a bridge between the RAC and the back end HSMs (via the hardserver). Its functionality is to:

  • Manage connections from multiple RACs

  • Supply a list of available HSMs to the connected RACs

  • Negotiate a connection to an HSM via the hardserver and route messages between the RAC and destination HSM.

The RAS participates as a crypto client of the HSMs. As such, the server used to host this software component must be a licensed client of the nShield HSMs being remotely administered. If your Remote File System (RFS) is already a licensed client, the RAS can be collocated on the RFS server without needing to purchase an additional client license.

nShield Trusted Verification Device

Entrust supply and recommend the use of the nShield Trusted Verification Device (TVD). This is an intelligent smart card reader that blocks any malware on the client machine from spoofing the HSM identity passed to the nShield Remote Administration smart card. The TVD allows the card holder to securely confirm the Electronic Serial Number (ESN) of the HSM to which they want to connect, using the Trusted Verification Device display.

For more information, see the Trusted Verification Device (TVD) User Guide.

Trusted Verification Device

Software installation

The Remote Administration Service with the nShield HSM

Remote Administration Service with nShield HSM
The Remote Access Server can be on a different client to the one where the Remote Administration Service is installed.

The Remote Administration Service must be installed on a client, which may also be the RFS.

The Remote Administration Service does not require a dedicated server.

A privileged connection is required to carry out privileged operations, such as, for example, changing the mode of the nShield HSM.

Remote Administration Service bundle

The Remote Administration Service (RAS) is provided through the Remote Administration Service bundle and needs to be installed in the default directory.

For information on installing the Remote Administration Service bundle, see the installation guide for your HSM.

Remote Administration Client

The Remote Administration Client is normally deployed on its own using the instructions in the nShield Remote Administration Client user guide but it can be deployed on a client at the same time as rest of nShield software

For more information on the Remote Administration Client, see the nShield Remote Administration Client user guide.

TVD

A nShield Remote Administration Client can connect to one nShield TVD during a session.

For information on installing the TVD driver and confirming the HSM Electronic Serial Number (ESN) using the nShield TVD, see the nShield Remote Administration Client user guide.

System configuration

Remote Administration Service port

The port used by Remote Administration Clients to access the Remote Administration Service can be changed by setting the port field in the remote_administration_service_slot_server_startup section of the hardserver configuration file, see [remote_administration_service_startup].

For more information on the Remote Administration port, see remote_administration_slot_server_startup.

Stopping and restarting the Remote Administration Service

The Remote Administration Service can be stopped and started using a command window or the Window Control Panel.

$ systemctl stop nc_raserv
$ systemctl start nc_raserv

Firewall settings

Assuming there is a firewall to protect your Remote Administration Service, open the port given in the Firewall settings section of the Installation Guide for the HSM.

Pushing configuration files to the nShield HSM

The config push feature allows HSM configuration to be performed remotely (i.e. without access to the front panel of the HSM). Configuration files may be pushed from the RFS or any client computer. The RFS config push is preferred unless the config push client is not actually the same machine as the RFS. The RFS config push is recommended at least when securely bootstrapping the configuration of the system from the nShield HSM front panel.

Enabling the config push feature allows a remote computer to change the HSM configuration file and make configuration changes that are otherwise only available through the HSM secure user interface.
The config push feature must be enabled if you want to use NTP time synchronisation on the HSM. See Configuring NTP in the nShield HSM.

Enabling config push from the RFS

On the nShield HSM display, use the right-hand navigation button to select System > System configuration > Remote File System, and follow the steps described in Configuring the remote file system (RFS). To enable config push from the RFS, set the push mode to AUTO with RFS secure authentication enabled (recommended), or to ON.

The RFS config push supports specifying secure authentication from the nShield HSM front panel, whereas the client config push only supports specifying authentication either from the nShield HSM Serial Console push command, or from the config file itself.

Enabling config push from a client computer

To enable config push from a client computer, on the nShield HSM display, use the right-hand navigation button to select System > System configuration > Config file options > Client config push > Config push mode, set ON or OFF, then select CONFIRM. A confirmation message will be displayed.

After enabling config push, specify the IP address of the client to push the configuration from. On the nShield HSM display, use the right-hand navigation button to select System > System configuration > Config file options > Client config push > Client address. Enter the IP address and select CONFIRM. A message is displayed confirming your chosen IP address. Select CONTINUE.

Any remote computer is allowed to push configuration files if no IP address or the 0.0.0.0 address is specified.

After enabling config push, complete the configuration steps by editing the configuration files, rather than by using nShield HSM front panel. See Configuring the nShield HSM with configuration files for more about configuration files.

If you do not want to enable config push, you can fetch the updated configuration file manually from the HSM, select System > System configuration > Config file options > Fetch configuration. An SEE machine cannot be installed or configured using the fetch configuration option from the front panel, the config push feature must be used for this.

Configuring Dynamic slots

To support Remote Administration, HSMs have to be configured to support between 1 and 16 Dynamic Slots. These Dynamic Slots are virtual card slots that can be associated with a card reader connected to a remote computer. Dynamic Slots are in addition to the local slot of an HSM and any soft token slot that may be available.

The default number of slots is 0. This disables Remote Administration on the relevant HSM.

  1. Do one of the following:

    1. Use the dynamic_slots section in the module configuration file to define the number of Dynamic Slots for an HSM and push the updated configuration file to the nShield HSM.
      See HSM and client configuration files for more about module configuration files, dynamic_slots for more about the dynamic_slots section and Configuring the nShield HSM with configuration files for more about editing the module configuration file.

      or:

    2. Use the front panel controls to navigate to Security World mgmt > Set up dynamic slots > Dynamic Slots and follow the instructions on the screen.

  2. Clear the HSM for the changes to take effect.

    For example, run the nopclearfail command:

    nopclearfail --clear --all

    You can check that the HSM has Dynamic Slots by:

    • Running the command:

      slotinfo -m 1

      For example, if four Dynamic Slots have been configured, the output from this command includes the lines:

      Slot    Type            Token   IC  Flags   Details
#0      Smartcard       -       1   A
#1      Software Tkn    -       0
#2      smartcard       -       0   AD
#3      smartcard       -       0   AD
#4      smartcard       -       0   AD
#5      smartcard       -       0   AD

    • The D in the Flags column indicates that slots 2 to 5 are Dynamic Slots.

      Depending upon your system configuration, it can take up to 30 seconds for the Dynamic Slots to appear.

      or:

    • Using the front panel controls to navigate to Security World mgmt > Display World.

Privileged client

Some nShield HSM administrative tasks can only be carried out from clients that have a privileged connection. There are two aspects to configuring a client with a privileged connection:

Using nethsmadmin to reboot an nShield HSM

The nShield HSM can be rebooted using the nethsmadmin command-line utility. Run the command:

nethsmadmin --module=<MODULE> --reboot

In this command:

--module=<MODULE>

Specifies the HSM to use, by its ModuleID (default = 1).

Enabling and disabling remote reboot

You can enable or disable rebooting an nShield HSM remotely with the nethsmadmin utility using:

  • The module configuration file

  • The front panel of the nShield HSM.

Enabling and disabling remote reboot using the module configuration file

See Configuring the nShield HSM with configuration files for more about editing the module configuration file.

Do the following:

  • To enable remote reboot, locate the server_settings section of the module configuration file, and set the enable_remote_reboot field to yes.

  • To disable remote reboot, set the enable_remote_reboot field to no. See server_settings for more about the enable_remote_reboot field.

Enabling and disabling remote reboot using the front panel of the nShield HSM

Do the following:

  • To enable remote reboot, navigate to System > System configuration > Remote config options > Remote Reboot and set to on.

  • To disable remote reboot, set Remote Reboot to off.

Once you have enabled remote reboot, you can reboot an nShield HSM from a computer using the nethsmadmin command, without accessing the unit itself.

Enabling and disabling remote mode change

You can enable or disable changing an nShield HSM remotely with the nopclearfail utility using:

  • The module configuration file

  • The front panel of the nShield HSM

Enabling and disabling remote mode changes using the module configuration file

See Configuring the nShield HSM with configuration files for more about editing the module configuration file.

Do the following:

  • To enable mode change using nopclearfail, locate the server_settings section of the module configuration file, and set the enable_remote_mode field to yes.

  • To disable mode change using nopclearfail1, set the Enable_remote_mode field to no. See server_settings for more about the enable_remote_mode field.

Enabling and disabling remote mode changes using the front panel of the nShield HSM

Do the following:

  • To enable remote mode change, navigate to System > System configuration > Remote config options > Remote mode changes and set to on.

  • To disable remote mode change, set Remote mode changes to off.

Once you have enabled remote mode change, you can change the mode of an nShield HSM from a computer using the nopclearfail command, without accessing the unit itself.

Enabling and disabling remote upgrade

You can enable or disable upgrading an nShield HSM remotely with the nethsmadmin utility using:

  • The module configuration file

  • The front panel of the nShield HSM

Enabling and disabling remote upgrade using the module configuration file

See Configuring the nShield HSM with configuration files for more about editing the module configuration file.

Do the following:

  • To enable remote upgrade, locate the server_settings section of the module configuration file, and set the enable_remote_upgrade field to yes.

  • To disable remote upgrade, set the enable_remote_upgrade field to no. See server_settings for more about the enable_remote_upgrade field.

Enabling and disabling remote upgrade using the front panel of the nShield HSM

Do the following:

  • To enable remote upgrade, navigate to System > System configuration > Remote config options > Remote Upgrade and set to on.

  • To disable remote upgrade, set Remote Upgrade to off.

Once you have enabled remote upgrade, you can upgrade the nShield HSM from a computer using the nethsmadmin command, without accessing the unit itself.

Adjusting card removal detection timers to account for network characteristics

Depending upon the characteristics of the network between nShield Remote Administration Clients and HSMs, you may need to adjust the timers that determine how long the system waits for a response, before it regards a card as having been removed. This enables you to balance the assured card removal detection time and network traffic.

Do the following:

  • Use The dynamic_slot_timeouts section in the module configuration file to define the round trip (HSM to smartcard and back) time limit (the default is 10 seconds), and the card removal detection timeout (the default is 30 seconds).

  • Push the updated configuration file to the nShield HSM. See dynamic_slot_timeouts and Configuring the nShield HSM with configuration files for more information.

Using Remote Administration with applications requiring cards in slot 0

If you want to use Remote Administration, but have an application that expects cards to be presented in slot 0, you must configure a slot mapping for each affected HSM.

  1. Do one of the following:

    1. Use the slot_mapping section in the module configuration file to define a Dynamic Slot to exchange with slot 0 for an HSM and push the updated configuration file to the nShield HSM.
      See HSM and client configuration files for more about module configuration file, slot_mapping for more about the slot_mapping section and About user privileges for more about editing the module configuration file.

      Or:

    2. Use the front panel controls to navigate to Security World mgmt > Set up dynamic slots > Slot mapping and follow the instructions on the screen. You can check the mapping by:

      • Running the command:

        slotinfo -m 1

        For example, if dynamic slot #2 has been mapped to slot #0, the output from this command includes the lines:

        Slot Type Token IC Flags Details
#0 Smartcard - 1 AD
#1 Software Tkn - 0
#2 smartcard - 0 A

      • The D in the Flags column indicates that slot #0 is now a Dynamic Slot

        or:

      • Using the front panel controls to navigate to Security World mgmt > Display World.

Authorized Card List

The use of nShield Remote Administration smart cards is controlled by an Authorized Card List. If the serial number of a card does not appear in the Authorized Card List, it is not recognized by the system and cannot be used. The list only applies to Remote Administration cards and is used when a card is inserted:

  • In the local slot of an HSM

  • In a card reader that is associated with a dynamic slot of the HSM, through the nShield Remote Administration Client

By default, the Authorized Card List is empty following software installation. The serial numbers of Remote Administration Cards must be added to the list before they can be used.

The Authorized Card List is a text file %NFAST_KMDATA%\config\cardlist on the RFS and each client computer. The file is read from the RFS by associated nShield HSMs as and when required for front panel operations. The list applies to all nShield network-attached HSMs associated with the RFS, regardless of the Security World to which an HSM may belong, including when creating a Security World from the front panel. For client initiated card operations the Authorized Card List file on that client computer is used. The RFS and client copies of the Authorized Card List have to be kept in step manually.

Adding cards to the Authorized Card List

Add the serial numbers (16 digits with no separators) of all Remote Administrator Cards you intend to use to the Authorized Card List, with a standard text editor. The serial numbers are printed on the smart cards and are reported by using slotinfo -m1 -s0 when the card is in a slot, where 1 is the number of the HSM and 0 is the number of the slot.

There is an option to allow any Remote Administration Card to be used, by including a wildcard (*) in the Authorized Card List. Entrust recommends that you do not use this option, except under controlled circumstances, as it effectively disables the Using Remote Administration control.

Using Remote Administration

A privileged client can run the Command Line Tools remotely to:

Presenting nShield Remote Administration smart cards using the Remote Administration Client

With Remote Administration, you present a smartcard in a remote work station or laptop rather than locally at the nShield HSM. Remote Administration creates a separate secure connection from the Remote Administration smart card to the nShield HSM enabling remote card presentation.

For information on presenting nShield Remote Administration smart cards, see the nShield® Remote Administration Client user guide.

Configuring the nShield HSM with configuration files

You normally configure the nShield HSM using the front panel controls. However, you can choose to export a configuration file, edit it, and then re-import it. You may prefer this approach, for example, if you are importing a number of clients.

There are two ways to configure the nShield HSM by importing edited configuration files.

If you need to configure the nShield HSM regularly, but do not require physical access to it every time you configure it, follow these steps:

  1. Ensure that the nShield HSM is configured to accept a configuration from the RFS or a client computer, see Pushing configuration files to the nShield HSM.

  2. Create a copy of the configuration file from the remote file system in the %NFAST_KMDATA%\hsm-ESN\config directory on the remote computer.

  3. Change the name of the copied configuration file to config.new.

  4. Edit the config.new file so that it contains the required configuration. For information about the contents of the nShield HSM configuration file, see HSM and client configuration files.

  5. Run the cfg-pushnethsm utility on the updated configuration file, specifying the config.new file and the IP address of the nShield HSM to load the new configuration. To do this, use a command similar to the following:

    cfg-pushnethsm --address= <module_IP_address> <config_file>

    In this command, <module_IP_address> is the nShield HSM on which to load the configuration and <config_file> is the path to, and name of the updated configuration file.

  6. Check that the configuration file on the RFS has been updated with the required changes.

    The nShield HSM checks that it is able to update the configuration file on the RFS before applying changes to its own configuration. If you want the nShield HSM to apply the configuration changes even if it cannot update the configuration file on the RFS, for example, because the RFS is going to be moved to a new IP address, use the --no-rfs-check command line option: 
    cfg-pushnethsm --address= <module_IP_address> <config_file> --no-rfs-check

    You will have to copy the configuration file to the RFS manually.

    Alternatively, the nShield HSM can be configured remotely without enabling the config push by fetching the configuration file from the RFS:

  7. Save the file %NFAST_KMDATA%\hsm-ESN\config in the same directory and edit it to contain the configuration you require. For more information about the contents of the configuration file, see HSM and client configuration files.

  8. On the nShield HSM, from the main menu select System > System configuration > Config file options > Fetch configuration.

An SEE machine cannot be installed or configured using the fetch configuration option from the front panel, the config push feature must be used for this. See Remotely loading and updating SEE machines for more information.

Whichever method you use, the updated configuration file becomes the new nShield HSM configuration. It is automatically copied back to the file %NFAST_KMDATA%\hsm-ESN\config on the remote file system.

Remote Administration Configuration file sections

The following sections relevant to Remote Administration are included in the hardserver configuration file:

[server_settings]

# Is remote mode changing enabled on this system? (default=yes)
# enable_remote_mode=ENUM
#
# Is remote reboot enabled on this system? (default=yes)
# enable_remote_reboot=ENUM
#
# Is remote upgrade enabled on this system? (default=yes)
# enable_remote_upgrade=ENUM

[dynamic_slot_timeouts]

# Start of the dynamic_slot_timeouts section
# Timeout values used to specify expected smartcard responsiveness for all
# modules on the network.
# Each entry has the following fields:
#
# Round trip time limit, in seconds, is how long to wait before giving up due
# to network delays. (default=10)
# round_trip_time_limit=INT
#
# Maximum time, in seconds, that can pass without a response from the
# smartcard before considering it removed and unloading all associated secrets
# (default=30)
# card_remove_detect_time_limit=INT
The dynamic_slot_timeout section is in the module configuration file for the HSM.

[dynamic_slots]

# Start of the dynamic_slots section
# The dynamic smartcard slots that the modules should provide for the use of
# administrators who do not have physical access to the module hardware
# Each entry has the following fields:
#
# ESN of the module to be configured with dynamic slots.
# esn=ESN
#
# Number of dynamic slots the module will support. (default=0)
# slotcount=INT
The dynamic_slots section is in the module configuration file for the HSM.

[slot_mapping]

# Start of the slot_mapping section
# Slot remapping configuration.
# Each entry has the following fields:
#
# ESN of the module on which slot 0 will be remapped with another.
# esn=ESN
#
# Slot to exchange with slot 0. Setting this value to 0 means do
# nothing.(default=0)
# slot=INT
The slot_mapping section is in the module configuration file for the HSM.
Mapping a Dynamic Slot to slot 0 is needed if you want to use Remote Administration with applications that are not aware of slot numbers greater than zero. This applies to KeySafe and CNG Wizard but may also apply to your own applications.

[remote_administration_service_startup]

# Start of the remote_administration_service_startup section
# Remote Administration Service communication settings, these are only read at
# Remote Administration Service startup time
# Each entry has the following fields:
#
# The port for the Remote Administration Service to listen on for incoming TCP
# connections from remote administration clients (default=9005)
# port=PORT

[ui_lockout]

# Start of the ui_lockout section
# UI lockout settings
# Each entry has the following fields:
#
# Set to "locked" to enable UI lockout without requiring a logical token.
Set
# to "locked_lt" to enable UI lockout with a logical token (requires a valid
# ltui_hash to be set) or "unlocked" for no UI lockout (default=unlocked).
# lockout_mode=ENUM
#
# The hash of the logical token (LTUI) required to authorise access to the
# unit menu structure when the lockout_mode is set to locked_lt; if the
# lockout_mode is locked_lt and a valid hash is provided then the lockout will
# be enabled.
Default is all-zero (disabled).
# ltui_hash=HASH
#
# Set to "no" to disable the front panel power switch in Operational mode.
# (default=yes, power switch causes shutdown)
# panel_poweroff=ENUM
The ui_lockout section is relevant for nShield network-attached HSMs only. It does not apply to nShield PCIe or USB HSMs.

To update an existing hardserver configuration file, edit and insert the sections above. Alternatively factory resetting an nShield HSM will generate a new configuration file including the new Remote Administration relevant sections listed above. See the appropriate User Guide for more information on editing and loading configuration files.