Skip to content

security_pki_architecture.md

Latest commit

 

History

History
630 lines (467 loc) · 19.6 KB

security_pki_architecture.md

File metadata and controls

630 lines (467 loc) · 19.6 KB

PKI Integration Architecture

Status: ✅ Produktiv (mit ENV-Konfiguration) | ⚙️ Stub-Modus (Development)
Version: 1.1 (February 2026) - Updated for FIND-022 & FIND-029
Compliance: eIDAS-konform, DSGVO Art. 32, HGB § 257, ISO 27001 A.8.24
Audit Findings Addressed: FIND-022 (PKI Infrastructure), FIND-029 (Client Certificates)

📑 Inhaltsverzeichnis

Überblick

ThemisDB integriert eine Public Key Infrastructure (PKI) für kryptographische Signaturen und Zertifikats-basiertes Key-Management. Die Implementierung erfüllt eIDAS-Anforderungen für qualifizierte elektronische Signaturen und unterstützt Encrypt-then-Sign-Workflows für Audit-Logs und SAGA-Transaktionen.

Architektur-Komponenten

┌──────────────────────────────────────────────────────────────┐
│                    ThemisDB PKI Stack                         │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────────┐   ┌──────────────────┐   ┌────────────┐ │
│  │  PKI Client    │───│  PKI Key Provider│───│ Vault/HSM  │ │
│  │  (Signing)     │   │  (KEK Derivation)│   │ (Optional) │ │
│  └────────────────┘   └──────────────────┘   └────────────┘ │
│         │                       │                             │
│         │                       │                             │
│  ┌──────▼───────────────────────▼───────────────────────┐   │
│  │         OpenSSL (RSA-SHA256/384/512)                 │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Certificate Store (X.509 PEM)                       │   │
│  │  - Private Key (RSA 2048/4096)                       │   │
│  │  - Public Certificate (with Serial Number)           │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

Core Components

1. PKIClient

Datei: src/utils/pki_client.cpp | include/utils/pki_client.h

Funktionalität

  • Sign: RSA-basierte digitale Signaturen (SHA256/SHA384/SHA512)
  • Verify: Signaturverifizierung mit Public Key
  • Certificate Handling: X.509-Zertifikatsverarbeitung
  • Dual-Mode: Produktiv (OpenSSL) vs. Stub (Base64, nur Dev)

Konfiguration

struct PKIConfig {
    std::string key_path;          // Path to RSA private key (PEM)
    std::string cert_path;         // Path to X.509 certificate (PEM)
    std::string key_passphrase;    // Optional passphrase for encrypted keys
    std::string vault_addr;        // Optional: HashiCorp Vault address
    std::string vault_token;       // Optional: Vault access token
    std::string signing_algorithm; // "RSA-SHA256", "RSA-SHA384", "RSA-SHA512"
};

ENV-Variablen (Produktiv-Modus)

Variable Beschreibung Beispiel
THEMIS_PKI_PRIVATE_KEY Pfad zum RSA Private Key /etc/themis/pki/service.key
THEMIS_PKI_CERTIFICATE Pfad zum X.509 Zertifikat /etc/themis/pki/service.crt
THEMIS_PKI_KEY_PASSPHRASE Passphrase für verschlüsselte Keys (optional) SecurePass123!
THEMIS_PKI_VAULT_ADDR Vault-Server-URL (optional) https://vault.example.com:8200
THEMIS_PKI_VAULT_TOKEN Vault Access Token (optional) s.abcdef123456
THEMIS_PKI_SIGNING_ALGORITHM Signatur-Algorithmus RSA-SHA256 (default)

Fallback: Wenn THEMIS_PKI_PRIVATE_KEY nicht gesetzt ist, aktiviert sich automatisch der Stub-Modus (Base64-Dummy-Signaturen, nur für Development).

API-Beispiel

#include "utils/pki_client.h"

// Konfiguration aus ENV
PKIConfig cfg = PKIConfig::fromEnvironment();

// PKI Client erstellen
PKIClient pki(cfg);

// Daten signieren
std::vector<uint8_t> data = {'H', 'e', 'l', 'l', 'o'};
auto result = pki.sign(data);

