git.stella-ops.org/docs/cli/crypto-commands.md

# Crypto Commands

**Sprint**: SPRINT_4100_0006_0001
**Status**: Implemented
**Distribution Support**: International, Russia (GOST), EU (eIDAS), China (SM)

## Overview

The `stella crypto` command group provides cryptographic operations with regional compliance support. The available crypto providers depend on your distribution build.

## Distribution Matrix

| Distribution | Build Flag | Crypto Standards | Providers |
|--------------|------------|------------------|-----------|
| **International** | (default) | NIST/FIPS | BouncyCastle (ECDSA, RSA, EdDSA) |
| **Russia** | `StellaOpsEnableGOST=true` | GOST R 34.10-2012<br>GOST R 34.11-2012<br>GOST R 34.12-2015 | CryptoPro CSP<br>OpenSSL GOST<br>PKCS#11 GOST |
| **EU** | `StellaOpsEnableEIDAS=true` | eIDAS Regulation 910/2014<br>ETSI EN 319 412 | Remote TSP (QES)<br>Local PKCS#12 (AdES) |
| **China** | `StellaOpsEnableSM=true` | GM/T 0003-2012 (SM2)<br>GM/T 0004-2012 (SM3)<br>GM/T 0002-2012 (SM4) | Remote CSP<br>GmSSL |

## Commands

### `stella crypto sign`

Sign artifacts using configured crypto provider.

**Usage:**
```bash
stella crypto sign --input <file> [options]
```

**Options:**
- `--input <path>` - Path to file to sign (required)
- `--output <path>` - Output path for signature (default: `<input>.sig`)
- `--provider <name>` - Override crypto provider (e.g., `gost-cryptopro`, `eidas-tsp`, `sm-remote`)
- `--key-id <id>` - Key identifier for signing
- `--format <format>` - Signature format: `dsse`, `jws`, `raw` (default: `dsse`)
- `--detached` - Create detached signature (default: true)
- `--verbose` - Show detailed output

**Examples:**

```bash
# Sign with default provider
stella crypto sign --input artifact.tar.gz

# Sign with specific GOST provider
stella crypto sign --input artifact.tar.gz --provider gost-cryptopro --key-id prod-signing-2025

# Sign with eIDAS QES
stella crypto sign --input contract.pdf --provider eidas-tsp --format jws
```

### `stella crypto verify`

Verify signatures using configured crypto provider.

**Usage:**
```bash
stella crypto verify --input <file> [options]
```

**Options:**
- `--input <path>` - Path to file to verify (required)
- `--signature <path>` - Path to signature file (default: `<input>.sig`)
- `--provider <name>` - Override crypto provider
- `--trust-policy <path>` - Path to trust policy YAML file
- `--format <format>` - Signature format: `dsse`, `jws`, `raw` (auto-detect if omitted)
- `--verbose` - Show detailed output

**Examples:**

```bash
# Verify with auto-detected signature
stella crypto verify --input artifact.tar.gz

# Verify with trust policy
stella crypto verify --input artifact.tar.gz --trust-policy ./policies/production-trust.yaml

# Verify specific provider signature
stella crypto verify --input contract.pdf --provider eidas-tsp --signature contract.jws
```

### `stella crypto profiles`

List available crypto providers and their capabilities.

**Usage:**
```bash
stella crypto profiles [options]
```

**Options:**
- `--details` - Show detailed provider capabilities
- `--provider <name>` - Filter by provider name
- `--test` - Run provider diagnostics and connectivity tests
- `--verbose` - Show detailed output

**Examples:**

```bash
# List all providers
stella crypto profiles

# Show detailed capabilities
stella crypto profiles --details

# Test GOST provider connectivity
stella crypto profiles --provider gost --test
```

**Output Distribution Info:**

The `profiles` command shows which regional crypto plugins are enabled:

```
Distribution Information:
┌──────────────────┬─────────┐
│ Feature          │ Status  │
├──────────────────┼─────────┤
│ GOST (Russia)    │ Enabled │
│ eIDAS (EU)       │ Disabled│
│ SM (China)       │ Disabled│
│ BouncyCastle     │ Enabled │
└──────────────────┴─────────┘
```

## Configuration

### Quick Start

1. Copy example configuration:
```bash
cp src/Cli/StellaOps.Cli/appsettings.crypto.yaml.example appsettings.crypto.yaml
```

2. Set active profile:
```yaml
StellaOps:
  Crypto:
    Registry:
      ActiveProfile: "russia-prod"  # or "eu-prod", "china-prod", "international"
```

3. Configure provider credentials:
```bash
export STELLAOPS_CRYPTO_KEYSTORE_PASSWORD="your-password"
export STELLAOPS_GOST_CONTAINER_NAME="your-container"  # For GOST
export STELLAOPS_EIDAS_TSP_API_KEY="your-api-key"     # For eIDAS
export STELLAOPS_SM_CSP_API_KEY="your-api-key"        # For SM
```

### Profile Configuration

See `appsettings.crypto.yaml.example` for detailed configuration examples for each distribution.

