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 internal certificates are generated each time the HSM is factory-stated. If your HSM has been upgraded from a firmware version earlier than 13.5 you must factory state your HSM to generate the certificates. See factory state for more information.

The hsmadmin enroll command automates the installation of SSH keys.

On Linux, this command is run automatically as part of the software installation script. On Windows, this command must be run immediately after installation of the software.

See the Installation Guide for your HSM for further details.

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 factory state, 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 hsmadmin enroll command automatically validates certificates as part of the enrollment process and produces a warning if it fails to find a certificate for any service. This warning is expected if the HSM:

If you receive this warning in any other circumstance you should contact Entrust support.

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 nShield 5s modes of operation.

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 command 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 the command hsmadmin keys backup you can restore that backup with the command 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.