Set up communication between host and module (nShield 5s HSMs)

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 (nShield 5 HSMs). You need to install the SSH keys for each service before you can use those services.

From firmware versions 13.5 onwards the SSH keys are further protected by an internally generated certificate. This certificate binds an SSH key to the ESN of the module which generated the key. Existing warrants validate that the HSM is a genuine Entrust module with that same ESN. The combination of the certificate and warrant provides a way to validate that the SSH keys have not been tampered with after being generated.

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.

From firmware versions 13.5 onwards, you will not be able to change the SSH keys while in Primary mode if the system clock is invalid. See System interaction with the system clock. In this situation you must be in Recovery mode to reset the system time.
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.

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.

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 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:

  • is in recovery mode

  • is running a firmware version prior to 13.5

  • has been upgraded to a firmware version of 13.5 or later but has not performed a factory state operation since the upgrade.

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

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 (nShield 5s HSMs) 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, for example, with /opt/nfast/sbin/init.d-ncipher restart.

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

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 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.

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 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.

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. Make sure that the HSM is in Maintenance mode, then 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. Run hsmadmin enroll on the source host to refresh the list it has of installed nShield HSM HSMs.

  5. Run hsmadmin enroll on the destination host.