# RootPack_RU Crypto Validation Runbook

## Purpose

This runbook documents the repeatable steps for validating the Russian sovereign crypto profile (CryptoPro + 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>/`.
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:
   - `stellaops crypto providers --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.

## 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 `stellaops crypto providers --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.