Aller au contenu principal

Flux de communication

Comprendre le flux de communication aide à diagnostiquer les problèmes et à optimiser les performances. Cette page offre une vue d'ensemble de la manière dont les opérations transitent dans le système, depuis Oracle Database vers DuoKey Cockpit et retour.

Référence API : les endpoints d'API détaillés ainsi que les formats de requête/réponse sont documentés séparément dans la documentation développeur.

Vue d'ensemble​

Flux d'opération typique​

Flux d'initialisation​

Étapes :

  1. Oracle appelle C_Initialize() : l'initialisation de la bibliothèque commence
  2. Lecture de la configuration : la bibliothèque lit server_url et access_guid depuis pkcs11.toml
  3. Authentification : la bibliothèque présente son jeton bearer access_guid au Cockpit lors de sa première requête
  4. Validation côté serveur : le Cockpit valide le jeton et résout le tenant à partir de l'identité de l'application ; aucun échange de jeton distinct n'est effectué
  5. Vérification du coffre : vérifie l'accès au coffre spécifié
  6. Retour de succès : la bibliothèque est prête pour les opérations

Flux de création de session​

Étapes :

  1. Oracle appelle C_OpenSession() : demande une nouvelle session
  2. Validation du slot : s'assure que l'ID de slot est valide
  3. Création de la session : crée l'objet session interne
  4. Initialisation des tables : crée la table de mappage des handles pour la session
  5. Retour du handle : renvoie le handle de session à Oracle

Remarque : La création de session ne nécessite pas d'appels API. Les sessions sont gérées localement.

Flux de connexion​

Étapes :

  1. Oracle appelle C_Login() : demande la connexion de la session
  2. Vérification du jeton : vérifie que le jeton bearer access_guid est configuré dans pkcs11.toml
  3. Marquage de la session : marque la session comme authentifiée
  4. Retour de succès : renvoie CKR_OK

Remarque : Pour DuoKey PKCS#11, l'authentification a lieu pendant C_Initialize(), lorsque la bibliothèque présente son jeton bearer access_guid au Cockpit. La fonction C_Login() confirme que le jeton est disponible mais n'effectue pas d'appels API supplémentaires.

Flux de génération de clé​

Étapes :

  1. Oracle appelle C_GenerateKey() : demande la génération d'une clé
  2. Analyse du modèle : extrait les attributs de clé (type, taille, label)
  3. Construction de la requête API : crée la requête de génération de clé
  4. Appel API : envoie la requête de génération de clé au Cockpit
  5. Génération HSM : le HSM backend génère la clé
  6. Réception de l'UUID : le Cockpit renvoie l'UUID de la clé
  7. Création du handle : mappe l'UUID vers un handle PKCS#11
  8. Retour du handle : renvoie le handle à Oracle

Flux de chiffrement​

Étapes :

  1. Oracle appelle C_Encrypt() / C_WrapKey() : demande un wrap sur le chemin de la clé maître (par exemple pour protéger une clé de tablespace)
  2. Recherche du handle : trouve l'UUID correspondant au handle de clé maître fourni
  3. Analyse du mécanisme : extrait l'algorithme (AES-CBC / AES-CBC-PAD) et l'IV
  4. Construction de la requête : crée la requête de wrap
  5. Appel API : envoie la requête de wrap au Cockpit
  6. Wrap HSM : le HSM backend effectue le wrap AES-CBC(-PAD) préservant la longueur
  7. Réception de la clé enveloppée : obtient les données enveloppées
  8. Retour du résultat : renvoie à Oracle

Remarque : Le wrap utilise un mécanisme AES-CBC / AES-CBC-PAD préservant la longueur. Une enveloppe AES-GCM expansive ne doit pas être utilisée sur ce chemin — elle casse le SET KEY d'Oracle avec l'erreur ORA-00600 [kcbtse_populate_tbskey_1]. Le chiffrement en masse des tables et des tablespaces est effectué localement par Oracle à l'aide d'AES-NI et ne quitte jamais la base de données.

Flux de déchiffrement​

