Bibliothèque PKCS#11 de DuoKey

S'applique à :

PKCS#11 (Cryptoki) 2.40Oracle TDEOracle Key VaultDuoKey Cockpit

Introduction

La bibliothèque PKCS#11 de DuoKey est une bibliothèque partagée native qui implémente le standard PKCS#11 (Cryptoki) 2.40. Des applications telles qu'Oracle Database TDE et Oracle Key Vault la chargent comme n'importe quel fournisseur HSM et appellent les fonctions standard C_*. La bibliothèque n'effectue aucune cryptographie localement — chaque opération est envoyée en HTTPS au DuoKey Cockpit, qui l'exécute auprès du coffre du tenant ou du HSM sous-jacent. Le matériel de clé ne réside jamais sur l'hôte de l'application.

Distribution

Propriété	Valeur
Artefact	Linux `libdke_pkcs11.so` · Windows `dke_pkcs11.dll`
Norme	PKCS#11 (Cryptoki) 2.40
Symbole exporté	`C_GetFunctionList` — le seul symbole qu'un fournisseur PKCS#11 doit exporter ; il retourne la table complète des fonctions
Cryptographie locale	Aucune — toutes les opérations sont relayées vers le DuoKey Cockpit
Identifiant fabricant	DuoKey

Architecture

Une application ne communique jamais directement avec le Cockpit. Elle charge la bibliothèque, qui transforme chaque appel Cryptoki en une unique requête vers un point de terminaison proxy du Cockpit ; le Cockpit effectue l'opération et retourne le résultat.

Points de conception

Aucune cryptographie locale

La bibliothèque ne détient aucune clé et n'exécute aucune cryptographie. Elle se contente d'encoder les payloads et de les transmettre ; le backend effectue le travail.

Un seul symbole exporté

Seul C_GetFunctionList est exporté ; toutes les autres fonctions sont atteintes via la table retournée.

Sessions série

Tout l'état de la bibliothèque est sérialisé derrière un verrou unique, et seules les sessions série sont prises en charge ; les sessions parallèles sont rejetées avec CKR_SESSION_PARALLEL_NOT_SUPPORTED.

Correspondance des handles d'objets

Les handles entiers PKCS#11 correspondent à des identifiants d'objets côté serveur ; les descripteurs sont mis en cache et dédupliqués afin que le même objet retourne toujours le même handle.

Authentification par jeton, sans PIN

C_Login ne transmet aucun PIN — il fait simplement passer la session à l'état utilisateur. L'authentification repose sur un jeton porteur par requête issu de la configuration.

Couverture fonctionnelle

La bibliothèque implémente le sous-ensemble de Cryptoki nécessaire pour gérer et utiliser des clés via le Cockpit — uniquement des opérations en une seule partie (single-part). La table complète par fonction se trouve sur la page Couverture des fonctions ; voici le résumé :

Catégorie	Fonctions implémentées
Usage général	`C_GetFunctionList`, `C_Initialize`, `C_Finalize`, `C_GetInfo`
Slot et token	`C_GetSlotList`, `C_GetSlotInfo`, `C_GetTokenInfo`, `C_GetMechanismList`, `C_GetMechanismInfo`
Session	`C_OpenSession`, `C_CloseSession`, `C_CloseAllSessions`, `C_GetSessionInfo`, `C_Login`, `C_Logout`
Objets	`C_FindObjectsInit` / `C_FindObjects` / `C_FindObjectsFinal`, `C_GetAttributeValue`, `C_DestroyObject`
Chiffrement / Déchiffrement	`C_EncryptInit` / `C_Encrypt`, `C_DecryptInit` / `C_Decrypt` (single-part)
Signature / Vérification / Digest	`C_Sign`, `C_Verify`, `C_Digest` (single-part)
Gestion des clés	`C_GenerateKey`, `C_GenerateKeyPair`, `C_WrapKey`, `C_UnwrapKey`
Aléatoire	`C_GenerateRandom` (`C_SeedRandom` is accepted and ignored)

Non pris en charge (conception single-part)

Les opérations multi-parties / en flux (*_Update / *_Final), la cryptographie double-fonction, C_DeriveKey, la création/copie/modification d'attributs d'objets (C_CreateObject, C_CopyObject, C_SetAttributeValue), et l'administration des tokens/PIN (C_InitToken, C_InitPIN, C_SetPIN) retournent CKR_FUNCTION_NOT_SUPPORTED. C_GetFunctionStatus et C_CancelFunction retournent CKR_FUNCTION_NOT_PARALLEL. Les opérations sur les clés maîtres sont en une seule partie par construction, ces fonctions sont donc volontairement omises.

