SoftHSM2 Test Environment Setup

Audience: Developers and CI maintainers running Stella Ops PKCS#11 / HSM integration tests.

This guide describes how to configure SoftHSM2 — a software PKCS#11 token — so the Stella Ops cryptography integration tests have a working HSM to exercise locally and in CI.

Scope: SoftHSM2 is for testing only. It is not production-eligible: the Authority and Attestor production signing paths fail closed against software-only HSM providers. For the simulator-vs-hardware boundary and which surfaces require real hardware, see Simulator and hardware test separation. For production HSM provisioning, see the HSM setup runbook.

Install SoftHSM2

# Ubuntu/Debian
sudo apt-get install softhsm2 opensc

# Verify installation
softhsm2-util --version
pkcs11-tool --version

Initialize Token

# Create token directory
mkdir -p /var/lib/softhsm/tokens
chmod 700 /var/lib/softhsm/tokens

# Initialize token
softhsm2-util --init-token \
  --slot 0 \
  --label "StellaOps-Dev" \
  --so-pin 12345678 \
  --pin 87654321

# Verify token
softhsm2-util --show-slots

Create a Test Key

# Generate RSA keypair
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 87654321 \
  --keypairgen \
  --key-type rsa:2048 \
  --id 01 \
  --label "stellaops-hsm-test"

# List objects
pkcs11-tool --module /usr/lib/softhsm/libsofthsm2.so \
  --login --pin 87654321 \
  --list-objects

Environment Variables for Tests

export STELLAOPS_SOFTHSM_LIB="/usr/lib/softhsm/libsofthsm2.so"
export STELLAOPS_SOFTHSM_SLOT="0"
export STELLAOPS_SOFTHSM_TOKEN_LABEL="StellaOps-Dev"
export STELLAOPS_SOFTHSM_PIN="87654321"
export STELLAOPS_SOFTHSM_KEY_ID="stellaops-hsm-test"
export STELLAOPS_SOFTHSM_MECHANISM="RsaSha256"

Run Integration Tests

dotnet test src/Cryptography/__Tests/StellaOps.Cryptography.Tests/StellaOps.Cryptography.Tests.csproj \
  --filter FullyQualifiedName~Pkcs11HsmClientIntegrationTests

Notes