git.stella-ops.org/docs/operations/softhsm2-test-environment.md

SoftHSM2 Test Environment Setup

This guide describes how to configure SoftHSM2 for PKCS#11 integration tests and local validation.

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_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

• The integration tests skip automatically if SoftHSM2 variables are not configured.
• Use a dedicated test token; never reuse production tokens.