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

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

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

```http
POST /sign
Content-Type: application/json

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

Response:

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

#### Hash Request

```http
POST /hash
Content-Type: application/json

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

Response:

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

## Docker Compose Integration

### Development Environment

Add to your `docker-compose.dev.yaml`:

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

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

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

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

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

```bash
# 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:**
   ```bash
   # 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:**
   ```bash
   docker load < wine-csp-2025.10.0-edge.tar.gz
   ```

4. **Run container:**
   ```bash
   docker run -p 5099:5099 wine-csp:2025.10.0-edge
   ```

## Integration with StellaOps

The Wine CSP service integrates with StellaOps cryptography infrastructure:

```csharp
// 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](../security/wine-csp-loader-design.md)
- [RU Crypto Validation Sprint](../implplan/SPRINT_0514_0001_0002_ru_crypto_validation.md)
- [Crypto Provider Registry](../contracts/crypto-provider-registry.md)
- [Crypto Compliance Review](../legal/crypto-compliance-review.md)