stella crypto — Command Guide

Distribution support: International, Russia (GOST), EU (eIDAS), China (SM)

The stella crypto command group provides signing and verification operations with regional compliance support. The available providers depend on which distribution you build or install (see the Distribution Matrix).

Audience: operators signing release artifacts and verifying signatures, and CI/CD pipelines that integrate signing into the release flow.

stella crypto sign resolves a real signing key from the configured provider set and emits a 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

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:

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 is scheduled for removal in Stella Ops 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

stella crypto secret-provider — inspect the secret registry

The unified secret provider (ADR-031) and URL-routed multi-provider registry (ADR-032) expose a read-only inspection surface. These verbs hit the Platform admin endpoints under /api/v1/admin/crypto/secret-providers and require the crypto:read scope (tenant-scoped). They never print secret bytes — paths returns path names only, and --format json / --json carries no value field.

# List the configured registry (e.g. builtin + vault + openbao):
stella crypto secret-provider list
#   Id            Kind       Reachable
#   builtin       builtin    yes
#   prod-vault    vault      yes
#   bao           openbao    yes

# Browse path names under a provider (NAMES only, never values):
stella crypto secret-provider paths --provider prod-vault --prefix secret/app
#   app/db/password

# Fail-closed: an unconfigured provider id → HTTP 404 listing configured ids, exit 14:
stella crypto secret-provider paths --provider does-not-exist
#   Error: … "Secret provider id 'does-not-exist' is not configured.
#            Configured ids: builtin, prod-vault, bao." (exit 14)

A secret is referenced by a URL (<scheme>://[<provider-id>/]<path>[#<version>], e.g. vault://prod-vault/secret/app/db/password#5, openbao://bao/kv/notify/smtp/password, builtin://integration:<guid>). The URL is a non-secret pointer — safe to store, display, log, and audit. Full grammar: secret-reference URL scheme spec; operator runbook: multi-provider secret registry.

stella crypto master-key — provision the master KEK

Provisioning verbs for the master key that roots seal/open (ADR-031 §D3). These mutate provisioning state and require the crypto:kek:rotate scope. Secret material is never echoed — only the non-secret fingerprint is printed.

WARNING. generate / import re-root the installation master key. On a running, data-bearing install this orphans every existing sealed secret unless a full re-seal walk follows (see KEK rotation runbook). Use master-key probe to health-check the live key; only generate/import on a fresh install or under a planned rotation.

# Health-check the live master key (no change):
stella crypto master-key probe
#   Master key probe: ok

# Fresh-install symmetric generate (default 32 bytes):
stella crypto master-key generate --format symmetric

# Import operator-provided asymmetric key material from a file:
stella crypto master-key import --format asymmetric --material-file ./kek.pem

This surface was proven end-to-end against a live, data-bearing stack on 2026-06-22 (builtin + 2× HashiCorp Vault + OpenBao): live-proof evidence.

Related documentation

• Cryptography Architecture
• Regional Compliance Guide
• Crypto Plugin Development
• Distribution Matrix
• Configuration
• Multi-provider secret registry (runbook)
• ADR-031 — unified secret provider
• ADR-032 — URL secret references
• Air-gap Operation

Security Considerations

1. Key protection — never commit private keys or credentials to version control.
2. Secret management — keep credentials out of config files; source them from a self-hosted secret store such as HashiCorp Vault.
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 — back up 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)