104 lines
5.9 KiB
Markdown
104 lines
5.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|