docs: Archive Sprint 3500 (PoE), Sprint 7100 (Proof Moats), and additional sprints
Archive completed sprint documentation and deliverables: ## SPRINT_3500 - Proof of Exposure (PoE) Implementation (COMPLETE ✅) - Windows filesystem hash sanitization (colon → underscore) - Namespace conflict resolution (Subgraph → PoESubgraph) - Mock test improvements with It.IsAny<>() - Direct orchestrator unit tests - 8/8 PoE tests passing (100% success) - Archived to: docs/implplan/archived/2025-12-23-sprint-3500-poe/ ## SPRINT_7100.0001 - Proof-Driven Moats Core (COMPLETE ✅) - Four-tier backport detection system - 9 production modules (4,044 LOC) - Binary fingerprinting (TLSH + instruction hashing) - VEX integration with proof-carrying verdicts - 42+ unit tests passing (100% success) - Archived to: docs/implplan/archived/2025-12-23-sprint-7100-proof-moats/ ## SPRINT_7100.0002 - Proof Moats Storage Layer (COMPLETE ✅) - PostgreSQL repository implementations - Database migrations (4 evidence tables + audit) - Test data seed scripts (12 evidence records, 3 CVEs) - Integration tests with Testcontainers - <100ms proof generation performance - Archived to: docs/implplan/archived/2025-12-23-sprint-7100-proof-moats/ ## SPRINT_3000_0200 - Authority Admin & Branding (COMPLETE ✅) - Console admin RBAC UI components - Branding editor with tenant isolation - Authority backend endpoints - Archived to: docs/implplan/archived/ ## Additional Documentation - CLI command reference and compliance guides - Module architecture docs (26 modules documented) - Data schemas and contracts - Operations runbooks - Security risk models - Product roadmap All archived sprints achieved 100% completion of planned deliverables. 🤖 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
1061
docs/cli/command-reference.md
Normal file
1061
docs/cli/command-reference.md
Normal file
File diff suppressed because it is too large
Load Diff
656
docs/cli/compliance-guide.md
Normal file
656
docs/cli/compliance-guide.md
Normal file
@@ -0,0 +1,656 @@
|
||||
# stella CLI - Regional Cryptographic Compliance Guide
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps CLI supports regional cryptographic algorithms to comply with national and international cryptographic standards and regulations. This guide covers compliance requirements for:
|
||||
|
||||
- **GOST** (Russia and CIS states)
|
||||
- **eIDAS** (European Union)
|
||||
- **SM** (China)
|
||||
|
||||
**Important:** Use the distribution appropriate for your jurisdiction. Unauthorized export or use of regional cryptographic implementations may violate export control laws.
|
||||
|
||||
---
|
||||
|
||||
## GOST (Russia and CIS States)
|
||||
|
||||
### Overview
|
||||
|
||||
**GOST** (Государственный стандарт, State Standard) refers to the family of Russian cryptographic standards mandated for government and regulated sectors in Russia and CIS states.
|
||||
|
||||
**Applicable Jurisdictions:** Russia, Belarus, Kazakhstan, Armenia, Kyrgyzstan
|
||||
|
||||
**Legal Basis:**
|
||||
- Federal Law No. 63-FZ "On Electronic Signature" (2011)
|
||||
- FSTEC (Federal Service for Technical and Export Control) regulations
|
||||
- GOST standards published by Rosstandart
|
||||
|
||||
---
|
||||
|
||||
### GOST Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **GOST R 34.10-2012** | Digital Signature Algorithm | Elliptic curve digital signatures (256-bit and 512-bit) |
|
||||
| **GOST R 34.11-2012** (Streebog) | Hash Function | Cryptographic hash (256-bit and 512-bit) |
|
||||
| **GOST R 34.12-2015** (Kuznyechik) | Block Cipher | Symmetric encryption (256-bit key) |
|
||||
| **GOST R 34.12-2015** (Magma) | Block Cipher | Legacy symmetric encryption (256-bit key, formerly GOST 28147-89) |
|
||||
| **GOST R 34.13-2015** | Cipher Modes | Modes of operation for block ciphers |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-russia` distribution includes three GOST providers:
|
||||
|
||||
#### 1. CryptoPro CSP (Recommended for Production)
|
||||
|
||||
**Provider:** Commercial CSP from CryptoPro
|
||||
**Certification:** FSTEC-certified
|
||||
**License:** Commercial (required for production use)
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install CryptoPro CSP (requires license)
|
||||
sudo ./install.sh
|
||||
|
||||
# Verify installation
|
||||
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: true
|
||||
ContainerName: "StellaOps-GOST-2024"
|
||||
ProviderType: 80 # PROV_GOST_2012_256
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
stella crypto sign \
|
||||
--provider gost \
|
||||
--algorithm GOST12-256 \
|
||||
--key-id gost-prod-key \
|
||||
--file document.pdf \
|
||||
--output document.pdf.sig
|
||||
```
|
||||
|
||||
#### 2. OpenSSL-GOST (Open Source, Non-certified)
|
||||
|
||||
**Provider:** OpenSSL with GOST engine
|
||||
**Certification:** Not FSTEC-certified (development/testing only)
|
||||
**License:** Open source
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install OpenSSL with GOST engine
|
||||
sudo apt install openssl gost-engine
|
||||
|
||||
# Verify installation
|
||||
openssl engine gost
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
OpenSslGost:
|
||||
Enabled: true
|
||||
EnginePath: "/usr/lib/x86_64-linux-gnu/engines-1.1/gost.so"
|
||||
```
|
||||
|
||||
#### 3. PKCS#11 (HSM Support)
|
||||
|
||||
**Provider:** PKCS#11 interface to hardware security modules
|
||||
**Certification:** Depends on HSM (e.g., Rutoken, JaCarta)
|
||||
**License:** Depends on HSM vendor
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
Pkcs11:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/librtpkcs11ecp.so"
|
||||
SlotId: 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | GOST Standard | Key Size | Recommended |
|
||||
|-----------|-------------|---------------|----------|-------------|
|
||||
| `GOST12-256` | GOST R 34.10-2012 (256-bit) | GOST R 34.10-2012 | 256-bit | ✅ Yes |
|
||||
| `GOST12-512` | GOST R 34.10-2012 (512-bit) | GOST R 34.10-2012 | 512-bit | ✅ Yes |
|
||||
| `GOST2001` | GOST R 34.10-2001 (legacy) | GOST R 34.10-2001 | 256-bit | ⚠️ Legacy |
|
||||
|
||||
**Recommendation:** Use `GOST12-256` or `GOST12-512` for new implementations. `GOST2001` is supported for backward compatibility only.
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.gost.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.ru"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "gost"
|
||||
|
||||
Profiles:
|
||||
- name: "gost-prod-signing"
|
||||
provider: "gost"
|
||||
algorithm: "GOST12-256"
|
||||
keyId: "gost-prod-key-2024"
|
||||
|
||||
- name: "gost-qualified-signature"
|
||||
provider: "gost"
|
||||
algorithm: "GOST12-512"
|
||||
keyId: "gost-qes-key"
|
||||
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: true
|
||||
ContainerName: "StellaOps-GOST"
|
||||
ProviderType: 80
|
||||
|
||||
Keys:
|
||||
- KeyId: "gost-prod-key-2024"
|
||||
Algorithm: "GOST12-256"
|
||||
Source: "csp"
|
||||
FriendlyName: "Production GOST Signing Key 2024"
|
||||
|
||||
- KeyId: "gost-qes-key"
|
||||
Algorithm: "GOST12-512"
|
||||
Source: "csp"
|
||||
FriendlyName: "Qualified Electronic Signature Key"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test Vectors (FSTEC Compliance)
|
||||
|
||||
Verify your GOST implementation with official test vectors:
|
||||
|
||||
```bash
|
||||
# Test vector from GOST R 34.11-2012 (Streebog hash)
|
||||
echo -n "012345678901234567890123456789012345678901234567890123456789012" | \
|
||||
openssl dgst -engine gost -streebog256
|
||||
|
||||
# Expected output:
|
||||
# 9d151eefd8590b89daa6ba6cb74af9275dd051026bb149a452fd84e5e57b5500
|
||||
```
|
||||
|
||||
**Official Test Vectors:**
|
||||
- GOST R 34.10-2012: [TC26 GitHub](https://github.com/tc26/gost-crypto/blob/master/test_vectors/)
|
||||
- GOST R 34.11-2012: [RFC 6986 Appendix A](https://datatracker.ietf.org/doc/html/rfc6986#appendix-A)
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
- [ ] Use FSTEC-certified cryptographic provider (CryptoPro CSP or certified HSM)
|
||||
- [ ] Use GOST R 34.10-2012 (not legacy GOST 2001) for new signatures
|
||||
- [ ] Use GOST R 34.11-2012 (Streebog) for hashing
|
||||
- [ ] Store private keys in certified HSM for qualified signatures
|
||||
- [ ] Maintain key management records per FSTEC requirements
|
||||
- [ ] Obtain certificate from accredited Russian CA for qualified signatures
|
||||
- [ ] Verify signatures against FSTEC test vectors
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Export Control:**
|
||||
- GOST implementations are subject to Russian export control laws
|
||||
- Distribution outside Russia/CIS may require special permissions
|
||||
- StellaOps `stella-russia` distribution is authorized for Russia/CIS only
|
||||
|
||||
**Qualified Electronic Signatures:**
|
||||
- Qualified signatures require accredited CA certificate
|
||||
- Accredited CAs: [Ministry of Digital Development list](https://digital.gov.ru/en/)
|
||||
- Private keys must be stored in FSTEC-certified HSM
|
||||
|
||||
---
|
||||
|
||||
## eIDAS (European Union)
|
||||
|
||||
### Overview
|
||||
|
||||
**eIDAS** (electronic IDentification, Authentication and trust Services) is the EU regulation (No 910/2014) governing electronic signatures, seals, and trust services across EU member states.
|
||||
|
||||
**Applicable Jurisdictions:** All 27 EU member states + EEA (Norway, Iceland, Liechtenstein)
|
||||
|
||||
**Legal Basis:**
|
||||
- Regulation (EU) No 910/2014 (eIDAS Regulation)
|
||||
- ETSI standards for implementation
|
||||
- National laws implementing eIDAS
|
||||
|
||||
---
|
||||
|
||||
### Signature Levels
|
||||
|
||||
| Level | Name | Description | Recommended Use |
|
||||
|-------|------|-------------|-----------------|
|
||||
| **QES** | Qualified Electronic Signature | Equivalent to handwritten signature | Contracts, legal documents |
|
||||
| **AES** | Advanced Electronic Signature | High assurance, not qualified | Internal approvals, workflows |
|
||||
| **AdES** | Advanced Electronic Signature | Basic electronic signature | General document signing |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-eu` distribution includes eIDAS-compliant providers:
|
||||
|
||||
#### 1. TSP Client (Remote Qualified Signature)
|
||||
|
||||
**Provider:** Trust Service Provider remote signing client
|
||||
**Certification:** Depends on TSP (must be EU-qualified)
|
||||
**License:** Subscription-based (per TSP)
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: true
|
||||
TspUrl: "https://tsp.example.eu/api/v1/sign"
|
||||
ApiKey: "${EIDAS_TSP_API_KEY}"
|
||||
CertificateId: "qes-cert-2024"
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Sign with QES (Qualified Electronic Signature)
|
||||
stella crypto sign \
|
||||
--provider eidas \
|
||||
--algorithm ECDSA-P256-QES \
|
||||
--key-id qes-cert-2024 \
|
||||
--file contract.pdf \
|
||||
--output contract.pdf.sig
|
||||
```
|
||||
|
||||
#### 2. Local Signer (Advanced Signature)
|
||||
|
||||
**Provider:** Local signing with software keys
|
||||
**Certification:** Not qualified (AES/AdES only)
|
||||
**License:** Open source
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
LocalSigner:
|
||||
Enabled: true
|
||||
KeyStorePath: "/etc/stellaops/eidas-keys"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **ETSI EN 319 412** | Certificate Profiles | Requirements for certificates (QES, AES) |
|
||||
| **ETSI EN 319 102** | Signature Policies | Signature policy requirements |
|
||||
| **ETSI EN 319 142** | PAdES (PDF Signatures) | PDF Advanced Electronic Signatures |
|
||||
| **ETSI TS 119 432** | Remote Signing | Remote signature creation protocols |
|
||||
| **ETSI EN 319 401** | Trust Service Providers | TSP requirements and policies |
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | Signature Level | Recommended |
|
||||
|-----------|-------------|-----------------|-------------|
|
||||
| `ECDSA-P256-QES` | ECDSA with P-256 curve (QES) | QES | ✅ Yes |
|
||||
| `ECDSA-P384-QES` | ECDSA with P-384 curve (QES) | QES | ✅ Yes |
|
||||
| `RSA-2048-QES` | RSA 2048-bit (QES) | QES | ⚠️ Use ECDSA |
|
||||
| `ECDSA-P256-AES` | ECDSA with P-256 curve (AES) | AES | ✅ Yes |
|
||||
|
||||
**Recommendation:** Use ECDSA P-256 or P-384 for new implementations. RSA is supported but ECDSA is preferred.
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.eidas.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.eu"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "eidas"
|
||||
|
||||
Profiles:
|
||||
- name: "eidas-qes"
|
||||
provider: "eidas"
|
||||
algorithm: "ECDSA-P256-QES"
|
||||
keyId: "qes-cert-2024"
|
||||
|
||||
- name: "eidas-aes"
|
||||
provider: "eidas"
|
||||
algorithm: "ECDSA-P256-AES"
|
||||
keyId: "aes-cert-2024"
|
||||
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: true
|
||||
TspUrl: "https://tsp.example.eu/api/v1/sign"
|
||||
ApiKey: "${EIDAS_TSP_API_KEY}"
|
||||
|
||||
# Qualified Trust Service Provider
|
||||
TspProfile:
|
||||
Name: "Example Trust Services Provider"
|
||||
QualifiedStatus: true
|
||||
Country: "DE"
|
||||
TrustedListUrl: "https://tsp.example.eu/tsl.xml"
|
||||
|
||||
Keys:
|
||||
- KeyId: "qes-cert-2024"
|
||||
Algorithm: "ECDSA-P256-QES"
|
||||
Source: "tsp"
|
||||
SignatureLevel: "QES"
|
||||
FriendlyName: "Qualified Electronic Signature 2024"
|
||||
|
||||
- KeyId: "aes-cert-2024"
|
||||
Algorithm: "ECDSA-P256-AES"
|
||||
Source: "local"
|
||||
SignatureLevel: "AES"
|
||||
FriendlyName: "Advanced Electronic Signature 2024"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### EU Trusted List Validation
|
||||
|
||||
Verify TSP is on the EU Trusted List:
|
||||
|
||||
```bash
|
||||
# Download EU Trusted List
|
||||
wget https://ec.europa.eu/tools/lotl/eu-lotl.xml
|
||||
|
||||
# Validate TSP certificate against trusted list
|
||||
stella crypto verify-tsp \
|
||||
--tsp-cert tsp-certificate.pem \
|
||||
--trusted-list eu-lotl.xml
|
||||
```
|
||||
|
||||
**Official EU Trusted List:**
|
||||
- https://ec.europa.eu/digital-building-blocks/wikis/display/DIGITAL/EU+Trusted+Lists
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
#### For QES (Qualified Electronic Signature):
|
||||
|
||||
- [ ] Use EU-qualified Trust Service Provider (on EU Trusted List)
|
||||
- [ ] Verify TSP certificate is qualified according to ETSI EN 319 412-2
|
||||
- [ ] Use signature policy compliant with ETSI EN 319 102-1
|
||||
- [ ] Include qualified certificate in signature
|
||||
- [ ] Use qualified signature creation device (QSCD) for key storage
|
||||
- [ ] Validate against EU Trusted List before accepting signatures
|
||||
- [ ] Maintain signature validation for 30+ years (long-term validation)
|
||||
|
||||
#### For AES (Advanced Electronic Signature):
|
||||
|
||||
- [ ] Uniquely linked to signatory
|
||||
- [ ] Capable of identifying signatory
|
||||
- [ ] Created using secure signature creation data
|
||||
- [ ] Linked to signed data to detect alterations
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Cross-border Recognition:**
|
||||
- QES has same legal effect as handwritten signature in all EU member states
|
||||
- AES/AdES may have varying legal recognition across member states
|
||||
|
||||
**Long-term Validation:**
|
||||
- QES must remain verifiable for decades
|
||||
- Use AdES with long-term validation (LTV) attributes
|
||||
- Timestamp signatures to prove time of signing
|
||||
|
||||
**Data Protection (GDPR):**
|
||||
- eIDAS signatures may contain personal data
|
||||
- Comply with GDPR when processing signature certificates
|
||||
- Obtain consent for processing qualified certificate data
|
||||
|
||||
---
|
||||
|
||||
## SM (China)
|
||||
|
||||
### Overview
|
||||
|
||||
**SM** (ShāngMì, 商密, Commercial Cipher) refers to China's national cryptographic algorithms mandated by OSCCA (Office of State Commercial Cryptography Administration).
|
||||
|
||||
**Applicable Jurisdiction:** People's Republic of China
|
||||
|
||||
**Legal Basis:**
|
||||
- Cryptography Law of PRC (2020)
|
||||
- GM/T standards published by OSCCA
|
||||
- MLPS 2.0 (Multi-Level Protection Scheme 2.0)
|
||||
|
||||
---
|
||||
|
||||
### SM Standards
|
||||
|
||||
| Standard | Name | Purpose |
|
||||
|----------|------|---------|
|
||||
| **GM/T 0003-2012** (SM2) | Public Key Cryptographic Algorithm | Elliptic curve signatures and encryption (256-bit) |
|
||||
| **GM/T 0004-2012** (SM3) | Cryptographic Hash Algorithm | Hash function (256-bit output) |
|
||||
| **GM/T 0002-2012** (SM4) | Block Cipher Algorithm | Symmetric encryption (128-bit key) |
|
||||
| **GM/T 0009-2012** (SM9) | Identity-Based Cryptography | Identity-based encryption and signatures |
|
||||
|
||||
---
|
||||
|
||||
### Crypto Providers
|
||||
|
||||
The `stella-china` distribution includes SM providers:
|
||||
|
||||
#### 1. GmSSL (Open Source)
|
||||
|
||||
**Provider:** GmSSL library
|
||||
**Certification:** Not OSCCA-certified (development/testing only)
|
||||
**License:** Apache 2.0
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
# Install GmSSL
|
||||
sudo apt install gmssl
|
||||
|
||||
# Verify installation
|
||||
gmssl version
|
||||
```
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Sm:
|
||||
GmSsl:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/libgmssl.so"
|
||||
```
|
||||
|
||||
#### 2. Commercial CSP (OSCCA-certified)
|
||||
|
||||
**Provider:** OSCCA-certified commercial CSP
|
||||
**Certification:** OSCCA-certified (required for production)
|
||||
**License:** Commercial (vendor-specific)
|
||||
|
||||
**Configuration:**
|
||||
```yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Sm:
|
||||
CommercialCsp:
|
||||
Enabled: true
|
||||
VendorId: "vendor-name"
|
||||
DeviceId: "device-serial"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Algorithms
|
||||
|
||||
| Algorithm | Description | GM Standard | Key Size | Recommended |
|
||||
|-----------|-------------|-------------|----------|-------------|
|
||||
| `SM2` | Elliptic curve signature and encryption | GM/T 0003-2012 | 256-bit | ✅ Yes |
|
||||
| `SM3` | Cryptographic hash | GM/T 0004-2012 | 256-bit output | ✅ Yes |
|
||||
| `SM4` | Block cipher | GM/T 0002-2012 | 128-bit key | ✅ Yes |
|
||||
| `SM9` | Identity-based crypto | GM/T 0009-2012 | 256-bit | ⚠️ Specialized |
|
||||
|
||||
---
|
||||
|
||||
### Configuration Example
|
||||
|
||||
```yaml
|
||||
# appsettings.sm.yaml
|
||||
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.cn"
|
||||
|
||||
Crypto:
|
||||
DefaultProvider: "sm"
|
||||
|
||||
Profiles:
|
||||
- name: "sm-prod-signing"
|
||||
provider: "sm"
|
||||
algorithm: "SM2"
|
||||
keyId: "sm-prod-key-2024"
|
||||
|
||||
Providers:
|
||||
Sm:
|
||||
GmSsl:
|
||||
Enabled: true
|
||||
LibraryPath: "/usr/lib/libgmssl.so"
|
||||
|
||||
Keys:
|
||||
- KeyId: "sm-prod-key-2024"
|
||||
Algorithm: "SM2"
|
||||
Source: "file"
|
||||
FilePath: "/etc/stellaops/keys/sm-key.pem"
|
||||
FriendlyName: "Production SM2 Signing Key 2024"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Usage Example
|
||||
|
||||
```bash
|
||||
# Sign with SM2
|
||||
stella crypto sign \
|
||||
--provider sm \
|
||||
--algorithm SM2 \
|
||||
--key-id sm-prod-key-2024 \
|
||||
--file document.pdf \
|
||||
--output document.pdf.sig
|
||||
|
||||
# Verify SM2 signature
|
||||
stella crypto verify \
|
||||
--provider sm \
|
||||
--algorithm SM2 \
|
||||
--key-id sm-prod-key-2024 \
|
||||
--file document.pdf \
|
||||
--signature document.pdf.sig
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Test Vectors (OSCCA Compliance)
|
||||
|
||||
Verify your SM implementation with official test vectors:
|
||||
|
||||
```bash
|
||||
# Test vector from GM/T 0004-2012 (SM3 hash)
|
||||
echo -n "abc" | gmssl sm3
|
||||
|
||||
# Expected output:
|
||||
# 66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0
|
||||
```
|
||||
|
||||
**Official Test Vectors:**
|
||||
- SM2: [GM/T 0003-2012 Appendix A](http://www.gmbz.org.cn/main/viewfile/20180108023812835219.html)
|
||||
- SM3: [GM/T 0004-2012 Appendix A](http://www.gmbz.org.cn/main/viewfile/20180108023528214322.html)
|
||||
|
||||
---
|
||||
|
||||
### Compliance Checklist
|
||||
|
||||
- [ ] Use OSCCA-certified cryptographic product for production
|
||||
- [ ] Use SM2 for digital signatures (not RSA/ECDSA)
|
||||
- [ ] Use SM3 for hashing (not SHA-256)
|
||||
- [ ] Use SM4 for symmetric encryption (not AES)
|
||||
- [ ] Obtain commercial cipher product model certificate
|
||||
- [ ] Register commercial cipher use with local authorities (MLPS 2.0)
|
||||
- [ ] Store keys in OSCCA-certified hardware for sensitive applications
|
||||
|
||||
---
|
||||
|
||||
### Legal Considerations
|
||||
|
||||
**Export Control:**
|
||||
- SM implementations are subject to Chinese export control laws
|
||||
- Distribution outside China may require special permissions
|
||||
- StellaOps `stella-china` distribution is authorized for China only
|
||||
|
||||
**MLPS 2.0 Requirements:**
|
||||
- Level 2+: SM algorithms recommended
|
||||
- Level 3+: SM algorithms mandatory
|
||||
- Level 4+: SM algorithms + OSCCA-certified hardware mandatory
|
||||
|
||||
**Commercial Cipher Regulations:**
|
||||
- Commercial use requires OSCCA product certification
|
||||
- Open-source implementations (GmSSL) for development/testing only
|
||||
- Production systems must use OSCCA-certified CSPs
|
||||
|
||||
---
|
||||
|
||||
## Distribution Selection
|
||||
|
||||
| Your Location | Required Compliance | Distribution |
|
||||
|---------------|---------------------|--------------|
|
||||
| Russia, CIS | GOST R 34.10-2012 (government/regulated) | `stella-russia` |
|
||||
| EU Member State | eIDAS QES (legal documents) | `stella-eu` |
|
||||
| China | SM2/SM3/SM4 (MLPS 2.0 Level 3+) | `stella-china` |
|
||||
| Other | None (international standards) | `stella-international` |
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Crypto command usage
|
||||
- [Crypto Plugin Development](crypto-plugins.md) - Develop custom plugins
|
||||
- [Distribution Matrix](distribution-matrix.md) - Build and distribution guide
|
||||
- [Troubleshooting](troubleshooting.md) - Common compliance issues
|
||||
1017
docs/cli/crypto-plugins.md
Normal file
1017
docs/cli/crypto-plugins.md
Normal file
File diff suppressed because it is too large
Load Diff
694
docs/cli/distribution-matrix.md
Normal file
694
docs/cli/distribution-matrix.md
Normal file
@@ -0,0 +1,694 @@
|
||||
# stella CLI - Build and Distribution Matrix
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
StellaOps CLI is distributed in **four regional variants** to comply with export control regulations and cryptographic standards. Each distribution includes different cryptographic plugins based on regional requirements.
|
||||
|
||||
**Key Principles:**
|
||||
1. **Build-time Selection**: Crypto plugins are conditionally compiled based on build flags
|
||||
2. **Export Compliance**: Each distribution complies with export control laws
|
||||
3. **Deterministic Builds**: Same source + flags = same binary (reproducible builds)
|
||||
4. **Validation**: Automated validation ensures correct plugin inclusion
|
||||
|
||||
---
|
||||
|
||||
## Distribution Matrix
|
||||
|
||||
| Distribution | Crypto Plugins | Build Flag | Target Audience | Export Restrictions |
|
||||
|--------------|----------------|------------|-----------------|---------------------|
|
||||
| **stella-international** | Default (.NET, BouncyCastle) | None | Global (unrestricted) | ✅ No restrictions |
|
||||
| **stella-russia** | Default + GOST | `StellaOpsEnableGOST=true` | Russia, CIS states | ⚠️ Russia/CIS only |
|
||||
| **stella-eu** | Default + eIDAS | `StellaOpsEnableEIDAS=true` | European Union | ⚠️ EU/EEA only |
|
||||
| **stella-china** | Default + SM | `StellaOpsEnableSM=true` | China | ⚠️ China only |
|
||||
|
||||
---
|
||||
|
||||
## Crypto Provider Matrix
|
||||
|
||||
| Provider | International | Russia | EU | China |
|
||||
|----------|---------------|--------|-----|-------|
|
||||
| **.NET Crypto** (RSA, ECDSA, EdDSA) | ✅ | ✅ | ✅ | ✅ |
|
||||
| **BouncyCastle** (Extended algorithms) | ✅ | ✅ | ✅ | ✅ |
|
||||
| **GOST** (R 34.10-2012, R 34.11-2012) | ❌ | ✅ | ❌ | ❌ |
|
||||
| **eIDAS** (QES, AES, AdES) | ❌ | ❌ | ✅ | ❌ |
|
||||
| **SM** (SM2, SM3, SM4) | ❌ | ❌ | ❌ | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## Build Instructions
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- .NET 10 SDK
|
||||
- Git
|
||||
- Docker (for Linux builds on Windows/macOS)
|
||||
|
||||
### Build Environment Setup
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://git.stella-ops.org/stella-ops.org/git.stella-ops.org
|
||||
cd git.stella-ops.org
|
||||
|
||||
# Verify .NET SDK
|
||||
dotnet --version
|
||||
# Expected: 10.0.0 or later
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Building Regional Distributions
|
||||
|
||||
### 1. International Distribution (Default)
|
||||
|
||||
**Includes:** Default crypto providers only (no regional algorithms)
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
```
|
||||
|
||||
**Supported Platforms:**
|
||||
- `linux-x64` - Linux x86_64
|
||||
- `linux-arm64` - Linux ARM64
|
||||
- `osx-x64` - macOS Intel
|
||||
- `osx-arm64` - macOS Apple Silicon
|
||||
- `win-x64` - Windows x64
|
||||
|
||||
**Example (all platforms):**
|
||||
```bash
|
||||
# Linux x64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
|
||||
# Linux ARM64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-arm64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-arm64
|
||||
|
||||
# macOS Intel
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime osx-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-osx-x64
|
||||
|
||||
# macOS Apple Silicon
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime osx-arm64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-osx-arm64
|
||||
|
||||
# Windows x64
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime win-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-win-x64
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Russia Distribution (GOST)
|
||||
|
||||
**Includes:** Default + GOST crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output dist/stella-russia-linux-x64
|
||||
```
|
||||
|
||||
**Important:** The build flag `StellaOpsEnableGOST=true` conditionally includes GOST plugin projects, and `DefineConstants` enables `#if STELLAOPS_ENABLE_GOST` preprocessor directives.
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-russia.sh - Build all Russia distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-russia for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output "dist/stella-russia-$runtime"
|
||||
done
|
||||
|
||||
echo "All Russia distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. EU Distribution (eIDAS)
|
||||
|
||||
**Includes:** Default + eIDAS crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableEIDAS=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
|
||||
--output dist/stella-eu-linux-x64
|
||||
```
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-eu.sh - Build all EU distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-eu for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableEIDAS=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_EIDAS" \
|
||||
--output "dist/stella-eu-$runtime"
|
||||
done
|
||||
|
||||
echo "All EU distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. China Distribution (SM)
|
||||
|
||||
**Includes:** Default + SM crypto providers
|
||||
|
||||
**Build Command:**
|
||||
```bash
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableSM=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_SM" \
|
||||
--output dist/stella-china-linux-x64
|
||||
```
|
||||
|
||||
**Multi-platform Example:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-china.sh - Build all China distributions
|
||||
|
||||
set -e
|
||||
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
echo "Building stella-china for $runtime..."
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableSM=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_SM" \
|
||||
--output "dist/stella-china-$runtime"
|
||||
done
|
||||
|
||||
echo "All China distributions built successfully"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build All Distributions
|
||||
|
||||
**Automated build script:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# build-all.sh - Build all distributions for all platforms
|
||||
|
||||
set -e
|
||||
|
||||
DISTRIBUTIONS=("international" "russia" "eu" "china")
|
||||
RUNTIMES=("linux-x64" "linux-arm64" "osx-x64" "osx-arm64" "win-x64")
|
||||
|
||||
build_distribution() {
|
||||
local dist=$1
|
||||
local runtime=$2
|
||||
local flags=""
|
||||
|
||||
case $dist in
|
||||
"russia")
|
||||
flags="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
|
||||
;;
|
||||
"eu")
|
||||
flags="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
|
||||
;;
|
||||
"china")
|
||||
flags="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
|
||||
;;
|
||||
esac
|
||||
|
||||
echo "Building stella-$dist for $runtime..."
|
||||
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime "$runtime" \
|
||||
--self-contained true \
|
||||
$flags \
|
||||
--output "dist/stella-$dist-$runtime"
|
||||
|
||||
# Create tarball (except Windows)
|
||||
if [[ ! $runtime =~ ^win ]]; then
|
||||
tar -czf "dist/stella-$dist-$runtime.tar.gz" -C "dist/stella-$dist-$runtime" .
|
||||
echo "✅ Created dist/stella-$dist-$runtime.tar.gz"
|
||||
else
|
||||
# Create zip for Windows
|
||||
(cd "dist/stella-$dist-$runtime" && zip -r "../stella-$dist-$runtime.zip" .)
|
||||
echo "✅ Created dist/stella-$dist-$runtime.zip"
|
||||
fi
|
||||
}
|
||||
|
||||
for dist in "${DISTRIBUTIONS[@]}"; do
|
||||
for runtime in "${RUNTIMES[@]}"; do
|
||||
build_distribution "$dist" "$runtime"
|
||||
done
|
||||
done
|
||||
|
||||
echo ""
|
||||
echo "🎉 All distributions built successfully!"
|
||||
echo "See dist/ directory for artifacts"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Validation
|
||||
|
||||
### Automated Validation Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-distribution.sh - Validate distribution has correct plugins
|
||||
|
||||
set -e
|
||||
|
||||
DISTRIBUTION=$1 # international, russia, eu, china
|
||||
BINARY_PATH=$2
|
||||
|
||||
if [ -z "$DISTRIBUTION" ] || [ -z "$BINARY_PATH" ]; then
|
||||
echo "Usage: $0 <distribution> <binary-path>"
|
||||
echo "Example: $0 russia dist/stella-russia-linux-x64/stella"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Validating $DISTRIBUTION distribution: $BINARY_PATH"
|
||||
echo ""
|
||||
|
||||
# Function to check for symbol in binary
|
||||
has_symbol() {
|
||||
local symbol=$1
|
||||
if command -v objdump &> /dev/null; then
|
||||
objdump -p "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
elif command -v nm &> /dev/null; then
|
||||
nm "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
else
|
||||
# Fallback: check if binary contains string
|
||||
strings "$BINARY_PATH" 2>/dev/null | grep -q "$symbol"
|
||||
fi
|
||||
}
|
||||
|
||||
# Validation rules
|
||||
validate_international() {
|
||||
echo "Checking International distribution..."
|
||||
|
||||
# Should NOT contain regional plugins
|
||||
if has_symbol "GostCryptoProvider" || \
|
||||
has_symbol "EidasCryptoProvider" || \
|
||||
has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: International distribution contains restricted plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: International distribution valid (no restricted plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_russia() {
|
||||
echo "Checking Russia distribution..."
|
||||
|
||||
# Should contain GOST
|
||||
if ! has_symbol "GostCryptoProvider"; then
|
||||
echo "❌ FAIL: Russia distribution missing GOST plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain eIDAS or SM
|
||||
if has_symbol "EidasCryptoProvider" || has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: Russia distribution contains non-GOST regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: Russia distribution valid (GOST included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_eu() {
|
||||
echo "Checking EU distribution..."
|
||||
|
||||
# Should contain eIDAS
|
||||
if ! has_symbol "EidasCryptoProvider"; then
|
||||
echo "❌ FAIL: EU distribution missing eIDAS plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain GOST or SM
|
||||
if has_symbol "GostCryptoProvider" || has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: EU distribution contains non-eIDAS regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: EU distribution valid (eIDAS included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
validate_china() {
|
||||
echo "Checking China distribution..."
|
||||
|
||||
# Should contain SM
|
||||
if ! has_symbol "SmCryptoProvider"; then
|
||||
echo "❌ FAIL: China distribution missing SM plugin"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# Should NOT contain GOST or eIDAS
|
||||
if has_symbol "GostCryptoProvider" || has_symbol "EidasCryptoProvider"; then
|
||||
echo "❌ FAIL: China distribution contains non-SM regional plugins"
|
||||
return 1
|
||||
fi
|
||||
|
||||
echo "✅ PASS: China distribution valid (SM included, no other regional plugins)"
|
||||
return 0
|
||||
}
|
||||
|
||||
# Run validation
|
||||
case $DISTRIBUTION in
|
||||
"international")
|
||||
validate_international
|
||||
;;
|
||||
"russia")
|
||||
validate_russia
|
||||
;;
|
||||
"eu")
|
||||
validate_eu
|
||||
;;
|
||||
"china")
|
||||
validate_china
|
||||
;;
|
||||
*)
|
||||
echo "❌ ERROR: Unknown distribution '$DISTRIBUTION'"
|
||||
echo "Valid distributions: international, russia, eu, china"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
exit $?
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Validate Russia distribution
|
||||
./validate-distribution.sh russia dist/stella-russia-linux-x64/stella
|
||||
|
||||
# Output:
|
||||
# Validating russia distribution: dist/stella-russia-linux-x64/stella
|
||||
#
|
||||
# Checking Russia distribution...
|
||||
# ✅ PASS: Russia distribution valid (GOST included, no other regional plugins)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Runtime Validation
|
||||
|
||||
Verify correct plugins are available at runtime:
|
||||
|
||||
```bash
|
||||
# International distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
|
||||
# Russia distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - gost (GOST R 34.10-2012, GOST R 34.11-2012)
|
||||
|
||||
# EU distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - eidas (QES, AES, AdES)
|
||||
|
||||
# China distribution
|
||||
./stella crypto providers
|
||||
# Expected output:
|
||||
# Available Crypto Providers:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - sm (SM2, SM3, SM4)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Packaging
|
||||
|
||||
### Tarball Creation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# package.sh - Create distribution tarballs
|
||||
|
||||
DIST=$1 # stella-russia-linux-x64
|
||||
OUTPUT_DIR="dist"
|
||||
|
||||
cd "$OUTPUT_DIR/$DIST"
|
||||
|
||||
# Create tarball
|
||||
tar -czf "../$DIST.tar.gz" .
|
||||
|
||||
echo "✅ Created $OUTPUT_DIR/$DIST.tar.gz"
|
||||
```
|
||||
|
||||
### Checksums
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# checksums.sh - Generate checksums for all distributions
|
||||
|
||||
cd dist
|
||||
|
||||
for tarball in *.tar.gz *.zip; do
|
||||
if [ -f "$tarball" ]; then
|
||||
sha256sum "$tarball" >> checksums.txt
|
||||
fi
|
||||
done
|
||||
|
||||
echo "✅ Checksums written to dist/checksums.txt"
|
||||
cat dist/checksums.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions / Gitea Actions
|
||||
|
||||
```yaml
|
||||
name: Build and Release CLI
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'v*'
|
||||
|
||||
jobs:
|
||||
build-matrix:
|
||||
strategy:
|
||||
matrix:
|
||||
distribution: [international, russia, eu, china]
|
||||
runtime: [linux-x64, linux-arm64, osx-x64, osx-arm64, win-x64]
|
||||
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup .NET
|
||||
uses: actions/setup-dotnet@v4
|
||||
with:
|
||||
dotnet-version: '10.0.x'
|
||||
|
||||
- name: Build Distribution
|
||||
run: |
|
||||
FLAGS=""
|
||||
case "${{ matrix.distribution }}" in
|
||||
"russia")
|
||||
FLAGS="-p:StellaOpsEnableGOST=true -p:DefineConstants=STELLAOPS_ENABLE_GOST"
|
||||
;;
|
||||
"eu")
|
||||
FLAGS="-p:StellaOpsEnableEIDAS=true -p:DefineConstants=STELLAOPS_ENABLE_EIDAS"
|
||||
;;
|
||||
"china")
|
||||
FLAGS="-p:StellaOpsEnableSM=true -p:DefineConstants=STELLAOPS_ENABLE_SM"
|
||||
;;
|
||||
esac
|
||||
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime ${{ matrix.runtime }} \
|
||||
--self-contained true \
|
||||
$FLAGS \
|
||||
--output dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
|
||||
- name: Validate Distribution
|
||||
run: |
|
||||
chmod +x scripts/validate-distribution.sh
|
||||
./scripts/validate-distribution.sh \
|
||||
${{ matrix.distribution }} \
|
||||
dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}/stella
|
||||
|
||||
- name: Create Tarball
|
||||
if: ${{ !contains(matrix.runtime, 'win') }}
|
||||
run: |
|
||||
cd dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
tar -czf ../stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz .
|
||||
|
||||
- name: Upload Artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: stella-${{ matrix.distribution }}-${{ matrix.runtime }}
|
||||
path: dist/stella-${{ matrix.distribution }}-${{ matrix.runtime }}.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Deployment
|
||||
|
||||
### Release Structure
|
||||
|
||||
```
|
||||
releases/
|
||||
├── v2.1.0/
|
||||
│ ├── stella-international-linux-x64.tar.gz
|
||||
│ ├── stella-international-linux-arm64.tar.gz
|
||||
│ ├── stella-international-osx-x64.tar.gz
|
||||
│ ├── stella-international-osx-arm64.tar.gz
|
||||
│ ├── stella-international-win-x64.zip
|
||||
│ ├── stella-russia-linux-x64.tar.gz
|
||||
│ ├── stella-russia-linux-arm64.tar.gz
|
||||
│ ├── stella-russia-osx-x64.tar.gz
|
||||
│ ├── stella-russia-osx-arm64.tar.gz
|
||||
│ ├── stella-russia-win-x64.zip
|
||||
│ ├── stella-eu-linux-x64.tar.gz
|
||||
│ ├── stella-eu-linux-arm64.tar.gz
|
||||
│ ├── stella-eu-osx-x64.tar.gz
|
||||
│ ├── stella-eu-osx-arm64.tar.gz
|
||||
│ ├── stella-eu-win-x64.zip
|
||||
│ ├── stella-china-linux-x64.tar.gz
|
||||
│ ├── stella-china-linux-arm64.tar.gz
|
||||
│ ├── stella-china-osx-x64.tar.gz
|
||||
│ ├── stella-china-osx-arm64.tar.gz
|
||||
│ ├── stella-china-win-x64.zip
|
||||
│ ├── checksums.txt
|
||||
│ └── RELEASE_NOTES.md
|
||||
└── latest -> v2.1.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Download Links
|
||||
|
||||
**Public Release Server:**
|
||||
```
|
||||
https://releases.stella-ops.org/cli/
|
||||
├── latest/
|
||||
│ ├── stella-international-linux-x64.tar.gz
|
||||
│ ├── stella-russia-linux-x64.tar.gz
|
||||
│ ├── stella-eu-linux-x64.tar.gz
|
||||
│ └── stella-china-linux-x64.tar.gz
|
||||
├── v2.1.0/
|
||||
├── v2.0.0/
|
||||
└── checksums.txt
|
||||
```
|
||||
|
||||
**User Installation:**
|
||||
```bash
|
||||
# International (unrestricted)
|
||||
wget https://releases.stella-ops.org/cli/latest/stella-international-linux-x64.tar.gz
|
||||
|
||||
# Russia (GOST)
|
||||
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
|
||||
|
||||
# EU (eIDAS)
|
||||
wget https://releases.stella-ops.org/cli/eu/latest/stella-eu-linux-x64.tar.gz
|
||||
|
||||
# China (SM)
|
||||
wget https://releases.stella-ops.org/cli/china/latest/stella-china-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Legal & Export Control
|
||||
|
||||
### Export Control Statement
|
||||
|
||||
> StellaOps CLI regional distributions contain cryptographic software subject to export control laws.
|
||||
>
|
||||
> - **stella-international**: No export restrictions (standard commercial crypto)
|
||||
> - **stella-russia**: Authorized for Russia and CIS states only
|
||||
> - **stella-eu**: Authorized for EU/EEA member states only
|
||||
> - **stella-china**: Authorized for China only
|
||||
>
|
||||
> Unauthorized export, re-export, or transfer may violate applicable laws. Users are responsible for compliance with export control regulations in their jurisdiction.
|
||||
|
||||
### License Compliance
|
||||
|
||||
All distributions are licensed under **AGPL-3.0-or-later**, with regional plugins subject to additional vendor licenses (e.g., CryptoPro CSP requires commercial license).
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Command usage
|
||||
- [Compliance Guide](compliance-guide.md) - Regional compliance requirements
|
||||
- [Crypto Plugins](crypto-plugins.md) - Plugin development
|
||||
- [Troubleshooting](troubleshooting.md) - Build and validation issues
|
||||
820
docs/cli/troubleshooting.md
Normal file
820
docs/cli/troubleshooting.md
Normal file
@@ -0,0 +1,820 @@
|
||||
# stella CLI - Troubleshooting Guide
|
||||
|
||||
**Sprint:** SPRINT_4100_0006_0006 - CLI Documentation Overhaul
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers common issues encountered when using the `stella` CLI and their solutions. Issues are categorized by functional area for easy navigation.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Authentication Issues](#authentication-issues)
|
||||
2. [Crypto Plugin Issues](#crypto-plugin-issues)
|
||||
3. [Build Issues](#build-issues)
|
||||
4. [Scanning Issues](#scanning-issues)
|
||||
5. [Configuration Issues](#configuration-issues)
|
||||
6. [Network Issues](#network-issues)
|
||||
7. [Permission Issues](#permission-issues)
|
||||
8. [Distribution Validation Issues](#distribution-validation-issues)
|
||||
|
||||
---
|
||||
|
||||
## Authentication Issues
|
||||
|
||||
### Problem: `stella auth login` fails with "Authority unreachable"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella auth login
|
||||
❌ Error: Failed to connect to Authority
|
||||
Authority URL: https://auth.stellaops.example.com
|
||||
Error: Connection refused
|
||||
```
|
||||
|
||||
**Possible Causes:**
|
||||
1. Authority service is down
|
||||
2. Network connectivity issues
|
||||
3. Incorrect Authority URL in configuration
|
||||
4. Firewall blocking connection
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify Authority URL**
|
||||
```bash
|
||||
# Check current Authority URL
|
||||
stella config get Backend.BaseUrl
|
||||
|
||||
# If incorrect, set correct URL
|
||||
stella config set Backend.BaseUrl https://api.stellaops.example.com
|
||||
|
||||
# Or set via environment variable
|
||||
export STELLAOPS_BACKEND_URL="https://api.stellaops.example.com"
|
||||
```
|
||||
|
||||
**Solution 2: Test network connectivity**
|
||||
```bash
|
||||
# Test if Authority is reachable
|
||||
curl -v https://auth.stellaops.example.com/health
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup auth.stellaops.example.com
|
||||
```
|
||||
|
||||
**Solution 3: Enable offline cache fallback**
|
||||
```bash
|
||||
# Allow offline cache fallback (uses cached tokens)
|
||||
export STELLAOPS_AUTHORITY_ALLOW_OFFLINE_CACHE_FALLBACK=true
|
||||
export STELLAOPS_AUTHORITY_OFFLINE_CACHE_TOLERANCE=00:30:00
|
||||
|
||||
stella auth login
|
||||
```
|
||||
|
||||
**Solution 4: Use API key authentication (bypass Authority)**
|
||||
```bash
|
||||
# Use API key instead of interactive login
|
||||
export STELLAOPS_API_KEY="sk_live_your_api_key"
|
||||
|
||||
stella auth whoami
|
||||
# Output: Authenticated via API key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: `stella auth whoami` shows "Token expired"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella auth whoami
|
||||
❌ Error: Token expired
|
||||
Expiration: 2025-12-22T10:00:00Z
|
||||
Please re-authenticate with 'stella auth login'
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Re-authenticate
|
||||
stella auth login
|
||||
|
||||
# Or refresh token (if supported by Authority)
|
||||
stella auth refresh
|
||||
|
||||
# Verify authentication
|
||||
stella auth whoami
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: HTTP 403 "Insufficient scopes" when running admin commands
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella admin policy export
|
||||
❌ HTTP 403: Forbidden
|
||||
Error: Insufficient scopes. Required: admin.policy
|
||||
Your scopes: scan.read, scan.write
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Re-authenticate to obtain admin scopes
|
||||
stella auth logout
|
||||
stella auth login
|
||||
|
||||
# Verify you have admin scopes
|
||||
stella auth whoami
|
||||
# Output should include: admin.policy, admin.users, admin.feeds, admin.platform
|
||||
|
||||
# If still missing scopes, contact your platform administrator
|
||||
# to grant admin role to your account
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crypto Plugin Issues
|
||||
|
||||
### Problem: `stella crypto sign --provider gost` fails with "Provider 'gost' not available"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --file document.pdf
|
||||
❌ Error: Crypto provider 'gost' not available
|
||||
Available providers: default
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
You are using the **International distribution** which does not include GOST plugin.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check which distribution you have
|
||||
stella --version
|
||||
# Output: stella CLI version 2.1.0
|
||||
# Distribution: stella-international <-- Problem!
|
||||
|
||||
# Download correct distribution for Russia/CIS
|
||||
wget https://releases.stella-ops.org/cli/russia/latest/stella-russia-linux-x64.tar.gz
|
||||
tar -xzf stella-russia-linux-x64.tar.gz
|
||||
sudo cp stella /usr/local/bin/
|
||||
|
||||
# Verify GOST provider is available
|
||||
stella crypto providers
|
||||
# Output:
|
||||
# - default (.NET Crypto, BouncyCastle)
|
||||
# - gost (GOST R 34.10-2012) <-- Now available
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: GOST signing fails with "CryptoPro CSP not initialized"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --algorithm GOST12-256 --file document.pdf
|
||||
❌ Error: CryptoPro CSP not initialized
|
||||
Container: StellaOps-GOST-2024 not found
|
||||
```
|
||||
|
||||
**Causes:**
|
||||
1. CryptoPro CSP not installed
|
||||
2. Container not created
|
||||
3. Invalid provider configuration
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify CryptoPro CSP installation**
|
||||
```bash
|
||||
# Check if CryptoPro CSP is installed
|
||||
/opt/cprocsp/bin/amd64/csptestf -absorb -alg GR3411_2012_256
|
||||
|
||||
# If not installed, install CryptoPro CSP
|
||||
sudo ./install.sh # From CryptoPro CSP distribution
|
||||
```
|
||||
|
||||
**Solution 2: Create GOST container**
|
||||
```bash
|
||||
# Create new container
|
||||
/opt/cprocsp/bin/amd64/csptest -keyset -newkeyset -container "StellaOps-GOST-2024"
|
||||
|
||||
# List containers
|
||||
/opt/cprocsp/bin/amd64/csptest -keyset -enum_cont -verifycontext
|
||||
|
||||
# Update configuration to use correct container name
|
||||
stella config set Crypto.Providers.Gost.CryptoProCsp.ContainerName "StellaOps-GOST-2024"
|
||||
```
|
||||
|
||||
**Solution 3: Use OpenSSL-GOST instead (development only)**
|
||||
```yaml
|
||||
# appsettings.yaml
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Gost:
|
||||
CryptoProCsp:
|
||||
Enabled: false # Disable CryptoPro CSP
|
||||
OpenSslGost:
|
||||
Enabled: true # Use OpenSSL-GOST
|
||||
```
|
||||
|
||||
**Warning:** OpenSSL-GOST is NOT FSTEC-certified and should only be used for development/testing.
|
||||
|
||||
---
|
||||
|
||||
### Problem: eIDAS signing fails with "TSP unreachable"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider eidas --algorithm ECDSA-P256-QES --file contract.pdf
|
||||
❌ Error: Trust Service Provider unreachable
|
||||
TSP URL: https://tsp.example.eu/api/v1/sign
|
||||
HTTP Error: Connection refused
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Verify TSP URL**
|
||||
```bash
|
||||
# Test TSP connectivity
|
||||
curl -v https://tsp.example.eu/api/v1/sign
|
||||
|
||||
# Update TSP URL if incorrect
|
||||
stella config set Crypto.Providers.Eidas.TspClient.TspUrl "https://correct-tsp.eu/api/v1/sign"
|
||||
```
|
||||
|
||||
**Solution 2: Check API key**
|
||||
```bash
|
||||
# Verify API key is set
|
||||
echo $EIDAS_TSP_API_KEY
|
||||
|
||||
# If not set, export it
|
||||
export EIDAS_TSP_API_KEY="your_api_key_here"
|
||||
|
||||
# Or set in configuration
|
||||
stella config set Crypto.Providers.Eidas.TspClient.ApiKey "your_api_key_here"
|
||||
```
|
||||
|
||||
**Solution 3: Use local signer for AES (not QES)**
|
||||
```yaml
|
||||
# For Advanced Electronic Signatures (not qualified)
|
||||
StellaOps:
|
||||
Crypto:
|
||||
Providers:
|
||||
Eidas:
|
||||
TspClient:
|
||||
Enabled: false
|
||||
LocalSigner:
|
||||
Enabled: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Build Issues
|
||||
|
||||
### Problem: Build fails with "DefineConstants 'STELLAOPS_ENABLE_GOST' not defined"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ dotnet build -p:StellaOpsEnableGOST=true
|
||||
error CS0103: The name 'STELLAOPS_ENABLE_GOST' does not exist in the current context
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Missing `-p:DefineConstants` flag.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Correct build command (includes both flags)
|
||||
dotnet build \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
|
||||
# Or for publish:
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Build succeeds but crypto plugin not available at runtime
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
# Build appears successful
|
||||
$ dotnet build -p:StellaOpsEnableGOST=true -p:DefineConstants="STELLAOPS_ENABLE_GOST"
|
||||
Build succeeded.
|
||||
|
||||
# But plugin not available
|
||||
$ ./stella crypto providers
|
||||
Available providers:
|
||||
- default
|
||||
|
||||
# GOST plugin missing!
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Plugin DLL not copied to output directory.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use dotnet publish instead of dotnet build
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
-p:StellaOpsEnableGOST=true \
|
||||
-p:DefineConstants="STELLAOPS_ENABLE_GOST" \
|
||||
--output dist/stella-russia-linux-x64
|
||||
|
||||
# Verify GOST plugin DLL is present
|
||||
ls dist/stella-russia-linux-x64/*.dll | grep Gost
|
||||
# Expected: StellaOps.Cli.Crypto.Gost.dll
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "GLIBC version not found" when running CLI on older Linux
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ ./stella --version
|
||||
./stella: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./stella)
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
CLI built with newer .NET runtime requiring newer GLIBC.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Check your GLIBC version
|
||||
ldd --version
|
||||
# If < 2.34, upgrade to a newer Linux distribution
|
||||
|
||||
# Or build with older .NET runtime (if possible)
|
||||
# Or use containerized version:
|
||||
docker run -it stellaops/cli:latest stella --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scanning Issues
|
||||
|
||||
### Problem: `stella scan` fails with "Image not found"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: Image not found
|
||||
Image: docker://nginx:latest
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Pull image first**
|
||||
```bash
|
||||
# Pull image from Docker registry
|
||||
docker pull nginx:latest
|
||||
|
||||
# Then scan
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
**Solution 2: Scan local tar archive**
|
||||
```bash
|
||||
# Export image to tar
|
||||
docker save nginx:latest -o nginx.tar
|
||||
|
||||
# Scan tar archive
|
||||
stella scan tar://nginx.tar
|
||||
```
|
||||
|
||||
**Solution 3: Specify registry explicitly**
|
||||
```bash
|
||||
# Use fully-qualified image reference
|
||||
stella scan docker://docker.io/library/nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Scan succeeds but no vulnerabilities found (expected some)
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://vulnerable-app:latest
|
||||
Scan complete: 0 vulnerabilities found
|
||||
```
|
||||
|
||||
**Possible Causes:**
|
||||
1. Advisory feeds not synchronized
|
||||
2. Offline mode with stale data
|
||||
3. VEX mode filtering vulnerabilities
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Refresh advisory feeds (admin)**
|
||||
```bash
|
||||
stella admin feeds refresh --source nvd --force
|
||||
stella admin feeds refresh --source osv --force
|
||||
```
|
||||
|
||||
**Solution 2: Check feed status**
|
||||
```bash
|
||||
stella admin feeds status
|
||||
# Output:
|
||||
# Feed Last Sync Status
|
||||
# ────────────────────────────────────────
|
||||
# NVD 2025-12-23 10:00 ✅ UP
|
||||
# OSV 2025-12-23 09:45 ⚠️ STALE (12 hours old)
|
||||
```
|
||||
|
||||
**Solution 3: Disable VEX filtering**
|
||||
```bash
|
||||
# Scan with VEX mode disabled
|
||||
stella scan docker://vulnerable-app:latest --vex-mode disabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration Issues
|
||||
|
||||
### Problem: "Configuration file not found"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella config show
|
||||
⚠️ Warning: No configuration file found
|
||||
Using default configuration
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Create user configuration directory
|
||||
mkdir -p ~/.stellaops
|
||||
|
||||
# Create configuration file
|
||||
cat > ~/.stellaops/config.yaml <<EOF
|
||||
StellaOps:
|
||||
Backend:
|
||||
BaseUrl: "https://api.stellaops.example.com"
|
||||
EOF
|
||||
|
||||
# Verify configuration is loaded
|
||||
stella config show
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Environment variables not overriding configuration
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ export STELLAOPS_BACKEND_URL="https://test.example.com"
|
||||
$ stella config get Backend.BaseUrl
|
||||
https://api.stellaops.example.com # Still shows old value!
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Incorrect environment variable format.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Correct environment variable format (double underscore for nested properties)
|
||||
export STELLAOPS_BACKEND__BASEURL="https://test.example.com"
|
||||
# ^^ Note: double underscore
|
||||
|
||||
# Verify
|
||||
stella config get Backend.BaseUrl
|
||||
# Output: https://test.example.com # Now correct
|
||||
```
|
||||
|
||||
**Environment Variable Format Rules:**
|
||||
- Prefix: `STELLAOPS_`
|
||||
- Nested properties: Double underscore `__`
|
||||
- Array index: Double underscore + index `__0`, `__1`, etc.
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Simple property
|
||||
export STELLAOPS_BACKEND__BASEURL="https://api.example.com"
|
||||
|
||||
# Nested property
|
||||
export STELLAOPS_CRYPTO__DEFAULTPROVIDER="gost"
|
||||
|
||||
# Array element
|
||||
export STELLAOPS_CRYPTO__PROVIDERS__GOST__KEYS__0__KEYID="key1"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Network Issues
|
||||
|
||||
### Problem: Timeouts when connecting to backend
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: Request timeout
|
||||
Backend: https://api.stellaops.example.com/api/v1/scan
|
||||
Timeout: 30s
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Increase timeout**
|
||||
```yaml
|
||||
# appsettings.yaml
|
||||
StellaOps:
|
||||
Backend:
|
||||
Http:
|
||||
TimeoutSeconds: 120 # Increase from 30 to 120
|
||||
```
|
||||
|
||||
**Solution 2: Check network latency**
|
||||
```bash
|
||||
# Ping backend
|
||||
ping api.stellaops.example.com
|
||||
|
||||
# Test HTTP latency
|
||||
time curl -v https://api.stellaops.example.com/health
|
||||
```
|
||||
|
||||
**Solution 3: Use proxy**
|
||||
```bash
|
||||
# Set HTTP proxy
|
||||
export HTTP_PROXY="http://proxy.example.com:8080"
|
||||
export HTTPS_PROXY="http://proxy.example.com:8080"
|
||||
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: SSL certificate verification fails
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella scan docker://nginx:latest
|
||||
❌ Error: SSL certificate verification failed
|
||||
Certificate: CN=api.stellaops.example.com
|
||||
Error: The SSL certificate is invalid
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Solution 1: Add CA certificate**
|
||||
```bash
|
||||
# Add custom CA certificate (Linux)
|
||||
sudo cp custom-ca.crt /usr/local/share/ca-certificates/
|
||||
sudo update-ca-certificates
|
||||
|
||||
# Add custom CA certificate (macOS)
|
||||
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain custom-ca.crt
|
||||
```
|
||||
|
||||
**Solution 2: Disable SSL verification (INSECURE - development only)**
|
||||
```bash
|
||||
# WARNING: This disables SSL verification. Use only for testing!
|
||||
export STELLAOPS_BACKEND__HTTP__DISABLESSLVERIFICATION=true
|
||||
|
||||
stella scan docker://nginx:latest
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Permission Issues
|
||||
|
||||
### Problem: "Permission denied" when running `stella`
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella --version
|
||||
bash: /usr/local/bin/stella: Permission denied
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Make binary executable
|
||||
chmod +x /usr/local/bin/stella
|
||||
|
||||
# Verify
|
||||
stella --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "Access denied" when accessing keys
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ stella crypto sign --provider gost --file doc.pdf
|
||||
❌ Error: Access denied to key file
|
||||
File: /etc/stellaops/keys/gost-key.pem
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Fix key file permissions
|
||||
sudo chmod 600 /etc/stellaops/keys/gost-key.pem
|
||||
sudo chown $(whoami):$(whoami) /etc/stellaops/keys/gost-key.pem
|
||||
|
||||
# Or run as root (not recommended)
|
||||
sudo stella crypto sign --provider gost --file doc.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Distribution Validation Issues
|
||||
|
||||
### Problem: Validation script reports "wrong plugins included"
|
||||
|
||||
**Symptoms:**
|
||||
```
|
||||
$ ./validate-distribution.sh international dist/stella-international-linux-x64/stella
|
||||
❌ FAIL: International distribution contains restricted plugins
|
||||
Found: GostCryptoProvider
|
||||
```
|
||||
|
||||
**Cause:**
|
||||
Built with wrong flags or flags not working.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Clean and rebuild without regional flags
|
||||
dotnet clean
|
||||
dotnet publish src/Cli/StellaOps.Cli \
|
||||
--configuration Release \
|
||||
--runtime linux-x64 \
|
||||
--self-contained true \
|
||||
--output dist/stella-international-linux-x64
|
||||
|
||||
# Verify no build flags were set
|
||||
echo "No StellaOpsEnableGOST, StellaOpsEnableEIDAS, or StellaOpsEnableSM flags"
|
||||
|
||||
# Re-validate
|
||||
./validate-distribution.sh international dist/stella-international-linux-x64/stella
|
||||
# Expected: ✅ PASS
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Diagnostic Commands
|
||||
|
||||
### Check CLI Version and Distribution
|
||||
|
||||
```bash
|
||||
stella --version
|
||||
# Output:
|
||||
# stella CLI version 2.1.0
|
||||
# Build: 2025-12-23T10:00:00Z
|
||||
# Commit: dfaa207
|
||||
# Distribution: stella-russia
|
||||
# Platform: linux-x64
|
||||
# .NET Runtime: 10.0.0
|
||||
```
|
||||
|
||||
### System Diagnostics
|
||||
|
||||
```bash
|
||||
stella system diagnostics
|
||||
# Output:
|
||||
# System Diagnostics:
|
||||
# ✅ CLI version: 2.1.0
|
||||
# ✅ .NET Runtime: 10.0.0
|
||||
# ✅ Backend reachable: https://api.stellaops.example.com
|
||||
# ✅ Authentication: Valid (expires 2025-12-24)
|
||||
# ✅ Crypto providers: default, gost
|
||||
# ⚠️ PostgreSQL: Not configured (offline mode)
|
||||
```
|
||||
|
||||
### Check Available Crypto Providers
|
||||
|
||||
```bash
|
||||
stella crypto providers --verbose
|
||||
# Output:
|
||||
# Available Crypto Providers:
|
||||
#
|
||||
# Provider: default
|
||||
# Description: .NET Crypto, BouncyCastle
|
||||
# Algorithms: ECDSA-P256, ECDSA-P384, EdDSA, RSA-2048, RSA-4096
|
||||
# Status: ✅ Healthy
|
||||
#
|
||||
# Provider: gost
|
||||
# Description: GOST R 34.10-2012, GOST R 34.11-2012
|
||||
# Algorithms: GOST12-256, GOST12-512, GOST2001
|
||||
# Status: ⚠️ CryptoPro CSP not initialized
|
||||
```
|
||||
|
||||
### Verbose Mode
|
||||
|
||||
```bash
|
||||
# Enable verbose logging for all commands
|
||||
stella --verbose <command>
|
||||
|
||||
# Example:
|
||||
stella --verbose auth login
|
||||
stella --verbose scan docker://nginx:latest
|
||||
stella --verbose crypto sign --provider gost --file doc.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you're still experiencing issues after trying these solutions:
|
||||
|
||||
1. **Check Documentation:**
|
||||
- [CLI Overview](README.md)
|
||||
- [CLI Architecture](architecture.md)
|
||||
- [Command Reference](command-reference.md)
|
||||
- [Compliance Guide](compliance-guide.md)
|
||||
|
||||
2. **Enable Verbose Logging:**
|
||||
```bash
|
||||
stella --verbose <command>
|
||||
```
|
||||
|
||||
3. **Check GitHub Issues:**
|
||||
- https://git.stella-ops.org/stella-ops.org/git.stella-ops.org/issues
|
||||
|
||||
4. **Community Support:**
|
||||
- GitHub Discussions: https://github.com/stellaops/stellaops/discussions
|
||||
|
||||
5. **Commercial Support:**
|
||||
- Contact: support@stella-ops.org
|
||||
|
||||
---
|
||||
|
||||
## Common Error Codes
|
||||
|
||||
| Exit Code | Meaning | Typical Cause |
|
||||
|-----------|---------|---------------|
|
||||
| `0` | Success | - |
|
||||
| `1` | General error | Check error message |
|
||||
| `2` | Policy violations | Scan found policy violations (with `--fail-on-policy-violations`) |
|
||||
| `3` | Authentication error | Token expired or invalid credentials |
|
||||
| `4` | Configuration error | Invalid configuration or missing required fields |
|
||||
| `5` | Network error | Backend unreachable or timeout |
|
||||
| `10` | Invalid arguments | Incorrect command usage or missing required arguments |
|
||||
|
||||
---
|
||||
|
||||
## Frequently Asked Questions (FAQ)
|
||||
|
||||
### Q: How do I switch between crypto providers?
|
||||
|
||||
**A:** Use the `--provider` flag or create a crypto profile:
|
||||
|
||||
```bash
|
||||
# Method 1: Use --provider flag
|
||||
stella crypto sign --provider gost --file doc.pdf
|
||||
|
||||
# Method 2: Create and use profile
|
||||
stella crypto profiles create my-gost --provider gost --algorithm GOST12-256
|
||||
stella crypto profiles use my-gost
|
||||
stella crypto sign --file doc.pdf # Uses my-gost profile
|
||||
```
|
||||
|
||||
### Q: Can I use multiple regional plugins in one distribution?
|
||||
|
||||
**A:** No. Each distribution includes only one regional plugin (GOST, eIDAS, or SM) to comply with export control laws.
|
||||
|
||||
### Q: How do I update the CLI?
|
||||
|
||||
**A:**
|
||||
```bash
|
||||
# If installed via .NET tool
|
||||
dotnet tool update --global StellaOps.Cli
|
||||
|
||||
# If installed via binary download
|
||||
wget https://releases.stella-ops.org/cli/latest/stella-<distribution>-<platform>.tar.gz
|
||||
tar -xzf stella-<distribution>-<platform>.tar.gz
|
||||
sudo cp stella /usr/local/bin/
|
||||
```
|
||||
|
||||
### Q: How do I enable offline mode?
|
||||
|
||||
**A:**
|
||||
```bash
|
||||
# Set offline mode
|
||||
export STELLAOPS_OFFLINE_MODE=true
|
||||
|
||||
# Create offline package (admin)
|
||||
stella offline sync --output stellaops-offline-$(date +%F).tar.gz
|
||||
|
||||
# Load offline package in air-gapped environment
|
||||
stella offline load --package stellaops-offline-2025-12-23.tar.gz
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [CLI Overview](README.md) - Installation and quick start
|
||||
- [CLI Architecture](architecture.md) - Plugin architecture
|
||||
- [Command Reference](command-reference.md) - Command usage
|
||||
- [Compliance Guide](compliance-guide.md) - Regional compliance
|
||||
- [Distribution Matrix](distribution-matrix.md) - Build and distribution
|
||||
- [Crypto Plugins](crypto-plugins.md) - Plugin development
|
||||
Reference in New Issue
Block a user