git.stella-ops.org/docs/security/rootpack_ru_validation.md

RootPack_RU Crypto Validation Runbook

Purpose

This runbook documents the repeatable steps for validating the Russian sovereign crypto profile (CryptoPro on Windows, OpenSSL/Bouncy-managed on Linux, plus PKCS#11) prior to publishing a RootPack bundle. It supplements the crypto routing audit by covering deterministic tests, hardware validation, and the audit metadata artifacts that must be attached to each release.

1. Deterministic Test Harness

1. Run scripts/crypto/run-rootpack-ru-tests.sh (optional ROOTPACK_LOG_DIR=/tmp/rootpack_ru_logs to override the output path). The script executes:
   • src/__Libraries/__Tests/StellaOps.Cryptography.Tests/StellaOps.Cryptography.Tests.csproj
   • src/Scanner/__Tests/StellaOps.Scanner.Worker.Tests/StellaOps.Scanner.Worker.Tests.csproj
   • src/Scanner/__Tests/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests/StellaOps.Scanner.Sbomer.BuildXPlugin.Tests.csproj and emits .log + .trx pairs plus README.tests under logs/rootpack_ru_<timestamp>/.

   Note: CryptoPro/PKCS#11 integration suites have not landed yet; the harness currently covers only default SHA/Ed25519 paths. Hardware validation (sections 2–3) is still manual until those tests exist.

2. For ad-hoc runs (CI or IDE) ensure the same three projects succeed; the cryptography tests validate SHA-256/SHA-512 against BCL implementations and both Streebog variants against BouncyCastle digests.
3. Archive the generated log directory (logs/rootpack_ru_<timestamp>/) along with any additional test outputs inside the RootPack evidence bundle.

2. Hardware Validation (CryptoPro CSP)

1. Install CryptoPro CSP (v5.0 or later) on the validation host and import the qualified certificate configured for the deployment.
2. Configure StellaOps:Crypto:CryptoPro:Keys with the container handle and certificate thumbprint and set StellaOps:Crypto:Registry:ActiveProfile=ru-offline.
3. Run the provider diagnostics to confirm the key material is visible:
   • dotnet run --project src/Tools/StellaOps.CryptoRu.Cli -- providers --config etc/rootpack/ru/crypto.profile.yaml --profile ru-offline --json > logs/ru_cryptopro_providers.json
4. Issue a JWKS fetch (curl https://authority.local/.well-known/jwks) and verify the kid and crv values match the CryptoPro-backed key.
5. Capture the Authority logs showing AuthoritySecretHasherInitializer startup and the CryptoProviderMetrics counters for ru.cryptopro.csp usage.

2.1 Hardware Validation (OpenSSL/Bouncy Linux path)

1. Install OpenSSL with the gost engine (or vendor equivalent) on the validation host and import the PEM key/cert that will back StellaOps:Crypto:OpenSsl:Keys.
2. Configure the OpenSsl section (PEM path plus PrivateKeyPassphraseEnvVar), keep StellaOps:Crypto:Registry:ActiveProfile=ru-offline, and restart the services.
3. Execute a signing workflow and confirm CryptoProviderMetrics records ru.openssl.gost activity. Linux nodes should no longer attempt to load ru.cryptopro.csp.
4. 2025-12-07 validation evidence (Linux, containerised OpenSSL GOST engine):
   • Ran scripts/crypto/validate-openssl-gost.sh (uses rnix/openssl-gost:latest) to generate deterministic digests and two md_gost12_256 signatures over a fixed message. Output folder: logs/openssl_gost_validation_<timestamp>/.
   • Summary from the run at 20251207T220926Z:
     • Message SHA256: e858745af13089d06e74022a75abfee7390aefe7635b15c80fe7d038f58ae6c6
   • md_gost12_256 digest: 01ddd6399e694bb23227925cb6b12e8c25f2f1303644ffbd267da8a68554a2cb
   • Signature SHA256 (run 1): 02321c5564ae902de77a12c8cc2876f0374d4225e52077ecd28876fbd0110b01
   • Signature SHA256 (run 2): 6564c7e0953dda7d40054ef46633c833eec5ee13d4ab8dd0557f2aed1b8d76c4
   • Determinism note: digests are stable; signatures vary per run (nonce-driven) but verify cleanly against the emitted public key.
5. Host defaults and toggles: Authority/Signer/Attestor now bind StellaOps:Crypto via AddStellaOpsCryptoRu and fail-closed on Linux if ru.openssl.gost/ru.pkcs11 are missing. Environment overrides:
   • STELLAOPS_CRYPTO_ENABLE_RU_OPENSSL (default: on for Linux)
   • STELLAOPS_CRYPTO_ENABLE_RU_PKCS11 (default: on)
   • STELLAOPS_CRYPTO_ENABLE_RU_WINECSP (default: off)
   • STELLAOPS_CRYPTO_ENABLE_RU_CSP (Windows only; default on) Disable both OpenSSL and PKCS#11 only when an alternate provider is configured; otherwise startup will fail.

3. Hardware Validation (PKCS#11 Tokens)

1. Install the vendor PKCS#11 library (e.g., Rutoken rtPKCS11ECP.dll or JaCarta) and configure the slot/PIN inside StellaOps:Crypto:Pkcs11:Keys.
2. Switch the registry profile to prioritize ru.pkcs11 and rerun dotnet run --project src/Tools/StellaOps.CryptoRu.Cli -- providers --config etc/rootpack/ru/crypto.profile.yaml --profile ru-offline --json > logs/ru_pkcs11_providers.json.
3. Execute a signing workflow (Authority JWKS refresh or Scanner manifest publish) and confirm the CryptoProviderMetrics counters record ru.pkcs11 activity.
4. Export the token audit logs (if available) and store them with the RootPack evidence bundle.

4. RootPack Audit Metadata

Create a metadata bundle per validation run and store it under logs/rootpack_ru_<timestamp>/ containing:

• providers_ru_offline.json – output from stellaops crypto providers --profile ru-offline --json.
• crypto_tests.txt – snippets from the unit-test executions listed above.
• hardware_notes.md – human-readable notes describing token serials, firmware, and operator initials.
• jwks_snapshot.json – raw JWKS response captured after sovereign providers are active.
• metrics_snapshot.json – scrape of CryptoProviderMetrics Prometheus samples for both providers.

Attach this directory to the RootPack artifact and reference it from the release checklist.

Refer back to docs/security/crypto-routing-audit-2025-11-07.md for the full inventory of components that must consume the shared cryptography stack, and docs/security/rootpack_ru_package.md for packaging/attachment steps.

Known gaps (2025-11-09)

• The stellaops crypto providers ... CLI referenced above is still pending implementation—operators must capture PKCS#11 slot info manually.
• No automated CryptoPro/PKCS#11 integration tests exist; sovereign hardware validation relies on manual signing runs.
• Symmetric GOST (Magma/Kuznyechik) validation is not covered yet.

These items are tracked in Sprint 514 and will be reflected in this runbook once the corresponding tooling lands.