# FIPS / eIDAS / KCMVP Hardware Validation Runbook · 2025-12-11

Use this runbook to validate hardware-backed crypto for the FIPS, eIDAS, and KCMVP profiles. When hardware is unavailable, keep the “non-certified” label and use the simulator (`ops/crypto/sim-crypto-service`) to exercise the registry path.

## Common prerequisites
- Hosts: Linux runners for FIPS/OpenSSL FIPS provider; EU QSCD host (HSM/smartcard) for eIDAS; KR host for KCMVP modules.
- Config: set `StellaOps:Crypto:Registry:ActiveProfile` to `fips`, `eidas`, or `kcmvp`.
- Evidence bundle: JWKS snapshot, `CryptoProviderMetrics` scrape, signing/verification logs for the fixed message `stellaops-validation-msg`.
- Simulator fallback: `STELLAOPS_CRYPTO_ENABLE_SIM=1` and `STELLAOPS_CRYPTO_SIM_URL=http://<host>:8080` if hardware is missing.

## FIPS (baseline or certified)
1) Enable the profile:
   ```yaml
   StellaOps:
     Crypto:
       Registry:
         ActiveProfile: fips
       Fips:
         UseBclFipsMode: true    # or OpenSSL FIPS provider path
   ```
2) If using AWS KMS FIPS endpoints, set `AWS_USE_FIPS_ENDPOINTS=true` and target a FIPS-enabled region.
3) Run signing tests (Authority/Signer/Attestor) with `FIPS_SOFT_ALLOWED=0` when a certified module is present; otherwise leave it at the default soft mode.
4) Capture evidence:
   - `openssl fipsinstall -module <path>` output (if OpenSSL FIPS).
   - JWKS export (P-256/384/521).
   - `CryptoProviderMetrics` counts for `fips.ecdsa.*`.
5) Keep the “non-certified” label until CMVP evidence is attached; simulator may be used for CI smoke only.

## eIDAS (QSCD)
1) Configure QSCD trust store and device:
   ```yaml
   StellaOps:
     Crypto:
       Registry:
         ActiveProfile: eidas
       Pkcs11:
         LibraryPath: /usr/lib/qscd/libpkcs11.so
         Keys:
           - KeyId: eidas-qscd
             SlotId: 0
             PinEnvVar: EIDAS_QSCD_PIN
             Algorithm: ecdsa-p256
   ```
2) Import the qualified cert to the trust store; capture OCSP/CRL endpoints.
3) Export JWKS from Authority/Signer; verify `kid` and `crv` match the QSCD key.
4) Sign `stellaops-validation-msg`; archive signature + certificate chain.
5) Evidence: PKCS#11 slot list, JWKS snapshot, QSCD audit logs (if available), provider metrics for `eu.eidas.*`.
6) If QSCD hardware is unavailable, keep `EIDAS_SOFT_ALLOWED=1` and run against the simulator for CI coverage.

## KCMVP
1) Configure KCMVP module (ARIA/SEED/KCDSA) or hash-only fallback:
   ```yaml
   StellaOps:
     Crypto:
       Registry:
         ActiveProfile: kcmvp
       Kcmvp:
         LibraryPath: /usr/lib/kcmvp/libpkcs11.so
         Keys:
           - KeyId: kcmvp-hw
             SlotId: 0
             PinEnvVar: KCMVP_PIN
             Algorithm: kcdsa
   ```
2) If hardware is unavailable, keep `KCMVP_HASH_ALLOWED=1` and record hash-only evidence.
3) Run signing/hash tests for `stellaops-validation-msg`; collect signatures/hashes and metrics for `kr.kcmvp.*`.
4) When a certified module is present, set `KCMVP_HASH_ALLOWED=0` and rerun tests to retire the hash-only label.

## Evidence checklist
- Command outputs: `pkcs11-tool --list-slots`, `--list-objects`, module self-tests (if provided).
- JWKS snapshots and `CryptoProviderMetrics` scrape.
- Signature/hash files and verification logs for the fixed message.
- Configuration files/env vars used during the run.

## Publishing
- Attach evidence to sprint artefacts for FIPS-EIDAS-VAL-01 and KCMVP-VAL-01.
- Update RootPack manifests to remove the “non-certified” wording once certified evidence is present; otherwise keep the simulator noted as the interim path.