SSH Client Key Protection

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

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.

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.

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`

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

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.

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.