RootPack_RU Packaging Guide

Audience: Release engineers and operators assembling sovereign-crypto bundles. Scope: The reproducible process for building, validating, and shipping the RootPack_RU cryptography bundle. Related: Crypto fork notes · Validation runbook

This guide describes the reproducible process for assembling the sovereign cryptography bundle that backs RootPack_RU deployments.

0. Fork provenance & licensing checklist

• Confirm the vendored fork commit recorded in src/__Libraries/StellaOps.Cryptography.Plugin.CryptoPro/third_party/AlexMAS.GostCryptography/STELLA_NOTES.md matches git -C src/__Libraries/StellaOps.Cryptography.Plugin.CryptoPro/third_party/AlexMAS.GostCryptography rev-parse HEAD before you package.
• Copy the fork’s LICENSE (MIT) and STELLA_NOTES.md into the bundle docs/ directory so downstream operators see the source provenance; keep the plug-ins themselves under BUSL-1.1.
• Do not publish the fork to NuGet; all builds must use the vendored sources shipped inside the bundle.

1. What the bundle contains

2. Build the bundle

# from repository root
ops/crypto/package-rootpack-ru.sh
# optionally specify destination
ops/crypto/package-rootpack-ru.sh /tmp/rootpack_ru_$(date -u +%Y%m%dT%H%M%SZ)

The script performs the following steps:

1. dotnet publish for the CryptoPro + PKCS#11 plug-ins (Release configuration).
2. Copies the relevant documentation (docs/security/rootpack_ru_validation.md, docs/security/crypto-routing-audit-2025-11-07.md, and this guide).
3. Includes the example configuration from etc/rootpack/ru/crypto.profile.yaml, placing it in the bundle as config/rootpack_ru.crypto.yaml (the file referenced in §1 and §5).
4. Adds the Russian trust anchors from certificates/russian_trusted_*.
5. Emits README.txt and optionally creates a *.tar.gz archive (set PACKAGE_TAR=0 to skip the tarball).

After the script finishes, drop the fork metadata into docs/ inside the bundle:

cp src/__Libraries/StellaOps.Cryptography.Plugin.CryptoPro/third_party/AlexMAS.GostCryptography/LICENSE "${OUTPUT_ROOT}/docs/LICENSE.gostcryptography"
cp src/__Libraries/StellaOps.Cryptography.Plugin.CryptoPro/third_party/AlexMAS.GostCryptography/STELLA_NOTES.md "${OUTPUT_ROOT}/docs/STELLA_NOTES.gostcryptography.md"

Temporary quarantine (2025-11-09). To keep day-to-day builds free of the vulnerable GostCryptography dependency, the repository disables the CryptoPro plug-in unless you pass -p:StellaOpsEnableCryptoPro=true. RootPack packaging still works because this script publishes the plug-in directly, but any host/service build that needs CryptoPro must opt in with that MSBuild property until the patched package lands.

3. Attach deterministic test evidence

After running ops/crypto/package-rootpack-ru.sh, execute the deterministic harness to capture logs:

ops/crypto/run-rootpack-ru-tests.sh
# or specify ROOTPACK_LOG_DIR=/tmp/rootpack_ru_tests ops/crypto/run-rootpack-ru-tests.sh

Copy the resulting logs/rootpack_ru_<timestamp>/ directory into the bundle before distributing it (or store it alongside the tarball in your evidence store).

Each harness run produces a README.tests file plus matching .log/.trx pairs for every project. Move the entire directory under an evidence folder inside the bundle (for example evidence/validation/<timestamp>/) so operators can quickly locate the README, raw logs, and provider JSON snapshots when assembling compliance paperwork:

dest="${1:-out/rootpack_ru}"
ts="$(ls logs | grep rootpack_ru_ | sort | tail -n1)"
mkdir -p "${dest}/evidence/validation"
cp -a "logs/${ts}" "${dest}/evidence/validation/${ts}"

4. Hardware validation + audit metadata

Follow docs/security/rootpack_ru_validation.md to:

• Validate CryptoPro CSP and PKCS#11 tokens.
• Capture stellaops crypto providers --profile ru-offline --json output.
• Archive JWKS snapshots and CryptoProviderMetrics samples.
• Document hardware serials and operator initials in hardware_notes.md.

Store these artifacts under logs/rootpack_ru_<timestamp>/ (same directory as the test harness outputs) and reference them in release paperwork.

5. Deployment summary

1. Import the bundled trust anchors into the target installation (Authority + Scanner).
2. Apply config/rootpack_ru.crypto.yaml, update certificate thumbprints, slots, and container labels to match the operator tokens.
3. Restart the services so ICryptoProviderRegistry reloads the ru-offline profile.
   • Windows nodes will prioritize ru.cryptopro.csp; Linux nodes automatically fall back to ru.openssl.gost (PEM/private-key based) before consulting ru.pkcs11.
4. Re-run the validation runbook to confirm JWKS, telemetry, and RootPack evidence are aligned with the shipping bundle.

5.1 Diagnostics CLI

Use the diagnostics CLI to validate configs before rolling out changes:

dotnet run --project src/Tools/StellaOps.CryptoRu.Cli -- providers --config etc/rootpack/ru/crypto.profile.yaml --profile ru-offline
dotnet run --project src/Tools/StellaOps.CryptoRu.Cli -- sign --config etc/rootpack/ru/crypto.profile.yaml --key-id ru-openssl-default --alg GOST12-256 --file samples/message.bin --format base64

Ship the CLI binary inside the RootPack so operators in sealed environments can run the same diagnostics offline.

Known gaps (2025-11-09)

The bundle and scripts above assume several pieces of functionality that have not landed yet:

• Integration tests: ops/crypto/run-rootpack-ru-tests.sh exercises only SHA/Ed25519 paths because CryptoPro/PKCS#11 integration tests are still TODO.
• Symmetric GOST: RootPack artifacts ship only signing plug-ins; Magma/Kuznyechik support for exports/data-at-rest is pending.

These gaps are being tracked in Sprint 514 (SEC-CRYPTO backlog). This guide will be updated once the missing work is delivered.