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)

```bash
# 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)

```bash
# 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:**
```bash
# Install OpenSSL GOST engine (Linux)
sudo apt-get install -y openssl openssl-gost

# Verify GOST engine
openssl engine -c gost
```

---

### EU Deployment (eIDAS)

```bash
# 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)

```bash
# 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):**
```bash
# 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`)

```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`)

```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:

```bash
# 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

```bash
# 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

```bash
# 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:
  ```yaml
  Compliance:
    EnforceJurisdiction: false
  ```
- OR add `world` to allowed jurisdictions:
  ```yaml
  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)

```bash
# 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](../implplan/CRYPTO_CONFIGURATION_DRIVEN_ARCHITECTURE.md)
- [Plugin Development Guide](../../src/__Libraries/StellaOps.Cryptography.PluginLoader/README.md)
- [Offline Verification Provider](../../src/__Libraries/StellaOps.Cryptography.Plugin.OfflineVerification/README.md)
- [Sprint 1000_0007_0003: Docker & CI/CD Integration](../implplan/SPRINT_1000_0007_0003_crypto_docker_cicd.md)

---

## Support

For deployment assistance:
- **Documentation**: [docs/](../../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