git.stella-ops.org/docs/security/sm-hardware-simulation.md

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)

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):

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:

   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.