stella-ops.org/git.stella-ops.org

Fork 0

Files

master 608a7f85c0 audit work, fixed StellaOps.sln warnings/errors, fixed tests, sprints work, new advisories

2026-01-07 18:50:11 +02:00

14 KiB

Raw Blame History

StellaOps Regional Deployments

Version: 2025.10.0 Last Updated: 2025-12-23 Audience: DevOps Engineers, System Administrators

Overview

StellaOps supports regional deployment profiles that enable cryptographic compliance with local regulations and standards. Each profile uses a different set of cryptographic plugins and algorithms, selected at runtime via configuration.

Build Once, Deploy Everywhere

The platform uses a single Docker image containing all crypto plugins. Regional selection happens at deployment time through:

Docker Compose file selection
Regional configuration file mounting
Environment variable settings

This architecture eliminates the need for region-specific builds while maintaining strict compliance boundaries.

Supported Regions

Region	Profile ID	Crypto Standards	Primary Plugins	Compliance
International	`international`	NIST (ECDSA, RSA, SHA-2)	`offline-verification`	FIPS 140-3 candidate
Russia	`russia`	GOST R 34.10-2012, GOST R 34.11-2012 (Streebog)	`openssl.gost`, `pkcs11.gost`, `cryptopro.gost`	FSB, GOST R
European Union	`eu`	eIDAS qualified trust services	`offline-verification` (temp), `eidas.soft` (planned)	eIDAS, ETSI TS 119 312
China	`china`	SM2, SM3, SM4 (ShangMi)	`offline-verification` (temp), `sm.soft` (planned)	OSCCA, GM/T

Quick Start

International Deployment (Default)

# Clone repository
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org.git
cd git.stella-ops.org

# Start services with international crypto profile
docker compose -f devops/compose/docker-compose.international.yml up -d

# Verify cryptographic configuration
docker exec stellaops-authority-1 cat /app/etc/appsettings.crypto.yaml

Algorithms Used:

Signing: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384, PS512
Hashing: SHA-256, SHA-384, SHA-512

Russia Deployment (GOST)

# Start services with GOST crypto profile
docker compose -f devops/compose/docker-compose.russia.yml up -d

Requirements:

OpenSSL GOST engine installed on host
PKCS#11 library for Rutoken/JaCarta (optional, for HSM support)
CryptoPro CSP (Windows only, optional)

Algorithms Used:

Signing: GOST R 34.10-2012-256, GOST R 34.10-2012-512
Hashing: GOST R 34.11-2012-256 (Streebog-256), GOST R 34.11-2012-512 (Streebog-512)

Dependencies:

# Install OpenSSL GOST engine (Linux)
sudo apt-get install -y openssl openssl-gost

# Verify GOST engine
openssl engine -c gost

EU Deployment (eIDAS)

# Start services with eIDAS crypto profile
docker compose -f devops/compose/docker-compose.eu.yml up -d

Status: Currently uses offline-verification plugin with NIST algorithms as a fallback. Full eIDAS plugin (eidas.soft) is planned for Phase 4.

Algorithms Used (Temporary):

Signing: ES256, ES384, ES512, RS256, RS384, RS512
Hashing: SHA-256, SHA-384, SHA-512

Planned eIDAS Support:

Qualified Electronic Signatures (QES)
Advanced Electronic Signatures (AdES): XAdES, PAdES, CAdES
ETSI TS 119 312 compliance
Qualified Signature Creation Device (QSCD) integration

China Deployment (ShangMi)

# Start services with SM crypto profile
docker compose -f devops/compose/docker-compose.china.yml up -d

Status: Currently uses offline-verification plugin with NIST algorithms as a fallback. Full SM plugin (sm.soft) is planned for Phase 4.

Planned SM Support:

SM2: Public key cryptography (GM/T 0003-2012)
SM3: Cryptographic hash function (GM/T 0004-2012)
SM4: Block cipher (GM/T 0002-2012)
SM9: Identity-based cryptography (GM/T 0044-2016)

Dependencies (Planned):

# GmSSL installation (Linux)
git clone https://github.com/guanzhi/GmSSL.git
cd GmSSL && mkdir build && cd build
cmake .. && make && sudo make install

Architecture

Docker Image Structure

┌──────────────────────────────────────┐
│ stellaops/platform:latest            │
│ (Base Runtime Image)                 │
├──────────────────────────────────────┤
│ Contains ALL crypto plugin DLLs:     │
│ • OfflineVerificationCryptoProvider  │
│ • OpenSslGostProvider                │
│ • CryptoProGostProvider              │
│ • (Future: eIDAS, SM plugins)        │
│                                      │
│ + crypto-plugins-manifest.json       │
│ + NO regional config selected        │
└──────────────────────────────────────┘
            ↓
