security_pki_architecture

PKI Integration Architecture

Status: ✅ Produktiv (mit ENV-Konfiguration) | ⚙️ Stub-Modus (Development)
Version: 1.0 (November 2025)
Compliance: eIDAS-konform, DSGVO Art. 32, HGB § 257

📑 Inhaltsverzeichnis

• Überblick
• Architektur-Komponenten
• Core Components
• Konfiguration
• Sicherheit

---

Ü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