up the blokcing tasks

docs/security/sm-hardware-simulation.md

@@ -0,0 +1,61 @@
+# 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.