Zum Hauptinhalt springen

Erste Schritte

Diese Anleitung ist der Cockpit-v2-Schnelleinstieg zur Integration von Oracle Transparent Data Encryption (TDE) mit DuoKey. Am Ende verwendet Oracle DuoKey als externen HSM-Keystore für seinen TDE-Masterschlüssel, wobei der Masterschlüssel niemals auf dem Datenbankhost verbleibt.

Cockpit v2

Diese Seite beschreibt die Cockpit v2-Integration: ein einziges access_guid-Bearer-Token, eine pkcs11.toml-Konfigurationsdatei und den libdke_pkcs11.so-Provider. Oracle TDE ist ausschließlich mit Cockpit v2 verfügbar — in der vorherigen Generation (Cockpit v1) existierte es nicht.

Konzepte und kanonische Konfiguration

Für das konzeptionelle Modell siehe die Installationsanleitung. Die maßgebliche Konfigurationsreferenz ist PKCS#11-Provider-Konfiguration (pkcs11.toml).

Wie alles zusammenspielt​

Oracle führt die Bulk-Verschlüsselung von Tabellen und Tablespaces weiterhin selbst in Hardware mit AES-NI durch. DuoKey liegt nur auf dem Masterschlüssel-Pfad – Öffnen des Keystores, SET KEY sowie Wrap/Unwrap der Tablespace-Schlüssel unter dem Masterverschlüsselungsschlüssel (MEK).

┌─────────────────────────────────────┐
│ Oracle Database Server              │
│                                     │
│   Oracle TDE                        │
│   (bulk AES table/tablespace        │
│    crypto stays local, AES-NI)      │
│        │ PKCS#11 (master-key path)  │
│        ▼                            │
│   DuoKey PKCS#11 provider           │
│   libdke_pkcs11.so / dke_pkcs11.dll │
│        │ HTTPS (one call per op)    │
└────────┼────────────────────────────┘
         ▼
   DuoKey Cockpit (v2 proxy endpoint)
         │
         ▼
   Tenant vault / HSM
   (Securosys HSM in production)

Voraussetzungen​

Oracle Database​

  • Oracle Database 11g R2, 12c, 18c, 19c, 21c oder 23ai
  • Lizenzierte Option Oracle Advanced Security
  • DBA-Zugriff mit SYSDBA und der Systemberechtigung ADMINISTER KEY MANAGEMENT
Oracle-11g-Patch

Stellen Sie für Oracle 11g R2 sicher, dass Patch 18948524 angewendet ist.

DuoKey​

  • Zugriff auf Ihre Cockpit v2-Weboberfläche von DuoKey
  • Die von DuoKey bereitgestellte DuoKey-PKCS#11-Provider-Bibliothek
  • Netzwerkverbindung vom Datenbankserver zum Cockpit-Host über HTTPS (Port 443)
Build-Ziel für die Bibliothek

Der Provider muss für Oracle Linux 8 / glibc 2.28 gebaut sein. Eine gegen eine neuere glibc kompilierte Bibliothek lässt sich nicht laden, und Oracle meldet ORA-28353 ohne zusätzliche Protokolleinträge. Verwenden Sie den von DuoKey für Ihre Plattform bereitgestellten Build.

System​

  • Linux-Server (Oracle Linux 8 empfohlen)
  • Root- oder sudo-Zugriff sowie das Konto des Oracle-Instanz-Eigentümers (oracle)

Schritt 1: Die Oracle-TDE-App im Cockpit erstellen​

  1. Melden Sie sich an Ihrer DuoKey-Cockpit-v2-URL an.
  2. Erstellen (oder aktivieren) Sie eine Oracle TDE-App für diese Datenbank. Die App stellt einen initialen aktiven Masterschlüssel (AES-256) bereit und stellt eine access_guid aus.
  3. Öffnen Sie die App und laden Sie das Deployment-Bundle herunter. Das Cockpit generiert alles, was Sie für diese Datenbank benötigen:
    • die Datei pkcs11.toml (mit der korrekten server_url und access_guid),
    • die Umgebungs-Exports (einschließlich DKE_PKCS11_CONF),
    • die Oracle-SQL-Skripte.
