# 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