Aller au contenu principal

Couche SDK DuoKey

La couche SDK DuoKey gère l'ensemble des communications avec DuoKey Cockpit. Elle achemine chaque opération PKCS#11 vers Cockpit via HTTPS, y joint le jeton d'authentification et prend en charge les nouvelles tentatives ainsi que la réutilisation des connexions.

Référence de l'API : le protocole de transport concret — endpoints et formats de requête/réponse — est interne et documenté séparément dans les Developer Docs. Cette page offre une vue de haut niveau des responsabilités de cette couche.

Vue d'ensemble​

Responsabilités​

Authentification​

L'authentification auprès de DuoKey Cockpit repose sur un unique jeton porteur access_guid. Le jeton fait partie de l'URL du proxy Cockpit configurée pour l'application Oracle TDE, et il est envoyé dans un en-tête Authorization: Bearer … à chaque requête.

Il n'y a aucun flux OAuth2 client-credentials, aucun client_id / client_secret, aucun nom d'utilisateur / mot de passe, et aucun en-tête de tenant côté client. Cockpit résout le tenant côté serveur à partir de l'identité de l'application intégrée à l'URL.

Flux d'authentification :

Configuration : le jeton est fourni par pkcs11.toml (ou par la surcharge DKE_PKCS11_ACCESS_TOKEN). Voir Configuration.

Client HTTPS​

Envoie les requêtes vers l'endpoint proxy de DuoKey Cockpit. Chaque opération PKCS#11 devient une seule requête, envoyée avec le jeton porteur ; la réponse est ré-analysée en un résultat PKCS#11. Sur le plan conceptuel, les opérations se répartissent en deux groupes :

  • Gestion des clés — provisionner une clé maître, consulter les informations d'une clé.
  • Wrap / unwrap — envelopper et désenvelopper les clés de table et de tablespace sous la clé maître.

Traitement des requêtes / réponses​

La couche sérialise la requête sortante, y attache les en-têtes et le jeton porteur, l'envoie via HTTPS et analyse la réponse.

Gestion des erreurs : la couche traduit les erreurs de Cockpit et de transport en codes de retour PKCS#11 appropriés, de sorte qu'Oracle TDE reçoit des résultats Cryptoki standard — par exemple, un échec d'authentification se manifeste par une erreur d'authentification, un objet manquant par une erreur de handle invalide, et les défaillances du backend ou du réseau par une erreur de périphérique.

Logique de nouvelle tentative​

Les défaillances transitoires font l'objet de nouvelles tentatives avec un délai exponentiel (backoff).

Nouvelles tentatives possibles : délais d'expiration réseau, 503 Service Unavailable, 502 Bad Gateway, erreurs de connexion.

Sans nouvelle tentative : 401 Unauthorized (authentification), 404 Not Found (objet manquant), 400 Bad Request (paramètres invalides).

Configuration : le délai d'expiration par requête est fixé par timeout_secs dans pkcs11.toml (30 secondes par défaut). Voir Configuration.

Réutilisation des connexions​

  • Keep-alive : les connexions HTTPS sont réutilisées d'une requête à l'autre afin d'éviter la répétition des poignées de main TCP/TLS.
  • TLS : toutes les connexions utilisent TLS 1.2+ avec une validation stricte des certificats (contrôlée par verify_tls).

Gestion des erreurs​

Cockpit renvoie une erreur structurée en cas d'échec ; la couche SDK l'analyse et la fait correspondre à un code de retour PKCS#11.

Considérations de sécurité​

TLS​

  • Version minimale : TLS 1.2+
  • Validation des certificats : stricte ; verify_tls = true en production
  • Suites de chiffrement : uniquement des suites robustes

Gestion des identifiants​

  • Un seul identifiant : le jeton porteur access_guid est le seul secret côté client.
  • Aucune journalisation : le jeton n'est jamais journalisé.
  • Fourni à l'exécution : transmis via pkcs11.toml ou la surcharge d'environnement DKE_PKCS11_ACCESS_TOKEN ; protégez le fichier avec des permissions restrictives.

Étapes suivantes​