if (result.success) {
    std::cout << "Signature: " << result.signature_b64 << std::endl;
    std::cout << "Algorithm: " << result.algorithm << std::endl;
    std::cout << "Cert Serial: " << result.cert_serial << std::endl;
}

// Signatur verifizieren
bool valid = pki.verify(data, result.signature_b64);
std::cout << "Valid: " << valid << std::endl;

2. PKIKeyProvider

Datei: src/security/pki_key_provider.cpp | include/security/pki_key_provider.h

Funktionalität

  • KEK-Ableitung aus PKI-Zertifikat: Verwendet X.509-Serial und Subject-DN als HKDF-Material
  • Produktions-Key-Hierarchie: Master KEK → Collection KEK → Field DEK
  • Vault-Integration: Optional HSM-backed Key-Storage über HashiCorp Vault

Key-Derivation Flow

┌──────────────────────────────────────────────────────────────┐
│  X.509 Certificate (Subject DN + Serial Number)             │
└───────────────────────┬──────────────────────────────────────┘
                        │
                        │ HKDF-SHA256
                        ▼
            ┌────────────────────────┐
            │   Master KEK (256 bit) │
            └───────────┬────────────┘
                        │
                        │ HKDF-SHA256 (salt: collection_name)
                        ▼
            ┌────────────────────────┐
            │  Collection KEK        │
            └───────────┬────────────┘
                        │
                        │ HKDF-SHA256 (salt: entity_id + field_name)
                        ▼
            ┌────────────────────────┐
            │   Field DEK (256 bit)  │
            └────────────────────────┘
                        │
                        │ AES-256-GCM
                        ▼
            ┌────────────────────────┐
            │   Encrypted Field Data │
            └────────────────────────┘

Beispiel-Integration

#include "security/pki_key_provider.h"

// PKI-Config laden
PKIConfig pki_cfg = PKIConfig::fromEnvironment();

// PKIKeyProvider erstellen
auto pki_kp = std::make_shared<PKIKeyProvider>(
    pki_cfg.cert_path,
    pki_cfg.vault_addr,
    pki_cfg.vault_token
);

// Master KEK ableiten
auto kek = pki_kp->getKey("master_kek");

// Collection-spezifischen Key ableiten
auto collection_key = pki_kp->deriveCollectionKey("master_kek", "users");

3. Audit-Log-Signierung (Encrypt-then-Sign)

Integration: src/server/saga_logger.cpp

Workflow

  1. Encryption: Sensitive Felder werden mit AES-256-GCM verschlüsselt
  2. Serialization: JSON-Serialisierung des Audit-Log-Eintrags
  3. Signing: RSA-SHA256-Signatur über serialisierte Daten
  4. Storage: Log-Eintrag + Signatur werden in RocksDB persistiert

Beispiel

#include "server/saga_logger.h"
#include "utils/pki_client.h"

// SAGA Logger mit PKI-Client
SAGALogger logger(field_encryption, pki_client, cfg);

// Log-Eintrag erstellen (wird automatisch signiert)
logger.logOperation(saga_id, step_id, "INSERT", 
                   "users", entity_pk, entity_json);

// Signatur wird in RocksDB unter `saga_signature:` gespeichert

Signatur-Format (JSON)

{
  "signature": "base64_encoded_rsa_signature",
  "algorithm": "RSA-SHA256",
  "cert_serial": "1A2B3C4D5E6F",
  "timestamp": 1731868800000,
  "signed_data_hash": "sha256_of_original_data"
}

4. LEK Manager (Lawful Evidence Key Management)

Datei: src/security/lek_manager.cpp | include/security/lek_manager.h

Funktionalität

  • LEK-Wrapping: Verschlüsselung von Log-Encryption-Keys mit KEK aus PKI
  • Key-Rotation: Unterstützt LEK-Rotation für Compliance-Anforderungen
  • Escrow: Optionales Key-Escrow für Behördenzugriff (DSGVO Art. 23)

API

#include "security/lek_manager.h"

LEKManager lek_mgr(db, pki_client, key_provider);

// LEK erstellen und mit KEK wrappen
auto lek = lek_mgr.createLEK("audit_logs_2025");

