git.stella-ops.org/docs/deploy/wine-csp-container.md

Wine CSP Container Deployment Guide

SECURITY WARNING: The Wine CSP container is for TEST VECTOR GENERATION ONLY. It MUST NOT be used for production cryptographic signing operations. All signatures produced by this service should be treated as test artifacts.

Overview

The Wine CSP container provides GOST cryptographic operations (GOST R 34.10-2012, GOST R 34.11-2012) via a Wine-hosted CryptoPro CSP environment. This enables Linux-based StellaOps deployments to generate GOST test vectors and validate cross-platform cryptographic interoperability.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Wine CSP Container                            │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │  Ubuntu 22.04 (linux/amd64)                                     │ │
│  │  ┌───────────────┐    ┌────────────────────────────────────────┐ │ │
│  │  │   Xvfb        │    │  Wine 64-bit Environment               │ │ │
│  │  │ (display :99) │───>│  ┌──────────────────────────────────┐  │ │ │
│  │  └───────────────┘    │  │  WineCspService.exe (.NET 8)     │  │ │ │
│  │                       │  │  ┌────────────────────────────┐  │  │ │ │
│  │                       │  │  │  GostCryptography.dll      │  │  │ │ │
│  │                       │  │  │  (MIT-licensed fork)       │  │  │ │ │
│  │                       │  │  └────────────────────────────┘  │  │ │ │
│  │                       │  │  ┌────────────────────────────┐  │  │ │ │
│  │                       │  │  │  CryptoPro CSP (optional)  │  │  │ │ │
│  │                       │  │  │  (customer-provided)       │  │  │ │ │
│  │                       │  │  └────────────────────────────┘  │  │ │ │
│  │                       │  └──────────────────────────────────┘  │ │ │
│  │                       └────────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                              │                                        │
│                              │ HTTP API (port 5099)                   │
│                              ▼                                        │
└─────────────────────────────────────────────────────────────────────┘

Deployment Modes

Limited Mode (Default)

Operates without CryptoPro CSP using the open-source GostCryptography library:

• Capabilities: Basic GOST signing/verification, hashing
• Requirements: None (self-contained)
• Use Case: Development, testing, CI/CD pipelines

docker run -p 5099:5099 -e WINE_CSP_MODE=limited wine-csp:latest

Full Mode

Enables full CryptoPro CSP functionality with customer-provided installer:

• Capabilities: Full GOST R 34.10-2012/34.11-2012, hardware token support
• Requirements: Licensed CryptoPro CSP installer MSI
• Use Case: Test vector generation matching production CSP output

docker run -p 5099:5099 \
  -e WINE_CSP_MODE=full \
  -v /path/to/csp-5.0.msi:/opt/cryptopro/csp-installer.msi:ro \
  wine-csp:latest

API Endpoints

Endpoint	Method	Description
/health	GET	Health check (Healthy/Degraded/Unhealthy)
/health/liveness	GET	Kubernetes liveness probe
/health/readiness	GET	Kubernetes readiness probe
/status	GET	Service status with CSP availability
/keys	GET	List available signing keys
/sign	POST	Sign data with GOST R 34.10-2012
/verify	POST	Verify GOST signature
/hash	POST	Compute GOST R 34.11-2012 hash
/test-vectors	GET	Generate deterministic test vectors

Request/Response Examples

Sign Request

POST /sign
Content-Type: application/json

{
  "keyId": "test-key-256",
  "algorithm": "GOST12-256",
  "data": "SGVsbG8gV29ybGQ="
}

Response:

{
  "signature": "MEQCIFh...",
  "algorithm": "GOST12-256",
  "keyId": "test-key-256",
  "timestamp": "2025-12-07T12:00:00Z"
}

Hash Request

POST /hash
Content-Type: application/json

{
  "algorithm": "STREEBOG-256",
  "data": "SGVsbG8gV29ybGQ="
}

Response:

{
  "hash": "5a7f...",
  "algorithm": "STREEBOG-256"
}

Docker Compose Integration

Development Environment

Add to your docker-compose.dev.yaml:

services:
  wine-csp:
    image: registry.stella-ops.org/stellaops/wine-csp:2025.10.0-edge
    restart: unless-stopped
    environment:
      WINE_CSP_PORT: "5099"
      WINE_CSP_MODE: "limited"
      WINE_CSP_LOG_LEVEL: "Information"
    volumes:
      - wine-csp-prefix:/home/winecsp/.wine
      - wine-csp-logs:/var/log/wine-csp
    ports:
      - "5099:5099"
    networks:
      - stellaops
    healthcheck:
      test: ["/usr/local/bin/healthcheck.sh"]
      interval: 30s
      timeout: 10s
      start_period: 90s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 2G

