PKCS#11-Schnittstellenschicht

Die PKCS#11-Schnittstellenschicht ist die oberste Komponente, mit der die Oracle-Datenbank kommuniziert. Sie stellt die standardmäßige PKCS#11-(Cryptoki-)C-Oberfläche bereit, die Oracle erwartet, und übersetzt jeden Aufruf in eine Anfrage, die die darunterliegenden Schichten an das DuoKey Cockpit übertragen.

Überblick

Verantwortlichkeiten

Cryptoki-Funktionsoberfläche

Die Schicht implementiert die standardmäßigen PKCS#11-(Cryptoki-)Funktionen, die Oracle TDE ansteuert. Oracle lädt die Bibliothek über den standardmäßigen Einstiegspunkt C_GetFunctionList und verwendet eine fokussierte Teilmenge:

• Initialisierung: C_Initialize, C_Finalize
• Slot / Token: C_GetSlotList, C_GetTokenInfo
• Session: C_OpenSession, C_CloseSession, C_Login, C_Logout
• Objekte: C_FindObjectsInit, C_FindObjects, C_GetAttributeValue, C_CreateObject, C_DestroyObject
• Schlüssel: C_GenerateKey
• Kryptografisch (Wrap / Unwrap): C_Encrypt, C_Decrypt sowie ihre mehrteiligen …Update- / …Final-Formen

Sitzungsverwaltung

Die Schicht pflegt den Sitzungszustand und unterstützt mehrere gleichzeitige Sessions.

Session-Lebenszyklus:

Merkmale:

• Mehrere Sessions: unterstützt gleichzeitige Sessions pro Slot.
• Zustandsverfolgung: verfolgt, ob eine Session geöffnet und im Benutzerzustand ist.
• Isolation: Jede Session hat ihre eigene Objekt-Handle-Mapping-Tabelle.
• Bereinigung: gibt Ressourcen frei, wenn eine Session geschlossen wird.

Es wird keine PIN gesendet

C_Login versetzt die Session in den Benutzerzustand, sendet aber keine PIN. Die Authentifizierung gegenüber dem Cockpit erfolgt über das access_guid-Bearer-Token, das mit jeder Anfrage übertragen wird (siehe DuoKey-SDK-Schicht).

Objekt-Handle-Verwaltung

Oracle referenziert Objekte über Integer-Handles, während das DuoKey Cockpit Schlüssel über dauerhafte Bezeichner referenziert. Die Schnittstellenschicht bildet die beiden pro Session aufeinander ab — das vollständige Modell finden Sie unter Objekt-Handle-Mapping.

Oracle uses:  integer object handle (e.g. 0x12345)
                    |
Library maps to:  DuoKey key identifier

Mechanismusbehandlung

Die Schicht akzeptiert die standardmäßigen Cryptoki-Mechanismen, die Oracle TDE verwendet — CKM_AES_KEY_GEN für den Masterschlüssel und CKM_AES_CBC_PAD für das Wrappen der Table- und Tablespace-Keys — und überträgt die Operation samt Parametern (IV, Padding) an die darunterliegenden Schichten. Details, einschließlich der Frage, warum der längenerhaltende AES-CBC-Pfad für TDE erforderlich ist, finden Sie unter Kryptografische Mechanismen.

Attributbehandlung

Die Schicht verarbeitet PKCS#11-Attribut-Templates für die Objekterstellung und -suche. Gängige Attribute:

• CKA_CLASS — Objektklasse (Secret Key, Datenobjekt)
• CKA_KEY_TYPE — Schlüsseltyp (z. B. CKK_AES)
• CKA_LABEL / CKA_ID — zum Auffinden des Masterschlüssels verwendet
• CKA_ENCRYPT / CKA_DECRYPT / CKA_WRAP / CKA_UNWRAP — Fähigkeits-Flags

CKA_VALUE ist sensitiv: C_GetAttributeValue verweigert die Herausgabe (CKR_ATTRIBUTE_SENSITIVE), sodass die Masterschlüssel-Bytes niemals an den Aufrufer zurückgegeben werden.

Wichtige Funktionen

C_Initialize

Liest die pkcs11.toml-Konfiguration und stellt die Verbindung zum DuoKey Cockpit her.

• Liest die Konfigurationsdatei (oder die DKE_PKCS11_*-Umgebungsüberschreibungen).
• Bereitet den HTTPS-Client mit dem access_guid-Bearer-Token vor.
• Überprüft die Konnektivität zum Cockpit.
• Gibt bei Erfolg CKR_OK zurück, oder CKR_DEVICE_ERROR, wenn das Cockpit nicht erreichbar ist.

C_OpenSession

Öffnet eine Session mit dem Token, initialisiert den Sitzungszustand und erstellt die Objekt-Handle-Mapping-Tabelle der Session.

C_Login

Versetzt die Session in den Benutzerzustand. Es wird keine PIN übertragen — das Bearer-Token pro Anfrage ist das Zugangsdatum — daher validiert dieser Aufruf die Betriebsbereitschaft, statt eine interaktive Anmeldung durchzuführen.

C_GenerateKey

Stellt den AES-256-Masterschlüssel bereit: validiert den Mechanismus, parst das Attribut-Template, fordert die Schlüsselerstellung im Cockpit an, bildet den zurückgegebenen Schlüsselbezeichner auf ein Handle ab und gibt das Handle an Oracle zurück.

C_FindObjects

Lokalisiert den Masterschlüssel anhand von CKA_LABEL / CKA_ID und bildet jeden passenden Schlüssel auf ein Session-Handle ab.

C_Encrypt / C_Decrypt

Wrappt / entpackt die Table- und Tablespace-Keys unter dem Masterschlüssel. Sowohl einteilige als auch mehrteilige Formen werden unterstützt; die Schicht löst das Handle in einen Schlüsselbezeichner auf, überträgt die Operation an das Cockpit und gibt das Ergebnis zurück.

Fehlerbehandlung

Die Schicht übersetzt Fehler der unteren Schichten und Transportfehler in standardmäßige Cryptoki-Rückgabecodes, sodass Oracle konsistente Ergebnisse sieht:

Bedingung	PKCS#11-Code
Cockpit nicht erreichbar / Backend-Fehler	CKR_DEVICE_ERROR
Authentifizierungsfehler	CKR_PIN_INCORRECT
Unbekanntes Objekt-Handle	CKR_OBJECT_HANDLE_INVALID
Ungültiger Parameter	CKR_ARGUMENTS_BAD
Nicht unterstützter Mechanismus	CKR_MECHANISM_INVALID
Sensitives Attribut angefordert	CKR_ATTRIBUTE_SENSITIVE

Nächste Schritte

• DuoKey-SDK-Schicht → - Wie Operationen das DuoKey Cockpit erreichen
• Objekt-Handle-Mapping → - Verstehen Sie die Handle-Übersetzung
• Kommunikationsfluss → - Sehen Sie, wie Operationen durch das System fließen