Zum Hauptinhalt springen

Kommunikationsfluss

Das Verständnis des Kommunikationsflusses hilft bei der Fehlerbehebung und der Performance-Optimierung. Diese Seite gibt einen Überblick darüber, wie Operationen das System von der Oracle-Datenbank zu DuoKey Cockpit und zurück durchlaufen.

API-Referenz: Detaillierte API-Endpunkte sowie Anfrage-/Antwortformate sind separat in den Developer Docs dokumentiert.

Überblick​

Typischer Operationsablauf​

Initialisierungsablauf​

Schritte:

  1. Oracle ruft C_Initialize() auf: Die Initialisierung der Bibliothek beginnt
  2. Konfiguration lesen: Die Bibliothek liest server_url und access_guid aus pkcs11.toml
  3. Authentifizierung: Die Bibliothek präsentiert dem Cockpit bei ihrer ersten Anfrage ihr access_guid-Bearer-Token
  4. Serverseitige Validierung: Das Cockpit validiert das Token und löst den Mandanten aus der App-Identität auf; es findet kein separater Token-Austausch statt
  5. Vault-Prüfung: Zugriff auf den angegebenen Vault verifizieren
  6. Erfolg zurückgeben: Die Bibliothek ist einsatzbereit

Ablauf der Session-Erstellung​

Schritte:

  1. Oracle ruft C_OpenSession() auf: Neue Session anfordern
  2. Slot validieren: Sicherstellen, dass die Slot-ID gültig ist
  3. Session erstellen: Internes Session-Objekt erstellen
  4. Tabellen initialisieren: Handle-Mapping-Tabelle für die Session erstellen
  5. Handle zurückgeben: Session-Handle an Oracle zurückgeben

Hinweis: Die Session-Erstellung erfordert keine API-Aufrufe. Sessions werden lokal verwaltet.

Anmeldeablauf​

Schritte:

  1. Oracle ruft C_Login() auf: Session-Anmeldung anfordern
  2. Token prüfen: Verifizieren, dass das access_guid-Bearer-Token in pkcs11.toml konfiguriert ist
  3. Session markieren: Session als authentifiziert markieren
  4. Erfolg zurückgeben: CKR_OK zurückgeben

Hinweis: Bei DuoKey PKCS#11 erfolgt die Authentifizierung während C_Initialize(), wenn die Bibliothek dem Cockpit ihr access_guid-Bearer-Token präsentiert. Die Funktion C_Login() bestätigt, dass das Token verfügbar ist, führt aber keine zusätzlichen API-Aufrufe durch.

Ablauf der Schlüsselerzeugung​

Schritte:

  1. Oracle ruft C_GenerateKey() auf: Schlüsselerzeugung anfordern
  2. Template parsen: Schlüsselattribute extrahieren (Typ, Größe, Label)
  3. API-Anfrage erstellen: Anfrage zur Schlüsselerzeugung erstellen
  4. API-Aufruf: Die Anfrage zur Schlüsselerzeugung an das Cockpit senden
  5. HSM-Erzeugung: Das Backend-HSM erzeugt den Schlüssel
  6. UUID empfangen: Das Cockpit gibt die Schlüssel-UUID zurück
  7. Handle erstellen: UUID auf ein PKCS#11-Handle abbilden
  8. Handle zurückgeben: Handle an Oracle zurückgeben

Verschlüsselungsablauf​

Schritte:

  1. Oracle ruft C_Encrypt() / C_WrapKey() auf: Ein Wrap auf dem Masterschlüssel-Pfad anfordern (z. B. zum Schutz eines Tablespace-Schlüssels)
  2. Handle-Auflösung: UUID für das übergebene Masterschlüssel-Handle finden
  3. Mechanismus parsen: Algorithmus (AES-CBC / AES-CBC-PAD) und IV extrahieren
  4. Anfrage erstellen: Wrap-Anfrage erstellen
  5. API-Aufruf: Die Wrap-Anfrage an das Cockpit senden
  6. HSM-Wrap: Das Backend-HSM führt den längenerhaltenden AES-CBC(-PAD)-Wrap durch
  7. Ge-wrappten Schlüssel empfangen: Ge-wrappte Daten erhalten
  8. Ergebnis zurückgeben: An Oracle zurückgeben

Hinweis: Der Wrap verwendet einen längenerhaltenden AES-CBC-/AES-CBC-PAD-Mechanismus. Eine expandierende AES-GCM-Hülle darf auf diesem Pfad nicht verwendet werden – sie bricht Oracles SET KEY mit ORA-00600 [kcbtse_populate_tbskey_1]. Die Bulk-Verschlüsselung von Tabellen und Tablespaces wird lokal von Oracle mittels AES-NI durchgeführt und verlässt niemals die Datenbank.

Entschlüsselungsablauf​

Schritte:

  1. Oracle ruft C_Decrypt() / C_UnwrapKey() auf: Ein Unwrap auf dem Masterschlüssel-Pfad anfordern (z. B. zur Wiederherstellung eines Tablespace-Schlüssels beim Öffnen des Keystores / bei SET KEY)
  2. Handle-Auflösung: UUID für das übergebene Masterschlüssel-Handle finden
  3. Mechanismus parsen: Algorithmus (AES-CBC / AES-CBC-PAD) und IV extrahieren
  4. Anfrage erstellen: Unwrap-Anfrage erstellen
  5. API-Aufruf: Die Unwrap-Anfrage an das Cockpit senden
  6. HSM-Unwrap: Das Backend-HSM führt den längenerhaltenden AES-CBC(-PAD)-Unwrap durch
  7. Tablespace-Schlüssel empfangen: Den ent-wrappten Schlüssel erhalten
  8. Ergebnis zurückgeben: An Oracle zurückgeben