// LEK abrufen und entschlüsseln
auto unwrapped_lek = lek_mgr.getLEK("audit_logs_2025");

// LEK rotieren (neue Version)
lek_mgr.rotateLEK("audit_logs_2025");

Deployment-Szenarien

Szenario 1: Development (Stub-Modus)

# Keine ENV-Variablen → automatisch Stub-Modus
./themis_server

# Logs:
# [INFO] PKI Client: Running in STUB mode (no private key configured)
# [WARN] Signatures are Base64-encoded hashes, NOT cryptographically secure!

Verwendung: Lokale Tests, CI/CD ohne echte Zertifikate

Szenario 2: Produktion (Self-Signed Certificates)

# 1. Zertifikat und Key generieren
openssl genrsa -out /etc/themis/pki/service.key 4096
openssl req -new -x509 -key /etc/themis/pki/service.key \
    -out /etc/themis/pki/service.crt -days 3650 \
    -subj "/C=DE/ST=Bavaria/L=Munich/O=ThemisDB/CN=themis.example.com"

# 2. ENV konfigurieren
export THEMIS_PKI_PRIVATE_KEY=/etc/themis/pki/service.key
export THEMIS_PKI_CERTIFICATE=/etc/themis/pki/service.crt
export THEMIS_PKI_SIGNING_ALGORITHM=RSA-SHA256

# 3. Server starten
./themis_server

# Logs:
# [INFO] PKI Client: Loaded private key from /etc/themis/pki/service.key
# [INFO] PKI Client: Certificate serial: 1A2B3C4D5E6F
# [INFO] PKI Client: Algorithm: RSA-SHA256

Szenario 3: Produktion (CA-Signed Certificates + Vault)

# 1. CA-signiertes Zertifikat erhalten
# (von interner CA oder öffentlicher CA)

# 2. Key in HashiCorp Vault speichern (optional)
vault kv put secret/themis/pki \
    private_key=@/path/to/service.key \
    certificate=@/path/to/service.crt

# 3. ENV mit Vault-Integration
export THEMIS_PKI_PRIVATE_KEY=/etc/themis/pki/service.key
export THEMIS_PKI_CERTIFICATE=/etc/themis/pki/service.crt
export THEMIS_PKI_VAULT_ADDR=https://vault.example.com:8200
export THEMIS_PKI_VAULT_TOKEN=s.abc123def456
export THEMIS_PKI_SIGNING_ALGORITHM=RSA-SHA384

# 4. Server starten
./themis_server

Vorteile:

  • CA-Chain-Validierung
  • Vault-backed Key-Rotation
  • HSM-Integration über Vault Transit Engine

Szenario 4: eIDAS-konforme Produktion (Qualifizierte Signaturen)

Voraussetzungen:

  • Zertifikat von qualifiziertem Vertrauensdiensteanbieter (QTSP)
  • HSM (Hardware Security Module) für Private Key Storage
  • Zeitstempel-Dienst (TSA) für Langzeitarchivierung

Konfiguration:

# 1. HSM-backed Key (z.B. PKCS#11)
export THEMIS_PKI_PRIVATE_KEY=/dev/pkcs11/slot0/key
export THEMIS_PKI_CERTIFICATE=/etc/themis/pki/eidas_qualified.crt
export THEMIS_PKI_SIGNING_ALGORITHM=RSA-SHA512  # Höhere Sicherheit

# 2. Optional: TSA für Zeitstempel
export THEMIS_PKI_TSA_URL=https://tsa.example.com/timestamp

# 3. Server starten
./themis_server

Compliance-Mapping:

Anforderung Umsetzung
eIDAS Art. 26 (Qualifizierte Signatur) RSA-SHA512 mit QTSP-Zertifikat
eIDAS Art. 32 (Langzeitarchivierung) TSA-Zeitstempel + Audit-Logs
eIDAS Art. 34 (Validierung) X.509-Chain-Validierung

API-Endpunkte

POST /api/pki/sign

Beschreibung: Signiert beliebige Daten mit PKI Private Key

Request:

{
  "data": "SGVsbG8gV29ybGQ=",  // Base64-encoded data
  "algorithm": "RSA-SHA256"      // Optional, default from config
}