Mécanismes

C_GetMechanismList annonce les familles suivantes (C_GetMechanismInfo définit également CKF_HW). Voir Couverture des fonctions pour la liste exacte et les plages de tailles de clé.

Famille	Mécanismes	Opérations
AES	`CKM_AES_KEY_GEN`, `CKM_AES_ECB/CBC/CBC_PAD`, `CKM_AES_GCM`, `CKM_AES_KEY_WRAP(_PAD)`	génération, chiffrement/déchiffrement, encapsulation/désencapsulation
RSA	`CKM_RSA_PKCS_KEY_PAIR_GEN`, `CKM_RSA_PKCS`, `CKM_RSA_PKCS_OAEP`, `CKM_RSA_PKCS_PSS`, `CKM_SHAn_RSA_PKCS`	génération, chiffrement/déchiffrement, signature/vérification, encapsulation/désencapsulation
EC	`CKM_EC_KEY_PAIR_GEN`, `CKM_ECDSA`, `CKM_ECDSA_SHA256/384`	génération, signature/vérification
Digest	`CKM_SHA_1`, `CKM_SHA256/384/512`	digest (SHA-256/384/512 au backend)
HMAC	`CKM_SHA256/384/512_HMAC`	signature/vérification

Les mécanismes utilisés dépendent du consommateur

Il s'agit d'un fournisseur Cryptoki généraliste, qui annonce donc AES, RSA, EC, SHA et HMAC. Chaque application n'utilise que ce dont elle a besoin. Par exemple, Oracle TDE utilise uniquement AES — sa clé maître est en AES256 et il n'utilise jamais RSA ni EC (voir Oracle TDE → Cockpit v2). D'autres intégrations peuvent utiliser RSA ou EC.

Objets et attributs

Classes d'objets : CKO_DATA, CKO_CERTIFICATE, CKO_PUBLIC_KEY, CKO_PRIVATE_KEY, CKO_SECRET_KEY, CKO_DOMAIN_PARAMETERS.
Types de clé : CKK_AES, CKK_RSA, CKK_EC, CKK_GENERIC_SECRET, CKK_DSA, CKK_DH, CKK_SHA256/384/512_HMAC.
Les clés sont adressées par CKA_LABEL et CKA_ID ; C_GetAttributeValue répond à partir d'un descripteur mis en cache.
CKA_VALUE n'est jamais retourné — il signale CKR_ATTRIBUTE_SENSITIVE, car le matériel de clé brut ne réside que dans le backend. Les clés retournées sont marquées non extractibles et sensibles.

Configuration

La bibliothèque lit un fichier TOML dont le chemin est donné par DKE_PKCS11_CONF (Oracle / OKV le définit dans l'environnement du portefeuille). Les variables d'environnement remplacent le fichier.

pkcs11.tomlTOML

[http_config]
server_url = "https://<cockpit-host>/api/apps/<app_id>/tde/pkcs11/<access_guid>"
access_token = "<access_guid>" # sent as the bearer token
timeout_secs = 30
verify_tls = true

[pkcs11]
slot_id = 0
logging_level = "info"
logging_folder = "/var/log/dke-pkcs11"

Variable d'environnement	Remplace
`DKE_PKCS11_CONF`	Chemin du fichier TOML (si non défini, la configuration est construite à partir des variables ci-dessous)
`DKE_PKCS11_SERVER_URL`	`http_config.server_url`
`DKE_PKCS11_ACCESS_TOKEN`	`http_config.access_token`
`DKE_PKCS11_VERIFY_TLS`	`http_config.verify_tls`
`DKE_PKCS11_SLOT_ID`	`pkcs11.slot_id`
`DKE_PKCS11_LOGGING_LEVEL`	`pkcs11.logging_level`
`DKE_PKCS11_LOGGING_FOLDER`	`pkcs11.logging_folder`

Conservez la vérification activée

verify_tls vaut true par défaut. Ne le définissez sur false que pour les tests avec des certificats auto-signés — cela désactive la validation des certificats TLS.

Consommateurs

Oracle Database TDE

Charge la bibliothèque depuis /opt/oracle/extapi/64/pkcs11/ pour stocker la clé maître TDE dans DuoKey.

Oracle Key Vault (OKV)

Mode HSM — la bibliothèque est référencée depuis okv_hsm.conf en tant que fournisseur PKCS#11 générique.

Pas cette bibliothèque

Microsoft SQL Server EKM utilise un fournisseur distinct (une DLL CNG Key Storage Provider), et non la bibliothèque PKCS#11 de DuoKey. Voir le guide SQL EKM.

Introduction​

Distribution​

Architecture​

Points de conception​