git.stella-ops.org/docs/modules/cli/guides/crypto/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.

stella crypto sign resolves a real signing key from the configured provider set and emits an actual dsse, detached jws, or raw signature. stella crypto verify performs real verification either against provider-managed key material or a supplied trust policy.

Distribution Matrix

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

Commands

stella crypto sign

Sign artifacts using configured crypto provider.

The CLI selects a provider-exposed signing key at runtime. When multiple provider keys are available, use --provider and --key-id to make the selection explicit.

Usage:

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 when multiple provider keys are exposed
• --format <format> - Signature format: dsse, jws, raw (default: dsse)
• --detached - Create detached signature (default: true; jws output is detached only)
• --verbose - Show detailed output

Examples:

# 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.

Verification behavior depends on the signature material:

• dsse and detached jws can carry key identity metadata, so the CLI can usually resolve the provider key directly.
• raw signatures carry no metadata, so --provider, --key-id, or --trust-policy are typically required.
• --trust-policy verifies against exported public keys and does not require provider access to private key material.

Usage:

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
• --key-id <id> - Key identifier used during verification when provider or trust-policy resolution is ambiguous
• --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:

# 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 --key-id prod-signing-2025 --signature contract.jws

# Verify a raw signature with explicit provider key selection
stella crypto verify --input artifact.tar.gz --signature artifact.tar.gz.sig --format raw --provider default --key-id prod-signing-2025

stella crypto profiles

List available crypto providers and their capabilities.

Usage:

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:

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

cp src/Cli/StellaOps.Cli/appsettings.crypto.yaml.example appsettings.crypto.yaml

2. Set active profile:

StellaOps:
  Crypto:
    Registry:
      ActiveProfile: "russia-prod"  # or "eu-prod", "china-prod", "international"

3. Configure provider credentials:

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)

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

Russia Distribution (GOST)

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

EU Distribution (eIDAS)

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

China Distribution (SM)

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

Multi-Region Distribution

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
• Compliance Matrix
• Configuration Reference
• Air-Gap Operation

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)