Response:

{
  "signature": "base64_encoded_signature",
  "algorithm": "RSA-SHA256",
  "cert_serial": "1A2B3C4D5E6F",
  "timestamp": 1731868800000,
  "success": true
}

POST /api/pki/verify

Beschreibung: Verifiziert Signatur mit Public Key

Request:

{
  "data": "SGVsbG8gV29ybGQ=",
  "signature": "base64_encoded_signature",
  "algorithm": "RSA-SHA256"
}

Response:

{
  "valid": true,
  "cert_serial": "1A2B3C4D5E6F",
  "message": "Signature verification successful"
}

GET /api/pki/certificate

Beschreibung: Gibt Public Certificate zurück (für Client-seitige Verifikation)

Response:

{
  "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
  "serial": "1A2B3C4D5E6F",
  "subject": "/C=DE/ST=Bavaria/O=ThemisDB/CN=themis.example.com",
  "issuer": "/C=DE/O=ThemisDB CA/CN=ThemisDB Root CA",
  "valid_from": "2025-01-01T00:00:00Z",
  "valid_to": "2035-01-01T00:00:00Z"
}

Security-Empfehlungen

Key-Management

  1. Private Key Protection:

    • Niemals im Git-Repository speichern
    • Dateiberechtigungen: chmod 400 service.key
    • Verschlüsselte Keys mit Passphrase bevorzugen

  2. Key-Rotation:

    • Regelmäßige Rotation (z.B. jährlich)
    • Alte Signaturen bleiben verifizierbar (behalte alte Zertifikate)

  3. HSM-Integration:

    • Für Produktionsumgebungen: HSM-backed Keys
    • Unterstützte Standards: PKCS#11, Vault Transit Engine

Zertifikats-Validierung

  1. Certificate Pinning: Client-seitige Validierung der Certificate Fingerprints
  2. CRL/OCSP: Regelmäßige Prüfung der Zertifikatswiderrufslisten
  3. Chain-Validierung: Vollständige CA-Chain bis zum Root-Zertifikat

Audit-Trail

  • Alle Sign/Verify-Operationen werden in Audit-Logs protokolliert
  • Signatur-Metadaten (Timestamp, Algorithm, Cert Serial) werden persistiert
  • Tamper-Evidence durch Encrypt-then-Sign

Troubleshooting

Fehler: "Failed to load private key"

Ursache: Falscher Pfad oder verschlüsselter Key ohne Passphrase

Lösung:

# Prüfen ob Key lesbar
openssl rsa -in /path/to/service.key -check -noout

# Falls verschlüsselt: Passphrase setzen
export THEMIS_PKI_KEY_PASSPHRASE="YourPassphrase"

Fehler: "Signature verification failed"

Ursache: Falscher Public Key oder Datenkorruption

Lösung:

# Manuell mit OpenSSL verifizieren
echo "SGVsbG8=" | base64 -d > data.bin
echo "signature_base64" | base64 -d > signature.bin

openssl dgst -sha256 -verify pubkey.pem -signature signature.bin data.bin

Stub-Modus deaktivieren

Problem: Produktionsserver läuft im Stub-Modus

Lösung:

# Prüfe ENV-Variablen
env | grep THEMIS_PKI

# Setze fehlende Variablen
export THEMIS_PKI_PRIVATE_KEY=/etc/themis/pki/service.key
export THEMIS_PKI_CERTIFICATE=/etc/themis/pki/service.crt

# Neustart
systemctl restart themis-server

Referenzen

  • Dateien:

    • src/utils/pki_client.cpp - Core PKI Client
    • src/security/pki_key_provider.cpp - KEK Derivation
    • src/server/pki_api_handler.cpp - HTTP API
    • src/server/saga_logger.cpp - Audit-Log-Integration

  • Standards:

    • eIDAS Regulation (EU) No 910/2014
    • X.509 v3 Certificate Standard (RFC 5280)
    • RSA PKCS#1 v2.1 (RFC 3447)
    • HKDF (RFC 5869)

  • Dependencies:

    • OpenSSL 1.1+ (EVP, RSA, X.509)
    • HashiCorp Vault (optional)
    • libcurl (HTTP-Client für Vault)