┌──────────────────────────────────────┐
│ Regional Profile Selection           │
│ (via Docker Compose)                 │
├──────────────────────────────────────┤
│ Mounts:                              │
│ • etc/appsettings.crypto.{profile}   │
│ • etc/crypto-plugins-manifest.json   │
│                                      │
│ Sets ENV:                            │
│ • STELLAOPS_CRYPTO_PROFILE           │
│ • STELLAOPS_CRYPTO_CONFIG_PATH       │
└──────────────────────────────────────┘
            ↓
┌──────────────────────────────────────┐
│ Runtime Plugin Loading               │
│ (CryptoPluginLoader)                 │
├──────────────────────────────────────┤
│ 1. Read regional config YAML         │
│ 2. Load enabled plugins from manifest│
│ 3. Validate platform compatibility   │
│ 4. Enforce jurisdiction compliance   │
│ 5. Register providers with DI        │
└──────────────────────────────────────┘
            ↓
┌──────────────────────────────────────┐
│ Application Uses ICryptoProvider     │
│ (Abstraction Layer)                  │
├──────────────────────────────────────┤
│ • GetHasher(algorithmId)             │
│ • GetSigner(algorithmId, keyRef)     │
│ • CreateEphemeralVerifier(...)       │
│                                      │
│ No direct crypto library usage!      │
└──────────────────────────────────────┘

Configuration Flow

Container Startup: Service starts, reads STELLAOPS_CRYPTO_PROFILE environment variable
Load Configuration: CryptoPluginLoader reads /app/etc/appsettings.crypto.yaml
Plugin Discovery: Loader reads /app/etc/crypto-plugins-manifest.json
Filtering:
- Platform compatibility check (Linux/Windows/macOS)
- Jurisdiction enforcement (if EnforceJurisdiction: true)
- Capability matching (signing, hashing, verification)
Registration: Enabled plugins registered with DI container
Application Start: Services use ICryptoProvider abstraction

Regional Configuration Files

International (`etc/appsettings.crypto.international.yaml`)

StellaOps:
  Crypto:
    Plugins:
      ManifestPath: "/app/etc/crypto-plugins-manifest.json"
      DiscoveryMode: "explicit"
      Enabled:
        - Id: "offline-verification"
          Priority: 100
          Options: {}
      FailOnMissingPlugin: true
      RequireAtLeastOne: true

    Compliance:
      ProfileId: "world"
      StrictValidation: false
      EnforceJurisdiction: false
      HashAlgorithm: "SHA-256"
      SignatureAlgorithm: "ES256"

Russia (`etc/appsettings.crypto.russia.yaml`)

StellaOps:
  Crypto:
    Plugins:
      Enabled:
        - Id: "openssl.gost"
          Priority: 100
        - Id: "pkcs11.gost"
          Priority: 95
        - Id: "cryptopro.gost"
          Priority: 110

    Compliance:
      ProfileId: "gost"
      StrictValidation: true
      EnforceJurisdiction: true
      AllowedJurisdictions:
        - "russia"
      HashAlgorithm: "GOST-R-34.11-2012-256"
      SignatureAlgorithm: "GOST-R-34.10-2012-256"

Operations

Switching Regions

To switch from one region to another:

# Stop current deployment
docker compose -f devops/compose/docker-compose.international.yml down

# Start new regional deployment
docker compose -f devops/compose/docker-compose.russia.yml up -d

Verifying Regional Configuration

# Check loaded crypto profile
docker exec stellaops-authority-1 env | grep STELLAOPS_CRYPTO

# View active configuration
docker exec stellaops-authority-1 cat /app/etc/appsettings.crypto.yaml

# Verify plugin manifest
docker exec stellaops-authority-1 cat /app/etc/crypto-plugins-manifest.json | jq '.plugins[] | {id, jurisdiction}'

Health Checks

# Check service health
docker compose -f devops/compose/docker-compose.international.yml ps

# Test crypto provider loading (Authority service example)
docker logs stellaops-authority-1 2>&1 | grep -i "crypto"

# Expected log output:
# [INFO] CryptoPluginLoader: Loaded plugin 'offline-verification' (priority 100)
# [INFO] CryptoProviderRegistry: Registered provider 'offline-verification' for capability 'signing:ES256'

Troubleshooting

Issue: Plugin Not Found

