Doctor plugin checks: implement health check classes and documentation
Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
127
docs/doctor/articles/crypto/certchain.md
Normal file
127
docs/doctor/articles/crypto/certchain.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
checkId: check.crypto.certchain
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: warn
|
||||
tags: [crypto, certificate, tls, security]
|
||||
---
|
||||
# Certificate Chain Validation
|
||||
|
||||
## What It Checks
|
||||
Verifies certificate chain completeness, trust anchor validity, and expiration for the configured TLS certificate. The check reads the certificate path from `Crypto:TlsCertPath`, `Kestrel:Certificates:Default:Path`, or `Server:TlsCertificate` and validates:
|
||||
|
||||
- **File existence**: whether the configured certificate file exists on disk.
|
||||
- **Chain completeness**: whether all intermediate certificates are present (no missing links).
|
||||
- **Trust anchor validity**: whether the root CA is trusted by the system trust store.
|
||||
- **Expiration**: days until the certificate expires, with tiered severity.
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| No TLS certificate configured | Skip |
|
||||
| Certificate file not found | Fail |
|
||||
| Certificate chain incomplete (missing intermediates) | Fail |
|
||||
| Trust anchor not valid (unknown root CA) | Fail |
|
||||
| Certificate already expired | Fail |
|
||||
| Certificate expires within 7 days | Fail |
|
||||
| Certificate expires within 30 days | Warn |
|
||||
| Chain complete, trust anchor valid, not expiring soon | Pass |
|
||||
|
||||
Evidence collected: `CertPath`, `ChainLength`, `MissingIntermediates`, `TrustAnchorValid`, `TrustAnchorIssuer`, `ExpirationDate`, `DaysRemaining`.
|
||||
|
||||
This check always runs (no precondition), but skips if no TLS certificate path is configured.
|
||||
|
||||
## Why It Matters
|
||||
An incomplete certificate chain causes TLS handshake failures for clients that do not have intermediate certificates cached. An untrusted root CA triggers browser and API client warnings or outright connection refusal. An expired certificate causes immediate service outage for all HTTPS connections. Certificate issues affect every component that communicates over TLS, including the UI, API, inter-service communication, and external integrations.
|
||||
|
||||
## Common Causes
|
||||
- Certificate file was moved or deleted from the configured path
|
||||
- Incorrect certificate path in configuration
|
||||
- Missing intermediate certificates in the certificate bundle
|
||||
- Incomplete certificate bundle (only leaf certificate, no intermediates)
|
||||
- Root CA not added to the system trust store
|
||||
- Self-signed certificate not explicitly trusted
|
||||
- Certificate not renewed before expiration
|
||||
- Automated renewal process failed silently
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check if certificate file exists at configured path
|
||||
docker compose exec gateway ls -la /certs/
|
||||
|
||||
# Verify certificate details
|
||||
docker compose exec gateway openssl x509 -in /certs/server.crt -noout -dates -subject -issuer
|
||||
|
||||
# Verify certificate chain
|
||||
docker compose exec gateway openssl verify -untrusted /certs/chain.pem /certs/server.crt
|
||||
|
||||
# Bundle certificates correctly (leaf + intermediates)
|
||||
cat server.crt intermediate.crt > fullchain.pem
|
||||
|
||||
# Update configuration in .env or compose override
|
||||
# Crypto__TlsCertPath=/certs/fullchain.pem
|
||||
|
||||
# Set up automated renewal notification
|
||||
# Notify__CertExpiry__ThresholdDays=14
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Verify certificate file exists
|
||||
ls -la /etc/stellaops/certs/server.crt
|
||||
|
||||
# Check certificate expiration
|
||||
openssl x509 -in /etc/stellaops/certs/server.crt -noout -enddate
|
||||
|
||||
# Download missing intermediates
|
||||
stella crypto cert fetch-chain --cert /etc/stellaops/certs/server.crt --output /etc/stellaops/certs/fullchain.pem
|
||||
|
||||
# Add CA to system trust store (Debian/Ubuntu)
|
||||
sudo cp root-ca.crt /usr/local/share/ca-certificates/
|
||||
sudo update-ca-certificates
|
||||
|
||||
# Or configure explicit trust anchor
|
||||
stella crypto trust-anchors add --type ca --cert root-ca.crt
|
||||
|
||||
# Renew certificate
|
||||
stella crypto cert renew --cert /etc/stellaops/certs/server.crt
|
||||
|
||||
# Update appsettings.json
|
||||
# "Crypto": { "TlsCertPath": "/etc/stellaops/certs/fullchain.pem" }
|
||||
|
||||
sudo systemctl restart stellaops-gateway
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```bash
|
||||
# Check certificate secret
|
||||
kubectl get secret stellaops-tls-cert -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl x509 -noout -dates
|
||||
|
||||
# Verify certificate chain
|
||||
kubectl get secret stellaops-tls-cert -o jsonpath='{.data.tls\.crt}' | base64 -d | openssl verify
|
||||
|
||||
# Update TLS certificate secret
|
||||
kubectl create secret tls stellaops-tls-cert \
|
||||
--cert=fullchain.pem \
|
||||
--key=server.key \
|
||||
--dry-run=client -o yaml | kubectl apply -f -
|
||||
```
|
||||
|
||||
```yaml
|
||||
# values.yaml - use cert-manager for automated renewal
|
||||
certManager:
|
||||
enabled: true
|
||||
issuer: letsencrypt-prod
|
||||
renewBefore: 360h # 15 days before expiry
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.certchain
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.fips` — FIPS compliance may impose certificate algorithm constraints
|
||||
- `check.crypto.eidas` — eIDAS compliance requires specific signature algorithms on certificates
|
||||
- `check.crypto.hsm` — HSM may store the private key associated with the certificate
|
||||
- `check.compliance.attestation-signing` — attestation signing uses related key material
|
||||
101
docs/doctor/articles/crypto/eidas.md
Normal file
101
docs/doctor/articles/crypto/eidas.md
Normal file
@@ -0,0 +1,101 @@
|
||||
---
|
||||
checkId: check.crypto.eidas
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: fail
|
||||
tags: [crypto, eidas, eu, compliance, signature]
|
||||
---
|
||||
# eIDAS Compliance
|
||||
|
||||
## What It Checks
|
||||
Verifies that eIDAS-compliant signature algorithms are available for EU deployments. The check references ETSI TS 119 312 (Cryptographic Suites) and validates availability of the following required algorithms:
|
||||
|
||||
- **RSA-PSS-SHA256** (RSA-PSS with SHA-256)
|
||||
- **RSA-PSS-SHA384** (RSA-PSS with SHA-384)
|
||||
- **RSA-PSS-SHA512** (RSA-PSS with SHA-512)
|
||||
- **ECDSA-P256-SHA256** (ECDSA with P-256 and SHA-256)
|
||||
- **ECDSA-P384-SHA384** (ECDSA with P-384 and SHA-384)
|
||||
- **Ed25519** (EdDSA with Curve25519)
|
||||
|
||||
The check also validates the minimum RSA key size. Per eIDAS guidelines post-2024, RSA keys must be at least 3072 bits. The configured minimum is read from `Crypto:MinRsaKeySize` (default 2048).
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| Any required algorithms missing | Fail |
|
||||
| All algorithms available but RSA key size < 3072 | Warn |
|
||||
| All algorithms available and key size >= 3072 | Pass |
|
||||
|
||||
Evidence collected: `CryptoProfile`, `AvailableAlgorithms`, `MissingAlgorithms`, `MinRsaKeySize`, `RequiredMinRsaKeySize`.
|
||||
|
||||
The check only runs when `Crypto:Profile` or `Cryptography:Profile` contains "eidas", "eu", or "european".
|
||||
|
||||
## Why It Matters
|
||||
eIDAS (Electronic Identification, Authentication and Trust Services) is an EU regulation that establishes standards for electronic signatures and trust services. Deployments in the EU that create qualified electronic signatures or seals must use algorithms approved by ETSI. Using non-compliant algorithms means signatures may not be legally recognized, and the deployment may fail regulatory requirements. RSA keys below 3072 bits are considered insufficient for long-term security under current eIDAS guidelines.
|
||||
|
||||
## Common Causes
|
||||
- OpenSSL version too old to support all required algorithms
|
||||
- Crypto libraries compiled without required algorithm support
|
||||
- Configuration restricting the set of available algorithms
|
||||
- Legacy RSA key size configuration not updated for post-2024 requirements
|
||||
- Using LibreSSL instead of OpenSSL (missing some algorithms)
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check OpenSSL version and available algorithms
|
||||
docker compose exec gateway openssl version
|
||||
docker compose exec gateway openssl list -signature-algorithms
|
||||
|
||||
# Update minimum RSA key size
|
||||
# Crypto__MinRsaKeySize=3072
|
||||
# Crypto__Profile=eu
|
||||
|
||||
# Restart services after configuration change
|
||||
docker compose restart gateway
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Check OpenSSL version
|
||||
openssl version
|
||||
|
||||
# Verify available signature algorithms
|
||||
openssl list -signature-algorithms
|
||||
|
||||
# Update OpenSSL if algorithms are missing
|
||||
sudo apt update && sudo apt install openssl libssl-dev
|
||||
|
||||
# Configure eIDAS crypto profile
|
||||
stella crypto profile set --profile eu
|
||||
|
||||
# Set minimum RSA key size in appsettings.json
|
||||
# "Crypto": { "Profile": "eu", "MinRsaKeySize": 3072 }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
profile: eu
|
||||
minRsaKeySize: 3072
|
||||
```
|
||||
|
||||
```bash
|
||||
# Verify algorithm support in pod
|
||||
kubectl exec deploy/stellaops-gateway -- openssl list -signature-algorithms
|
||||
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.eidas
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.certchain` — certificate chain must use eIDAS-compliant algorithms
|
||||
- `check.crypto.fips` — FIPS and eIDAS have overlapping but distinct algorithm requirements
|
||||
- `check.crypto.hsm` — HSM may be required for qualified eIDAS signatures
|
||||
- `check.compliance.attestation-signing` — attestation signing should use eIDAS-compliant algorithms in EU deployments
|
||||
141
docs/doctor/articles/crypto/fips.md
Normal file
141
docs/doctor/articles/crypto/fips.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
checkId: check.crypto.fips
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: fail
|
||||
tags: [crypto, fips, compliance, security]
|
||||
---
|
||||
# FIPS 140-2 Compliance
|
||||
|
||||
## What It Checks
|
||||
Verifies that FIPS 140-2 mode is enabled and that FIPS-compliant algorithms are functional. The check performs two phases:
|
||||
|
||||
**Phase 1 - FIPS mode detection:**
|
||||
- On Linux: reads `/proc/sys/crypto/fips_enabled` (expects "1").
|
||||
- On Windows: checks the registry at `HKLM\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy\Enabled` and the `DOTNET_SYSTEM_NET_SECURITY_USEFIPSVALIDATED` environment variable.
|
||||
- Reports the platform, crypto provider (OpenSSL/bcrypt/CoreCrypto), and whether the OpenSSL FIPS module is loaded.
|
||||
|
||||
**Phase 2 - Algorithm verification** (actual crypto operations, not just configuration):
|
||||
- **AES-256**: creates key, encrypts test data, verifies output.
|
||||
- **SHA-256**: hashes test data, verifies 32-byte output.
|
||||
- **SHA-384**: hashes test data, verifies 48-byte output.
|
||||
- **SHA-512**: hashes test data, verifies 64-byte output.
|
||||
- **RSA-2048**: generates key pair, signs and verifies test data.
|
||||
- **ECDSA-P256**: generates key pair, signs and verifies test data.
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| FIPS mode not enabled at OS level | Fail |
|
||||
| FIPS mode enabled but some algorithms fail testing | Warn |
|
||||
| FIPS mode enabled and all algorithms pass | Pass |
|
||||
|
||||
Evidence collected: `fips_mode_enabled`, `platform`, `crypto_provider`, `openssl_fips_module_loaded`, `crypto_profile`, `algorithms_tested`, `algorithms_available`, `algorithms_missing`, per-algorithm test results.
|
||||
|
||||
The check only runs when `Crypto:Profile` or `Cryptography:Profile` contains "fips", "fedramp", or equals "us-gov".
|
||||
|
||||
## Why It Matters
|
||||
FIPS 140-2 compliance is mandatory for US government deployments (FedRAMP, DoD, ITAR) and many regulated industries (finance, healthcare). Running without FIPS mode means cryptographic operations may use non-validated implementations, which violates federal security requirements. Even with FIPS mode enabled, individual algorithm failures indicate a broken crypto subsystem that could silently produce invalid signatures or weak encryption.
|
||||
|
||||
## Common Causes
|
||||
- FIPS mode not enabled in the operating system
|
||||
- OpenSSL FIPS provider not loaded or not installed
|
||||
- .NET runtime not configured for FIPS-validated algorithms
|
||||
- FIPS module version incompatible with the OpenSSL version
|
||||
- Algorithm test failure due to incomplete FIPS provider installation
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check if FIPS mode is enabled in the container
|
||||
docker compose exec gateway cat /proc/sys/crypto/fips_enabled
|
||||
|
||||
# Enable FIPS mode in the host OS first (container inherits host FIPS)
|
||||
# Then restart the compose stack
|
||||
|
||||
# Set crypto profile
|
||||
# Crypto__Profile=fips
|
||||
|
||||
# Verify algorithms inside container
|
||||
docker compose exec gateway openssl list -providers
|
||||
docker compose exec gateway openssl list -digest-algorithms
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
|
||||
**Linux (RHEL/CentOS/Fedora):**
|
||||
```bash
|
||||
# Enable FIPS mode
|
||||
sudo fips-mode-setup --enable
|
||||
|
||||
# Verify FIPS status
|
||||
fips-mode-setup --check
|
||||
|
||||
# Reboot required after enabling
|
||||
sudo reboot
|
||||
|
||||
# After reboot, verify
|
||||
cat /proc/sys/crypto/fips_enabled # Should output "1"
|
||||
|
||||
# Restart StellaOps services
|
||||
sudo systemctl restart stellaops
|
||||
```
|
||||
|
||||
**Linux (Ubuntu/Debian):**
|
||||
```bash
|
||||
# Install FIPS packages
|
||||
sudo apt install ubuntu-fips
|
||||
sudo ua enable fips
|
||||
|
||||
# Reboot required
|
||||
sudo reboot
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```
|
||||
Enable via Local Security Policy:
|
||||
Security Settings > Local Policies > Security Options >
|
||||
"System cryptography: Use FIPS compliant algorithms" = Enabled
|
||||
|
||||
Or via registry (requires reboot):
|
||||
reg add HKLM\System\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy /v Enabled /t REG_DWORD /d 1 /f
|
||||
```
|
||||
|
||||
```bash
|
||||
# Configure StellaOps
|
||||
# "Crypto": { "Profile": "fips" }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
profile: fips
|
||||
|
||||
# FIPS must be enabled at the node level
|
||||
# For EKS: use Amazon Linux 2 FIPS AMI
|
||||
# For AKS: use FIPS-enabled node pools
|
||||
# For GKE: use Container-Optimized OS with FIPS
|
||||
```
|
||||
|
||||
```bash
|
||||
# Verify FIPS in pod
|
||||
kubectl exec deploy/stellaops-gateway -- cat /proc/sys/crypto/fips_enabled
|
||||
|
||||
# Check OpenSSL FIPS provider
|
||||
kubectl exec deploy/stellaops-gateway -- openssl list -providers
|
||||
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.fips
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.certchain` — certificates must use FIPS-approved algorithms
|
||||
- `check.crypto.eidas` — eIDAS has overlapping but distinct requirements from FIPS
|
||||
- `check.crypto.hsm` — FIPS 140-2 Level 3+ may require HSM for key storage
|
||||
- `check.compliance.attestation-signing` — signing must use FIPS-validated algorithms in FIPS deployments
|
||||
120
docs/doctor/articles/crypto/gost.md
Normal file
120
docs/doctor/articles/crypto/gost.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
checkId: check.crypto.gost
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: fail
|
||||
tags: [crypto, gost, russia, compliance]
|
||||
---
|
||||
# GOST Algorithm Availability
|
||||
|
||||
## What It Checks
|
||||
Verifies that GOST cryptographic algorithms are available for Russian deployments. The check validates two layers:
|
||||
|
||||
**Layer 1 - GOST engine detection:**
|
||||
Checks whether the OpenSSL GOST engine is loaded by looking for the engine shared object at:
|
||||
- A custom path configured via `Crypto:Gost:EnginePath`
|
||||
- Common system paths: `/usr/lib/x86_64-linux-gnu/engines-{3,1.1}/gost.so`, `/usr/lib64/engines-{3,1.1}/gost.so`
|
||||
|
||||
**Layer 2 - Algorithm availability** (only if engine is loaded):
|
||||
Verifies the following GOST algorithms are accessible:
|
||||
- **GOST R 34.10-2012-256** (digital signature, 256-bit)
|
||||
- **GOST R 34.10-2012-512** (digital signature, 512-bit)
|
||||
- **GOST R 34.11-2012-256** (Stribog hash, 256-bit)
|
||||
- **GOST R 34.11-2012-512** (Stribog hash, 512-bit)
|
||||
- **GOST R 34.12-2015** (Kuznyechik block cipher)
|
||||
- **GOST 28147-89** (Magma legacy block cipher)
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| GOST engine not loaded | Fail |
|
||||
| Engine loaded but some algorithms missing | Warn |
|
||||
| Engine loaded and all algorithms available | Pass |
|
||||
|
||||
Evidence collected: `CryptoProfile`, `GostEngineLoaded`, `AvailableAlgorithms`, `MissingAlgorithms`, `RequiredAlgorithms`.
|
||||
|
||||
The check only runs when `Crypto:Profile` or `Cryptography:Profile` contains "gost", "russia", or equals "ru".
|
||||
|
||||
## Why It Matters
|
||||
Russian regulatory requirements mandate the use of GOST cryptographic algorithms for government and many commercial deployments. Without GOST algorithm support, the platform cannot create compliant digital signatures or encrypt data according to Russian standards. This blocks deployment in regulated Russian environments and may violate data protection requirements.
|
||||
|
||||
## Common Causes
|
||||
- OpenSSL GOST engine not installed on the system
|
||||
- GOST engine not configured in `openssl.cnf`
|
||||
- Missing `gost-engine` package
|
||||
- GOST engine version too old (missing newer algorithms)
|
||||
- GOST engine installed but algorithm disabled in configuration
|
||||
- Incomplete GOST engine installation
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check if GOST engine is available
|
||||
docker compose exec gateway openssl engine gost -c 2>/dev/null || echo "GOST engine not found"
|
||||
|
||||
# Install GOST engine in the container (add to Dockerfile for persistence)
|
||||
# For Debian/Ubuntu based images:
|
||||
# RUN apt-get install -y libengine-gost-openssl1.1
|
||||
|
||||
# Set crypto profile
|
||||
# Crypto__Profile=ru
|
||||
# Crypto__Gost__EnginePath=/usr/lib/x86_64-linux-gnu/engines-3/gost.so
|
||||
|
||||
docker compose restart gateway
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Install GOST engine (Debian/Ubuntu)
|
||||
sudo apt install libengine-gost-openssl1.1
|
||||
|
||||
# Or install from source
|
||||
git clone https://github.com/gost-engine/engine
|
||||
cd engine && mkdir build && cd build
|
||||
cmake .. && make && sudo make install
|
||||
|
||||
# Configure OpenSSL to load GOST engine
|
||||
# Add to /etc/ssl/openssl.cnf:
|
||||
# [gost_section]
|
||||
# engine_id = gost
|
||||
# default_algorithms = ALL
|
||||
|
||||
# Verify engine is loaded
|
||||
openssl engine gost -c
|
||||
|
||||
# Configure StellaOps GOST profile
|
||||
stella crypto profile set --profile ru
|
||||
|
||||
# In appsettings.json:
|
||||
# "Crypto": { "Profile": "ru" }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
profile: ru
|
||||
gost:
|
||||
enginePath: /usr/lib/x86_64-linux-gnu/engines-3/gost.so
|
||||
```
|
||||
|
||||
```bash
|
||||
# Verify in pod
|
||||
kubectl exec deploy/stellaops-gateway -- openssl engine gost -c
|
||||
|
||||
# Use a base image that includes GOST engine support
|
||||
# Or mount the engine as a volume
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.gost
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.certchain` — certificates in GOST deployments should use GOST signature algorithms
|
||||
- `check.crypto.fips` — FIPS and GOST are mutually exclusive regional crypto profiles
|
||||
- `check.crypto.sm` — SM (Chinese) is another regional crypto profile with similar structure
|
||||
- `check.crypto.hsm` — GOST keys may be stored in an HSM with GOST support
|
||||
131
docs/doctor/articles/crypto/hsm.md
Normal file
131
docs/doctor/articles/crypto/hsm.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
checkId: check.crypto.hsm
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: warn
|
||||
tags: [crypto, hsm, pkcs11, security]
|
||||
---
|
||||
# HSM/PKCS#11 Availability
|
||||
|
||||
## What It Checks
|
||||
Verifies HSM (Hardware Security Module) availability via PKCS#11 interface. The check validates three layers:
|
||||
|
||||
1. **Module configuration**: whether a PKCS#11 module path is configured via `Crypto:Hsm:ModulePath` or `Cryptography:Pkcs11:ModulePath`.
|
||||
2. **Module file existence**: whether the configured `.so` (Linux) or `.dll` (Windows) file exists on disk.
|
||||
3. **Slot access**: whether the PKCS#11 module can enumerate slots and access the configured slot.
|
||||
4. **Token presence**: whether a token is initialized in the slot and accessible (login test).
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| Module path not configured | Fail |
|
||||
| Module file not found at configured path | Fail |
|
||||
| Slot access failed (init error, no slots, permission denied) | Fail |
|
||||
| Token not accessible (not initialized, login failure) | Warn |
|
||||
| Module loaded, slot accessible, token present | Pass |
|
||||
|
||||
Evidence collected: `ModulePath`, `ModuleExists`, `SlotId`, `SlotLabel`, `SlotAccess`, `TokenPresent`, `TokenLabel`.
|
||||
|
||||
The check only runs when `Crypto:Hsm:Enabled` or `Cryptography:Pkcs11:Enabled` is set to "true".
|
||||
|
||||
## Why It Matters
|
||||
HSMs provide tamper-resistant hardware protection for cryptographic keys. When HSM is enabled, all signing operations (attestations, evidence seals, certificate signing) depend on the HSM being accessible. An unavailable HSM means no signing can occur, which blocks evidence generation, attestation creation, and release approvals. HSM connectivity issues can silently degrade to software-based signing if fallback is enabled, which may violate compliance requirements for FIPS 140-2 Level 3 or eIDAS qualified signatures.
|
||||
|
||||
## Common Causes
|
||||
- PKCS#11 module path not configured in application settings
|
||||
- Module file was moved or deleted from the configured path
|
||||
- HSM software not installed (e.g., SoftHSM2 not installed for development)
|
||||
- PKCS#11 module initialization failure (driver compatibility issues)
|
||||
- No slots available in the HSM
|
||||
- Permission denied accessing the PKCS#11 module or device
|
||||
- Token not initialized in the configured slot
|
||||
- Token login required but PIN not configured or incorrect
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Verify HSM module is accessible
|
||||
docker compose exec gateway ls -la /usr/lib/softhsm/libsofthsm2.so
|
||||
|
||||
# Initialize a token if needed (SoftHSM2 for development)
|
||||
docker compose exec gateway softhsm2-util --init-token --slot 0 --label "stellaops" --pin 1234 --so-pin 0000
|
||||
|
||||
# List available slots
|
||||
docker compose exec gateway softhsm2-util --show-slots
|
||||
|
||||
# Set environment variables
|
||||
# Crypto__Hsm__Enabled=true
|
||||
# Crypto__Hsm__ModulePath=/usr/lib/softhsm/libsofthsm2.so
|
||||
# Crypto__Hsm__Pin=1234
|
||||
|
||||
docker compose restart gateway
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Install SoftHSM2 (for development/testing)
|
||||
sudo apt install softhsm2
|
||||
|
||||
# Configure PKCS#11 module path
|
||||
stella crypto config set --hsm-module /usr/lib/softhsm/libsofthsm2.so
|
||||
|
||||
# Initialize token
|
||||
softhsm2-util --init-token --slot 0 --label "stellaops" --pin 1234 --so-pin 0000
|
||||
|
||||
# List slots
|
||||
softhsm2-util --show-slots
|
||||
|
||||
# Verify module permissions
|
||||
ls -la /usr/lib/softhsm/libsofthsm2.so
|
||||
|
||||
# Configure token PIN
|
||||
stella crypto config set --hsm-pin <your-pin>
|
||||
|
||||
# For Windows with SoftHSM2:
|
||||
# stella crypto config set --hsm-module C:\SoftHSM2\lib\softhsm2.dll
|
||||
|
||||
# In appsettings.json:
|
||||
# "Crypto": {
|
||||
# "Hsm": {
|
||||
# "Enabled": true,
|
||||
# "ModulePath": "/usr/lib/softhsm/libsofthsm2.so"
|
||||
# }
|
||||
# }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
hsm:
|
||||
enabled: true
|
||||
modulePath: /usr/lib/softhsm/libsofthsm2.so
|
||||
pinSecret: stellaops-hsm-pin
|
||||
slotId: 0
|
||||
```
|
||||
|
||||
```bash
|
||||
# Create HSM PIN secret
|
||||
kubectl create secret generic stellaops-hsm-pin \
|
||||
--from-literal=pin=<your-pin>
|
||||
|
||||
# For hardware HSMs, mount the device into the pod
|
||||
# Add to pod spec: devices: ["/dev/pkcs11"]
|
||||
|
||||
# Initialize token
|
||||
kubectl exec deploy/stellaops-gateway -- softhsm2-util --init-token --slot 0 --label stellaops --pin 1234 --so-pin 0000
|
||||
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.hsm
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.fips` — FIPS 140-2 Level 3+ requires key storage in a validated HSM
|
||||
- `check.crypto.eidas` — qualified eIDAS signatures may require HSM-backed keys
|
||||
- `check.crypto.certchain` — the TLS certificate private key may reside in the HSM
|
||||
- `check.compliance.attestation-signing` — attestation signing keys may be HSM-protected
|
||||
112
docs/doctor/articles/crypto/sm.md
Normal file
112
docs/doctor/articles/crypto/sm.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
checkId: check.crypto.sm
|
||||
plugin: stellaops.doctor.crypto
|
||||
severity: fail
|
||||
tags: [crypto, sm2, sm3, sm4, china, compliance]
|
||||
---
|
||||
# SM2/SM3/SM4 Availability
|
||||
|
||||
## What It Checks
|
||||
Verifies that Chinese national cryptographic algorithms (GM/T standards) are available for CN deployments. The check validates:
|
||||
|
||||
1. **OpenSSL version**: SM algorithms are natively supported in OpenSSL 1.1.1+. If the version is older, the check fails immediately.
|
||||
2. **Algorithm availability**: tests each required algorithm:
|
||||
- **SM2**: Elliptic curve cryptography (signature, key exchange)
|
||||
- **SM3**: Cryptographic hash function (256-bit output)
|
||||
- **SM4**: Block cipher (128-bit blocks, 128-bit key)
|
||||
3. **SM2 curve parameters**: verifies the SM2 elliptic curve is properly initialized.
|
||||
|
||||
| Condition | Result |
|
||||
|---|---|
|
||||
| OpenSSL < 1.1.1 and algorithms missing | Fail |
|
||||
| Any SM algorithms unavailable | Fail |
|
||||
| All algorithms available but SM2 curve cannot be verified | Warn |
|
||||
| All algorithms available and SM2 curve verified | Pass |
|
||||
|
||||
Evidence collected: `CryptoProfile`, `OpenSslVersion`, `NativeSmSupport`, `AvailableAlgorithms`, `MissingAlgorithms`, `SM2CurveVerified`.
|
||||
|
||||
The check only runs when `Crypto:Profile` or `Cryptography:Profile` contains "sm", "china", or equals "cn".
|
||||
|
||||
## Why It Matters
|
||||
Chinese regulatory requirements (GB/T standards) mandate the use of SM2, SM3, and SM4 algorithms for government systems, financial services, and critical infrastructure. Without SM algorithm support, the platform cannot create compliant digital signatures or encrypt data according to Chinese national standards. This blocks deployment in regulated Chinese environments and may violate the Cryptography Law of the People's Republic of China.
|
||||
|
||||
## Common Causes
|
||||
- OpenSSL version too old (pre-1.1.1) to include native SM support
|
||||
- Using LibreSSL instead of OpenSSL (lacks SM algorithm support)
|
||||
- System OpenSSL not updated to a version with SM support
|
||||
- OpenSSL compiled without SM algorithm support (custom builds)
|
||||
- SM algorithms disabled in OpenSSL configuration
|
||||
- SM2 curve not properly initialized in the crypto provider
|
||||
- Missing external SM crypto provider (e.g., GmSSL)
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```bash
|
||||
# Check OpenSSL version (must be 1.1.1+)
|
||||
docker compose exec gateway openssl version
|
||||
|
||||
# Verify SM algorithm support
|
||||
docker compose exec gateway openssl list -cipher-algorithms | grep -i sm
|
||||
docker compose exec gateway openssl ecparam -list_curves | grep -i sm2
|
||||
|
||||
# Set crypto profile
|
||||
# Crypto__Profile=cn
|
||||
|
||||
# If OpenSSL is too old, rebuild with a newer base image
|
||||
# FROM ubuntu:22.04 (includes OpenSSL 3.0+)
|
||||
|
||||
docker compose restart gateway
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
```bash
|
||||
# Check current OpenSSL version
|
||||
openssl version
|
||||
|
||||
# Update OpenSSL to 1.1.1+ if needed
|
||||
sudo apt update && sudo apt install openssl
|
||||
|
||||
# Verify SM algorithm support
|
||||
openssl list -cipher-algorithms | grep -i sm
|
||||
openssl ecparam -list_curves | grep -i sm2
|
||||
|
||||
# Configure SM crypto profile
|
||||
stella crypto profile set --profile cn
|
||||
|
||||
# Or use external SM provider (GmSSL)
|
||||
stella crypto config set --sm-provider gmssl
|
||||
|
||||
# In appsettings.json:
|
||||
# "Crypto": { "Profile": "cn" }
|
||||
|
||||
sudo systemctl restart stellaops-platform
|
||||
```
|
||||
|
||||
### Kubernetes / Helm
|
||||
```yaml
|
||||
# values.yaml
|
||||
crypto:
|
||||
profile: cn
|
||||
# Optionally specify external SM provider
|
||||
smProvider: native # or "gmssl" for GmSSL
|
||||
```
|
||||
|
||||
```bash
|
||||
# Verify SM support in pod
|
||||
kubectl exec deploy/stellaops-gateway -- openssl version
|
||||
kubectl exec deploy/stellaops-gateway -- openssl ecparam -list_curves | grep -i sm2
|
||||
|
||||
helm upgrade stellaops ./charts/stellaops -f values.yaml
|
||||
```
|
||||
|
||||
## Verification
|
||||
```
|
||||
stella doctor run --check check.crypto.sm
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.crypto.certchain` — certificates in CN deployments should use SM2 signatures
|
||||
- `check.crypto.gost` — GOST (Russian) is another regional crypto profile with similar structure
|
||||
- `check.crypto.fips` — FIPS and SM are mutually exclusive regional crypto profiles
|
||||
- `check.crypto.hsm` — SM keys may be stored in an HSM with SM algorithm support
|
||||
Reference in New Issue
Block a user