Ablauf der Objektsuche​

Schritte:

  1. C_FindObjectsInit(): Suche mit Template initialisieren
  2. Template parsen: Suchkriterien extrahieren (Label, Klasse usw.)
  3. C_FindObjects(): Suche ausführen
  4. API-Aufruf: Die Objektsuchanfrage an das Cockpit senden
  5. UUIDs empfangen: UUIDs der übereinstimmenden Objekte erhalten
  6. Handles erstellen: UUIDs auf Handles abbilden
  7. Handles zurückgeben: Handle-Array an Oracle zurückgeben
  8. C_FindObjectsFinal(): Suchzustand aufräumen

Ablauf der Fehlerbehandlung​

Behandlung von Netzwerkfehlern​

Behandlung von Authentifizierungsfehlern​

Hinweis: Die access_guid ist ein einziges statisches Bearer-Token. Es gibt keinen Token-Endpunkt und keinen Refresh-Zyklus, sodass ein abgelehntes Token ein terminaler Fehler ist (prüfen Sie die access_guid in pkcs11.toml) und nicht etwas, das die Bibliothek erneut versucht.

Behandlung von HSM-Fehlern​

Performance-Optimierung​

Verbindungswiederverwendung​

Vorteile:

  • Beseitigt den Overhead des TCP-Handshakes
  • Reduziert die Zeit für den Verbindungsaufbau
  • Verbessert den Gesamtdurchsatz

Bearer-Token​

Die Bibliothek authentifiziert jede Anfrage mit einem einzigen access_guid-Bearer-Token, eingebettet in die App-Proxy-server_url. Es gibt keinen Token-Endpunkt und keinen Refresh-Zyklus: Dasselbe Token wird bei jeder Anfrage präsentiert und serverseitig vom Cockpit validiert, das den Mandanten aus der App-Identität auflöst.

Vorteile:

  • Keine Roundtrips für den Token-Austausch
  • Kein zur Laufzeit zu rotierendes Secret (kein client_id / client_secret)
  • Connection-Keep-alive reduziert die TLS-Handshakes pro Operation

Handle-Caching​

Vorteile:

  • Vermeidet doppelte API-Aufrufe
  • Schnellere Handle-Auflösung
  • Reduzierter Netzwerkverkehr

Überwachung und Debugging​

Request-Tracing​

Aktivieren Sie das Debug-Logging, um Anfragen zu verfolgen:

export DKE_PKCS11_LOGGING_LEVEL=debug
export DKE_PKCS11_LOGGING_FOLDER=/var/log/dke-pkcs11

Log-Ausgabe:

[2025-12-19 10:30:45] [DEBUG] C_Initialize() called
[2025-12-19 10:30:45] [DEBUG] Reading pkcs11.toml (server_url, access_guid)
[2025-12-19 10:30:45] [INFO] Connecting to DuoKey Cockpit: https://cockpit-api-dev.duokey.cloud
[2025-12-19 10:30:46] [INFO] access_guid bearer token validated by Cockpit
[2025-12-19 10:30:46] [DEBUG] C_Initialize() completed: CKR_OK

Performance-Metriken​

Überwachen Sie wichtige Metriken:

  • Request-Latenz: Zeit vom Oracle-Aufruf bis zur Antwort
  • API-Latenz: Zeit für DuoKey-Cockpit-API-Aufrufe
  • Fehlerrate: Prozentsatz fehlgeschlagener Anfragen
  • Auth-Fehler: Anzahl abgelehnter access_guid-Bearer-Tokens

Netzwerküberwachung​

Überwachen Sie den Netzwerkverkehr:

  • HTTPS-Verbindungen: Anzahl aktiver Verbindungen
  • Anfrage-/Antwortgrößen: Payload-Größen
  • Retry-Anzahl: Anzahl der Retries pro Anfrage
  • Timeout-Ereignisse: Häufigkeit von Timeouts

Best Practices​

Fehlerbehandlung​

  1. Transiente Fehler erneut versuchen: Netzwerkfehler, Timeouts
  2. Auth-Fehler nicht erneut versuchen: Ungültige Berechtigungsnachweise
  3. Alle Fehler protokollieren: Zur Fehlerbehebung
  4. Passende Codes zurückgeben: In PKCS#11-Codes übersetzen

Performance​

  1. Verbindungen wiederverwenden: Connection-Pooling nutzen
  2. Verbindungen offen halten: TLS-Handshakes über Operationen hinweg amortisieren
  3. Operationen bündeln: Wenn möglich (zukünftig)
  4. Latenz überwachen: Performance-Metriken verfolgen

Sicherheit​

  1. TLS verwenden: Alle Verbindungen verschlüsselt
  2. Zertifikate validieren: Strikte Zertifikatsvalidierung
  3. Berechtigungsnachweise absichern: Die access_guid niemals protokollieren
  4. pkcs11.toml schützen: Das access_guid-Bearer-Token als Secret behandeln; Dateiberechtigungen einschränken

Nächste Schritte​