Étapes :

  1. Oracle appelle C_Decrypt() / C_UnwrapKey() : demande un unwrap sur le chemin de la clé maître (par exemple pour récupérer une clé de tablespace à l'ouverture du keystore / SET KEY)
  2. Recherche du handle : trouve l'UUID correspondant au handle de clé maître fourni
  3. Analyse du mécanisme : extrait l'algorithme (AES-CBC / AES-CBC-PAD) et l'IV
  4. Construction de la requête : crée la requête d'unwrap
  5. Appel API : envoie la requête d'unwrap au Cockpit
  6. Unwrap HSM : le HSM backend effectue l'unwrap AES-CBC(-PAD) préservant la longueur
  7. Réception de la clé de tablespace : obtient la clé désenveloppée
  8. Retour du résultat : renvoie à Oracle

Flux de recherche d'objets​

Étapes :

  1. C_FindObjectsInit() : initialise la recherche avec un modèle
  2. Analyse du modèle : extrait les critères de recherche (label, classe, etc.)
  3. C_FindObjects() : exécute la recherche
  4. Appel API : envoie la requête de recherche d'objets au Cockpit
  5. Réception des UUID : obtient les UUID des objets correspondants
  6. Création des handles : mappe les UUID vers des handles
  7. Retour des handles : renvoie le tableau de handles à Oracle
  8. C_FindObjectsFinal() : nettoie l'état de recherche

Flux de gestion des erreurs​

Gestion des erreurs réseau​

Gestion des erreurs d'authentification​

Remarque : L'access_guid est un jeton bearer statique unique. Il n'existe aucun endpoint de jeton ni cycle de rafraîchissement ; un jeton rejeté constitue donc une erreur terminale (vérifiez l'access_guid dans pkcs11.toml) plutôt qu'une opération que la bibliothèque réessaie.

Gestion des erreurs HSM​

Optimisation des performances​

Réutilisation des connexions​

Avantages :

  • Élimine le surcoût de la négociation TCP
  • Réduit le temps d'établissement des connexions
  • Améliore le débit global

Jeton bearer​

La bibliothèque authentifie chaque requête à l'aide d'un unique jeton bearer access_guid intégré dans le server_url de l'app proxy. Il n'existe aucun endpoint de jeton ni cycle de rafraîchissement : le même jeton est présenté à chaque requête et validé côté serveur par le Cockpit, qui résout le tenant à partir de l'identité de l'application.

Avantages :

  • Aucun aller-retour d'échange de jeton
  • Aucun secret à rotationner à l'exécution (pas de client_id / client_secret)
  • Le maintien des connexions (keep-alive) réduit les négociations TLS par opération

Mise en cache des handles​

Avantages :

  • Évite les appels API en double
  • Résolution de handle plus rapide
  • Trafic réseau réduit

Supervision et débogage​

Traçage des requêtes​

Activez la journalisation de débogage pour tracer les requêtes :

export DKE_PKCS11_LOGGING_LEVEL=debug
export DKE_PKCS11_LOGGING_FOLDER=/var/log/dke-pkcs11

Sortie de journal :

[2025-12-19 10:30:45] [DEBUG] C_Initialize() called
[2025-12-19 10:30:45] [DEBUG] Reading pkcs11.toml (server_url, access_guid)
[2025-12-19 10:30:45] [INFO] Connecting to DuoKey Cockpit: https://cockpit-api-dev.duokey.cloud
[2025-12-19 10:30:46] [INFO] access_guid bearer token validated by Cockpit
[2025-12-19 10:30:46] [DEBUG] C_Initialize() completed: CKR_OK

Métriques de performance​

Surveillez les métriques clés :

  • Latence des requêtes : temps entre l'appel Oracle et la réponse
  • Latence API : temps des appels à l'API DuoKey Cockpit
  • Taux d'erreur : pourcentage de requêtes échouées
  • Échecs d'authentification : nombre de jetons bearer access_guid rejetés

Supervision réseau​

Surveillez le trafic réseau :

  • Connexions HTTPS : nombre de connexions actives
  • Tailles requête/réponse : tailles des charges utiles
  • Nombre de nouvelles tentatives : nombre de réessais par requête
  • Événements de timeout : fréquence des timeouts

Bonnes pratiques​

Gestion des erreurs​

  1. Réessayer les erreurs transitoires : erreurs réseau, timeouts
  2. Ne pas réessayer les erreurs d'authentification : identifiants invalides
  3. Journaliser toutes les erreurs : pour le diagnostic
  4. Renvoyer les codes appropriés : traduire en codes PKCS#11

Performance​

  1. Réutiliser les connexions : utiliser le pool de connexions
  2. Maintenir les connexions actives : amortir les négociations TLS sur plusieurs opérations
  3. Regrouper les opérations : lorsque c'est possible (futur)
  4. Surveiller la latence : suivre les métriques de performance

Sécurité​

  1. Utiliser TLS : toutes les connexions chiffrées
  2. Valider les certificats : validation stricte des certificats
  3. Sécuriser les identifiants : ne jamais journaliser l'access_guid
  4. Protéger pkcs11.toml : traiter le jeton bearer access_guid comme un secret ; restreindre les permissions du fichier

Étapes suivantes​