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. See nShield 5s modes of operation for more about changing the mode.
Configure the HSM hardservers on their respective host machines 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 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 cfg-remoteslots utility.
Update the HSM configuration file, see Configuring hardservers for Remote Operator using the HSM configuration file.

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):
1. Edit the slot_exports section of the hardserver configuration file by adding lines of the form:
  local_esn=AAAA-AAAA-AAAA local_slotid=0 remote_ip=222.222.222.222 remote_esn=BBBB-BBBB-BBBB
2. Run the cfg-reread command-line utility to prompt the hardserver to read the configuration changes.
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).
1. Edit the slot_imports section of the hardserver configuration file by adding lines of the form:
  local_esn=BBBB-BBBB-BBBB local_slotid=2 remote_ip=111.111.111.111 remote_esn=AAAA-AAAA-AAAA remote_slotid=0
  This example assigns the imported slot to ID 2.
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.

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.

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 the following:
1. Use the slot_imports section in the hardserver configuration file to import remote slots from HSMs in the same Security World for each relevant HSM.
2. Use the slot_mapping section in the hardserver configuration file to define the remote slot which is to be swapped with slot #0 for each relevant HSM.

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.

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:

Re-read the hardserver configuration file by running cfg-reread.
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 hardservers for Remote Operator, 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, 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 hardservers for Remote Operator, 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.