Konfiguration

Gegenüber dem DuoKey Cockpit wird der PKCS#11-Provider über eine pkcs11.toml-Datei sowie optionale DKE_PKCS11_*-Umgebungsvariablen konfiguriert. Die Datei enthält nur zwei wesentliche Angaben — die Cockpit-Proxy-URL und das access_guid-Bearer-Token — denn das Cockpit löst App und Mandant serverseitig auf.

Kanonische Referenz

Diese Seite beschreibt das Konfigurationsmodell auf Architekturebene. Das vollständige Schema, die Standardwerte und die Migrationszuordnung v1 → v2 finden Sie unter PKCS#11-Provider-Konfiguration (pkcs11.toml).

Überblick

Konfigurationsdatei

Der Provider liest seine Konfiguration bei C_Initialize aus dem Pfad, der in der Umgebungsvariablen DKE_PKCS11_CONF angegeben ist. Oracle setzt diese Variable im Profil des Oracle-Benutzers (oder im OKV-Wrapper). Ein üblicher Installationspfad ist:

/usr/local/okv/hsm/generic/pkcs11.toml

Schema

# pkcs11.toml — DuoKey PKCS#11 provider configuration

[http_config]
# Full Cockpit proxy URL for this Oracle TDE app (required).
# It already contains the app identity and access_guid, so no separate
# endpoint, tenant, or credential fields are needed.
server_url = "https://cockpit.example.com/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"

# Bearer token used to authenticate every request — the app's access_guid.
access_token = "ACCESS_GUID"

# HTTP request timeout in seconds (default: 30).
timeout_secs = 30

# Verify the server's TLS certificate (default: true).
# Set to false ONLY for testing against self-signed certificates.
verify_tls = true

[pkcs11]
# Id of the single virtual slot the library presents (default: 0).
slot_id = 0

# Logging level: "error" | "warn" | "info" | "debug" | "trace" (default: "info").
logging_level = "info"

# Optional folder for provider log files (default: none — logs to stderr).
logging_folder = "/var/log/dke-pkcs11"

[http_config] — Verbindung zum Cockpit

Schlüssel	Typ	Standard	Zweck
server_url	String	(erforderlich)	Vollständige Cockpit-Proxy-URL für diese App. Sie enthält bereits die App-Identität und die access_guid, sodass keine separaten Endpunkt- oder Mandantenfelder erforderlich sind.
access_token	String	""	Bearer-Token, das als Authorization: Bearer … gesendet wird. Für Oracle TDE ist dies die access_guid der App.
timeout_secs	Integer	30	HTTP-Timeout pro Anfrage.
verify_tls	Boolean	true	TLS-Zertifikatsprüfung. In der Produktion auf true belassen.

[pkcs11] — lokales Provider-Verhalten

Schlüssel	Typ	Standard	Zweck
slot_id	Integer	0	Id des einzelnen virtuellen Slots, der Oracle präsentiert wird.
logging_level	String	"info"	Ausführlichkeit der Provider-Protokollierung.
logging_folder	String	(keiner)	Verzeichnis für Provider-Protokolle; falls nicht gesetzt, gehen die Protokolle an stderr.

Authentifizierungsmodell

• Ein einziges Zugangsdatum. Die Authentifizierung erfolgt über ein einzelnes access_guid-Bearer-Token, das in server_url eingebettet und als access_token wiederholt wird. Es gibt keinen OAuth2-Client-Credentials-Flow, keine client_id / client_secret, keinen Benutzernamen / Passwort und keine OpenID-Connect-Discovery.
• Kein Mandantenfeld. Das Cockpit löst den Mandanten serverseitig anhand der App-Identität in der URL auf — es gibt clientseitig weder eine Mandanten-Id noch einen Mandanten-Header.
• Kein Vault-Feld. Der zugrunde liegende Vault / Keystore wird von der App im Cockpit verwaltet und nicht clientseitig konfiguriert.

pkcs11.toml schützen

Die access_guid in server_url / access_token ist ein Bearer-Zugangsdatum. Beschränken Sie den Dateizugriff auf den Oracle-OS-Benutzer — zum Beispiel chmod 600, im Besitz von oracle — und rotieren Sie das Access-Token der App im Cockpit, falls es jemals offengelegt wird.

Überschreibungen per Umgebungsvariablen

Umgebungsvariablen haben Vorrang vor der Datei, sodass Sie eine Basis-pkcs11.toml beibehalten und pro Host überschreiben können:

Umgebungsvariable	Überschreibt
DKE_PKCS11_CONF	Pfad zur pkcs11.toml-Datei
DKE_PKCS11_SERVER_URL	http_config.server_url
DKE_PKCS11_ACCESS_TOKEN	http_config.access_token
DKE_PKCS11_VERIFY_TLS	http_config.verify_tls (0 / false / no = deaktiviert)
DKE_PKCS11_SLOT_ID	pkcs11.slot_id
DKE_PKCS11_LOGGING_LEVEL	pkcs11.logging_level
DKE_PKCS11_LOGGING_FOLDER	pkcs11.logging_folder

Wenn kein Dateipfad angegeben ist, kann die Bibliothek ihre Konfiguration vollständig aus Umgebungsvariablen aufbauen, sofern mindestens die Server-URL und das Access-Token gesetzt sind.

Bezug der Werte

Sie stellen diese Werte nicht von Hand zusammen. Öffnen Sie im Cockpit die Oracle-TDE-App und verwenden Sie deren Deployment-Bundle — das Cockpit generiert die pkcs11.toml (mit der korrekten server_url und access_guid), die Umgebungs-Exports und die Oracle-SQL-Skripte zum Herunterladen.

Validierung

Die Bibliothek validiert die Konfiguration während der Initialisierung:

• Die Server-URL ist vorhanden und wohlgeformt.
• Das Access-Token ist vorhanden.
• Bei einem Fehler gibt die Initialisierung CKR_DEVICE_ERROR (Verbindung / Konfiguration) oder CKR_PIN_INCORRECT (Authentifizierung) zurück.

Bewährte Sicherheitspraktiken

• Niemals pkcs11.toml oder die access_guid in die Versionsverwaltung committen.
• Dateiberechtigungen auf den Oracle-OS-Benutzer beschränken (chmod 600).
• Das Access-Token der App im Cockpit nach einem regelmäßigen Zeitplan rotieren — und sofort, falls es offengelegt wird.
• verify_tls = true beibehalten und TLS 1.2+ für alle Verbindungen verwenden.

Nächste Schritte

• Kommunikationsfluss → - Sehen Sie, wie die Konfiguration verwendet wird
• Architekturüberblick → - Verstehen Sie die Gesamtarchitektur
• PKCS#11-Provider-Konfiguration (pkcs11.toml) → - Das vollständige Schema und die v1 → v2-Zuordnung