Zum Hauptinhalt springen

DuoKey-SDK-Schicht

Die DuoKey-SDK-Schicht wickelt die gesamte Kommunikation mit dem DuoKey Cockpit ab. Sie überträgt jede PKCS#11-Operation über HTTPS an das Cockpit, hängt das Authentifizierungs-Token an und kümmert sich um Wiederholungen und die Wiederverwendung von Verbindungen.

API-Referenz: Das konkrete Wire-Protokoll — Endpunkte und Anfrage-/Antwortformate — ist intern und wird separat in den Developer Docs dokumentiert. Diese Seite bietet eine übergeordnete Sicht auf die Verantwortlichkeiten der Schicht.

Überblick​

Verantwortlichkeiten​

Authentifizierung​

Die Authentifizierung gegenüber dem DuoKey Cockpit erfolgt über ein einzelnes access_guid-Bearer-Token. Das Token ist Teil der für die Oracle-TDE-App konfigurierten Cockpit-Proxy-URL und wird bei jeder Anfrage als Authorization: Bearer …-Header gesendet.

Es gibt keinen OAuth2-Client-Credentials-Flow, keine client_id / client_secret, keinen Benutzernamen / Passwort und keinen Mandanten-Header auf Client-Seite. Das Cockpit löst den Mandanten serverseitig anhand der in der URL eingebetteten App-Identität auf.

Authentifizierungsablauf:

Konfiguration: Das Token wird über pkcs11.toml (oder die Überschreibung DKE_PKCS11_ACCESS_TOKEN) bereitgestellt. Siehe Konfiguration.

HTTPS-Client​

Sendet Anfragen an den DuoKey-Cockpit-Proxy-Endpunkt. Jede PKCS#11-Operation wird zu einer einzelnen Anfrage, die mit dem Bearer-Token gesendet wird; die Antwort wird in ein PKCS#11-Ergebnis zurückübersetzt. Konzeptionell lassen sich die Operationen in zwei Gruppen einteilen:

  • Schlüsselverwaltung — einen Masterschlüssel bereitstellen, Schlüsselinformationen nachschlagen.
  • Wrap / Unwrap — die Table- und Tablespace-Keys unter dem Masterschlüssel wrappen und entpacken.

Anfrage-/Antwortbehandlung​

Die Schicht serialisiert die ausgehende Anfrage, hängt die Header und das Bearer-Token an, sendet sie über HTTPS und parst die Antwort.

Fehlerbehandlung: Die Schicht übersetzt Cockpit- und Transportfehler in die passenden PKCS#11-Rückgabecodes, sodass Oracle TDE standardkonforme Cryptoki-Ergebnisse sieht — beispielsweise erscheint ein Authentifizierungsfehler als Authentifizierungsfehler, ein fehlendes Objekt als Fehler wegen ungültigem Handle und Backend- oder Netzwerkausfälle als Gerätefehler.

Wiederholungslogik​

Transiente Fehler werden mit exponentiellem Backoff wiederholt.

Wiederholbar: Netzwerk-Timeouts, 503 Service Unavailable, 502 Bad Gateway, Verbindungsfehler.

Nicht wiederholbar: 401 Unauthorized (Authentifizierung), 404 Not Found (Objekt fehlt), 400 Bad Request (ungültige Parameter).

Konfiguration: Das Timeout pro Anfrage wird über timeout_secs in pkcs11.toml festgelegt (Standard 30 Sekunden). Siehe Konfiguration.

Wiederverwendung von Verbindungen​

  • Keep-Alive: HTTPS-Verbindungen werden über Anfragen hinweg wiederverwendet, um wiederholte TCP/TLS-Handshakes zu vermeiden.
  • TLS: Alle Verbindungen verwenden TLS 1.2+ mit strikter Zertifikatsvalidierung (gesteuert über verify_tls).

Fehlerbehandlung​

Das Cockpit gibt bei einem Fehler eine strukturierte Fehlermeldung zurück; die SDK-Schicht parst sie und bildet sie auf einen PKCS#11-Rückgabecode ab.

Sicherheitsüberlegungen​

TLS​

  • Minimale Version: TLS 1.2+
  • Zertifikatsvalidierung: strikt; verify_tls = true in der Produktion
  • Cipher-Suites: nur starke Suites

Umgang mit Zugangsdaten​

  • Ein einziges Zugangsdatum: Das access_guid-Bearer-Token ist das einzige clientseitige Geheimnis.
  • Keine Protokollierung: Das Token wird niemals protokolliert.
  • Bereitstellung zur Laufzeit: über pkcs11.toml oder die Umgebungs-Überschreibung DKE_PKCS11_ACCESS_TOKEN; schützen Sie die Datei mit restriktiven Berechtigungen.

Nächste Schritte​