git.stella-ops.org/docs/operations/regional-deployments.md

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:

1. Docker Compose file selection
2. Regional configuration file mounting
3. 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 deploy/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 deploy/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 deploy/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 deploy/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

1. Container Startup: Service starts, reads STELLAOPS_CRYPTO_PROFILE environment variable
2. Load Configuration: CryptoPluginLoader reads /app/etc/appsettings.crypto.yaml
3. Plugin Discovery: Loader reads /app/etc/crypto-plugins-manifest.json
4. Filtering:
   • Platform compatibility check (Linux/Windows/macOS)
   • Jurisdiction enforcement (if EnforceJurisdiction: true)
   • Capability matching (signing, hashing, verification)
5. Registration: Enabled plugins registered with DI container
6. 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 deploy/compose/docker-compose.international.yml down

# Start new regional deployment
docker compose -f deploy/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 deploy/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:

1. Verify plugin ID in etc/crypto-plugins-manifest.json
2. Check regional config etc/appsettings.crypto.{profile}.yaml for typos
3. 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:

1. Check etc/appsettings.crypto.{profile}.yaml has at least one enabled plugin
2. Verify RequireAtLeastOne: true setting
3. 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:

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

---

Migration Guide

From Hardcoded Crypto

If migrating from a version with hardcoded crypto usage:

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

From Single-Region to Multi-Region

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

---

References

• Crypto Architecture Overview
• Plugin Development Guide
• Offline Verification Provider
• Sprint 1000_0007_0003: Docker & CI/CD Integration

---

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