Zum Hauptinhalt springen

Objekt-Handle-Mapping

Ein zentraler Aspekt der DuoKey-PKCS#11-Bibliothek ist das Objekt-Handle-Mapping-System, das zwischen den Integer-Objekt-Handles von PKCS#11 und den dauerhaften Schlüsselbezeichnern des DuoKey Cockpit vermittelt.

Überblick​

Das Problem​

PKCS#11 referenziert Objekte über Integer-Handles (32-Bit-Ganzzahlen ohne Vorzeichen), während das DuoKey Cockpit Schlüssel über dauerhafte Bezeichner (Zeichenketten im UUID-Format) referenziert. Das Mapping-System übersetzt zwischen beiden.

PKCS#11-Handles​

  • Typ: CK_OBJECT_HANDLE (Integer)
  • Geltungsbereich: pro Session (Handles sind sitzungsspezifisch)
  • Lebensdauer: nur gültig, solange die Session geöffnet ist

DuoKey-Schlüsselbezeichner​

  • Typ: Zeichenkette (UUID-Format, z. B. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  • Geltungsbereich: dauerhaft und plattformweit eindeutig
  • Lebensdauer: persistent (Bezeichner ändern sich nicht)

So funktioniert es​

Mapping-Prozess​

Handle-Generierung​

Handles werden pro Session generiert:

Algorithmus:

  1. Das erste Handle wird dem ersten Objekt zugewiesen.
  2. Für jedes neue Objekt wird inkrementiert.
  3. Das Mapping wird in der Handle-Tabelle der Session gespeichert.

Mapping-Tabelle​

Jede Session verwaltet ihre eigene Mapping-Tabelle mit zwei Sichten:

  • Vorwärts: Handle → Schlüsselbezeichner
  • Rückwärts: Schlüsselbezeichner → Handle (für schnelle Reverse-Lookups)

Operationen: ein neues Mapping einfügen, einen Bezeichner für ein Handle nachschlagen, ein Handle für einen Bezeichner rückwärts nachschlagen und ein Mapping löschen, wenn ein Objekt zerstört wird.

Objekttypen​

Secret Keys​

AES-Schlüssel, die für die Wrap- / Unwrap-Operationen verwendet werden.

Handle: 0x12345
Type:   CKO_SECRET_KEY
Algorithm: AES-256

Data Objects​

Metadatenobjekte, die Oracle zur Verfolgung von Keystore-Informationen verwendet.

Handle: 0x12346
Type:   CKO_DATA
Label:  ORACLE.TDE.CDB$ROOT.MK.IDENT

Handle-Lebenszyklus​

Erstellung​

Handles werden erstellt, wenn Objekte gefunden werden (C_FindObjects), wenn ein Schlüssel generiert wird (C_GenerateKey) oder wenn ein Datenobjekt erstellt wird (C_CreateObject).

Verwendung​

Operationen, die ein Handle entgegennehmen: C_Encrypt / C_Decrypt (Wrap / Unwrap), C_GetAttributeValue und C_DestroyObject.

Bereinigung​

Handles werden ungültig, wenn die Session geschlossen wird; ein einzelnes Mapping wird entfernt, wenn das zugehörige Objekt zerstört wird.

Beispielszenarien​

Szenario 1: Einen vorhandenen Masterschlüssel finden​

  1. Oracle ruft C_FindObjects mit einem Template wie { CKA_LABEL: "TDE-MASTER-20251219" } auf.
  2. Die Bibliothek bittet das Cockpit, den Schlüssel anhand dieses Labels zu lokalisieren.
  3. Das Cockpit gibt den Schlüsselbezeichner zurück.
  4. Die Bibliothek prüft ihre Mapping-Tabelle; der Bezeichner ist neu, also weist sie ein Handle zu (z. B. 0x12345) und speichert das Mapping.
  5. Sie gibt das Handle 0x12345 an Oracle zurück.

Szenario 2: Einen Tablespace-Key wrappen​

  1. Oracle ruft C_Encrypt(session, 0x12345, tablespaceKey) auf.
  2. Die Bibliothek schlägt den Schlüsselbezeichner für das Handle 0x12345 nach.
  3. Die Bibliothek bittet das Cockpit, den Tablespace-Key unter diesem Masterschlüssel zu wrappen (längenerhaltendes AES-CBC-PAD).
  4. Das Cockpit gibt den gewrappten Schlüssel zurück.
  5. Die Bibliothek gibt den gewrappten Schlüssel an Oracle zurück.

Szenario 3: Einen neuen Masterschlüssel generieren​

  1. Oracle ruft C_GenerateKey(session, mechanism, template) für einen AES-256-Schlüssel auf.
  2. Die Bibliothek bittet das Cockpit, den Schlüssel bereitzustellen.
  3. Das Cockpit gibt den neuen Schlüsselbezeichner zurück.
  4. Die Bibliothek weist ein Handle zu (z. B. 0x12346) und speichert das Mapping.
  5. Sie gibt das Handle 0x12346 an Oracle zurück.

Leistungsüberlegungen​

  • Lookup: O(1) im Durchschnittsfall (Hash-Map-Lookup).
  • Handle-Wiederverwendung: Wird derselbe Bezeichner erneut angefordert, wird das vorhandene Handle zurückgegeben, um doppelte Mappings zu vermeiden.
  • Reverse Lookup: Eine Bezeichner-→-Handle-Map ermöglicht schnelle Reverse-Lookups.
  • Speicher: Mappings werden gelöscht, wenn die Session geschlossen wird.

Fehlerbehandlung​

SzenarioAntwort
Oracle übergibt ein Handle, das nicht in der Mapping-Tabelle enthalten istCKR_OBJECT_HANDLE_INVALID
Ein zuvor zurückgegebener Schlüsselbezeichner existiert nicht mehr (Objekt zwischen Operationen gelöscht)CKR_DEVICE_ERROR

Bewährte Praktiken​

  • Handles nicht über Sessions hinweg zwischenspeichern — sie sind sitzungsspezifisch.
  • Handles vor der Verwendung validieren.
  • Mappings beim Schließen der Session bereinigen.
  • Ordnungsgemäß löschen mit C_DestroyObject, damit Mappings entfernt werden.

Nächste Schritte​