Symptom:

CryptoPluginException: Plugin 'openssl.gost' not found in manifest

Solution:

Verify plugin ID in etc/crypto-plugins-manifest.json
Check regional config etc/appsettings.crypto.{profile}.yaml for typos
Ensure manifest is mounted in Docker Compose file

Issue: Platform Incompatibility

Symptom:

[WARN] Plugin 'cryptopro.gost' not supported on platform Linux, skipping

Solution:

CryptoPro GOST is Windows-only. Use openssl.gost or pkcs11.gost on Linux instead.
Update etc/appsettings.crypto.russia.yaml to prioritize Linux-compatible plugins.

Issue: Jurisdiction Enforcement Failure

Symptom:

[WARN] Plugin 'offline-verification' jurisdiction 'world' not allowed, skipping

Solution:

Disable jurisdiction enforcement:

Compliance:
  EnforceJurisdiction: false

OR add world to allowed jurisdictions:

Compliance:
  AllowedJurisdictions:
    - "russia"
    - "world"

Issue: No Plugins Loaded

Symptom:

InvalidOperationException: No crypto plugins configured

Solution:

Check etc/appsettings.crypto.{profile}.yaml has at least one enabled plugin
Verify RequireAtLeastOne: true setting
Check Docker volume mounts in docker-compose.{profile}.yml

Security Considerations

Plugin Trust

Verification: All plugins should be built from source or obtained from trusted registries
Checksums: Verify plugin DLL checksums before deployment
Signing: Future versions will support signed plugin assemblies

Jurisdiction Enforcement

When EnforceJurisdiction: true:

Only plugins matching AllowedJurisdictions are loaded
Prevents accidental use of non-compliant crypto in regulated environments
Recommended for production deployments in Russia, EU, China

Key Management

International: Keys stored in PostgreSQL, encrypted at rest
Russia: PKCS#11 HSM recommended (Rutoken, JaCarta)
EU: Qualified Signature Creation Device (QSCD) required for QES
China: OSCCA-certified HSM required for production

Building Regional Images

Manual Build (Development)

# Build platform image with all plugins
docker build -f deploy/docker/Dockerfile.platform --target runtime-base -t stellaops/platform:latest .

# Build regional service images
docker build -f deploy/docker/Dockerfile.crypto-profile \
  --build-arg CRYPTO_PROFILE=international \
  --target authority \
  -t stellaops/authority:international .

CI/CD Build (Automatic)

The .gitea/workflows/docker-regional-builds.yml workflow automatically builds all regional images on push to main:

Build platform image once
Build 4 regional profiles × 14 services = 56 images
Validate regional configurations
Push to container registry

Migration Guide

From Hardcoded Crypto

If migrating from a version with hardcoded crypto usage:

Audit: Run scripts/audit-crypto-usage.ps1 to find direct crypto usage
Refactor: Replace System.Security.Cryptography with ICryptoProvider
Test: Verify crypto operations with OfflineVerificationCryptoProviderTests
Deploy: Use regional Docker Compose file

From Single-Region to Multi-Region

Backup: Export existing keys and configurations
Update: Pull latest images with multi-region support
Configure: Select appropriate docker-compose.{profile}.yml
Migrate Keys: Import keys using new plugin system
Validate: Test crypto operations in new profile

References

Support

For deployment assistance:

Documentation: docs/
Issues: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues
Discussions: https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/discussions

14 KiB Raw Blame History Unescape Escape

StellaOps Regional Deployments

Overview

Build Once, Deploy Everywhere

Supported Regions

Quick Start

International Deployment (Default)

Russia Deployment (GOST)

EU Deployment (eIDAS)

China Deployment (ShangMi)

Architecture

Docker Image Structure

Configuration Flow

Regional Configuration Files

International (etc/appsettings.crypto.international.yaml)

Russia (etc/appsettings.crypto.russia.yaml)

Operations

Switching Regions

Verifying Regional Configuration

Health Checks

Troubleshooting

Issue: Plugin Not Found

Issue: Platform Incompatibility

Issue: Jurisdiction Enforcement Failure

Issue: No Plugins Loaded

Security Considerations

Plugin Trust

Jurisdiction Enforcement

Key Management

Building Regional Images

Manual Build (Development)

CI/CD Build (Automatic)

Migration Guide

From Hardcoded Crypto

From Single-Region to Multi-Region

References

Support

14 KiB

Raw Blame History

International (`etc/appsettings.crypto.international.yaml`)

Russia (`etc/appsettings.crypto.russia.yaml`)