# SM Hardware Simulation & Bring-Up · 2025-12-11

Use this runbook to simulate or attach SM2/SM3 hardware (PKCS#11) for the CN profile. When hardware is unavailable, use the unified simulator (`ops/crypto/sim-crypto-service`) to keep CI green.

## Goals
- Provide a repeatable PKCS#11 path (SoftHSM2 or vendor token).
- Document slots/PIN wiring for StellaOps hosts.
- Capture validation evidence (sign/verify/hash) to retire the “software-only” caveat once certified hardware is ready.

## Simulation path (SoftHSM2)
```bash
sudo apt-get install softhsm2
softhsm2-util --init-token --slot 0 --label "SM2SIM" --so-pin 1234 --pin 1234
softhsm2-util --import sm2-private-key.pem --token "SM2SIM" --label "sm2key" --id 1 --pin 1234
```

Configure StellaOps hosts (example):
```yaml
StellaOps:
  Crypto:
    Registry:
      ActiveProfile: sm
    Pkcs11:
      LibraryPath: /usr/lib/softhsm/libsofthsm2.so
      Keys:
        - KeyId: sm2-hw
          SlotId: 0
          PinEnvVar: SM_PKCS11_PIN   # export SM_PKCS11_PIN=1234
          Algorithm: sm2
```

## Vendor hardware bring-up
1) Install vendor PKCS#11 library (e.g., Feitian/Jacarta SM modules).
2) Export `SM_PKCS11_LIBRARY` with the library path; set `SM_SOFT_ALLOWED=0` to force hardware.
3) Import the SM2 private key/cert per vendor tooling; record SlotId/TokenLabel.
4) Run the SM unit/integration suite with env:
   ```bash
   SM_SOFT_ALLOWED=0 \
   STELLAOPS_CRYPTO_ENABLE_SM_PKCS11=1 \
   SM_PKCS11_LIBRARY=/path/to/libpkcs11.so \
   SM_PKCS11_PIN=1234 \
   dotnet test src/__Libraries/StellaOps.Cryptography.Plugin.SmSoft.Tests
   ```

## Simulator fallback
- Unified simulator: `ops/crypto/sim-crypto-service` with provider `sim.crypto.remote`.
- Enable via `STELLAOPS_CRYPTO_ENABLE_SIM=1` and `STELLAOPS_CRYPTO_SIM_URL=http://localhost:8080`.
- Use when hardware or licenses are unavailable; keep the “non-certified” label in RootPack_CN.

## Validation evidence to capture
- `pkcs11-tool --module <lib> --list-slots` and `--list-objects`.
- Signing/verification logs for `stellaops-sm2-demo` with signature hash.
- JWKS export snapshot from Authority/Signer when the `sm` profile is active.

## Determinism
- Hashes are deterministic (SM3). Signatures are nonce-driven; record signature hash and public key.
- Keep test seeds fixed; prefer the existing SM2 unit tests with the env overrides above.

## Publishing
- Attach command outputs and configs to the sprint evidence bundle.
- Once a certified token passes this harness, flip `SM_SOFT_ALLOWED` default to `0` for production CN profile and update RootPack_CN notes.