Documentation

1. Purpose

This guide describes how to configure the CBOM HSM sensor to connect to an Entrust nShield Hardware Security Module (HSM) using the PKCS#11 interface. The sensor enumerates cryptographic objects stored within the nShield Security World and collects metadata for inclusion in a Cryptographic Bill of Materials (CBOM).

The following cryptographic asset types are discovered:

CKO_PRIVATE_KEY — Private keys protected by the nShield Security World
CKO_PUBLIC_KEY — Public keys associated with key pairs
CKO_CERTIFICATE — X.509 certificates stored in the HSM token
CKO_SECRET_KEY — Symmetric keys (AES, DES, etc.)

For each object, the sensor reads metadata including label, key type, key size, and object ID. The sensor operates in read-only mode and never extracts private key material or secret key values.

2. Prerequisites

Before beginning this setup, ensure the following are in place:

An Entrust nShield HSM (Connect XC, Solo XC, or equivalent) is installed, initialized, and joined to a Security World.
The nShield client software is installed on the host machine running the CBOM sensor. The default installation path is /opt/nfast/.
The PKCS#11 toolkit library is present at /opt/nfast/toolkits/pkcs11/libcknfast.so.
The nShield Management Console (MC) is accessible and the Security World has been created and distributed to the HSM.
CipherTools Manager (ciphertools) is available on the host for creating operator credentials.
You have Administrator-level access to the nShield Management Console to create and authorize the Operator Card Set (OCS).
The CBOM sensor package is installed on the host and the Discover_HSM sensor binary is available.
Network connectivity between the sensor host and the nShield Connect HSM (if using a network-attached HSM) on port 9004.

3. Create an Operator Card Set (OCS)

The CBOM sensor authenticates to the nShield Security World using an Operator Card Set. This section covers creating a new OCS dedicated to read-only CBOM discovery.

3.1 Create the OCS via nShield Management Console

Open the nShield Management Console in a web browser and log in with Administrator credentials.
Navigate to Security World mgmt > Operator Card Sets.
Click Create new OCS.
Enter the following values: - OCS Name: CBOM-Sensor-OCS - K of N: 1 of 1 (single card, single operator — adjust to your policy) - Persistent: Yes (allows the card to remain loaded between sessions) - Timeout: 0 (no timeout, or set per your security policy)
Click Create and follow the on-screen prompts to write the card using the nShield card reader attached to the Administrator workstation.
Set and confirm a passphrase for the OCS when prompted. Record this passphrase securely in your organization's secrets manager.
Click Finish. The OCS is now registered with the Security World.

3.2 Enroll the OCS with the HSM

On the HSM host, verify the Security World is loaded:
```
/opt/nfast/bin/enquiry
```
Confirm the output shows Module #1 with state operational and the Security World hash matches your expected value.
Load the OCS using cardpp to confirm the card is readable:
```
/opt/nfast/bin/cardpp --check --cardset CBOM-Sensor-OCS
```
If the OCS requires a passphrase, verify authentication succeeds:
```
/opt/nfast/bin/cardpp --auth --cardset CBOM-Sensor-OCS
```
Enter the OCS passphrase when prompted. A successful response confirms the card is enrolled and accessible.

4. Create a Softcard-Protected Security World Slot

For environments where physical card insertion is not practical (e.g., automated sensor deployments), a softcard provides a software-based alternative to the OCS.

4.1 Create the Softcard

On the sensor host, use the ppmk utility to create a new softcard:
```
/opt/nfast/bin/ppmk --new CBOM-Sensor-Softcard
```
Enter and confirm a passphrase for the softcard when prompted.
Verify the softcard was created in the Security World:
```
/opt/nfast/bin/nfkminfo --softcards
```
Confirm CBOM-Sensor-Softcard appears in the output with a valid hash.

4.2 Pre-load the Softcard for PKCS#11 Access

Use preload to load the softcard into the nShield key management facility (KMF) before starting the CBOM sensor:
```
/opt/nfast/bin/preload --soft CBOM-Sensor-Softcard /opt/nfast/bin/enquiry
```
For persistent pre-loading in automated environments, create a systemd service or use the nShield preload daemon. Refer to the Entrust nShield Integration Guide for daemon configuration.

5. Create an nShield Operator Credential with CipherTools Manager

The CBOM sensor requires an operator credential that CipherTools Manager issues. This credential authorizes the PKCS#11 session to enumerate objects without key extraction permissions.

