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.

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:

  2. Cards have been enabled for use through RAC. See Edit the cardlist file to enable cards for use through RAC.

  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 a remote computer, see Enable auto 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.

  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/12-60-2-latest/nCx3N.nff
Initiating appliance image upgrade using file nethsm-firmware/12-60-2-latest/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 auto push on nShield Connect

  1. From the nShield Connect front panel main menu, select System configuration > Config file options > Allow auto push.

  2. Select IPv4 then specify the IP address of the computer from which to accept the configuration.

  3. Make sure that port 9005 is open for incoming connection requests from the nShield Remote Administration clients.

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.

Edit the cardlist file to enable cards for use through RAC

  1. Go to the following folder on the RFS:

    Linux:

    #/opt/nfast/kmdata/config

    Windows:

    C:\ProgramData\nCipher\Key Management Data\config

  2. Open the cardlist file in a text editor.

    Add * to authorize all Smartcards for Remote Administration. If only certain cards are authorized for this use, list them by their serial number:

    4286005559064791
4286005559064792
4286005559064793

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

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 RFS server is being used as remote push computer. For setting up autopush, see Enable auto 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 e.g. 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 Connect ESN and the number of the slot you want to mark as slot #0 (e.g. 2).

  6. Save the file as config.new.

  7. Push the config.new file to the nShield Connect 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 Connect module.