SoftHSM2 Setup Guide for CBOM HSM Discovery Sensor
1. Purpose
This document describes the step-by-step procedure to install, configure, and integrate SoftHSM2 with the CBOM HSM Discovery Sensor so that the sensor can enumerate cryptographic objects stored in SoftHSM2 token slots.
The CBOM sensor connects via the PKCS#11 interface to:
List all initialized token slots
Enumerate key objects: private keys (
CKO_PRIVATE_KEY), public keys (CKO_PUBLIC_KEY), certificates (CKO_CERTIFICATE), and secret keys (CKO_SECRET_KEY)Read metadata: label, key type, key size, object ID, and token label
The sensor operates in read-only mode and never extracts private key material.
2. Prerequisites
Before starting, ensure:
You have root or sudo access on the host system (Linux or macOS)
SoftHSM2 is installed or you are authorized to install it
The CBOM Collector agent is already deployed on the target host
You know the SO-PIN and User PIN for each SoftHSM2 token you intend to scan
Supported platforms:
Linux (Debian/Ubuntu, RHEL/CentOS/Rocky, Fedora)
macOS (via Homebrew)
3. Install SoftHSM2
3.1 Install on Linux (Debian/Ubuntu)
sudo apt-get update
sudo apt-get install -y softhsm2 openscThe PKCS#11 library will be placed at:
/usr/lib/softhsm/libsofthsm2.so3.2 Install on Linux (RHEL/CentOS/Rocky/Fedora)
sudo dnf install -y softhsm openscThe PKCS#11 library will be placed at:
/usr/lib64/softhsm/libsofthsm2.so3.3 Install on macOS (Homebrew)
brew install softhsmThe PKCS#11 library will be placed at:
/usr/local/lib/softhsm/libsofthsm2.soOr on Apple Silicon:
/opt/homebrew/lib/softhsm/libsofthsm2.soConfirm the library path after installation:
find /usr -name "libsofthsm2.so" 2>/dev/null
find /opt/homebrew -name "libsofthsm2.so" 2>/dev/null4. Configure SoftHSM2
4.1 Locate the Configuration File
SoftHSM2 reads its configuration from one of the following paths (searched in order):
Path in the environment variable
SOFTHSM2_CONF~/.config/softhsm2/softhsm2.conf(per-user)/etc/softhsm/softhsm2.conf(system-wide)
4.2 Create or Verify the Configuration File
For a system-wide deployment, create or verify /etc/softhsm/softhsm2.conf:
sudo mkdir -p /etc/softhsm
sudo tee /etc/softhsm/softhsm2.conf > /dev/null <<EOF
# SoftHSM2 configuration file
directories.tokendir = /var/lib/softhsm/tokens/
objectstore.backend = file
log.level = ERROR
slots.removable = false
EOFCreate the token storage directory:
sudo mkdir -p /var/lib/softhsm/tokens
sudo chmod 750 /var/lib/softhsm/tokensFor a per-user setup (no sudo required):
mkdir -p ~/.config/softhsm2
mkdir -p ~/.local/share/softhsm/tokens
cat > ~/.config/softhsm2/softhsm2.conf <<EOF
directories.tokendir = $HOME/.local/share/softhsm/tokens/
objectstore.backend = file
log.level = ERROR
slots.removable = false
EOF4.3 Verify the Configuration
softhsm2-util --show-slotsExpected output when no tokens are initialized yet:
Available slots:
Slot 0
Slot info:
Description: SoftHSM slot ID 0x0
Manufacturer ID: SoftHSM project
Hardware version: 2.6
Firmware version: 2.6
Token present: yes
Token info:
Manufacturer ID: SoftHSM project
Model: SoftHSM v2
Hardware version: 2.6
Firmware version: 2.6
Serial number:
Initialized: no
User PIN init.: no
Label:5. Initialize a Token
5.1 Initialize the First Token
softhsm2-util --init-token --slot 0 --label "CBOM-Test-Token" \
--so-pin <SO-PIN> --pin <USER-PIN>Replace <SO-PIN> and <USER-PIN> with strong values (minimum 6 characters).
After initialization, SoftHSM2 reassigns the slot to a new slot ID. Confirm with:
softhsm2-util --show-slotsNote the new Slot ID shown for the initialized token.
5.2 Initialize Additional Tokens (Optional)
Each additional token occupies its own slot. Use --free to pick the next available uninitialized slot:
softhsm2-util --init-token --free --label "CBOM-Prod-Token" \
--so-pin <SO-PIN> --pin <USER-PIN>6. Create Test Key Objects (Optional)
This section creates sample objects to validate that the CBOM sensor discovers them correctly. Skip if real keys already exist in the token.
6.1 Generate an RSA Key Pair
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--slot-index 0 \
--login --pin <USER-PIN> \
--keypairgen --key-type rsa:2048 \
--label "cbom-rsa-key" \
--id 016.2 Generate an EC Key Pair
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--slot-index 0 \
--login --pin <USER-PIN> \
--keypairgen --key-type EC:prime256v1 \
--label "cbom-ec-key" \
--id 026.3 List Objects in the Token
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
--slot-index 0 \
--login --pin <USER-PIN> \
--list-objectsConfirm that public and private key objects appear with the expected labels and IDs.
7. Collect Credentials for the CBOM Sensor
The CBOM sensor requires the following information for each SoftHSM2 token to scan:
| Parameter | Description |
|---|---|
lib_path | Absolute path to libsofthsm2.so |
slot_id | Integer slot ID returned by softhsm2-util --show-slots |
user_pin | User PIN for the token |
token_label | Label assigned at --init-token time |
Retrieve the slot ID:
softhsm2-util --show-slots | grep -E "Slot [0-9]|Label"8. Configure the CBOM Sensor
8.1 CBOM YAML Configuration
Add the following block to the CBOM sensor configuration file for each token to scan:
sensor:
name: Discover_HSM
type: softhsm2
lib_path: /usr/lib/softhsm/libsofthsm2.so
tokens:
- slot_id: 1
token_label: "CBOM-Test-Token"
user_pin: "<USER-PIN>"
- slot_id: 2
token_label: "CBOM-Prod-Token"
user_pin: "<USER-PIN>"
discovery:
object_types:
- CKO_PRIVATE_KEY
- CKO_PUBLIC_KEY
- CKO_CERTIFICATE
- CKO_SECRET_KEY
read_metadata_only: true
scan_name: SoftHSM2DiscoveryFor macOS, update lib_path to match the Homebrew installation path:
lib_path: /usr/local/lib/softhsm/libsofthsm2.so8.2 Adjust Library Path Per Platform
| Platform | Default lib_path |
|---|---|
| Debian/Ubuntu | /usr/lib/softhsm/libsofthsm2.so |
| RHEL/CentOS/Rocky | /usr/lib64/softhsm/libsofthsm2.so |
| macOS (Intel) | /usr/local/lib/softhsm/libsofthsm2.so |
| macOS (Apple Silicon) | /opt/homebrew/lib/softhsm/libsofthsm2.so |
9. Validation
9.1 Verify the PKCS#11 Library Loads
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so --show-infoExpected output includes:
Cryptoki version 2.40
Manufacturer SoftHSM9.2 Verify Slot and Token Visibility
softhsm2-util --show-slotsConfirm:
All expected tokens appear as Initialized: yes
Each token has the correct Label
Each token has a valid Slot ID
9.3 Run the CBOM Discovery Task
Open the CBOM web interface
Navigate to Discovery Tasks
Select the SoftHSM2 sensor configuration
Click Run Now
Confirm: Task completes with status Success Discovered objects appear under Crypto Assets Object metadata (label, key type, key size) is populated correctly No
CKR_PIN_INCORRECTorCKR_TOKEN_NOT_PRESENTerrors appear in the task log
10. Common Errors and Resolution
Error: CKR_PIN_INCORRECT
Cause: The User PIN in the CBOM YAML does not match the PIN set during --init-token.
Resolution:
-
Verify the PIN by logging in manually:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \ --slot-index 0 --login --pin <USER-PIN> --list-objects -
If the PIN is unknown, reset the token using the SO-PIN:
softhsm2-util --init-token --slot <SLOT_ID> \ --so-pin <SO-PIN> --pin <NEW-USER-PIN> --label <LABEL>
Error: CKR_TOKEN_NOT_PRESENT
Cause: The slot ID in the CBOM config does not correspond to an initialized token.
Resolution:
Run
softhsm2-util --show-slotsand update theslot_idin the YAMLConfirm the SoftHSM2 config file path is set correctly (check
SOFTHSM2_CONFenvironment variable)
Error: Cannot load PKCS#11 library
Cause: The lib_path in the YAML points to a non-existent or incorrect file.
Resolution:
find /usr /opt/homebrew -name "libsofthsm2.so" 2>/dev/nullUpdate lib_path to the path returned.
Error: CKR_FUNCTION_NOT_SUPPORTED
Cause: Attempting to export private key material (not supported and not attempted by CBOM).
Resolution: This error should not appear during normal CBOM discovery. If it does, check the sensor version and confirm read_metadata_only: true is set.
11. Security Recommendations
For development and test environments, SoftHSM2 is appropriate. For production use, consider the following:
Use hardware HSMs for production workloads where key material security is required. SoftHSM2 does not protect key material in hardware.
-
Restrict token directory permissions so that only the CBOM collector service account and authorized administrators can read token files:
sudo chmod 750 /var/lib/softhsm/tokens sudo chown root:cbom-collector /var/lib/softhsm/tokens Use strong PINs — minimum 12 characters, alphanumeric with symbols. Avoid dictionary words.
Store PINs in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) rather than in plaintext YAML files. Reference the secret at runtime via CBOM credential injection.
-
Rotate User PINs periodically. Use the SO-PIN to reset the User PIN without re-initializing the token:
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \ --slot-index 0 --login --login-type so --so-pin <SO-PIN> \ --init-pin --new-pin <NEW-USER-PIN> Audit token access by enabling SoftHSM2 logging (
log.level = INFO) and forwarding logs to a SIEM.Keep SO-PIN offline — the Security Officer PIN should be stored separately from operational credentials and used only for token administration.
12. Conclusion
Following this guide ensures that the CBOM HSM Discovery Sensor operates against SoftHSM2 with:
Least-privilege, read-only PKCS#11 access
Correct token slot mapping and PIN configuration
Full enumeration of public keys, private key metadata, certificates, and secret key metadata — without ever extracting private key material
SoftHSM2 is well-suited for development, CI/CD pipelines, and lab environments where a hardware HSM is not available. When migrating to production, the same CBOM sensor configuration structure applies to hardware PKCS#11 HSMs (Thales Luna, Entrust nShield, etc.) with only the lib_path and credential fields updated.