git.stella-ops.org/docs/security/fips-eidas-kcmvp-validation.md

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:

   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:

   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:

   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.