**Key sections:**
- `Profiles.<profile>.PreferredProviders` - Provider precedence order
- `Profiles.<profile>.Providers.<name>.Configuration` - Provider-specific settings
- `Validation` - Startup validation rules
- `Attestation.Dsse` - DSSE envelope settings
- `Kms` - Key Management Service integration

## Build Instructions

### International Distribution (Default)

```bash
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj
```

### Russia Distribution (GOST)

```bash
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
  -p:StellaOpsEnableGOST=true
```

### EU Distribution (eIDAS)

```bash
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
  -p:StellaOpsEnableEIDAS=true
```

### China Distribution (SM)

```bash
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
  -p:StellaOpsEnableSM=true
```

### Multi-Region Distribution

```bash
dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj \
  -p:StellaOpsEnableGOST=true \
  -p:StellaOpsEnableEIDAS=true \
  -p:StellaOpsEnableSM=true
```

**Note:** Multi-region builds include all crypto plugins but only activate those configured in the active profile.

## Compliance Notes

### GOST (Russia)

- **Algorithms**: GOST R 34.10-2012 (256/512-bit), GOST R 34.11-2012, GOST R 34.12-2015
- **CSP Support**: CryptoPro CSP, OpenSSL GOST engine, PKCS#11 tokens
- **Certification**: Certified by FSB (Federal Security Service of Russia)
- **Use Cases**: Government contracts, regulated industries in Russia

### eIDAS (EU)

- **Regulation**: (EU) No 910/2014
- **Signature Levels**:
  - QES (Qualified Electronic Signature) - Legal equivalence to handwritten
  - AES (Advanced Electronic Signature)
  - AdES (Advanced Electronic Signature with validation data)
- **Trust Anchors**: EU Trusted List (EUTL)
- **Use Cases**: Legal contracts, public procurement, cross-border transactions

### SM/ShangMi (China)

- **Standards**: GM/T 0003-2012 (SM2), GM/T 0004-2012 (SM3), GM/T 0002-2012 (SM4)
- **Authority**: OSCCA (Office of State Commercial Cryptography Administration)
- **Algorithms**: SM2 (elliptic curve), SM3 (hash), SM4 (block cipher)
- **Use Cases**: Government systems, financial services, critical infrastructure in China

## Migration from `cryptoru` CLI

The standalone `cryptoru` CLI is deprecated. Functionality has been integrated into `stella crypto`:

| Old Command | New Command |
|-------------|-------------|
| `cryptoru providers` | `stella crypto profiles` or `stella crypto providers` |
| `cryptoru sign` | `stella crypto sign` |

**Migration Steps:**

1. Update scripts to use `stella crypto` instead of `cryptoru`
2. Update configuration from `cryptoru.yaml` to `appsettings.crypto.yaml`
3. The `cryptoru` tool will be removed in StellaOps 2.0 (sunset date: 2025-07-01)

## Troubleshooting

### "No crypto providers available"

**Cause**: CLI built without regional crypto flags, or providers not registered.

**Solution**:
1. Check build flags: `stella crypto profiles` shows distribution info
2. Rebuild with appropriate flag (e.g., `-p:StellaOpsEnableGOST=true`)
3. Verify `appsettings.crypto.yaml` configuration

### "Provider not found"

**Cause**: Active profile references unavailable provider.

**Solution**:
1. List available providers: `stella crypto profiles`
2. Update active profile in configuration
3. Or override with `--provider` flag

### GOST Provider Initialization Failed

**Cause**: CryptoPro CSP not installed or configured.

**Solution**:
1. Install CryptoPro CSP 5.0+
2. Configure container: `csptest -keyset -enum_cont -fqcn -verifyc`
3. Set environment: `export STELLAOPS_GOST_CONTAINER_NAME="your-container"`

### eIDAS TSP Connection Error

**Cause**: TSP endpoint unreachable or invalid API key.

**Solution**:
1. Verify TSP endpoint: `curl -I https://tsp.example.eu/api/v1`
2. Check API key: `export STELLAOPS_EIDAS_TSP_API_KEY="valid-key"`
3. Review TSP logs for authentication errors

## Related Documentation

- [Cryptography Architecture](../architecture/cryptography.md)
- [Compliance Matrix](../compliance/crypto-standards.md)
- [Configuration Reference](../configuration/crypto.md)
- [Air-Gap Operation](../operations/airgap.md#crypto-bundles)

## Security Considerations

1. **Key Protection**: Never commit private keys or credentials to version control
2. **Environment Variables**: Use secure secret management (Vault, AWS Secrets Manager)
3. **Trust Policies**: Validate certificate chains and revocation status
4. **Audit Trail**: Enable crypto operation logging for compliance
5. **Key Rotation**: Implement periodic key rotation policies
6. **Disaster Recovery**: Backup key material securely

## Support

For regional crypto compliance questions:
- **GOST**: Contact your CryptoPro representative
- **eIDAS**: Consult qualified Trust Service Provider (TSP)
- **SM**: Contact OSCCA-certified crypto service provider
- **General**: StellaOps support team (support@stella-ops.org)