Utiliser une clé Cloud HSM avec OpenSSL

Ce guide fournit des instructions de configuration d'OpenSSL pour l'utilisation d'une clé Cloud HSM sur Debian 11 (BullsEye). Ces instructions sont généralement applicables même si vous utilisez un autre système d'exploitation ou environnement, mais sachez que vous pouvez constater de légères différences.

Exigences

Pour commencer, téléchargez une version de la bibliothèque. Un guide de l'utilisateur est à votre disposition pour vous conseiller.

Avant de commencer, installez le package libengine-pkcs11-openssl.

sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl

Configuration

Définir la variable d'environnement PKCS11_MODULE_PATH

Pour que openssl utilise notre bibliothèque PKCS #11, définissez la variable d'environnement PKCS11_MODULE_PATH :

export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee /etc/profile

Configuration de la bibliothèque PKCS #11

La bibliothèque PKCS #11 nécessite un fichier de configuration YAML pour localiser les ressources Cloud KMS. Le fichier YAML doit au minimum configurer un seul jeton PKCS #11.

Si vous utilisez OpenSSL avec un autre processus pouvant entraîner des duplications (par exemple, Apache ou Nginx), vous devez également vous assurer que le champ refresh_interval_secs reste non défini, ou défini sur 0.

Exemple de fichier de configuration :

---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"

Avec cette configuration, toutes les clés de signature et de déchiffrement asymétriques dans my-keyring seront disponibles dans la bibliothèque.

Vous devez définir les autorisations sur le fichier de configuration pour qu'il ne soit accessible en écriture que par son propriétaire. Pointez KMS_PKCS11_CONFIG vers votre fichier de configuration :

export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

Là encore, vous pouvez rendre ce paramètre définitif en l'ajoutant à /etc/profile.

echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee /etc/profile

Exécuter des commandes OpenSSL

Une fois le moteur et la bibliothèque correctement configurés, vous pouvez maintenant utiliser le moteur dans les commandes OpenSSL.

Lors de la création de signatures asymétriques, gardez à l'esprit que les clés Cloud KMS sont contraintes d'utiliser un seul condensé. Par exemple, une version de clé de chiffrement CryptoKeyVersion avec l'algorithme EC_SIGN_P256_SHA256 doit toujours être utilisée conjointement avec un condensé SHA-256. Cela correspond à l'option -sha256 dans OpenSSL. Les clés nécessitant des condensés SHA-384 ou SHA-512 doivent être utilisées avec les options -sha384 ou -sha512.

Créer une nouvelle signature

En supposant qu'il existe une clé nommée foo dans votre trousseau de clés configuré, utilisez la commande suivante pour créer une signature sur bar.txt :

openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt

Le résultat de cette commande est un binaire non formaté.

Cette commande suppose que vous utilisez une clé exploitant un condensé SHA-256. Par conséquent, l'argument -sha256 a été utilisé. Les options -sha384 ou -sha512 sont appropriées pour les clés Cloud HSM utilisant ces types de condensés.

Pour une clé RSA-PSS, n'oubliez pas d'utiliser les options -sigopt décrites précédemment.

Créer une nouvelle requête de signature de certificat

Vous pouvez également générer une demande de signature de certificat (CSR) pour une clé de signature Cloud HSM. Cela est utile si votre autorité de certification exige une demande de signature de certificat afin de générer un nouveau certificat pour la signature du code, ou pour protéger les sessions Web TLS.

openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.csr

Générer un nouveau certificat autosigné

Pour le développement et les tests locaux, vous pouvez utiliser un certificat autosigné pour une clé de signature Cloud HSM. Les certificats autosignés sont également utiles pour la signature de jetons SAML.

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.crt