Ein einziger Berechtigungsnachweis

Cockpit v2 verwendet ein einziges access_guid-Bearer-Token, eingebettet in den Pfad der server_url. Es gibt kein OAuth2, keine Client-ID/kein Secret, keinen Benutzernamen/kein Passwort und keinen Mandanten-Header – der Mandant wird serverseitig aufgelöst. Behandeln Sie das Bundle als vertraulich und übertragen Sie es niemals in die Versionskontrolle.

Schritt 2: Konnektivität prüfen​

Bestätigen Sie vom Datenbankserver aus, dass der Cockpit-Host über HTTPS erreichbar ist:

curl -v https://<cockpit-host>

Ein GET auf die Proxy-URL der App fungiert als Bereitschaftsprüfung (Readiness-Probe). Schlägt die Verbindung fehl, prüfen Sie, ob Port 443 offen ist, ob DNS auflöst und ob die TLS-Zertifikate vertrauenswürdig sind (fügen Sie bei einem On-Premise-Cockpit dessen CA dem Trust Store des Betriebssystems hinzu).

Schritt 3: Den DuoKey-PKCS#11-Provider installieren​

Legen Sie die Bibliothek unverändert in das PKCS#11-Herstellerverzeichnis von Oracle. Oracle lädt das erste Shared Object, das es im Hersteller-/Versionsverzeichnis findet, unter beliebigem Dateinamen – benennen Sie sie nicht in libpkcs11.so um.

# Standard Oracle Database location
sudo mkdir -p /opt/oracle/extapi/64/hsm/DuoKey/1.0
sudo cp libdke_pkcs11.so /opt/oracle/extapi/64/hsm/DuoKey/1.0/

# Set ownership for the Oracle user
sudo chown -R oracle:oinstall /opt/oracle/extapi/64/hsm/DuoKey
sudo chmod -R 755 /opt/oracle/extapi/64/hsm/DuoKey

Unter Windows ist das Artefakt dke_pkcs11.dll. Bei Oracle Key Vault lautet der Herstellerpfad stattdessen /usr/local/okv/hsm/generic/.

Das Herstellerverzeichnis sauber halten

Oracle lädt das erste .so in /opt/oracle/extapi/64/hsm/DuoKey/1.0/ unabhängig von seinem Namen. Belassen Sie nur die DuoKey-Bibliothek in diesem Verzeichnis, damit der korrekte Provider geladen wird.

Schritt 4: Die Konfigurationsdatei ablegen​

Kopieren Sie die pkcs11.toml aus dem Deployment-Bundle an einen geschützten Ort und verweisen Sie den Provider über die Umgebungsvariable DKE_PKCS11_CONF (gesetzt im Profil des Oracle-Benutzers) darauf. Beschränken Sie die Datei auf den Oracle-Benutzer:

sudo chown oracle:oinstall /etc/dke/pkcs11.toml
sudo chmod 600 /etc/dke/pkcs11.toml
export DKE_PKCS11_CONF=/etc/dke/pkcs11.toml

Die pkcs11.toml aus dem Bundle enthält bereits die [http_config]-server_url (mit app_id und access_guid), das access_token, timeout_secs, verify_tls sowie die [pkcs11]-Werte slot_id, logging_level und logging_folder. Einzelne Felder können pro Host mit DKE_PKCS11_*-Umgebungsvariablen überschrieben werden. Das vollständige Schema finden Sie unter PKCS#11-Provider-Konfiguration (pkcs11.toml).

Schritt 5: Oracle für HSM-basiertes TDE konfigurieren​

Verbinden Sie sich als SYSDBA und führen Sie das SQL aus dem Deployment-Bundle aus. Der Keystore-Typ ist HSM.