Launch CipherTools Manager on the sensor host:
```
/opt/nfast/bin/ciphertools
```
Select Manage Credentials > New Credential.
Configure the credential with the following settings: - Credential Name: cbom-sensor-operator - Protection: Softcard — select CBOM-Sensor-Softcard - Permissions: Enumerate, GetAttributeValue — do not grant Decrypt, Sign, Unwrap, or Derive - ACL (Access Control List): Read-only enumeration only
Save the credential and note the credential token hash displayed in the output.

Export the credential token to the CBOM sensor configuration directory:

cp /opt/nfast/kmdata/local/key_pkcs11_cbom-sensor-operator \
   /etc/cbom/sensors/hsm/nshield/

Restrict file permissions:

chown cbom-service:cbom-service \
   /etc/cbom/sensors/hsm/nshield/key_pkcs11_cbom-sensor-operator
chmod 600 /etc/cbom/sensors/hsm/nshield/key_pkcs11_cbom-sensor-operator

6. Configure PKCS#11 Environment

Before configuring the CBOM sensor, verify the PKCS#11 library is accessible and functional.

Set the PKCS#11 library environment variable for testing:

export NFAST_PKCS11_LIB=/opt/nfast/toolkits/pkcs11/libcknfast.so

List available PKCS#11 slots to confirm the Security World is visible:
```
/opt/nfast/bin/cklist -L
```
Expected output lists one or more slots with the Security World label.
List objects in a specific slot (slot 0 by default) to confirm enumeration works:
```
/opt/nfast/bin/cklist -s 0
```
The output should list cryptographic objects with their labels and types. If the OCS or softcard is required, load it first using preload as described in Section 4.2.

Confirm the library path resolves correctly:

ls -lh /opt/nfast/toolkits/pkcs11/libcknfast.so

7. Configure CBOM Sensor

Create or update the CBOM sensor configuration file for the Discover_HSM sensor. The default configuration path is /etc/cbom/sensors/hsm/nshield-sensor.yaml.

sensor:
  name: Discover_HSM
  type: hsm
  vendor: entrust_nshield
  enabled: true

connection:
  pkcs11_library: /opt/nfast/toolkits/pkcs11/libcknfast.so
  slot_id: 0
  # Set slot_id to -1 to enumerate all available slots automatically
  token_label: "CipherTools Security World"
  # token_label must match the label shown by: /opt/nfast/bin/cklist -L

authentication:
  method: softcard
  softcard_name: CBOM-Sensor-Softcard
  # Passphrase can be supplied via environment variable or secrets manager
  passphrase_env: CBOM_NSHIELD_SOFTCARD_PASSPHRASE
  # Alternative: path to a file containing the passphrase (chmod 600)
  # passphrase_file: /etc/cbom/sensors/hsm/nshield/.softcard_pass

discovery:
  enumerate_object_classes:
    - CKO_PRIVATE_KEY
    - CKO_PUBLIC_KEY
    - CKO_CERTIFICATE
    - CKO_SECRET_KEY
  collect_attributes:
    - CKA_LABEL
    - CKA_KEY_TYPE
    - CKA_VALUE_LEN
    - CKA_ID
    - CKA_CLASS
    - CKA_TOKEN
    - CKA_SENSITIVE
    - CKA_EXTRACTABLE
  # The sensor will never set CKA_EXTRACTABLE to true or attempt CKM operations
  read_only: true
  include_sensitive_flags: true
  # include_sensitive_flags captures whether keys are marked sensitive/non-extractable
  # but does not retrieve key values

scheduling:
  interval_minutes: 60
  retry_on_failure: true
  max_retries: 3
  retry_delay_seconds: 30

output:
  format: cbom_json
  destination: /var/cbom/output/nshield/
  filename_prefix: nshield_hsm_cbom
  include_timestamp: true

logging:
  level: INFO
  log_file: /var/log/cbom/nshield-sensor.log
  max_size_mb: 50
  retain_days: 30

Set the softcard passphrase as an environment variable for the sensor process:

export CBOM_NSHIELD_SOFTCARD_PASSPHRASE="your-softcard-passphrase-here"

Or store it using your organization's secrets manager and inject it at runtime via a systemd EnvironmentFile or Vault agent.

8. Validation

After completing the configuration, validate the sensor operates correctly.

Run the CBOM sensor in dry-run mode to confirm connectivity and enumeration without writing output:
```
cbom-sensor run --config /etc/cbom/sensors/hsm/nshield-sensor.yaml --dry-run
```

Verify the output includes discovered objects. Example expected output:

[INFO] Discover_HSM: Loaded PKCS#11 library: /opt/nfast/toolkits/pkcs11/libcknfast.so
[INFO] Discover_HSM: Connected to slot 0 — Token: CipherTools Security World
[INFO] Discover_HSM: Authenticated via softcard CBOM-Sensor-Softcard
[INFO] Discover_HSM: Discovered 14 cryptographic object(s)
[INFO] Discover_HSM: CKO_PRIVATE_KEY: 4 object(s)
[INFO] Discover_HSM: CKO_PUBLIC_KEY: 4 object(s)
[INFO] Discover_HSM: CKO_CERTIFICATE: 3 object(s)
[INFO] Discover_HSM: CKO_SECRET_KEY: 3 object(s)
[INFO] Discover_HSM: Dry-run complete. No output written.

Run the sensor in live mode and confirm the output file is created:

cbom-sensor run --config /etc/cbom/sensors/hsm/nshield-sensor.yaml
ls -lh /var/cbom/output/nshield/

Inspect the CBOM output file to verify key metadata is present and no key values appear:

cat /var/cbom/output/nshield/nshield_hsm_cbom_<timestamp>.json | \
  python3 -m json.tool | grep -i "key_type\|label\|key_size"

Confirm the sensor log shows no errors:

tail -50 /var/log/cbom/nshield-sensor.log

9. Common Errors and Resolution

Error 1: CKR_TOKEN_NOT_PRESENT when connecting to slot

[ERROR] Discover_HSM: PKCS#11 C_OpenSession failed — CKR_TOKEN_NOT_PRESENT (0x000000E0)

Cause: The nShield Security World is not loaded on the host, or the slot ID in the configuration does not correspond to an active token. This can also occur if the HSM module is in a pre-operational state.
Fix: Run /opt/nfast/bin/enquiry to check module state. Ensure the Security World is loaded (/opt/nfast/bin/nfkminfo). If using a network HSM, verify connectivity on port 9004. Update slot_id in the sensor YAML to match the correct slot from /opt/nfast/bin/cklist -L.

Error 2: CKR_USER_NOT_LOGGED_IN during object enumeration

[ERROR] Discover_HSM: C_FindObjects failed — CKR_USER_NOT_LOGGED_IN (0x00000101)

Cause: The softcard or OCS was not loaded before the PKCS#11 session was opened, or the passphrase environment variable CBOM_NSHIELD_SOFTCARD_PASSPHRASE is not set or is incorrect.
Fix: Verify the environment variable is exported in the shell or systemd unit running the sensor. Test softcard authentication manually: /opt/nfast/bin/ppmk --check CBOM-Sensor-Softcard. If using OCS, ensure the card is inserted and loaded with /opt/nfast/bin/preload.

Error 3: libcknfast.so: cannot open shared object file

[ERROR] Discover_HSM: Failed to load PKCS#11 library — libcknfast.so: cannot open shared object file: No such file or directory

Cause: The nShield client software is not installed on the sensor host, or it was installed to a non-default path. The path /opt/nfast/toolkits/pkcs11/libcknfast.so does not exist.
Fix: Verify the nShield client installation: ls /opt/nfast/toolkits/pkcs11/. If the file is missing, reinstall the nShield client software matching the HSM firmware version. If installed to a custom path, update pkcs11_library in the sensor YAML to the correct absolute path. Also ensure the cbom-service user has read and execute permissions on the library.

10. Security Recommendations

Dedicate a minimal-privilege credential: The CipherTools credential cbom-sensor-operator should be granted only Enumerate and GetAttributeValue permissions. Never grant Decrypt, Sign, Unwrap, or Derive to the sensor credential.
Protect the softcard passphrase: Store the softcard passphrase in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) and inject it at runtime. Avoid hardcoding it in configuration files or shell scripts.
Restrict file permissions: The sensor configuration file, softcard passphrase file, and credential token file should all be owned by the cbom-service system account with permissions 600. No other users should have read access.
Audit PKCS#11 access: Enable nShield audit logging via the Management Console to record all PKCS#11 session openings and object enumeration calls. Review these logs periodically and alert on unexpected access patterns.
Isolate the sensor host: Run the CBOM sensor on a dedicated host or container with network access restricted to the nShield HSM port (9004) and the CBOM backend. Avoid running other workloads on the same host that could access the loaded softcard or OCS.

11. Conclusion

This guide has walked through the full configuration of the CBOM Discover_HSM sensor for an Entrust nShield HSM, including creating an Operator Card Set, enrolling it with the Security World, issuing a minimal-privilege operator credential via CipherTools Manager, and configuring the sensor to enumerate cryptographic objects over PKCS#11. The sensor provides full visibility into keys, certificates, and tokens stored in the nShield Security World while operating in a strictly read-only mode that never accesses private key material. Once deployed, the sensor feeds nShield cryptographic asset metadata into the CBOM platform for inventory, compliance reporting, and cryptographic risk analysis.

CBOM Secure

Entrust nShield Setup Guide for CBOM HSM Sensor