Server-side preparation tasks

This chapter outlines the tasks required on the server-side that must be completed before the Remote Administration Client can be installed and used.

For more information on updating the configuration file for your HSM, see the Hardserver configuration files (PCIe HSMs) or HSM and client configuration files (network-attached HSMs) chapter in the HSM User Guide.

The Remote Administration Client requires that quorum participants use their cards in a TVD associated with the HSM. The steps involved in meeting this requirement are as follows:

  1. Remote Administration Service has been enabled.

    • If the HSM and the associated Security World are being installed the first time, install the HSM and, as part of the overall installation process, install the Remote Administration Service bundle (raserv). For installation instructions, follow the Installation Guide of the HSM.

    • If the HSM and the associated Security World are already installed but Remote Administration was not installed:

    • Ensure the Remote Administration Service firewall port (default: 9005) is open for incoming connection requests from nShield Remote Administration clients.

  2. Cards have been enabled for use through RAC. See Edit the Authorized Card List.

  3. Dynamic slots have been configured so that cards can be presented remotely. See Set up dynamic slots.

In some cases, the steps are covered in more detail in the User Guide for your HSM. These are referenced in the appropriate section. We recommend you have the User Guide available to you at the same time as reviewing the Remote Administration setup steps.

Prepare an existing Security World installation for Remote Administration

If you need to enable the Remote Administration Service into an existing system:

  1. Ensure the HSM firmware is compatible with Remote Administration.

  2. For Solo HSMs only: Ensure the nShield Solo+/ XC HSM is warranted with a KLF2 warrant.

  3. For Connect HSMs only: Connect HSM can also accept a configuration from the RFS or a remote computer, see Enable config push on nShield Connect.

  4. Re-install the Security World software.

Ensure the HSM firmware is compatible with Remote Administration

You can confirm current firmware version via the enquiry command. In section Module, look for version and check it against the information in Compatibility with nShield firmware and Security World releases.

If the firmware needs upgrading, follow the instructions relevant to the HSM:

Upgrade the nShield Connect image file and firmware using the front panel

Important: If you upgrade your nShield Connect firmware you must make sure that you have a working quorum of Administrator Cards, as you will need to reload your Security World back onto the HSM once the firmware has been upgraded. If you cannot provide the required quorum from the ACS do not perform a firmware upgrade!

  1. From the main menu on the nShield Connect front panel, select System > Upgrade system.

  2. Confirm that you want to upgrade the image file and/or firmware.

  3. Verify the image version, HSM (firmware) version, and image VSN that are displayed, and confirm the upgrade when prompted. If in doubt contact nShield support for assistance in determining the correct version to use.

  4. When the image file and/or firmware upgrade is complete, the front panel may be slow to respond. We recommend a full power off and power on to complete the upgrade procedure and to restore optimum front panel responsiveness. This may need to be repeated for a second time if the front panel seems slow to respond.

    1. On the front panel select System > Shutdown/Reboot > Shutdown.

    2. Switch the power supplies, at the rear of the nShield Connect, to 0, then back to 1.

Upgrade the nShield Connect image file and firmware from privileged client

  1. Use the nethsmadmin utility to list the nethsm image files on the RFS. Run the command:

    Linux:

    #/opt/nfast/bin/nethsmadmin --module=MODULE --rfs=RFS_IP --list-images

    Windows:

    C:\Program Files\nCipher\nfast\bin>nethsmadmin --module=MODULE --rfs=RFS_IP --list-images

    In this command:

    • RFS_IP specifies the IP address of the RFS.

    • Additionally the --rfs-hkneti=RFS_HKNETI and --rfs-esn=RFS_ESN options can be set to enable secure authentication of the RFS. There are three possible cases:

      • Without secure authentication: The authentication of the RFS will be based on the IP address only if the --rfs-hkneti and --rfs-esn options are not specified.

      • Software-based authentication: The --rfs-hkneti option specifies the software KNETI hash of the RFS. The --rfs-esn option shall not be specified.

        RFS_HKNETI can be obtained by running anonkneti -m0 localhost on the RFS.

      • nToken authentication: Only if an nToken (or local HSM) is installed in the RFS. The --rfs-hkneti and --rfs-esn options specify the KNETI hash and ESN of the nToken.

        RFS_HKNETI and RFS_ESN can be obtained by running ntokenenroll -H on the RFS.

  2. If the image file you require is not on the RFS, copy the directory that contains the required image file to the following directory on the RFS:

    %NFAST_HOME%\nethsm-firmware

  3. Use the nethsmadmin utility to make the nShield Connect use a specific image file from the RFS. Run the command:

    nethsmadmin --module=MODULE --upgrade-image=image_name

    In this command:

    • MODULE specifies the HSM to use, by its ModuleID (default = 1)

    • image_name specifies the image file to use from the RFS

      image_name must be the path to the image file that is displayed when you execute the nethsmadmin command with the --list-images option. Errors are reported if you use either just the image name, or the full path.

      The following is an example of the output:

      nethsmadmin --upgrade-image=nethsm-firmware/latest-xc-plus-12-60-2-vsn31/nCx3N.nff
