# 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.