OpenSSL

Avertissement

Essayer de récupérer la clé privée fera planter OpenSSL. C’est normal car les clés privées ne peuvent pas être extraites d’un NetHSM. Il se peut que vous souhaitiez récupérer la clé publique à la place (voir l’exemple ci-dessous).

Moteur

Avertissement

Lors de l’utilisation d’un moteur (libp11) de version 0.4.12 ou antérieure, le fait d’avoir une clé EdDSA sur le NetHSM fera en sorte qu’OpenSSL ne trouvera aucune clé. Sur les versions 0.4.12 et antérieures, le moteur liste toutes les clés sur le NetHSM lorsqu’une clé est demandée. Lors de la recherche d’une clé par label ou identifiant, il est recommandé d’utiliser la version 0.4.13 ou une version plus récente, ou de construire libp11 à partir des sources. Le binaire du moteur sera dans src/.libs/pkcs11.so.

L’interface OpenSSL engine est l’ancienne façon d’implémenter des backends personnalisés pour OpenSSL et elle est obsolète dans OpenSSL 3. C’est toujours la façon la plus stable d’utiliser le NetHSM avec OpenSSL.

Vous devrez installer le module PKCS#11 en suivant ces instructions.

Installer le moteur :

apt install libengine-pkcs11-openssl

Ensuite, vous devez configurer OpenSSL pour qu’il utilise le moteur. Pour ce faire, ajoutez les lignes suivantes à votre fichier openssl.cnf :

openssl_conf = openssl_init

[openssl_init]
engines = engine_section

[engine_section]
pkcs11 = pkcs11_section

[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so
MODULE_PATH = /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so
init = 0

Note

Vous pouvez indiquer à OpenSSL le chemin du fichier de configuration OpenSSL en utilisant la variable d’environnement OPENSSL_CONF.

Avertissement

Si le fichier de configuration principal d’OpenSSL est modifié pour ne contenir que ces lignes, d’autres programmes utilisant OpenSSL risquent d’être interrompus. Il est donc préférable de créer un fichier de configuration distinct pour le moteur.

Remplacez /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so par le chemin d’accès au module PKCS#11 que vous avez installé précédemment.

Remplacez /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so par le chemin vers le moteur OpenSSL que vous avez installé. Ce chemin varie en fonction de votre distribution. Le nombre dans engines-3 correspond à votre version d’OpenSSL. Sous Debian, le chemin pour le moteur OpenSSL 3 est /usr/lib/x86_64-linux-gnu/engines-3/libpkcs11.so ; pour Fedora, c’est /usr/lib64/engines-3/libpkcs11.so.

Vous pouvez maintenant utiliser des clés sur le NetHSM en utilisant PKCS#11 URIs, exemple :

engine:pkcs11:pkcs11:object=webserver;type=private

Il utilisera la clé webserver.

Note

Vous pouvez utiliser la commande p11tool de GnuTLS <https://gnutls.org/> pour obtenir l’URI complet des clés :

p11tool --provider /usr/lib/x86_64-linux-gnu/pkcs11/libnethsm_pkcs11.so --list-all

Exemple de commande

Récupérer la clé publique d’une paire de clés asymétriques sur le NetHSM :

openssl pkey -engine pkcs11 -inform ENGINE -in "pkcs11:object=webserver;type=public" -pubout

Fournisseur

L’interface du fournisseur OpenSSL est la nouvelle façon d’implémenter des backends personnalisés pour OpenSSL. Le backend pkcs11-provider est encore à un stade précoce de développement.

Vous devrez installer le module PKCS#11 en suivant ces instructions.

Installez le fournisseur. Pour Fedora, un paquet nommé pkcs11-provider existe. Pour les autres distributions Linux, vous devrez le construire à partir des sources.

Vous devez ensuite configurer OpenSSL pour qu’il utilise le fournisseur. Pour ce faire, ajoutez les lignes suivantes à votre fichier openssl.cnf :

openssl_conf = openssl_init

[openssl_init]
providers = provider_sect

[provider_sect]
pkcs11 = pkcs11_sect

[pkcs11_sect]
module = /home/sautax/git/pkcs11-provider/src/.libs/pkcs11.so
pkcs11-module-path = /usr/lib/libnethsm_pkcs11.so
activate = 1

Définissez module comme le chemin du fournisseur que vous avez installé et pkcs11-module-path comme le chemin du module PKCS#11 que vous avez installé.

Si vous souhaitez définir NetHSM comme fournisseur par défaut, vous pouvez ajouter default = pkcs11 à la section provider_sect.

Note

Vous pouvez indiquer à OpenSSL le chemin du fichier de configuration OpenSSL en utilisant la variable d’environnement OPENSSL_CONF.

Avertissement

Si le fichier de configuration principal d’OpenSSL est modifié pour ne contenir que ces lignes, d’autres programmes utilisant OpenSSL risquent d’être interrompus. Il est donc préférable de créer un fichier de configuration distinct pour le fournisseur.

Vous pouvez ensuite utiliser des clés sur le NetHSM en utilisant PKCS#11 URIs, par exemple :

openssl pkey -provider pkcs11 -in "pkcs11:object=rsakey" -pubout

Si vous avez choisi NetHSM comme fournisseur par défaut, vous pouvez omettre l’argument -provider pkcs11.

Note

Actuellement, lorsque vous définissez manuellement un type de clé dans l’URI, le fournisseur n’est pas en mesure de trouver la clé. Vous pouvez omettre la partie ;type=private ou ;type=public de l’URI pour que cela fonctionne.