Initiating appliance image upgrade using file nethsm-firmware/latest-xc-plus-12-60-2-vsn31/nCx3N.nff
Upgrade operation state changed to: Image Transfer Initiated
Upgrade operation state changed to: Image Transferred
Upgrade operation state changed to: Image Verified
Not able to contact appliance because of reason(23): CrossModule,#1-NetworkError
Upgrade operation final state: Image Verified
Image upgrade completed. Please wait for appliance to reboot.
Please wait for approximately half an hour for the appliance to internally upgrade.

      The following line is expected as the Connect temporarily severs its network connection whilst it performs certain sensitive activities such as a firmware upgrade. No action is required.

      Not able to contact appliance because of reason(23): CrossModule,#1-NetworkError
      If the nShield Connect suffers a loss of power while you are upgrading the image file and/or internal module firmware, you should exit the nethsmadmin utility and try to restart the process at Step 1, once power has been restored to the HSM.

  4. Run the enquiry command-line utility to verify the HSM is in operational state and has the correct firmware version. In Operational mode, the enquiry command-line utility shows the version number of the firmware

    Linux:

    /opt/nfast/bin/enquiry

    Windows:

    C:\Program Files\nCipher\nfast\bin>enquiry.exe

Upgrade the nShield Solo firmware

  1. Sign in to the host as an Administrator.

  2. Put the HSM in Maintenance mode and reset the HSM.

    For information on changing the mode, see the nShield Edge and nShield Solo User Guide Appendix, Checking and changing the mode on an nShield Solo module.

  3. Run the following command-line utility to check that the HSM is in the pre-maintenance state.

    Linux:

    /opt/nfast/bin/enquiry

    Windows:

    C:\Program Files\nCipher\nfast\bin>enquiry
    If the nShield Solo HSM is still in the operational state, it means that the override switch is on. Refer to the installation instructions in the nShield Edge and nShield Solo Installation Guide for information on accessing the override switch and switching it off.

  4. Locate the firmware folder on the installation media in the firmware directory. For example:

    Linux:

    /tmp/firmware/FW_VERSION

    Windows:

    E:\firmware\FW_VERSION

  5. Load the new firmware:

    Linux:

    /opt/nfast/bin/loadrom –m1 /tmp/firmware/FW_Version/ncx3p-xx.nff

    Windows:

    C:\Program Files\nCipher\nfast\bin>loadrom –m1 E:\firmware\FW_VERSION\ncx3p-xx.nff

    The upgrade may take a while to complete, during which time no activity will be observed. Wait at least five minutes before proceeding unless you are informed the upgrade has completed successfully beforehand.

  6. Solo XC only:

    Reboot the Solo XC for the firmware upgrade to take effect.

    Linux:

    • Bare metal environments:

      With the module in Maintenance mode, run the following command to reboot the Solo XC.

      nopclearfail -S -m<module_number>

      Wait for the Solo XC to reboot, which will take about ten minutes on a host machine running Linux.

      The module has completed rebooting when running enquiry no longer shows the module as Offline.

    • Virtual environment hosts:

      Reboot the Solo XC by rebooting the system that is hosting the Solo XC.

    Windows:

    With the module in Maintenance mode, reboot the Solo XC for the firmware upgrade to take effect. To do this, reboot the system that is hosting the Solo XC.

    Wait for the Solo XC to reboot. The module has completed rebooting when running enquiry no longer shows the module as Offline.

  7. Put the HSM in Initialization mode and reset the HSM:

    Linux:

    /opt/nfast/bin/initunit

    Windows:

    C:\Program Files\nCipher\nfast\bin>initunit

  8. Put the HSM into Operational mode.

  9. Run the enquiry command-line utility to verify the HSM is in operational state and has the correct firmware version. In Operational mode, the enquiry command-line utility shows the version number of the firmware.

