Documentation

1. Purpose

This guide explains how to configure a Thales Luna Network HSM as a cryptographic asset source for the CBOM HSM Sensor. The sensor connects to the Luna HSM using the PKCS#11 interface and discovers the following cryptographic material:

Symmetric keys (AES, DES, 3DES) stored within Luna partitions
Asymmetric key pairs (RSA, ECC, DSA) and their associated metadata
X.509 certificates stored as PKCS#11 certificate objects
Secret key objects and data objects within accessible partitions
Key attributes: label, key type, key size, usage flags, extractability, and validity dates

This guide covers registering a client workstation with the Luna Network HSM, creating a dedicated partition, provisioning a read-only Crypto User credential for the CBOM sensor, and configuring the sensor YAML.

2. Prerequisites

Before starting, ensure the following are in place:

Administrative access to the Thales Luna Network HSM appliance (HSM SO / Appliance Admin credentials).
The Luna Network HSM is reachable over the network from the CBOM sensor host (default port: 1792/TCP).
The Luna HSM Client software is installed on the CBOM sensor host. Verify installation:
```
ls /usr/lib/libCryptoki2_64.so
```
The lunacm and vtl command-line utilities are available in your PATH:
```
which lunacm
which vtl
```
The HSM appliance firmware version is 7.x or later.
You have the HSM SO (Security Officer) PIN and the Partition SO PIN available.
An NTP-synchronized clock on the CBOM sensor host (required for certificate validation during NTLS handshake).

3. Register the CBOM Sensor Host as a Luna Client

The Luna Network HSM uses NTLS (Network Trust Link Service) for mutual TLS authentication. The CBOM sensor host must be registered as a trusted client on the HSM appliance before it can access any partition.

3.1 Generate a Client Certificate on the Sensor Host

On the CBOM sensor host, generate a client certificate using the Luna client utility:
```
vtl createCert -n cbom-sensor-client
```
This creates the certificate and private key in /usr/safenet/lunaclient/cert/client/.

Verify the certificate was created:

ls /usr/safenet/lunaclient/cert/client/
# Expected output:
# cbom-sensor-client.pem
# cbom-sensor-clientKey.pem

3.2 Copy the Client Certificate to the HSM Appliance

Transfer the client certificate to the Luna HSM appliance using scp:

scp /usr/safenet/lunaclient/cert/client/cbom-sensor-client.pem \
    admin@<HSM_APPLIANCE_IP>:/tmp/cbom-sensor-client.pem

SSH into the Luna HSM appliance as the appliance admin:
```
ssh admin@<HSM_APPLIANCE_IP>
```

On the appliance, register the client certificate:

client register -client cbom-sensor -hostname <CBOM_SENSOR_HOSTNAME>
client certificate add -client cbom-sensor -file /tmp/cbom-sensor-client.pem

Confirm the client registration:
```
client list
```
The output should include cbom-sensor in the list of registered clients.

3.3 Retrieve and Register the HSM Server Certificate on the Sensor Host

While still on the HSM appliance, display the server certificate:
```
sysconf tls show
```

Copy the HSM server certificate to the CBOM sensor host:

scp admin@<HSM_APPLIANCE_IP>:server.pem \
    /usr/safenet/lunaclient/cert/server/<HSM_APPLIANCE_HOSTNAME>.pem

On the sensor host, register the HSM server:

vtl addServer -n <HSM_APPLIANCE_HOSTNAME> -c \
    /usr/safenet/lunaclient/cert/server/<HSM_APPLIANCE_HOSTNAME>.pem

Verify the server is registered:
```
vtl listServers
```

4. Create a Dedicated Luna Partition for CBOM

A partition is an isolated cryptographic space within the Luna HSM. Create a dedicated partition that the CBOM sensor will access.

4.1 Create the Partition on the HSM Appliance

SSH into the HSM appliance as the admin user:
```
ssh admin@<HSM_APPLIANCE_IP>
```
Create a new partition (requires HSM SO credentials). Enter the HSM SO PIN when prompted:
```
partition create -partition cbom-discovery -label "CBOM Discovery Partition"
```
Confirm the partition was created:
```
partition list
```

4.2 Assign the Client to the Partition

On the HSM appliance, assign the registered CBOM sensor client to the new partition:
```
client assignPartition -client cbom-sensor -partition cbom-discovery
```
Verify the assignment:
```
client show -client cbom-sensor
```
Confirm that cbom-discovery appears under the assigned partitions for cbom-sensor.

5. Create a Read-Only Crypto User Credential

The CBOM sensor must authenticate to the Luna partition using a Crypto User (CU) role. The Crypto User role has read access to cryptographic objects but cannot create, delete, or modify keys — making it appropriate for the CBOM sensor's read-only discovery purpose.

