Aller au contenu principal

Mappage des handles d'objet

L'un des aspects clés de la bibliothèque DuoKey PKCS#11 est le système de mappage des handles d'objet, qui fait le pont entre les handles d'objet entiers de PKCS#11 et les identifiants de clé durables de DuoKey Cockpit.

Vue d'ensemble​

Le problème​

PKCS#11 référence les objets à l'aide de handles entiers (entiers non signés sur 32 bits), tandis que DuoKey Cockpit référence les clés à l'aide d'identifiants durables (chaînes au format UUID). Le système de mappage effectue la traduction entre les deux.

Handles PKCS#11​

  • Type : CK_OBJECT_HANDLE (entier)
  • Portée : par session (les handles sont spécifiques à la session)
  • Durée de vie : valides uniquement tant que la session est ouverte

Identifiants de clé DuoKey​

  • Type : chaîne (format UUID, par exemple xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  • Portée : durables et uniques sur l'ensemble de la plateforme
  • Durée de vie : persistante (les identifiants ne changent pas)

Fonctionnement​

Processus de mappage​

Génération des handles​

Les handles sont générés par session :

Algorithme :

  1. Attribuer le premier handle au premier objet.
  2. Incrémenter pour chaque nouvel objet.
  3. Stocker le mappage dans la table de handles de la session.

Table de mappage​

Chaque session maintient sa propre table de mappage avec deux vues :

  • Directe : handle → identifiant de clé
  • Inverse : identifiant de clé → handle (pour une recherche inverse rapide)

Opérations : insérer un nouveau mappage, rechercher l'identifiant correspondant à un handle, effectuer une recherche inverse du handle correspondant à un identifiant, et supprimer un mappage lorsqu'un objet est détruit.

Types d'objets​

Clés secrètes​

Clés AES utilisées pour les opérations de wrap / unwrap.

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

Objets de données​

Objets de métadonnées qu'Oracle utilise pour suivre les informations du keystore.

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

Cycle de vie des handles​

Création​

Les handles sont créés lorsque des objets sont trouvés (C_FindObjects), lorsqu'une clé est générée (C_GenerateKey), ou lorsqu'un objet de données est créé (C_CreateObject).

Utilisation​

Opérations qui prennent un handle : C_Encrypt / C_Decrypt (wrap / unwrap), C_GetAttributeValue et C_DestroyObject.

Nettoyage​

Les handles sont invalidés à la fermeture de la session ; un mappage individuel est retiré lorsque son objet est détruit.

Scénarios d'exemple​

Scénario 1 : trouver une clé maître existante​

  1. Oracle appelle C_FindObjects avec un modèle tel que { CKA_LABEL: "TDE-MASTER-20251219" }.
  2. La bibliothèque demande au Cockpit de localiser la clé par ce label.
  3. Le Cockpit renvoie l'identifiant de clé.
  4. La bibliothèque vérifie sa table de mappage ; l'identifiant étant nouveau, elle attribue un handle (par exemple 0x12345) et stocke le mappage.
  5. Elle renvoie le handle 0x12345 à Oracle.

Scénario 2 : wrapper une clé de tablespace​

  1. Oracle appelle C_Encrypt(session, 0x12345, tablespaceKey).
  2. La bibliothèque recherche l'identifiant de clé correspondant au handle 0x12345.
  3. La bibliothèque demande au Cockpit de wrapper la clé de tablespace sous cette clé maître (AES-CBC-PAD préservant la longueur).
  4. Le Cockpit renvoie la clé enveloppée.
  5. La bibliothèque renvoie la clé enveloppée à Oracle.

Scénario 3 : générer une nouvelle clé maître​

  1. Oracle appelle C_GenerateKey(session, mechanism, template) pour une clé AES-256.
  2. La bibliothèque demande au Cockpit de provisionner la clé.
  3. Le Cockpit renvoie le nouvel identifiant de clé.
  4. La bibliothèque attribue un handle (par exemple 0x12346) et stocke le mappage.
  5. Elle renvoie le handle 0x12346 à Oracle.

Considérations de performance​

  • Recherche : O(1) en moyenne (recherche dans une table de hachage).
  • Réutilisation des handles : si le même identifiant est demandé à nouveau, le handle existant est renvoyé afin d'éviter les mappages en double.
  • Recherche inverse : une table identifiant → handle permet des recherches inverses rapides.
  • Mémoire : les mappages sont effacés à la fermeture de la session.

Gestion des erreurs​

ScénarioRéponse
Oracle fournit un handle absent de la table de mappageCKR_OBJECT_HANDLE_INVALID
Un identifiant de clé renvoyé précédemment n'existe plus (objet supprimé entre deux opérations)CKR_DEVICE_ERROR

Bonnes pratiques​

  • Ne pas mettre en cache les handles entre les sessions — ils sont spécifiques à la session.
  • Valider les handles avant utilisation.
  • Nettoyer les mappages à la fermeture de la session.
  • Supprimer correctement avec C_DestroyObject afin que les mappages soient retirés.

Étapes suivantes​