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

RootPack_RU Packaging Guide

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 third_party/forks/AlexMAS.GostCryptography/STELLA_NOTES.md matches git -C third_party/forks/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 AGPL-3.0-or-later.
• Do not publish the fork to NuGet; all builds must use the vendored sources shipped inside the bundle.

1. What the bundle contains

Directory	Purpose
artifacts/	Published binaries for StellaOps.Cryptography.Plugin.CryptoPro, StellaOps.Cryptography.Plugin.OpenSslGost, and StellaOps.Cryptography.Plugin.Pkcs11Gost (targeting net10.0).
config/rootpack_ru.crypto.yaml	Opinionated configuration template that enables the ru-offline crypto profile and defines CryptoPro + PKCS#11 keys.
docs/	Validation runbook, audit report, and this packaging guide.
trust/	Russian trust-anchor PEM files copied from certificates/russian_trusted_*.
README.txt	High-level summary plus operator checklist.

2. Build the bundle

# from repository root
scripts/crypto/package-rootpack-ru.sh
# optionally specify destination
scripts/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 found at etc/rootpack/ru/crypto.profile.yaml.
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 third_party/forks/AlexMAS.GostCryptography/LICENSE "${OUTPUT_ROOT}/docs/LICENSE.gostcryptography"
cp third_party/forks/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 scripts/crypto/package-rootpack-ru.sh, execute the deterministic harness to capture logs:

scripts/crypto/run-rootpack-ru-tests.sh
# or specify ROOTPACK_LOG_DIR=/tmp/rootpack_ru_tests scripts/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.

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. 4. Re-run the validation runbook to confirm JWKS, telemetry, and RootPack evidence are aligned with the shipping bundle.

Known gaps (2025-11-09)

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

• Integration tests: scripts/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.