5.1 Initialize the Partition and Set the Partition SO PIN

On the CBOM sensor host, launch lunacm:
```
lunacm
```
List available slots to identify the partition slot number:
```
lunacm:> slot list
```
Note the slot number corresponding to cbom-discovery.
Set the active slot:
```
lunacm:> slot set -slot <SLOT_NUMBER>
```
Initialize the partition (sets the Partition SO PIN). You will be prompted for the HSM SO PIN and to set a new Partition SO PIN:
```
lunacm:> partition init -label "CBOM Discovery Partition"
```

5.2 Initialize the Crypto Officer PIN

Log in to the partition as the Partition SO:
```
lunacm:> role login -name Partition SO
```
Initialize the Crypto Officer role and set its PIN:
```
lunacm:> role init -name Crypto Officer
```
Enter and confirm a strong PIN when prompted.

5.3 Initialize the Crypto User PIN

The Crypto User (CU) is the least-privileged role and is appropriate for the CBOM sensor.

Log out of the Partition SO session and log in as Crypto Officer:
```
lunacm:> role logout
lunacm:> role login -name Crypto Officer
```
Initialize the Crypto User role and set its PIN:
```
lunacm:> role init -name Crypto User
```
Enter and confirm a PIN for the Crypto User. Record this PIN securely — it will be required for the CBOM sensor configuration.
Log out:
```
lunacm:> role logout
```
Exit lunacm:
```
lunacm:> exit
```

5.4 Verify the Crypto User Credential

Test a login as the Crypto User to confirm the credentials work:
```
lunacm
```
```
lunacm:> slot set -slot <SLOT_NUMBER>
lunacm:> role login -name Crypto User
```
Enter the Crypto User PIN. A successful login confirms the credential is valid.
Optionally, list objects visible to the Crypto User:
```
lunacm:> object list
```
Log out and exit:
```
lunacm:> role logout
lunacm:> exit
```

5.5 Confirm the PKCS#11 Library Path

Verify the PKCS#11 library is present at the expected path:

ls -lh /usr/lib/libCryptoki2_64.so

If the file is missing, locate it:

find /usr/safenet -name "libCryptoki2_64.so" 2>/dev/null

Update your system library path if needed:

export CRYPTOKI_LIB=/usr/lib/libCryptoki2_64.so

6. CBOM Sensor YAML Configuration

Use the following YAML block to configure the CBOM HSM Sensor for the Thales Luna Network HSM. Replace all placeholder values with your environment-specific settings.

sensors:
  - name: Discover_HSM
    type: hsm
    enabled: true
    vendor: thales-luna
    description: "Discovers cryptographic keys and certificates from Thales Luna Network HSM partition cbom-discovery"

    connection:
      pkcs11_library: /usr/lib/libCryptoki2_64.so
      hsm_host: 192.168.10.50
      hsm_port: 1792
      slot_number: 0                        # Slot index for cbom-discovery partition
      partition_label: cbom-discovery

    credentials:
      role: CryptoUser
      pin: "${LUNA_CRYPTO_USER_PIN}"        # Injected from environment or secrets manager

    discovery:
      object_types:
        - keys
        - certificates
        - data_objects
      include_attributes:
        - label
        - key_type
        - key_size
        - id
        - extractable
        - sensitive
        - local
        - start_date
        - end_date
        - usage_flags
      scan_interval_minutes: 60

    tls:
      client_cert: /usr/safenet/lunaclient/cert/client/cbom-sensor-client.pem
      client_key: /usr/safenet/lunaclient/cert/client/cbom-sensor-clientKey.pem
      server_cert: /usr/safenet/lunaclient/cert/server/luna-hsm-appliance.pem

    output:
      tags:
        environment: production
        hsm_vendor: thales
        hsm_model: luna-network-hsm-7
        partition: cbom-discovery

Store the Crypto User PIN as an environment variable or in a secrets manager. Do not hardcode it in the YAML file. Reference it using the ${} syntax shown above.

7. Validation

After saving the sensor configuration, perform the following checks to confirm the sensor is operating correctly.

Run the CBOM sensor in dry-run mode to validate connectivity and credentials without writing results:
```
cbom-sensor run --config /etc/cbom/sensors/thales-luna.yaml --dry-run
```

Confirm the sensor discovers objects from the partition. Expected output includes:

[INFO] Connected to Luna HSM at 192.168.10.50:1792
[INFO] Authenticated to partition 'cbom-discovery' as Crypto User
[INFO] Discovered 42 cryptographic objects (38 keys, 4 certificates)
[INFO] Dry-run complete. No data written.

