Configuration

Avec DuoKey Cockpit, le fournisseur PKCS#11 se configure au moyen d'un fichier pkcs11.toml, complété par des surcharges optionnelles via les variables d'environnement DKE_PKCS11_*. Le fichier ne contient que deux éléments essentiels — l'URL du proxy Cockpit et le jeton porteur access_guid — car Cockpit résout l'application et le tenant côté serveur.

Référence canonique

Cette page décrit le modèle de configuration au niveau architectural. Pour le schéma complet, les valeurs par défaut et la table de correspondance de migration v1 → v2, consultez Configuration du fournisseur PKCS#11 (pkcs11.toml).

Vue d'ensemble

Fichier de configuration

Le fournisseur lit sa configuration lors de C_Initialize, depuis le chemin indiqué dans la variable d'environnement DKE_PKCS11_CONF. Oracle définit cette variable dans le profil de l'utilisateur Oracle (ou dans l'enveloppe OKV). Un chemin d'installation courant est :

/usr/local/okv/hsm/generic/pkcs11.toml

Schéma

# pkcs11.toml — DuoKey PKCS#11 provider configuration

[http_config]
# Full Cockpit proxy URL for this Oracle TDE app (required).
# It already contains the app identity and access_guid, so no separate
# endpoint, tenant, or credential fields are needed.
server_url = "https://cockpit.example.com/api/apps/APP_ID/tde/pkcs11/ACCESS_GUID"

# Bearer token used to authenticate every request — the app's access_guid.
access_token = "ACCESS_GUID"

# HTTP request timeout in seconds (default: 30).
timeout_secs = 30

# Verify the server's TLS certificate (default: true).
# Set to false ONLY for testing against self-signed certificates.
verify_tls = true

[pkcs11]
# Id of the single virtual slot the library presents (default: 0).
slot_id = 0

# Logging level: "error" | "warn" | "info" | "debug" | "trace" (default: "info").
logging_level = "info"

# Optional folder for provider log files (default: none — logs to stderr).
logging_folder = "/var/log/dke-pkcs11"

[http_config] — connexion à Cockpit

Clé	Type	Valeur par défaut	Rôle
server_url	chaîne	(requis)	URL complète du proxy Cockpit pour cette application. Contient l'identité de l'application et l'access_guid, de sorte qu'aucun champ distinct d'endpoint ou de tenant n'est nécessaire.
access_token	chaîne	""	Jeton porteur envoyé sous la forme Authorization: Bearer …. Pour Oracle TDE, il s'agit de l'access_guid de l'application.
timeout_secs	entier	30	Délai d'expiration HTTP par requête.
verify_tls	booléen	true	Vérification du certificat TLS. Conservez la valeur true en production.

[pkcs11] — comportement local du fournisseur

Clé	Type	Valeur par défaut	Rôle
slot_id	entier	0	Identifiant de l'unique slot virtuel exposé à Oracle.
logging_level	chaîne	"info"	Niveau de verbosité des journaux du fournisseur.
logging_folder	chaîne	(aucune)	Répertoire des journaux du fournisseur ; s'il n'est pas défini, les journaux sont écrits sur stderr.

Modèle d'authentification

• Un seul identifiant. L'authentification repose sur un unique jeton porteur access_guid, intégré à server_url et repris dans access_token. Il n'y a aucun flux OAuth2 client-credentials, aucun client_id / client_secret, aucun nom d'utilisateur / mot de passe, et aucune découverte OpenID Connect.
• Aucun champ de tenant. Cockpit résout le tenant côté serveur à partir de l'identité de l'application contenue dans l'URL — il n'y a ni identifiant de tenant ni en-tête de tenant côté client.
• Aucun champ de Vault. Le Vault / keystore sous-jacent est géré par l'application dans le Cockpit, et non configuré côté client.

Protégez pkcs11.toml

L'access_guid présent dans server_url / access_token est un identifiant porteur. Restreignez le fichier à l'utilisateur système Oracle — par exemple chmod 600, appartenant à oracle — et faites tourner le jeton d'accès de l'application depuis le Cockpit s'il venait à être exposé.

Surcharges par variables d'environnement

Les variables d'environnement priment sur le fichier ; vous pouvez donc conserver un pkcs11.toml de base et le surcharger par hôte :

Variable d'environnement	Surcharge
DKE_PKCS11_CONF	Chemin vers le fichier pkcs11.toml
DKE_PKCS11_SERVER_URL	http_config.server_url
DKE_PKCS11_ACCESS_TOKEN	http_config.access_token
DKE_PKCS11_VERIFY_TLS	http_config.verify_tls (0 / false / no = désactivé)
DKE_PKCS11_SLOT_ID	pkcs11.slot_id
DKE_PKCS11_LOGGING_LEVEL	pkcs11.logging_level
DKE_PKCS11_LOGGING_FOLDER	pkcs11.logging_folder

Si aucun chemin de fichier n'est fourni, la bibliothèque peut construire sa configuration entièrement à partir des variables d'environnement, à condition qu'au moins l'URL du serveur et le jeton d'accès soient définis.

Obtenir les valeurs

Vous n'assemblez pas ces valeurs à la main. Dans le Cockpit, ouvrez l'application Oracle TDE et utilisez son bundle de déploiement — le Cockpit génère pour vous le fichier pkcs11.toml (avec le bon server_url et le bon access_guid), les exports d'environnement et les scripts SQL Oracle prêts à télécharger.

Validation

La bibliothèque valide la configuration lors de l'initialisation :

• L'URL du serveur est présente et correctement formée.
• Le jeton d'accès est présent.
• En cas d'échec, l'initialisation renvoie CKR_DEVICE_ERROR (connexion / configuration) ou CKR_PIN_INCORRECT (authentification).

Bonnes pratiques de sécurité

• Ne validez jamais pkcs11.toml ni l'access_guid dans un système de gestion de versions.
• Restreignez les permissions du fichier à l'utilisateur système Oracle (chmod 600).
• Faites tourner le jeton d'accès de l'application depuis le Cockpit à intervalles réguliers, et immédiatement en cas d'exposition.
• Conservez verify_tls = true et utilisez TLS 1.2+ pour toutes les connexions.

Étapes suivantes

• Flux de communication → - Découvrez comment la configuration est utilisée
• Vue d'ensemble de l'architecture → - Comprenez l'architecture globale
• Configuration du fournisseur PKCS#11 (pkcs11.toml) → - Le schéma complet et la correspondance v1 → v2