SSH Client Key Protection (nShield 5s HSMs)

SSH Services

This table explains what the different services are used for, to help inform what protection settings are appropriate for the client keys for those services in a deployment.

Service Service Description

Service	Service Description
`sshadmin`	Main authority for administration of the SSH services on the HSM. This key should have the strongest protection.
`ncoreapi`	nCore API service. Used by the hardserver for routine communication with the HSM.
`setup`	Setup service. Used for some administration options such as factory state.
`updater`	Updater service. Used for installing signed firmware upgrade packages.
`monitor`	Monitor service. Used for diagnostic operations such as retrieving logs with `hsmadmin logs`.
`launcher`	Launcher service. On versions with CodeSafe 5 support, this is used for starting CodeSafe 5 applications on the HSM.

sshadmin

Main authority for administration of the SSH services on the HSM. This key should have the strongest protection.

ncoreapi

nCore API service. Used by the hardserver for routine communication with the HSM.

setup

Setup service. Used for some administration options such as factory state.

updater

Updater service. Used for installing signed firmware upgrade packages.

monitor

Monitor service. Used for diagnostic operations such as retrieving logs with hsmadmin logs.

launcher

Launcher service. On versions with CodeSafe 5 support, this is used for starting CodeSafe 5 applications on the HSM.

SSH Client Key Encryption

SSH client keys are protected by a passphrase derived from one or more inputs including machine IDs and user-supplied passphrases.

These passphrases are derived automatically by applications which use the SSH keys, and with the exception of the option of user-supplied passphrases do not prompt the user.

Available SSH Key Protection Options

The following are the supported protection options for SSH keys. Multiple options can be combined in any order.

On Linux, although the hardserver runs as nfast user, it starts as root and then drops privileges. The hardserver derives any SSH key passphrases before dropping privileges, and so can use protections that are available only to root.

Option Description

Option	Description
`K`	Per-key nonce. Ensures that the derived passphrase is unique to the key.
`F`	Fixed nonce present in the nShield client software.
`S`	System UUID. Ties the key to the local machine. On Linux, this is only readable by root. This is available on most systems.
`B`	Baseboard UUID. Ties the key to the baseboard (motherboard) of the local machine. On Linux, this is only readable by root. This may not be available on all systems.
`G`	Global nonce. Ties the key to the local OS install. The global nonce is readable only by root or Administrators and is generated the first time the option is used to protect a key.
`P`	User passphrase. The key will require a user-supplied passphrase (in addition to any other protection options specified).

K

Per-key nonce. Ensures that the derived passphrase is unique to the key.

F

Fixed nonce present in the nShield client software.

S

System UUID. Ties the key to the local machine. On Linux, this is only readable by root. This is available on most systems.

B

Baseboard UUID. Ties the key to the baseboard (motherboard) of the local machine. On Linux, this is only readable by root. This may not be available on all systems.

G

Global nonce. Ties the key to the local OS install. The global nonce is readable only by root or Administrators and is generated the first time the option is used to protect a key.

P

User passphrase. The key will require a user-supplied passphrase (in addition to any other protection options specified).

User-supplied SSH Key passphrases

If a key is generated with protection by a user-supplied SSH key passphrase, there will be an interactive prompt on the console to enter and confirm the passphrase. When a key is loaded with passphrase protection, there will be an interactive prompt on the console to enter the passphrase.

To avoid interactive prompts for automation purposes, the user passphrase can be supplied using the environment variable NFAST_KEYPROT_PASS. If a user passphrase is specified for the ncoreapi service SSH key, then the environment variable is the only way to supply the passphrase as interactive prompts are disabled for the hardserver service.

Setting Protections on SSH keys

Protections are set on SSH keys when they are generated, either during hsmadmin enroll (if the keys are not already present) or during hsmadmin keys roll (if switching to a freshly generated set of SSH client keys).

Protections can be overridden using environment variables that are set in the environment of the above commands when the keys are generated. The protections for all SSH service keys can be overridden using the NFAST_KEYPROT environment variable. Individual SSH service keys can have their protections set directly using per-service environment variables as specified in the table below. If both NFAST_KEYPROT and the per-service environment variable are set, the per-service environment variable takes precedence.

Service Default Protection Environment Variable

Service	Default Protection	Environment Variable
`sshadmin`	`KFSG`	`NFAST_SSHADMIN_KEYPROT`
`ncoreapi`	`KFSG`	`NFAST_NCOREAPI_KEYPROT`
`setup`	`KFSG`	`NFAST_SETUP_KEYPROT`
`updater`	`KF`	`NFAST_UPDATER_KEYPROT`
`monitor`	`KF`	`NFAST_MONITOR_KEYPROT`
`launcher`	`KF`	`NFAST_LAUNCHER_KEYPROT`

sshadmin

KFSG

NFAST_SSHADMIN_KEYPROT

ncoreapi

KFSG

NFAST_NCOREAPI_KEYPROT

setup

KFSG

NFAST_SETUP_KEYPROT

updater

KF

NFAST_UPDATER_KEYPROT

monitor

KF

NFAST_MONITOR_KEYPROT

launcher

KF

NFAST_LAUNCHER_KEYPROT

Permissions on SSH keys

Access to SSH keys is controlled by permissions on the directories they are created in. The key directories are created with permissions during installation of the nShield software.

Linux

All keys are owned by user root, except for ncoreapi which is owned by user nfast. The table below shows what group can read each of the service keys by default. The group that can read each key can also be overridden with the environment variables listed below if set in the environment when running the install script /opt/nfast/sbin/install. The install script will always set the owner and group on the key, so if custom groups are used, they must be specified every time the install script is run. If the group specified in the environment variable does not exist, it will be created automatically by the install script.

Service Default Group Environment Variable

Service	Default Group	Environment Variable
`sshadmin`	`root`	`NFAST_SSHADMIN_GROUP`
`ncoreapi`	`root`	`NFAST_NCOREAPI_GROUP`
`setup`	`root`	`NFAST_SETUP_GROUP`
`updater`	`nfastadmin`	`NFAST_UPDATER_GROUP`
`monitor`	`nfastadmin`	`NFAST_MONITOR_GROUP`
`launcher`	`nfastadmin`	`NFAST_LAUNCHER_GROUP`

sshadmin

root

NFAST_SSHADMIN_GROUP

ncoreapi

root

NFAST_NCOREAPI_GROUP

setup

root

NFAST_SETUP_GROUP

updater

nfastadmin

NFAST_UPDATER_GROUP

monitor

nfastadmin

NFAST_MONITOR_GROUP

launcher

nfastadmin

NFAST_LAUNCHER_GROUP

Windows

SSH keys are created under the directory %NFAST_SERVICES_HOME%\client (C:\ProgramData\nCipher\services\client by default). The installer sets permissions on this directory to be read/write by the built-in local Administrators group only. If different permissions are wanted on particular keys to enable particular users or groups to perform certain operations, then these must be set manually on the keys and parent directories to permit the required access.