Re-install the Security World software

Ensure that you select to install the Remote Administration Service package. The new installation will create the user roles, etc. that are required for Remote Administration. For re-installation instructions, follow the Installation Guide of the HSM

Ensure the nShield Solo+/ XC HSM is warranted with a KLF2 warrant

  1. Confirm that a warrant is installed and that it is a KLF2 warrant.

    nfwarrant.exe --check

  2. If no warrant exists or it is a KLF1 one, generate a certificate signing request:

    nfwarrant.exe --csr --req=esn_of_module

  3. Supply the certificate signing request to Entrust nShield Support who will then issue you a warrant for use with the specified HSM.

  4. Warrant the HSM, see the nShield Solo User Guide.

Enable config push on nShield Connect

You can allow configuration files to be pushed from the RFS and/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 Connect front panel.

Enabling config push from the RFS

On the Connect display, use the right-hand navigation button to select System > System configuration > Remote File System, and follow the steps described in the nShield Connect User Guide. 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 Connect front panel, whereas the client config push only supports specifying authentication either from the nShield Connect 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 Connect 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 Connect 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.

Migrate existing ACS cards to Smartcards

If your existing ACS is of type not explicitly labeled as Remote Administrator Ready, it may be necessary to migrate existing ACS to the Smartcards, see Replacing the Administrator Card Set in the nShield Connect User Guide.

Change the Remote Administration Service port

To change the port used by Remote Administration Clients to access the Remote Administration Service, set the port field in the remote_administration_service_slot_server_startup section of the configuration file:

[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

Edit the Authorized Card List

You can only use Smartcards with Remote Administration if they belong to the Authorized Card List.

To include a Smartcard in the Authorized Card List:

  1. Obtain the serial number for the Smartcard you want to add to the list.

    The serial number is printed on the card or can be displayed by inserting the Smartcard into a slot and running slotinfo -m1 -s0, where 1 is the number of the HSM and 0 is the number of the slot.

  2. Add the 16-digit serial number of the card to the opt/nfast/kmdata/config/cardlist (Linux) or C:\ProgramData\nCipher\Key Management data\config\cardlist (Windows) text file, for example:

    4286005559064791
4286005559064792
4286005559064793

  3. Copy the updated cardlist file from the RFS to all clients.

    The cardlist file must be updated on all clients. Network-attached HSMs use the cardlist file on the RFS for front panel operations. Client-initiated card operations use the cardlist file on the client computer.

You can allow any Smartcard to be used by adding the wildcard character * to the cardlist file instead of individual serial numbers, however Entrust recommends against this. Because authorizing Smartcards in this way allows all Smartcards to be used as Remote Administrator Cards, you should only do it in controlled circumstances.

Set up dynamic slots

Set up dynamic slots using the nShield Connect HSM front panel

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

    OR

    Use the dynamic_slots section in the client configuration file to define the number of dynamic slots for each relevant HSM.

  2. Clear the HSM for the changes to take effect, run the nopclearfail command or press the Clear button on the front of the unit. The -a option clears all enrolled HSMs.

    Linux:

    #/opt/nfast/bin/nopclearfail -c -a

    Windows:

    C:\Program Files\nCipher\nfast\bin>nopclearfail.exe -c -a

    The following message is displayed:

    Module 1, command ClearUnit: OK
Module 2, command ClearUnit: OK

  3. Check if dynamic slots appear by running the slotinfo command:

    Linux:

    #/opt/nfast/bin/slotinfo -m2

    Windows:

    C:\Program Files\nCipher\nfast\bin>slotinfo.exe -m2

    The following message is displayed:

    Module 2:
Slot    Type            Token       IC  Flags   Details
#0      Smartcard       present     1   A
#1      Software Tkn    -           0
#2      Smartcard       -           0   AD
#3      Smartcard       -           0   AD

    The dynamic slots are identified with the D flag in the example above, slots 2 and 3.

Set up dynamic slots for nShield Connect remotely via config push option

In the following example the configuration file is pushed from the RFS. For more information, see Enable config push on nShield Connect.

  1. Sign in to the RFS machine as a privileged user.

  2. Create a copy of the configuration file as config.new, from the RFS in the following directory on the remote computer.

    Linux:

    /opt/nfast/kmdata/hsm-ESN/config

    Windows:

    C:\Program Data\nCipher\nfast\kmdata\hsm-ESN\config

    In the example below, following config file copied as config.new.

    /opt/nfast/kmdata/hsm-49D5-C944-F159/config/config.new

  3. Edit the config.new file so that it contains the required configuration for dynamic_slots as shown below:

    [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
esn=esn_number
slotcount=2

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

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

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

    For example:

    /opt/nfast/bin/cfg-pushnethsm –address 192.168.156.30 /opt/nfast/kmdata/hsm-49D5-C944-F159/config/config.new

  5. Check that the configuration file on the RFS has been updated with the dynamic_slots changes. This can be confirmed using the timestamp on the updated config file.

  6. Clear the HSM for the changes to take effect, run the nopclearfail command:

    #/opt/nfast/bin/nopclearfail -c -a
Module 1, command ClearUnit: OK
Module 2, command ClearUnit: OK

  7. Check if dynamic slots appear by running the slotinfo command:

    #/opt/nfast/bin/slotinfo –m2
Module 2:
Slot    Type            Token       IC  Flags Details
#0      Smartcard       present     1   A
#1      Software Tkn    -           0
#2      Smartcard       -           0   AD
#3      Smartcard       -           0   AD

Set up dynamic slots for nShield Solo

  1. Sign in into the computer where the nShield Solo HSM is installed, as privileged user.

  2. Navigate to the following folder from the terminal.

    Linux:

    /opt/nfast/kmdata/config/

    Windows:

    C:\Program Data\nCipher\nfast\kmdata\config

  3. Edit the config file so that it contains the required configuration for dynamic_slots as shown below:

    [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
esn=esn_number
slotcount=2

    To add multiple ESN and slot count entries, separate them by four dashes:

    esn=esn_number_1
slotcount=2
----
esn=esn_number_2
slotcount=2

  4. Clear the HSM for the changes to take effect, run the nopclearfail command:

    Linux:

    #/opt/nfast/bin/nopclearfail -c -a

    Windows:

    C:\Program Files\nCipher\nfast\bin>nopclearfail.exe -c -a

    The following message will be displayed:

    Module 1, command ClearUnit: OK
Module 2, command ClearUnit: OK

  5. Check if dynamic slots appear by running the slotinfo command:

    #/opt/nfast/bin/slotinfo –m1
Module 1:
Slot    Type            Token       IC  Flags   Details
#0      Smartcard       present     1   A
#1      Software Tkn    -           0
#2      Smartcard       -           0   AD
#3      Smartcard       -           0   AD

Map dynamic slots to slot #0

You must have a working initialized Security World before you can map slots to Slot #0. Some APIs require that all tokens be loaded to Slot #0, for example, PKCS#11.

To map a dynamic slot to slot 0 from the front panel of an nShield Connect:

  1. From the menu navigate to Security World mgmt [3] > Set up dynamic slots [3-9] > Slot mapping and set the required dynamic slot to exchange for slot 0.

  2. Clear the HSM after initiating the change.

  3. If you want to set slot mapping using the nShield Connect configuration file, make sure that you have enabled Allow autopush for the nShield Connect.

  4. Navigate to the nShield Connect configuration file %NFAST_KMDATA%\HSM-ESN (for example, C:\ProgramData\nCipher\Key Management Data\hsm-HSM-ESN\config\config) and open it using your preferred test editor. Look for:

    [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

  5. Uncomment the esn and slot entries and enter the relevant nShield HSM ESN and the number of the slot you want to mark as slot #0 (for example, 2).

  6. Save the file as config.new.

  7. Push the config.new file to the nShield HSM using the following command:

    cfg-pushnethsm.exe -a Connect_IP_address full_path_to_the_config.new_file

  8. Execute the nopclearfail -c -mx command, where x is the number of the nShield HSM.

Change the timeout limits for dynamic slots

To change the timeout limit for round trip network delays or card removal, set the round_trip_time_limit or card_remove_detect_time_limit fields in the dynamic_slot_timeouts section of the configuration file:

[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