5.1 Wallet-Root und TDE-Konfiguration setzen​

ALTER SYSTEM SET WALLET_ROOT='<oracle-base>/admin/<sid>/wallet' SCOPE=SPFILE;
-- Restart to apply WALLET_ROOT
SHUTDOWN IMMEDIATE;
STARTUP;

ALTER SYSTEM SET TDE_CONFIGURATION='KEYSTORE_CONFIGURATION=HSM' SCOPE=BOTH;

5.2 Den HSM-Keystore öffnen​

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
  IDENTIFIED BY "<pin>"
  CONTAINER = ALL;
Die PIN ist beratend

Beim DuoKey-Provider ist der eigentliche Berechtigungsnachweis die access_guid in pkcs11.toml; der IDENTIFIED BY-Wert hat beratenden Charakter. Sie können den Keystore auch mit IDENTIFIED BY EXTERNAL STORE öffnen, wenn der Berechtigungsnachweis in einem externen Speicher gehalten wird.

5.3 Den TDE-Masterschlüssel setzen​

ADMINISTER KEY MANAGEMENT SET KEY
  IDENTIFIED BY "<pin>"
  WITH BACKUP
  CONTAINER = ALL;

Der Masterschlüssel ist AES-256.

Mandantenfähigkeit (CDB / PDB)

Setzen Sie zuerst den Schlüssel für die Root, anschließend für jede PDB in ihrer eigenen Session. Eine PDB, die während eines CONTAINER=ALL-Rekeys nicht OPEN READ WRITE ist, löst ORA-46664 aus.

ALTER SESSION SET CONTAINER = <pdb_name>;
ADMINISTER KEY MANAGEMENT SET KEY IDENTIFIED BY "<pin>" WITH BACKUP;

Schritt 6: Verifizieren​

SELECT wrl_type, status, wallet_type FROM V$ENCRYPTION_WALLET;

Erwartet:

  • WRL_TYPE: HSM
  • STATUS: OPEN

Erstellen Sie einen verschlüsselten Tablespace, um die Funktionsfähigkeit durchgängig zu bestätigen:

CREATE TABLESPACE encrypted_ts
  DATAFILE '<oradata-path>/encrypted_ts01.dbf' SIZE 128M
  ENCRYPTION USING 'AES256' DEFAULT STORAGE(ENCRYPT);

Bestätigen Sie anschließend, dass die Schlüsseloperationen im Cockpit-Audit-Log für diese App erscheinen.

Schlüsselrotation​

Rotieren Sie den Masterschlüssel über das Cockpit. Bei der Rotation wird ein neuer Schlüssel aktiv gesetzt und der vorherige Schlüssel deaktiviert, aber beibehalten, sodass Tablespace-Schlüssel, die unter dem alten MEK ge-wrappt wurden, entschlüsselbar bleiben. Das Cockpit liefert das Oracle-Rotations-SQL (ADMINISTER KEY MANAGEMENT SET KEY … WITH BACKUP).

Nächste Schritte​

Fehlerbehebung​

Bibliothek lässt sich nicht laden (ORA-28353, kein Log) – die Bibliothek wurde gegen eine neuere glibc gebaut. Verwenden Sie den Oracle-Linux-8-/glibc-2.28-Build von DuoKey.

ORA-28365: wallet is not open – Öffnen Sie den Keystore erneut:

ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN
  IDENTIFIED BY "<pin>" CONTAINER = ALL;

ORA-46664 bei einem mandantenfähigen Rekey – eine Ziel-PDB war nicht OPEN READ WRITE. Öffnen Sie die PDB (oder setzen Sie den Schlüssel einzeln) und versuchen Sie es erneut.

Konnektivität – prüfen Sie Port 443 zu <cockpit-host>, die server_url in pkcs11.toml und (On-Premise) das CA-Vertrauen. Provider-Logs werden in den logging_folder geschrieben (Standard /var/log/dke-pkcs11).

Support​