Zum Hauptinhalt springen

Funktionsweise

Wie sich die DuoKey-PKCS#11-Bibliothek verhält — das Proxy-Modell, Sitzungen, Login, sensible Attribute, Konfigurationsrangfolge und bekannte Eigenheiten.

Gilt für:
PKCS#11 (Cryptoki) 2.40DuoKey-PKCS#11-Bibliothek

Diese Hinweise ergänzen den Überblick und die Funktionsabdeckung. Sie beschreiben das Verhalten des Providers, damit Integratoren Fehler, Sitzungen und Konfiguration nachvollziehen können.

Das Proxy-Modell​

Die Bibliothek führt keine Kryptografie lokal aus und hält keine Schlüssel. Jeder Cryptoki-Aufruf wird in eine einzelne HTTPS-Anfrage an das DuoKey Cockpit umgewandelt, das die Operation gegen den Mandanten-Vault oder das zugrunde liegende HSM ausführt und das Ergebnis zurückgibt. Die Bibliothek kodiert Payloads nur und leitet sie weiter; Schlüsselmaterial überschreitet die PKCS#11-Grenze nie zum Anwendungs-Host.

  • Nur serielle Sitzungen. Der gesamte Bibliothekszustand wird hinter einem einzigen globalen Lock serialisiert, und nur serielle Sitzungen werden unterstützt — C_OpenSession lehnt jede Anfrage ohne CKF_SERIAL_SESSION mit CKR_SESSION_PARALLEL_NOT_SUPPORTED ab. Der langsame Netzwerk-Roundtrip wird ausgeführt, ohne den Lock zu halten, sodass ein langsames Backend andere Aufrufe nicht blockiert.
  • Objekt-Handles. PKCS#11-Ganzzahl-Handles werden serverseitigen Objektkennungen zugeordnet. Interning dedupliziert nach Server-ID, sodass das erneute Auffinden desselben Objekts denselben Handle zurückgibt. C_DestroyObject löscht das Objekt im Cockpit und vergisst anschließend den lokalen Handle.

Login & Authentifizierung​

Es wird keine PIN übertragen

C_Login sendet keine PIN — die Argumente pPin / ulPinLen werden ignoriert. Die Backend-Authentifizierung erfolgt pro Anfrage über das Bearer-Access-Token aus der Konfiguration. C_Login akzeptiert nur CKU_USER und CKU_CONTEXT_SPECIFIC (die SO-Rolle gibt CKR_USER_TYPE_INVALID zurück) und versetzt die Sitzung lediglich in den Benutzerzustand, sodass die Anwendung fortfahren kann. C_GenerateKey und C_GenerateKeyPair erfordern den angemeldeten Zustand.

Attribute & sensibles Material​

C_GetAttributeValue antwortet aus einem zwischengespeicherten Deskriptor und folgt dem standardmäßigen zweistufigen Cryptoki-Pufferprotokoll (ein Null-Wertzeiger gibt die erforderliche Länge zurück; ein zu kleiner Puffer gibt CKR_BUFFER_TOO_SMALL zurück).

  • CKA_VALUE gibt immer CKR_ATTRIBUTE_SENSITIVE zurück — rohes Schlüsselmaterial existiert ausschließlich im Backend.
  • Schlüssel melden sinnvolle Standardwerte: CKA_TOKEN = true, CKA_SENSITIVE = true, CKA_EXTRACTABLE = false, CKA_NEVER_EXTRACTABLE = true, CKA_MODIFIABLE = false.
  • Ein nicht erkannter Attributtyp gibt CKR_ATTRIBUTE_TYPE_INVALID zurück. Nicht erkannte Attribute in Suchfiltern und Schlüsselgenerierungs-Templates werden stillschweigend verworfen.

Behandlung von AES-GCM​

Bei AES-GCM wird das Authentifizierungs-Tag an den Chiffretext angehängt (ciphertext || tag) und beim Entschlüsseln wieder abgetrennt, sodass Aufrufer einen einzigen opaken Blob sehen.

Wire-Protokoll​

Jede Cryptoki-Operation ist eine einzelne HTTPS-Anfrage an die eine konfigurierte server_url, authentifiziert mit dem Bearer-Access-Token. Kryptografische Fehler werden so zurückgegeben, dass die Bibliothek den exakten Cryptoki-Rückgabewert statt eines generischen Transportfehlers abbilden kann.

API-Referenz
Das detaillierte Anfrage-/Antwort-Protokoll ist separat in den Entwicklerdokumenten → DKE-API dokumentiert.

Konfigurationsrangfolge​

Die Bibliothek liest eine TOML-Datei aus DKE_PKCS11_CONF; Umgebungsvariablen überschreiben die Datei. Die Rangfolge ist Umgebungsvariable (nicht leer) > TOML-Datei > eingebauter Standard. Ist keine Datei gesetzt, wird die Konfiguration vollständig aus Umgebungsvariablen aufgebaut (mindestens DKE_PKCS11_SERVER_URL ist erforderlich).

  • verify_tls = false deaktiviert die TLS-Zertifikatsvalidierung — nur zum Testen.
  • Die Protokollierung wird bei C_Initialize aus logging_level / logging_folder initialisiert.

Siehe Überblick → Konfiguration für das vollständige pkcs11.toml-Schema und die Variablenliste.

Bekannte Eigenheiten & Vorbehalte​

Randfälle bei Mechanismen
  • CKM_SHA_1 wird von C_GetMechanismList bekanntgegeben, aber ein SHA-1-Digest wird vom Backend abgelehnt (CKR_MECHANISM_INVALID) — es werden nur SHA-256/384/512 berechnet.
  • Verschlüsselung und Entschlüsselung verwenden dieselbe Vault-Primitive, daher ist der Cryptoki-Mechanismus empfehlend — die Round-Trip-Integrität ist für die vom Consumer gespeicherten opaken Blobs garantiert.
Keine lokale Objekterstellung

C_CreateObject, C_CopyObject und C_SetAttributeValue werden nicht unterstützt (CKR_FUNCTION_NOT_SUPPORTED). Objekte werden über die Schlüsselgenerierungsoperationen (C_GenerateKey / C_GenerateKeyPair) erstellt oder mit C_FindObjects entdeckt, niemals attributweise auf dem Client zusammengesetzt.

Consumer verwenden unterschiedliche Mechanismen

Da dies ein allgemeiner Cryptoki-Provider ist, werden die bekanntgegebenen Mechanismen (AES / RSA / EC / SHA / HMAC) je nach Consumer genutzt. Oracle TDE verwendet ausschließlich AES — sein Masterschlüssel ist AES256 — siehe Oracle TDE → Cockpit v2.

Siehe auch