volumes:
  wine-csp-prefix:
  wine-csp-logs:

With CryptoPro CSP Installer

services:
  wine-csp:
    image: registry.stella-ops.org/stellaops/wine-csp:2025.10.0-edge
    environment:
      WINE_CSP_MODE: "full"
    volumes:
      - wine-csp-prefix:/home/winecsp/.wine
      - /secure/path/to/csp-5.0.msi:/opt/cryptopro/csp-installer.msi:ro

Environment Variables

Variable	Default	Description
WINE_CSP_PORT	5099	HTTP API port
WINE_CSP_MODE	limited	Operation mode: limited or full
WINE_CSP_INSTALLER_PATH	/opt/cryptopro/csp-installer.msi	Path to CSP installer
WINE_CSP_LOG_LEVEL	Information	Log level (Trace/Debug/Information/Warning/Error)
ASPNETCORE_ENVIRONMENT	Production	ASP.NET Core environment
WINEDEBUG	-all	Wine debug output (set to warn+all for troubleshooting)

Volume Mounts

Path	Purpose	Persistence
/home/winecsp/.wine	Wine prefix (CSP installation, keys)	Required for full mode
/opt/cryptopro	CSP installer directory (read-only)	Optional
/var/log/wine-csp	Service logs	Recommended

Security Considerations

Production Restrictions

1. Never expose to public networks - Internal use only
2. No sensitive keys - Use only test keys
3. Audit logging - Enable verbose logging for forensics
4. Network isolation - Place in dedicated network segment
5. Read-only root filesystem - Not supported due to Wine requirements

Container Security

• Non-root user: Runs as winecsp (UID 10001)
• No capabilities: No elevated privileges required
• Minimal packages: Only Wine and dependencies installed
• Security labels: Container labeled test-vectors-only=true

CryptoPro CSP Licensing

CryptoPro CSP is commercial software. StellaOps does not distribute CryptoPro CSP:

1. Customer must provide their own licensed CSP installer
2. Mount the MSI file as read-only volume
3. Installation occurs on first container start
4. License persisted in Wine prefix volume

See docs/legal/crypto-compliance-review.md for distribution matrix.

Known Limitations

Limitation	Impact	Mitigation
linux/amd64 only	No ARM64 support	Deploy on x86_64 hosts
Large image (~1GB)	Storage/bandwidth	Air-gap bundles, layer caching
Slow startup (60-90s)	Health check delays	Extended start_period
Writable filesystem	Security hardening	Minimize writable paths
Wine compatibility	Potential CSP issues	Test with specific CSP version

Troubleshooting

Container Won't Start

# Check container logs
docker logs wine-csp

# Verify Wine initialization
docker exec wine-csp ls -la /home/winecsp/.wine

# Check for Wine errors
docker exec wine-csp cat /var/log/wine-csp/*.log

Health Check Failing

# Manual health check
docker exec wine-csp wget -q -O - http://127.0.0.1:5099/health

# Check Xvfb is running
docker exec wine-csp pgrep Xvfb

# Verbose Wine output
docker exec -e WINEDEBUG=warn+all wine-csp wine64 /app/WineCspService.exe

CSP Installation Issues

# Check installation marker
docker exec wine-csp cat /home/winecsp/.wine/.csp_installed

# View installation logs
docker exec wine-csp cat /home/winecsp/.wine/csp_install_logs/*.log

# Verify CSP directory
docker exec wine-csp ls -la "/home/winecsp/.wine/drive_c/Program Files/Crypto Pro"

Performance Issues

# Increase memory limit
docker run --memory=4g wine-csp:latest

# Check resource usage
docker stats wine-csp

Air-Gap Deployment

For air-gapped environments:

1. Download bundle:

   # From CI artifacts or release
   wget https://artifacts.stella-ops.org/wine-csp/wine-csp-2025.10.0-edge.tar.gz
   

2. Transfer to air-gapped system (via approved media)

3. Load image:

   docker load < wine-csp-2025.10.0-edge.tar.gz
   

4. Run container:

   docker run -p 5099:5099 wine-csp:2025.10.0-edge
   

Integration with StellaOps

The Wine CSP service integrates with StellaOps cryptography infrastructure:

// Configure Wine CSP provider
services.AddWineCspProvider(options =>
{
    options.ServiceUrl = "http://wine-csp:5099";
    options.TimeoutSeconds = 30;
    options.MaxRetries = 3;
});

See src/__Libraries/StellaOps.Cryptography.Plugin.WineCsp/ for the provider implementation.

Related Documentation

• Wine CSP Loader Design
• RU Crypto Validation Sprint
• Crypto Provider Registry
• Crypto Compliance Review