Set up communication between host and module

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.

The hsmadmin enroll command automates the installation of SSH keys.

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.

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.

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

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.

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.

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.

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.