Using an Entrust nShield HSM with VSatellites¶

You can protect the VSatellite data encryption key (DEK) with an Entrust nShield hardware security module (HSM). The overall flow is the same as for Thales Luna: you install the HSM client on the VSatellite host, and then pass its location to vsatctl install. This topic covers what is different for nShield. For the general behavior of HSM-protected DEK, including which operations are supported, see Using HSM-protected DEK with VSatellites.

How VSatellite uses nShield¶

When you install the VSatellite, vsatctl mounts the nShield client directory (normally /opt/nfast) from the host into the VSatellite pod at the same path, with read and write access. The VSatellite loads the nShield PKCS #11 library from that directory and reaches the HSM through the hardserver running on the host. It generates one P-384 key pair per tenant in the HSM, labeled with the tenant ID.

Unlike Luna, nShield doesn't keep keys inside the HSM. It stores each key as a key blob, encrypted under the Security World, in /opt/nfast/kmdata/local on the host. That directory is what you back up, and every VSatellite host needs a copy of it. If the key blob is lost, the key it holds can't be recovered.

Before you begin¶

On every host that will run a VSatellite, make sure that:

• nShield Security World Software is installed (the default location is /opt/nfast) and the hardserver is running.
• The host is enrolled as a client of the HSM. Running /opt/nfast/bin/enquiry reports the module mode as operational, and running /opt/nfast/bin/nfkminfo reports the Security World as Initialised and Usable.
• The key protection you plan to use already exists in the Security World. For details, see Choose a protection mode.
• A cknfastrc file exists. vsatctl requires one, even if it's empty. To create an empty file, run sudo touch /opt/nfast/cknfastrc.

Choose a protection mode¶

nShield offers three ways to protect the key that the VSatellite uses. vsatctl asks you to choose one during installation, and then sets the nShield environment variables that the mode requires on the VSatellite pod.

• Module protection: The key requires no credential, so anyone who can use the HSM module can use the key. We recommend softcard or OCS protection for production. The choice depends on your security policies.
• Softcard: Create the softcard with ppmk --new <softcard-name> before you install the VSatellite.
• OCS: The card set must have a quorum of 1 (a 1/N card set), because the VSatellite logs in with a single passphrase. The card must stay in the HSM's card reader while the VSatellite runs. If you remove it, the VSatellite can't use the key until you insert it again.

The environment variables do the following:

• CKNFAST_OVERRIDE_SECURITY_ASSURANCES=explicitness allows the key operations that the VSatellite needs, which nShield's default security assurance checks would otherwise block. To decrypt data, the HSM derives a shared secret from the tenant's private key through elliptic-curve Diffie-Hellman (ECDH). It returns the secret to the VSatellite wrapped with a temporary key that the VSatellite generates for that operation, and the VSatellite completes the decryption. The private key never leaves the HSM. Entrust advises a review of your security policies when this override is set. For details, see explicitness in the nShield documentation.
• CKNFAST_LOADSHARING=1 is required for softcards, because the nShield library presents softcards as PKCS #11 tokens only when load sharing is on.

Install a VSatellite with nShield¶

Install the VSatellite interactively. vsatctl configures nShield from your answers to its HSM prompts, and non-interactive installation isn't recommended.

1. Find the token label. On the host, run cklist with the same load-sharing setting that the VSatellite will use:

   # Softcard
   CKNFAST_LOADSHARING=1 /opt/nfast/bin/cklist
   
   # OCS or module protection
   /opt/nfast/bin/cklist
   

   cklist prints the token label and serialNumber of each slot. Note the label exactly as cklist prints it. PKCS #11 limits token labels to 32 characters, so cklist truncates a longer softcard name.

2. Run vsatctl install with the nShield HSM options. For example, for a softcard named vsat_softcard:

   sudo ./vsatctl install \
     --pairing-code <pairing-code> \
     --hsm-client-path /opt/nfast \
     --hsm-lib-path /opt/nfast/toolkits/pkcs11/libcknfast.so \
     --hsm-config /opt/nfast/cknfastrc \
     --label vsat_softcard
   

   For module protection, set --label to the module slot label, for example --label accelerator.

3. Answer the HSM prompts:

   1. For the HSM, enter 2 (nShield).
   2. For the protection mode, enter 1 (module protection), 2 (softcard), or 3 (OCS).
   3. Review the environment variables that vsatctl sets on the VSatellite pod, and then enter y to continue. If you enter n, the installation stops.
   4. For a softcard or OCS, enter the passphrase. Module protection doesn't prompt for one.

4. Verify the installation:

   # Prints "Entrust nShield"
   sudo kubectl -n satellite get configmap hsm-client-files -o jsonpath='{.data.vendor}{"\n"}'
   
   # Shows the satellite pod as Running
   sudo kubectl -n satellite get pods
   

   If the hsm-client-files ConfigMap doesn't exist, the VSatellite was installed without HSM protection. Reinstall the VSatellite with the HSM options.

   After the VSatellite generates its key, a new key_pkcs11_* file appears in /opt/nfast/kmdata/local on the host.

nShield values for the HSM options¶

Running more than one VSatellite¶

All VSatellites in a tenant must use the same key. With nShield, this means:

• Every host is a client of the same Security World and uses the same protection mode and token label.
• Every host has the VSatellite key blob in /opt/nfast/kmdata/local. After the first VSatellite pairs and generates its key, copy that host's /opt/nfast/kmdata/local directory to each of the other hosts before you install a VSatellite on them. Alternatively, keep the hosts in sync with the nShield Remote File System (rfs-sync). Key blobs are encrypted under the Security World, so copying them is safe.

If a host is missing the key blob, the installation still completes, but the VSatellite enters an Unhealthy state because it can't find the tenant's key. To fix it, copy the key blob to the host, and then restart the VSatellite with vsatctl restart.

Uninstalling a VSatellite doesn't delete the key blob from /opt/nfast/kmdata/local, so reinstalling on the same host reuses the existing key. Include /opt/nfast/kmdata/local in your host backups.

Troubleshooting¶

To read the VSatellite log, run:

sudo kubectl -n satellite logs deployment/satellite