feat(cli): Implement crypto plugin CLI architecture with regional compliance
Sprint: SPRINT_4100_0006_0001 Status: COMPLETED Implemented plugin-based crypto command architecture for regional compliance with build-time distribution selection (GOST/eIDAS/SM) and runtime validation. ## New Commands - `stella crypto sign` - Sign artifacts with regional crypto providers - `stella crypto verify` - Verify signatures with trust policy support - `stella crypto profiles` - List available crypto providers & capabilities ## Build-Time Distribution Selection ```bash # International (default - BouncyCastle) dotnet build src/Cli/StellaOps.Cli/StellaOps.Cli.csproj # Russia distribution (GOST R 34.10-2012) dotnet build -p:StellaOpsEnableGOST=true # EU distribution (eIDAS Regulation 910/2014) dotnet build -p:StellaOpsEnableEIDAS=true # China distribution (SM2/SM3/SM4) dotnet build -p:StellaOpsEnableSM=true ``` ## Key Features - Build-time conditional compilation prevents export control violations - Runtime crypto profile validation on CLI startup - 8 predefined profiles (international, russia-prod/dev, eu-prod/dev, china-prod/dev) - Comprehensive configuration with environment variable substitution - Integration tests with distribution-specific assertions - Full migration path from deprecated `cryptoru` CLI ## Files Added - src/Cli/StellaOps.Cli/Commands/CryptoCommandGroup.cs - src/Cli/StellaOps.Cli/Commands/CommandHandlers.Crypto.cs - src/Cli/StellaOps.Cli/Services/CryptoProfileValidator.cs - src/Cli/StellaOps.Cli/appsettings.crypto.yaml.example - src/Cli/__Tests/StellaOps.Cli.Tests/CryptoCommandTests.cs - docs/cli/crypto-commands.md - docs/implplan/SPRINT_4100_0006_0001_COMPLETION_SUMMARY.md ## Files Modified - src/Cli/StellaOps.Cli/StellaOps.Cli.csproj (conditional plugin refs) - src/Cli/StellaOps.Cli/Program.cs (plugin registration + validation) - src/Cli/StellaOps.Cli/Commands/CommandFactory.cs (command wiring) - src/Scanner/__Libraries/StellaOps.Scanner.Core/Configuration/PoEConfiguration.cs (fix) ## Compliance - GOST (Russia): GOST R 34.10-2012, FSB certified - eIDAS (EU): Regulation (EU) No 910/2014, QES/AES/AdES - SM (China): GM/T 0003-2012 (SM2), OSCCA certified ## Migration `cryptoru` CLI deprecated → sunset date: 2025-07-01 - `cryptoru providers` → `stella crypto profiles` - `cryptoru sign` → `stella crypto sign` ## Testing ✅ All crypto code compiles successfully ✅ Integration tests pass ✅ Build verification for all distributions (international/GOST/eIDAS/SM) Next: SPRINT_4100_0006_0002 (eIDAS plugin implementation) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
master
304
docs/cli/crypto-commands.md
Normal file
304
docs/cli/crypto-commands.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user