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.
Conditions requises
Pour commencer, téléchargez une version de la bibliothèque. Pour en savoir plus sur la bibliothèque PKCS #11, consultez le guide de l'utilisateur.
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"
Pour définir la variable d'environnement de manière permanente, ajoutez export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" à /etc/profile en exécutant la commande suivante:
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /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 -a /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
Dépannage avec PKCS #11 Spy
PKCS #11 Spy est un outil Open Source qui consigne le contenu des interactions sur une interface PKCS #11. Pour ce faire, il se trouve entre l'application et la bibliothèque PKCS #11, et consigne tous les appels effectués. Cela peut être utile pour le dépannage.
Pour utiliser Spy PKCS #11, vous devez avoir installé le package opensc. Le package opensc contient Spy PKCS #11. Pour vous assurer que opensc est installé, exécutez la commande suivante:
sudo apt-get install opensc
Ensuite, définissez la variable d'environnement PKCS11_MODULE_PATH de sorte qu'elle pointe OpenSSL vers la bibliothèque Spy PKCS #11 en exécutant la commande suivante:
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Enfin, pointez PKCS #11 Spy vers la bibliothèque Cloud HSM PKCS #11 en définissant les variables d'environnement PKCS11SPY et PKCS11SPY_OUTPUT. Pour définir ces variables d'environnement, exécutez les commandes suivantes:
export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"