Run the sensor normally and verify results appear in the CBOM dashboard:
```
cbom-sensor run --config /etc/cbom/sensors/thales-luna.yaml
```
In the CBOM UI, navigate to Assets > HSM and confirm that objects from the cbom-discovery partition are listed with correct metadata (key type, size, label).
Verify no write operations were performed on the HSM by reviewing the Luna audit log on the appliance:
```
ssh admin@<HSM_APPLIANCE_IP>
audit log list
```
Confirm only C_Login, C_FindObjects, C_GetAttributeValue, and C_Logout operations appear for the CBOM sensor session.

8. Common Errors

Error: CKR_PIN_INCORRECT during authentication

[ERROR] PKCS#11 error: CKR_PIN_INCORRECT (0x000000A0) on slot 0

Cause: The Crypto User PIN provided in the sensor configuration does not match the PIN set on the partition, or the wrong role PIN is being used.

Resolution: Re-verify the Crypto User PIN by logging in manually with lunacm. If the PIN has been locked due to failed attempts, the Partition SO or Crypto Officer must reset it using role changepw in lunacm.

Error: CKR_SLOT_ID_INVALID or slot not found

[ERROR] PKCS#11 error: CKR_SLOT_ID_INVALID (0x00000003) — slot 0 not present

Cause: The slot number in the YAML does not match the actual slot index assigned to the cbom-discovery partition. Slot indices can change after an HSM restart or after partition additions/removals.

Resolution: Run vtl verify or open lunacm and execute slot list to obtain the current slot index. Update the slot_number field in the YAML accordingly.

Error: NTLS connection refused or TLS handshake failure

[ERROR] Failed to connect to HSM at 192.168.10.50:1792 — TLS handshake failed: certificate verify failed

Cause: The CBOM sensor host is not registered as a trusted client on the HSM appliance, the client certificate has expired, or the HSM server certificate on the sensor host does not match the appliance's current certificate (e.g., after an HSM firmware update or certificate rotation).

Resolution: Re-run vtl verify on the sensor host. If the server certificate has changed, remove the old server entry and re-register:

vtl deleteServer -n <HSM_APPLIANCE_HOSTNAME>
vtl addServer -n <HSM_APPLIANCE_HOSTNAME> -c /path/to/new-server.pem

If the client is not registered, repeat steps 3.2 and 3.3.

9. Security Recommendations

Use the Crypto User role exclusively. Never configure the CBOM sensor with Crypto Officer or Partition SO credentials. The Crypto User role cannot create, delete, wrap, or unwrap keys, limiting the sensor's blast radius in the event of credential compromise.
Inject the PIN via a secrets manager. Store the Crypto User PIN in a vault solution (e.g., HashiCorp Vault, AWS Secrets Manager, CyberArk) and reference it at runtime using the ${} environment variable syntax. Do not hardcode PINs in configuration files or commit them to source control.
Enable HSM audit logging. Ensure the Luna audit log is active and monitored. Any unexpected operations (key creation, deletion, export) originating from the CBOM sensor's client identity should trigger an alert.
Restrict network access. Firewall the Luna HSM appliance to allow port 1792/TCP only from the CBOM sensor host IP. Use Luna's IP-based client restrictions in conjunction with certificate-based NTLS authentication.
Rotate the Crypto User PIN regularly. Establish a PIN rotation schedule (e.g., every 90 days) and update the corresponding secret in your secrets manager. Coordinate rotation with CBOM sensor maintenance windows to avoid scan failures.
Protect client key material. The CBOM sensor's NTLS private key (cbom-sensor-clientKey.pem) must be stored with permissions 600 and owned by the CBOM service account. A compromised client key allows impersonation of the sensor on the HSM.
```
chmod 600 /usr/safenet/lunaclient/cert/client/cbom-sensor-clientKey.pem
chown cbom-service:cbom-service /usr/safenet/lunaclient/cert/client/cbom-sensor-clientKey.pem
```

10. Conclusion

This guide walked through registering a CBOM sensor host with a Thales Luna Network HSM, creating a dedicated cbom-discovery partition, provisioning a least-privileged Crypto User credential, and configuring the CBOM HSM Sensor YAML. The sensor connects over NTLS using mutual TLS and authenticates to the partition using the PKCS#11 interface via /usr/lib/libCryptoki2_64.so. With this configuration, CBOM can continuously inventory cryptographic keys, certificates, and data objects stored on the Luna HSM, giving your security team full visibility into HSM-resident cryptographic assets without granting any write or management access to the HSM partition.

CBOM Secure

Thales Luna Network HSM Setup Guide for CBOM HSM Sensor