Set up communication between host and module

Overview of SSH keys

Communications between the host and the HSM are protected by use of SSH secure channels. To allow mutual authentication of the endpoints, the SSH protocol uses separate key pairs in the host and the HSM. The functionality within the HSM is divided into different services that use separate SSH channels. See Platform services and ncoreapi. You need to install the SSH keys for each service before you can use those services.

Entrust recommends that you back up the sshadmin key as described in Making a backup whenever SSH keys are installed or changed, if your security policy allows.

Installation of SSH keys as part of software installation

The hsmadmin enroll command automates the installation of SSH keys.

This command is run automatically as part of the software installation script

Installation of SSH keys independently of a software installation

If the HSM has been returned to factory state, either with the hsmadmin factorystate command or by booting the HSM in recovery mode, as described in Recovery mode, you must install the SSH keys with the hsmadmin enroll command before any other actions can be performed.

The hsmadmin enroll command can be run on a module in which SSH keys have already been installed. In such a system, the command detects that valid keys already exist and takes no action.

If you are installing SSH keys due to their accidental loss or erasure, and you have previously made a backup of the sshadmin key using hsmadmin keys backup, then you can install them without returning your HSM to factory state by passing the path to the backed-up sshadmin key to hsmadmin keys restore.

Viewing installed SSH keys

The SSH keys installed on the host and each connected HSM can be viewed using the command hsmadmin keys show. All the keys shown are public keys. Private keys are not viewable with this command.

The command also shows the date and time at which the client (host) keys were installed.

Changing installed SSH keys

If your security policy requires you to change the client (host) SSH keys, you can achieve this with the following method.

  1. Print the currently installed keys with the command hsmadmin keys show

  2. Generate and install new client keys with the command hsmadmin keys roll. See SSH Client Key Protection for information about protection options that can be set on keys during generation.

The hardserver must be restarted in order to be able to use the new ncoreapi SSH client key after performing this operation, e.g. with /opt/nfast/sbin/init.d-ncipher restart. . Verify that the new keys have been installed with the command hsmadmin keys show

It is not possible to change the server (HSM) keys with this method. Should you be required to change the server keys, this can only be achieved by returning the unit to factory state with the hsmadmin factorystate command or by booting the HSM in recovery mode, see Recovery mode.

Making a backup of installed SSH keys

If your security policy allows it, make a backup of your private client key for the sshadmin service so that communication with the HSM can be re-established if the installed keys are erased or otherwise lost.

Do this with hsmadmin keys backup for verbatim copy of the sshadmin key with its existing protections (by default, it is tied to the host machine). Use hsmadmin keys backup --passphrase to backup the sshadmin key with a user-supplied passphrase so that it can be restored on another machine or after a re-installlation of the OS if necessary.

The backup key should be protected from unauthorized access. Refer to your security procedures for information on how to store the backup file.

Restoring SSH keys from backup

If you erase or lose your SSH keys, communication with the HSM will be lost. If you have previously made a backup of those keys using hsmadmin keys backup you can restore that backup with hsmadmin keys restore. This command will restore the private client key for the sshadmin service and then create keys for all other services.

Preparing an HSM for use in another host

The client (host) SSH keys must be the same for every HSM connected to the same host. This will happen automatically if the HSMs are all installed together and are all in factory state. The hsmadmin enroll command installs the same client keys in each HSM.

Additional HSMs can be installed in a host at any time and, provided that the new modules are in factory state, the hsmadmin enroll command installs the same client keys in the new modules as are currently installed in any existing modules.

If it is necessary to be able to transfer a module from one host to another without returning it to factory state this can be achieved with the following method.

In the method below, the term 'source' refers to the host from which the module will be transferred and the term 'destination' refers to the host to which the module will be transferred.

  1. Backup the private sshadmin client key from the destination host to a location that can be accessed by the source host, such as a shared drive or a USB stick, with the following command:

    hsmadmin keys backup --passphrase <FILE>

    Where <FILE> specifies the location of the shared drive or USB stick. You will be prompted to enter and confirm a passphrase to use to protect the key.

  2. Install the destination host private sshadmin key on the source host with the following command:

     hsmadmin keys migrate --privkeyfile <FILE>

    Where <FILE> specifies the location of the file written in the previous step. You will be prompted to enter the passphrase of the key.

  3. Remove the module from the source host and install in the destination host.

    If the keys are not changed on the destination host, this step may be left indefinitely or until needed. For example, the module could be kept in storage as a cold standby unit.
  4. After removing the module, run hsmadmin enroll on the source host to refresh the list of installed nShield 5s HSMs.

  5. After installing the module, run hsmadmin enroll on the destination host.