# SoftHSM2 Test Environment Setup

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

## Install SoftHSM2

```bash
# Ubuntu/Debian
sudo apt-get install softhsm2 opensc

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

## Initialize Token

```bash
# 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

```bash
# 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

```bash
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

```bash
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.