Letzte Aktualisierung: 17. November 2025
Version: 1.0
Autor: ThemisDB Development Team

Client Certificate Authentication (FIND-029)

Überblick

Status: 🟡 GEPLANT für v1.5.0 (Q1 2026)
Priorität: Mittel (Audit Finding FIND-029)
Compliance: ISO 27001 A.8.5, SOC 2 CC6.1, BSI C5 IAM-2

Client-Zertifikate bieten eine zusätzliche Authentifizierungsebene für mTLS (Mutual TLS), bei der nicht nur der Server, sondern auch der Client seine Identität durch ein X.509-Zertifikat nachweist.

Implementierungsplan

Phase 1: CA Infrastructure (v1.5.0 - Q1 2026)

Komponenten:

  • Root CA (Self-signed, RSA 4096, 20 Jahre)
  • Intermediate CA für Client-Certs (RSA 4096, 10 Jahre)
  • Server CA für Server-Certs (RSA 4096, 10 Jahre)
  • HSM-backed CA Key Storage

Tools: openssl, HashiCorp Vault PKI Engine, CFSSL

Phase 2: Client Certificate Issuance (v1.5.0)

Funktionen:

  • Certificate Request (CSR) API
  • Automated Certificate Issuance
  • Certificate Renewal
  • Revocation (CRL/OCSP)

Phase 3: mTLS Authentication (v1.5.0)

Features:

  • TLS Server Config mit mTLS-Enforcement
  • X.509 Chain Verification
  • Identity Mapping (Cert CN → User Identity)
  • RBAC Integration

Vorteile

  • Starke Authentifizierung: Kryptographischer Identitätsnachweis
  • Mutual Trust: Beide Seiten authentifizieren sich
  • Non-Repudiation: Digitale Signaturen verhindern Abstreiten
  • Zero-Trust Ready: Basis für Zero-Trust-Architekturen
  • Compliance: ISO 27001 A.9.2.1, SOC 2 CC6.1, BSI C5 IAM-2

PKI Infrastructure Improvements (FIND-022)

Aktuelle Limitierungen (v1.4.1)

  • Basic PKI Only (keine Client-Certs)
  • Single CA (keine CA-Hierarchie)
  • Manual Certificate Management
  • No CRL/OCSP
  • Limited HSM Integration

Verbesserungen (Roadmap)

1. CA-Hierarchie (v1.5.0)

  • Root CA (Offline, Air-Gapped)
  • Intermediate CAs für Client & Server Certs
  • Separate CAs für verschiedene Zwecke

2. Automatisierte Certificate Lifecycle (v1.5.0)

  • Auto-Issuance via Vault PKI / CFSSL
  • Auto-Renewal mit Cert-Manager
  • Expiration Monitoring (Prometheus)
  • Certificate Inventory

3. Certificate Revocation (v1.5.0)

  • CRL (Certificate Revocation List)
  • OCSP (Online Certificate Status Protocol)
  • OCSP Stapling (v1.6.0)

4. HSM-Integration (v1.5.0)

  • HSM für CA Private Key Storage
  • HSM für Certificate Signing
  • PKCS#11-Integration

Roadmap

  • v1.5.0 (Q1 2026): CA-Hierarchie, Client-Cert Auth, CRL/OCSP, HSM
  • v1.6.0 (Q2 2026): OCSP Stapling, Auto-Rotation, Cert Inventory
  • v2.0.0 (Q3 2026): ACME Protocol, External CA Integration

Compliance-Abdeckung

Standard v1.4.1 v1.5.0 (geplant)
ISO 27001 A.8.24 ⚠️ Basic ✅ Vollständig
ISO 27001 A.8.5 ⚠️ Token only ✅ mTLS + Token
SOC 2 CC6.1 ⚠️ Basic ✅ Certificate-based
BSI C5 IAM-2 ⚠️ Basic ✅ Multi-Factor

Dokumentverantwortlicher: ThemisDB Security Team
Letzte Aktualisierung: 3. Februar 2026 (FIND-022, FIND-029 addressiert)
Nächstes Review: 1. Mai 2026