Remote Operator

This chapter explains:

The concept of Remote Operator
How to configure Remote Operator.

If you wish to use the Remote Operator feature, you must have enabled it as described in Enabling optional features. The Remote Operator feature must have been ordered for, and enabled on, the nShield module that you intend to use as the remote, unattended module.

About Remote Operator

The Remote Operator feature enables the contents of a smart card inserted into the slot of one module (the attended module) to be securely transmitted and loaded onto another module (an unattended module). This is useful when you need to load an OCS-protected key onto a machine to which you do not have physical access (because, for example, it is in a secure area).

For Remote Operator to work, the modules must be in the same Security World. You insert the required cards from the OCS into a slot in the attended module. From this module, the contents of the OCS are transmitted over secure channels to the unattended module, which then loads them. You do not need physical access to the unattended module in order to load the OCS onto it.

The following limitations apply to Remote Operator:

You cannot access non-persistent card sets remotely
You cannot use the createocs command-line utility to write new cards or card sets remotely.

You can export a slot from an attended module and import a slot to any (unattended) module in the Security World. Before you can import a slot to one module, you must first export it from another module.

Configuring Remote Operator

This section explains how to configure Remote Operator.

Overview of configuring Remote Operator

Before you can use Remote Operator, you must perform the following initial configuration tasks:

Configure the HSMs for Remote Operator.

The HSMs must be in the same Security World, and must have been initialized with remote card set reading enabled.

Both the attended and the unattended HSM must be in operational mode before they can import or export slots. * The HSM must be in pre-initialization mode. See Checking and changing the mode on the HSM for more about changing the mode.
Configure the HSMs for slot import and export, as appropriate.

Starting from 12.81, you can export and import dynamic slots as Remote Operator slots.

After the initial configuration is complete, to use Remote Operator you must:

Create a Remote OCS (that is, an OCS with the correct permissions for Remote Operator).
Generate keys that are protected by the Remote OCS.
Ensure your application is configured to use keys protected by the Remote OCS.

Configuring HSMs for Remote Operator

Ensure both HSMs are initialized into the same Security World; see Adding or restoring an HSM to the Security World.

By default, HSMs are initialized with remote card-set reading enabled. If you do not want an HSM to be able to read remote card sets, you can initialize it by running the new-world with the -S MODULE (where MODULE is the HSM’s ID number).

For the unattended HSM:
1. Check whether the Remote Operator feature is enabled by running the enquiry command-line utility. The output for the HSM must include Remote Share in its list of Features.
2. Check whether the HSM has permission to allow loading of Remote OCSs by selecting Security World mgmt > Display World info.
3. Check whether the correct software, with permission to receive remote shares, is present by running the nfkminfo command-line utility.
  
  The output from this selection must show that flags are set to include ShareTarget, as in the following example:
  Module #1 generation 2 state 0x2 Usable flags 0x10000 ShareTarget n_slots 3 esn 8851-43DF-3795 hkml 391eb12cf98c112094c1d3ca06c54bfe3c07a103

Configuring slot import and export

For information about the parameters controlled by the hardserver configuration file, see:

Before you can configure hardservers for Remote Operator, ensure that:

You have configured the attended and unattended HSMs for Remote Operator as described in Configuring HSMs for Remote Operator.
Your network firewall settings are correct. See the Installation Guide for more information about firewall settings.

When the HSMs have been configured, use one of the following methods to configure slot import and export:

Use the nShield HSM front panel, see Configuring slot import and export using the nShield HSM front panel.
Update the HSM configuration file, see Configuring hardservers for Remote Operator using the HSM configuration file.

Configuring slot import and export using the nShield HSM front panel

Configure the attended HSM to export a slot by following these steps:
1. From the main menu, select Security World mgmt > Set up remote slots > Export slot.
  
  Use this option for exporting slot #0 only.
  
  If you need to configure the export of slots other than 0, see Configuring hardservers for Remote Operator using the HSM configuration file.
2. Specify the HSM to which the slot is being export by supplying values for:
  - The IP address of the unattended HSM
  - The ESN of the unattended HSM.
Configure the unattended HSM to import the slot that you are exporting from the attended HSM by following these steps:
1. From the main menu, select Security World mgmt > Set up remote slots > Import slot.
2. Specify the details of the Remote Operator slot by supplying values for:
  - The IP address of the HSM from which the slot is being exported
  - The ESN of the HSM from which the slot is being exported
  - The ID of the slot on the importing HSM
  - The port to use to connect to the hardserver hosting the attended HSM.

