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:

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).
- If the HSM and the associated Security World are already installed but Remote Administration was not installed:
  - You have to re-install the Security World software. See Prepare an existing Security World installation for Remote Administration.
  - If ACS cards are already in use but they are not labeled Remote Administrator Ready, then the cards have to be migrated to Java cards before they can be used via a Remote Administration Client.
- Ensure the Remote Administration Service firewall port (default: 9005) is open for incoming connection requests from nShield Remote Administration clients.
Cards have been enabled for use through RAC. See Edit the Authorized Card List.
Dynamic slots have been configured so that cards can be presented remotely. See Set up dynamic slots.

Prepare an existing Security World installation for Remote Administration

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

Ensure the HSM firmware is compatible with Remote Administration.
For Solo HSMs only: Ensure the nShield Solo+/ XC HSM is warranted with a KLF2 warrant.
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.
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:

Re-install the Security World software

Ensure that you select to install the Remote Administration Service package. The new installation will set up everything that is required for Remote Administration, including user roles.

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

Confirm that a warrant is installed and that it is a KLF2 warrant.
```
nfwarrant.exe --check
```
If no warrant exists or it is a KLF1 one, generate a certificate signing request:
```
nfwarrant.exe --csr --req=esn_of_module
```
Supply the certificate signing request to Entrust nShield Support who will then issue you a warrant for use with the specified HSM.
Warrant the HSM, see Warrant Management.

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 nShield Connect front panel.

For more information, see Enable config push.

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 Replace the ACS.

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:

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.
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
```
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

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.
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
```

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.

Sign in to the RFS machine as a privileged user.
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
```

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

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.

Use the IP address of the nShield Connect on which to load the configuration and the full_path_to_config_file, including the 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
```
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.

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

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

Navigate to the following folder from the terminal.

Linux:

/opt/nfast/kmdata/config/

Windows:

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

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

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

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

Some APIs require that all tokens be loaded to Slot #0, for example, PKCS#11.

Prerequisite for network-attached HSMs

Allow autopush must be enabled for all network-attached HSM that you want to push configuration file changes to.

Map dynamic slots to slot #0 by updating the HSM configuration file (all HSM types)

Open the configuration file of the HSM (in %NFAST_KMDATA%\HSM-ESN) for editing.

Find the [slot-mapping] section, which defines for each specified HSM a slot to exchange with slot 0 for that HSM so that slot 0 becomes a dynamic slot and the local slot becomes the specified slot number. This is so that applications and utilities that only support slot 0 can use the Remote Administration Service.

esn	The ESN of the HSM to which the mapping applies.
slot	The slot number to be swapped with slot `0` so that `0` refers to a dynamic slot and the specified slot number refers to the HSM’s local slot. Default: `0`, which means no slot mapping.

[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

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.
Save the file as config.new.
Only for network-attached HSMs:
Push the config.new file to the network-attached HSM.
<path-to-config.new> is the full path to the <config.new> file of the network-attached HSM.
```
cfg-pushnethsm.exe -a <path-to-config.new>
```
Run nopclearfail for HSM <n>:
```
nopclearfail -c -m<n>
```

Map dynamic slots to slot #0 using the front panel (only network-attached HSMs)

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.
Clear the HSM after initiating the change.

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