KeySafe 5 Concepts

nShield KeySafe 5 agent

On each host machine in your estate that you want to manage with KeySafe 5, the KeySafe 5 agent service is required. The KeySafe 5 agent runs alongside the existing hardserver. The agent communicates the current state of the HSMs / Security World to the central platform and can action management operations for these resources. The KeySafe 5 agent ensures that all key management data, with the exception of keys, is synchronised between the nShield host machine and the central database. This information is then shared with each host machine in the Security World that has the KeySafe 5 agent running.

Host Machines

Each host machine can have one or more HSMs installed, and a single Security World. The HSM estate monitored by KeySafe 5 is located on one or more host machines.

For each nShield host machine that you want to manage with KeySafe 5, you must install a KeySafe 5 agent alongside the existing nShield hardserver on the host machine, see nShield KeySafe 5 agent.

HSM Pool

An HSM Pool is a collection of HSMs that are managed together, and which communicate using a KeySafe 5 agent. When you load a Security World into an HSM Pool, the Security World will be loaded onto all the HSMs in the HSM pool. The KeySafe 5 agent synchronises the configuration of the HSM pool with all other HSM pools in the Security World. For example:

  • When you create a new Card Set or Softcard (either through KeySafe 5 or manually) on a host machine, it will be synchronised to all HSM pools in the same Security World.

  • When you delete a Card Set or Softcard using KeySafe 5, that deletion will be applied by the agent to all HSM pools in the same Security World. However, if you delete a Softcard without using KeySafe 5, that deletion will not be applied to other HSM Pools in the same Security World.

An HSM can only be in one HSM pool at any time unless it is network-connected. However, the HSM can be moved between machines in the usual manner, and KeySafe 5 will reflect this change. An HSM may have the HSM Pool’s Security World loaded.

An nShield Connect may be enrolled into multiple HSM Pools, but it can only have one active Security World at a time.

HSM Type

KeySafe 5 uses HSM Type to distinguish between the management/monitoring capabilities of different HSM resources in KeySafe 5.

Full HSM

A complete HSM resource capable of most functionality except for creation of Tenancies. For example: nShield 5s, nShield Connect 5c, nShield XC, nShield Connect XC.

Platform HSM

An HSM that manages Tenancies and configuration for the physical module (Only applicable for nShield 5c 10G).

Tenant HSM

An HSM that can perform cryptographic operations but cannot manage Tenancies or configuration of the physical module (Only applicable for nShield 5c 10G).

Security World

Each HSM Pool can make use of a single Security World. Loading a Security World into an HSM Pool will result in that Security World being loaded onto all the HSMs in the pool. A single Security World may be loaded on multiple HSM Pools across many host machines.

For details of Security World use in KeySafe 5, see Security Worlds. For full details of Security World use, refer to the Security World documentation.

Security World Operations and authorizations

When performing an operation on the command-line, it must be performed in a single step. For example, creating a Security World. Here, all parameters must be specified, all cards inserted, and their passphrases entered.

With KeySafe 5 this is separated into two steps: creating an operation, and then authorising it. When creating an operation all the parameters for that operation are requested. The operation is then listed in a list of outstanding operations for the Security World to which it belongs, see Outstanding operations.

Whenever a user is required to present a card or a passphrase to complete an operation, an authorization is created. For example:

  • Security World creation requires writing a new Administrator Card Set so will require 'BlankCard' authorizations.

  • Security World loading requires presenting an existing Administrator Card Set so will require 'AdminCard' authorizations.

  • Operator Card Set creation requires writing a new Operator Card Set so will require 'BlankCard' authorizations.

  • Softcard creation requires setting a passphrase so will require a 'Passphrase' authorization.

If there is a specific order that the authorizations must be provided then a subset of the authorizations may initially be in 'Blocked' state.

Examples:

  • In a FIPS-140-2-level-3 Security World, operations such as OCS or Softcard creation require an initial FIPS authorization (presentation of an Administrator or Operator card from the Security World) to authorize the operation. In this case a 'FIPS' authorization is created that must be completed before any other authorization types.

  • Creating a Security World with a quorum of 2/4 cards in the ACS on a pool with 2 HSMs results in 6 authorization requests. The first 4 will be to create the Administrator Card Set on one HSM, and the subsequent 2 will be to load the Security World onto the other HSM.

In local management of nShield Security World software the use of nShield Remote Administration smart cards is controlled by an Authorized Card List located at %NFAST_KMDATA%\config\cardlist. In this release of KeySafe 5, no restrictions are enforced on which smart cards may be presented to HSMs via KeySafe 5, regardless of the contents of any existing cardlist files.

Resource health measurements

Many of the resources in KeySafe 5 include health measurements.

Liveness checks

The central platform receives updates from KeySafe 5 agents on host machines and HSMs. These updates are used to determine how recently the central platform communicated with the resource.

A resource is considered to be "live" if it has been communicated with during a pre-configured liveness interval.

For example, if the central platform last communicated with an HSM at 12:00:00 and there is a configured liveness interval of 5 minutes:

  • API requests up to 12:05 will have a healthy liveness check

  • API requests after 12:05 will have a failing liveness check.

To configure the liveness interval, see the KeySafe 5 Installation Guide.

The liveness check behaves according to the following table:

Health Status Host Agent Connect Agent

Healthy

Live

Live

Not Live

Live

Warning

Live

Not Live

Failure

Not Live

Not Live

HSM Management Service

The following health measurements relate to HSM management.

Measurement Description

liveness

This check passes if the resource has been communicated with during the last health interval.

The time returned in the liveness check is the time at which the check was performed.

See Liveness checks.

hardwareStatus

This check passes if the hardware status of the HSM is "OK".

Check omitted if the HSM does not support reporting its hardware status.

remoteConnectionStatus

This check passes if the remote connection status of the HSM is "OK".

Check only valid for Host Health when a Hardserver is configured with a remote module.

hsmQuorum

This check is used for Pool health.

  • pass indicates all HSMs in the Pool are healthy.

  • warn indicates at least one HSM in the Pool is healthy, but not all HSMs in the Pool are healthy.

  • fail indicates all HSMs in the Pool are unhealthy, or there are no HSMs in the Pool.

clockSkew

This check is used for Host health.

It passes if the clock on this host is different by no more than the allowed clock skew from the clock on the machine running the HSM Management service.

It takes into consideration different time zones between the host machine and the central platform.

The allowed clock skew is configurable in the central platform, see the KeySafe 5 Installation Guide.

Security World Management Service

The following health measurements relate to Security World management.

Measurement Description

liveness

This check passes if the resource has been communicated with during the last health interval.

The time returned in the liveness check is the time at which the check was performed.

See Liveness checks.

poolHealthStatus

This check is used for Authorized Pool health and returns the overall health status of a HSM Pool. This is returned by the HSM Management service API endpoint.

hsmUsableQuorum

This check is used for Authorized Pool health:

  • pass indicates that all HSMs in the Authorized Pool are currently in a "Usable" module state by the Security World that the Pool is authorized to use.

  • warn indicates that at least one HSM in the Pool is not in "Usable" module state.

  • fail indicates that no HSMs in the Pool are in "Usable" module state.