You can check that the slot was imported successfully by, on the unattended machine, running the command:

slotinfo -m 1

If slot importation was successful, the output from this command includes the line:

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

The R in the Flags column indicates that slot 2 is a Remote Operator slot.

Applications running on the unattended machine can now use slot 2 to load OCSs that are presented to slot 0 on the attended machine. If any of the cards require a passphrase, the application must pass this to the unattended HSM in the usual way.

For the application to be able to load the OCS onto the unattended HSM, it must be able to read the card set files associated with the OCS from the local Key Management Data directory. If the OCS was created on a different machine, you must copy the card set files in the Key Management Data directory onto the unattended machine (either manually or by using client cooperation; for more information, see Setting up client cooperation).

The same applies for any keys that an application on an unattended HSM needs to load but that were not generated on that machine.

Configuring hardservers for Remote Operator using the HSM configuration file

On the attended HSM’s host machine, configure the hardserver to allow slot 0 of the local HSM (with ESN AAAA-AAAA-AAAA) to be exported to a remote HSM (with ESN BBBB-BBBB-BBBB, hosted by the machine with the IP address 222.222.222.222):

Create a copy of the configuration file as config.new in the following directory.

Edit the sections related to slot export in config.new:

[slot_exports]
# Start of the slot_exports section
# Local slots that the hardserver should allow remote modules to import. Note
# that if a slot which has been remapped in the slot_mapping section is to be
# exported, it must be referred to in this section by its original
# (pre-mapping) local_slotid.
# Each entry has the following fields:
#
# ESN of the local module whose slot is allowed to be exported.
#  local_esn=ESN
#
# SlotID of the slot which is allowed to be exported. (default=0)
#  local_slotid=INT
#
# IP address of the machine allowed to import the slot or empty to allow all
# machines. (which is the default)
#  remote_ip=ADDR
#
# ESN of the module allowed to import the slot or "" to allow all modules
# which are permitted in the security world. (default ="")
#  remote_esn=ESN

[slot_mapping]
# Start of the slot_mapping section
# Slot remapping configuration. Notes for Remote Operator users: If a slot
# which is remapped in this section is also exported in the slot_exports
# section, the local_slotid field in the slot_exports section must be set to
# the original (pre-mapping) local_slotid. When importing that slot in another
# module, the slot_imports section must refer instead to the new
# (post-mapping) remote_slotid.
# 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

Run the cfg-pushnethsm utility on the updated configuration file, specifying the updated file and the network address of the nShield HSM to load the new configuration.
```
cfg-pushnethsm --address=<module_address> <path_to_config_file>
```
Check that the configuration file has been updated. 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:

On the unattended module’s host machine, configure the hardserver to import slot 0 from the remote attended module (with ESN AAAA-AAAA-AAAA, hosted by the machine with the IP address 111.111.111.111) to the local module (with ESN BBBB-BBB-BBBB).

Edit the sections related to slot import in config.new:

[slot_imports]
# Start of the slot_imports section
# Remote slots that the hardserver should import to modules on this machine.
# Note that if a remote slot which has been remapped in the slot_mapping
# section on the remote system is to be imported, it must be referred to in
# this section by its new (post-mapping) remote_slotid.
# Each entry has the following fields:
#
# ESN of the local module to import the slot to
#  local_esn=ESN
#
# SlotID to use to refer to the slot when it is imported on the local module.
# Setting this value to 0 means it will be automatically assigned to the
# lowest available value. (default=0)
#  local_slotid=INT
#
# IP address of the machine hosting the slot to import
#  remote_ip=ADDR
#
# Port to connect to on the remote machine
#  remote_port=PORT
#
# ESN of the remote module to import the slot from
#  remote_esn=ESN
#
# SlotID of the slot to import on the remote module (default=0)
#  remote_slotid=INT

Run the cfg-pushnethsm utility on the updated configuration file, specifying the updated file and the network address of the nShield HSM to load the new configuration.
```
cfg-pushnethsm --address=<module_address> <path_to_config_file>
```
Check that the configuration file has been updated. 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:

Check the Remote Operator slot configuration:
```
slotinfo -m 1
```
If slot import was successful, the output from this command includes the line:
```
Slot Type            Token   IC    Flags   Details
#0   Smartcard       present 3     A
#1   Software Tkn    -       0
#2   Smartcard       -       0     AR
```
The R in the Flags column indicates that slot 2 is a Remote Operator slot.

The same applies for any keys that an application on an unattended HSM needs to load but that were not generated on that machine.

Using Remote Operator with applications requiring cards in slot 0

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

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, 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 remote 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 AR
#1 Software Tkn - 0
#2 Smartcard - 0 A
```
The R in the Flags column indicates that slot #0 is now a Remote Slot

Slot mapping can also be configured for a dynamic remote slot, i.e. a dynamic slot in a different HSM which has been imported to the relevant HSM. The Flags column will contain the flags ARD.

or:

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

When dynamic slots are added to an HSM after the initial configuration was done with only remote slots, the dynamic slots will take precedence over the remote slots. The slot numbers of the remote slots will therefore change. You will have to revise the slot mapping and specify the new slot number of the remote slot.

Using Remote Operator on Remapped Slots

If a slot has been mapped to slot #0 on the attended HSM, it is still possible to export the local slot to an unattended HSM. Further, if the mapped slot is a dynamic slot, it is possible to export it as well. To do this, do the following:

On the attended HSM’s host machine, configure the hardserver to allow the export of the relevant slot by refering to it by its original slotID.
1. To export the local slot, local_slotid=0.
2. To export a dynamic slot, local_slotid=2 (or higher if the HSM is configured with multiple dynamic slots).
On the unattended HSM’s host machine, configure the hardserver to import the relevant slot by refering to it by its new slotID.
1. To import the exported local slot, remote_slotid=2 (or higher, same as the slotID specified in the mapping section of the attended HSM’s configuration file).
2. To import the exported dynamic slot, remote_slotid=0.

Configuration Example for Using Remote Administration and Remote Operator Concurrently

Below is an example of the relevant portions of a hardserver config file to achieve concurrent usage of Remote Administration and Remote Operator. It is broken up and explained per config file section.

The dynamic_slots section allocates exactly 1 dynamic slot to each of modules 1 and 2.

[dynamic_slots]
esn=BBBB-BBBB-BBBB
slotcount=1
-----
esn=AAAA-AAAA-AAAA
slotcount=1

The slot_imports section first imports module 1 slot #0 to module 2 slot #3 and then imports module 1 slot #2 to module 2 slot #4.

[slot_imports]
local_esn=AAAA-AAAA-AAAA
remote_ip=127.0.0.1
remote_port=9004
remote_esn=BBBB-BBBB-BBBB
remote_slotid=0
-----
local_esn=AAAA-AAAA-AAAA
remote_ip=127.0.0.1
remote_port=9004
remote_esn=BBBB-BBBB-BBBB
remote_slotid=2

The slot_exports section allows module 1 slot #0 and module 1 slot #2 to be exported by that module.

[slot_exports]
local_esn=BBBB-BBBB-BBBB
local_slotid=0
-----
local_esn=BBBB-BBBB-BBBB
local_slotid=2

The slot_mapping section swaps module 2 slot #0 and module 2 slot #2.

[slot_mapping]
esn=AAAA-AAAA-AAAA
slot=2

After making the changes above to the hardserver configuration file:

Push the hardserver configuration file to the nShield HSM by running cfg-pushnethsm.
Clear the modules by running nopclearfail.

This is the expected system configuration output for the relevant modules:

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

slotinfo -m2
Slot Type             Token    IC     Flags    Details
#0   Smartcard        -        0      AD
#1   Software Tkn     -        0
#2   Smartcard        -        0      A
#3   Smartcard        -        0      AR
#4   Smartcard        -        0      ARD

Using Remote Operator with Remote Administration with Older Versions of the Software

Versions of Remote Operator older than 12.81 do not support its concurrent use with the Remote Administrator feature. In such a case, the following features are not supported:

Exporting and importing dynamic slots
Mapping remote slots to slot #0
Automatic assignment of slotID when importing slots

It is possible to use some of the features when the attended HSM (exporting end) has the new version of the software (12.81+) and the unattended HSM (importing end) has an older version (pre-12.81).

A dynamic slot which has been exported by the attended HSM can be imported to the unattended HSM. Its local slotID will need to be manually specified if the unattended HSM has any dynamic slots configured. This is due to the default import slot (slot #2) being occupied by the dynamic slot. The unattended HSM can remap its dynamic slots to slot #0, but cannot remap any of its imported slots.

Creating OCSs and keys for Remote Operator

When you have configured the HSMs and slot import and export, you can create Remote OCSs and generate keys protected by them. These Remote OCSs and keys can be used by applications running on the unattended HSM.

For the most part, card sets and keys intended to be used with Remote Operator are similar to their ordinary, non-Remote counterparts.

Creating OCSs for use with Remote Operator

You can generate Remote OCSs by using KeySafe or by running the createocs command-line utility with the -q|--remotely_readable option specified. The cards in a Remote OCS must be created as persistent; see Persistent Operator Card Sets.

To check whether the card in a slot is from a Remote OCS, select Security World mgmt > Display World info from the main menu or run the nfkminfo command-line utility. The output displays slot section information similar to the following:

Module #1 Slot #0 IC 1
generation         1
phystype           SmartCard
slotlistflags      0x2
state              0x5
Operator flags     0x20000 RemoteEnabled
shareno            1
shares             LTU(Remote)
error              OK

In this example output, the RemoteEnabled flag indicates the card in the slot is from a Remote OCS.

If you create a Remote OCS on the attended machine, then you must copy the Key Management Data files on the attended machine to the unattended machine.

Both the attended and unattended HSMs must be in the same Security World before you generate a Remote OCS. If you are not using client cooperation, the Key Management Data directories must be manually synchronized after you generate the Remote OCS.

If you already have recoverable keys protected by a non-Remote OCS, you can transfer them to a new Remote OCS by using KeySafe or the replaceocs command-line utility.

Loading Remote Operator Card Sets

Once configured, the Remote Operator slots can be used by all the standard nShield libraries. A Remote Operator slot can be used to load any OCSs that have been created to allow remote loading. For more information about the applications to use with remote cards, see Application interfaces. For more information about Remote Operator slots, see Remote Operator.

After an OCS has been inserted into a Remote Operator slot, for each time a given card is inserted, the module only allows each share on that card to be read one time. If there is a second attempt to read shares from that card before the card is reinserted, the operation fails with a UseLimitsUnavailable error.

Generating keys for use with Remote Operator

After you have created a Remote OCS, to generate keys protected by it you can run KeySafe or the generatekey and preload command-line utilities on the unattended module, inserting cards to the slot attached to the attended module. For more information about generating and working with keys, see Working with keys.

If you generate keys protected by a Remote OCS on the attended module, then you must copy the files in the Key Management Data directory on the attended machine to the unattended module.

KeySafe can list imported slots, but cannot use them.

If you already have an OCS-protected key that you want to use, but the protecting OCS is not a Remote OCS, you can use KeySafe to protect the key under a new Remote OCS if the key was originally generated with the key recovery option enabled.

However, if the key was not generated with key recovery enabled, you cannot protect it under a different OCS. In such a case, you must generate a new key to be protected by a Remote OCS.

Configuring the application

After you have configured the HSMs and slot import and export, created a Remote OCS, and generated keys protected by the Remote OCS, configure the application with which you want to use these keys as appropriate for the particular application.

After you have configured the application, start it remotely from the attended machine. Insert cards from the OCS into the attended machine’s exported slot as prompted.

Managing Remote Operator slots using the unit front panel

Editing Remote Operator slots

You can change the details of a Remote Operator slot. You must always update the details of both the exported slot on the local module and the imported slot on the remote module.

To update an exported a slot on the module:

From the main menu, select Security World mgmt > Set up remote slots > Edit exported slot.
Select the exported slot that you want to update. Slots are identified by the IP address of the remote module.
Update the details of the slot.

To update an imported slot on the unit:

From the main menu, select Security World mgmt > Set up remote slots > Edit imported slot.
Select the imported slot that you want to update. Slots are identified by the IP address of the remote module.
Update the details of the slot.

Deleting Remote Operator slots

You can delete Remote Operator slots.

To delete an exported slot, from the main menu, select Security World mgmt > Set up remote slots > Delete exported slot and select the slot you want to delete.

To delete an imported slot, from the main menu, select Security World mgmt > Set up remote slots > Delete imported slot and select the slot you want to delete.