Utiliser une clé Cloud HSM pour le déchargement TLS avec NGINX

Ce guide fournit des instructions pour configurer NGINX afin d'utiliser un Clé Cloud HSM pour le déchargement TLS sur Debian 11 (Bullseye). Vous devrez peut-être modifier ces commandes pour qu'elles fonctionnent avec votre système d'exploitation ou votre distribution Linux.

Remarque : La terminaison TLS avec Nginx n'est compatible qu'avec les clés ECDSA (Elliptic Curve Digital Signature Algorithm).

Vous trouverez une version du plan basée sur Terraform de ce tutoriel dans la dépôt GitHub kms-solutions.

Cas d'utilisation

L'utilisation d'une clé Cloud HSM avec NGINX pour l'externalisation TLS permet de répondre aux besoins de sécurité d'entreprise suivants :

• Vous souhaitez que votre serveur Web NGINX décharge les données cryptographiques TLS des opérations vers Cloud HSM.
• Vous ne souhaitez pas stocker la clé privée de votre certificat dans le système de fichiers local de l'instance Compute Engine qui héberge votre application Web.
• Vous devez respecter les exigences réglementaires pour lesquelles les applications publiques ont besoin que leurs certificats soient protégés par un HSM certifié FIPS 140-2 3.
• Vous souhaitez utiliser NGINX pour créer un proxy inverse avec TLS pour protéger votre application Web.

Avant de commencer

Avant de continuer, suivez les étapes du Utiliser une clé Cloud HSM avec OpenSSL

Une fois la configuration d'OpenSSL terminée, assurez-vous qu'une version récente d'nginx est installé:

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

Remarque : nginx 1.18.0-6.1 et les versions ultérieures sont compatibles avec le schéma d'URI PKCS #11 (RFC 7512). Vous devrez peut-être mettre à niveau votre a installé le package nginx.

Recommandations concernant la configuration de la sécurité

Sécurisez l'instance qui héberge NGINX avec les éléments suivants : recommandations:

1. Suivez les instructions pour créer et activer des comptes de service pour des instances pour héberger NGINX.

   1. Attribuez les rôles suivants:
      • roles/cloudkms.signerVerifier
      • roles/cloudkms.viewer

2. Configurez les règles d'administration comme suit pour limiter les adresses IP externes et la création de clés de compte de service.

   • constraints/compute.vmExternalIpAccess
   • constraints/iam.disableServiceAccountKeyCreation

3. Créez un sous-réseau personnalisé qui active l'accès privé à Google.

4. Configurer les règles de pare-feu

   • Créez des règles de pare-feu IAP pour SSH uniquement.

5. Créez une VM Linux et configurez-la comme suit :

   • Sélectionnez le compte de service approprié que vous avez créé précédemment.
   • Sélectionnez le réseau que vous avez créé précédemment.
     • Ajoutez les étiquettes appropriées pour toutes les règles de pare-feu.
     • Assurez-vous que le sous-réseau dispose de l'adresse IP externe défini sur none.

6. Accorder à votre identité l'utilisateur de tunnels sécurisés par IAP (roles/iap.tunnelResourceAccessor) sur l'instance.

   • Pour en savoir plus, consultez la page Configurer IAP pour le calcul.

Créer et configurer une clé de signature hébergée par Cloud KMS

Les sections suivantes détaillent les étapes nécessaires pour créer et configurer un Clé de signature hébergée par Cloud KMS.

Créer une clé de signature hébergée par Cloud KMS

Créez une clé de signature Cloud KMS EC-P256-SHA256 dans votre un projet Google Cloud, dans le trousseau de clés que vous avez précédemment configuré pour OpenSSL:

gcloud kms keys create NGINX_KEY \
  --keyring "KEY_RING" --project "PROJECT_ID" \
  --location "LOCATION" --purpose "asymmetric-signing" \
  --default-algorithm "ec-sign-p256-sha256" --protection-level "hsm"

Remarque : Assurez-vous que votre compte de service Compute Engine dispose des autorisations IAM appropriées sur le trousseau de clés pour pouvoir l'utiliser.

Se connecter en SSH à votre VM à l'aide d'IAP

Connectez-vous en SSH à votre VM à l'aide d'IAP en exécutant la commande suivante:

gcloud compute ssh INSTANCE \
  --zone ZONE --tunnel-through-iap

Si vous rencontrez un problème, vérifiez que vous avez utilisé l'indicateur --tunnel-through-iap. Vérifiez également que vous disposez du rôle "Utilisateur de tunnels sécurisés par IAP" (roles/iap.tunnelResourceAccessor) sur l'instance pour l'identité authentifiée avec la CLI gcloud.

Créer un certificat avec OpenSSL

Dans un environnement de production, créez une demande de signature de certificat (CSR). Apprendre Lisez l'exemple permettant de générer une requête de signature de certificat. Fournir la requête de signature de certificat à votre autorité de certification afin qu'elle puisse créer un certificat pour vous. Utilisez le certificat fourni par votre autorité de certification dans les sections suivantes.

Par exemple, vous pouvez générer un certificat autosigné avec Clé de signature hébergée par Cloud KMS. Pour ce faire, OpenSSL vous permet d'utiliser les URI PKCS #11 au lieu d'un chemin d'accès standard, en identifiant la clé par son libellé (pour les clés Cloud KMS, le libellé est le nom de la CryptoKey).

openssl req -new -x509 -days 3650 -subj '/CN=CERTIFICATE_NAME/' \
  DIGEST_FLAG -engine pkcs11 -keyform engine \
  -key PKCS_KEY_TYPE=KEY_IDENTIFIER > CA_CERT

Remplacez les éléments suivants :

• CERTIFICATE_NAME : nom du certificat.
• DIGEST_FLAG: algorithme de condensé utilisé par la signature asymétrique . Utilisez -sha256, -sha384 ou -sha512 selon la clé.
• PKCS_KEY_TYPE: type d'identifiant utilisé pour identifier la clé. Pour utiliser la dernière version de clé, utilisez pkcs11:object avec le nom de la clé. À utilisez une version de clé spécifique, utilisez pkcs11:id avec l'ID de ressource complet de version de clé.
• KEY_IDENTIFIER: identifiant de la clé. Si vous utilisez pkcs11:object, utilisez le nom de la clé (par exemple, NGINX_KEY). Si vous utilisez pkcs11:id, indiquez l'ID de ressource complet de la clé ou de la clé. version (par exemple, projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/NGINX_KEY/cryptoKeyVersions/KEY_VERSION
• CA_CERT: chemin d'accès où vous souhaitez enregistrer le certificat .

Si la commande échoue, il est possible que PKCS11_MODULE_PATH ait été défini de manière incorrecte. ou vous ne disposez peut-être pas des autorisations nécessaires pour utiliser l'API Cloud KMS clé de signature.

Vous devriez maintenant avoir un certificat semblable à celui-ci :

-----BEGIN CERTIFICATE-----
...
...
...
-----END CERTIFICATE-----

Installer votre certificat pour NGINX

Exécutez les commandes suivantes pour créer un emplacement où placer votre certificat public :

sudo mkdir /etc/ssl/nginx
sudo mv CA_CERT /etc/ssl/nginx

Configurer votre environnement pour utiliser la bibliothèque PKCS #11

Les sections suivantes détaillent les étapes nécessaires pour préparer et tester votre environnement.

Préparer les configurations de bibliothèque pour NGINX

Autoriser NGINX à consigner les opérations sur le moteur PKCS #11 à l'aide du paramètre bibliothèque avec ce qui suit:

sudo mkdir /var/log/kmsp11
sudo chown www-data /var/log/kmsp11

Créez un fichier de configuration de bibliothèque vide avec les autorisations appropriées pour NGINX.

sudo touch /etc/nginx/pkcs11-config.yaml
sudo chmod 744 /etc/nginx/pkcs11-config.yaml

Modifiez le fichier de configuration vide et ajoutez la configuration nécessaire comme indiqué dans la l'extrait suivant:

# cat /etc/nginx/pkcs11-config.yaml
---
tokens:
  - key_ring: "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING"
log_directory: "/var/log/kmsp11"

Tester votre configuration OpenSSL

Exécutez la commande suivante :

openssl engine -tt -c -v pkcs11

La sortie obtenue doit ressembler à ceci :

(pkcs11) pkcs11 engine
 [RSA, rsaEncryption, id-ecPublicKey]
     [ available ]
     SO_PATH, MODULE_PATH, PIN, VERBOSE, QUIET, INIT_ARGS, FORCE_LOGIN

Configurer NGINX pour utiliser Cloud HSM

Autorisez le déchargement TLS en modifiant quelques fichiers NGINX. Commencez par modifier le fichier /etc/nginx/nginx.conf à deux endroits pour ajouter quelques directives afin de configurer NGINX pour qu'il utilise PKCS #11.

Après le bloc event et avant le bloc http, ajoutez les directives suivantes :

ssl_engine pkcs11;
env KMS_PKCS11_CONFIG=/etc/nginx/pkcs11-config.yaml;

Dans le même fichier /etc/nginx/nginx.conf, configurez les directives SSL pour utiliser votre certificat et sa clé privée dans Cloud HSM. Dans le bloc http, ajoutez le les attributs suivants:

ssl_certificate "/etc/ssl/nginx/CA_CERT";
ssl_certificate_key "engine:pkcs11:PKCS_KEY_TYPE=KEY_IDENTIFIER";
ssl_protocols TLSv1.2 TLSv1.3; # Consider changing the default to only TLS1.2 or newer

# Consider defining the `ssl_ciphers` to use ciphers approved by your security teams and handle
# appropriate client compatibility requirements.

Le fichier /etc/nginx/nginx.conf doit se présenter comme suit:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
        worker_connections 768;
        # multi_accept on;
}

ssl_engine pkcs11;
env KMS_PKCS11_CONFIG=/etc/nginx/pkcs11-config.yaml;

http {

        #...
        #...

        # SSL configuration
        ssl_certificate "/etc/ssl/nginx/CA_CERT";
        ssl_certificate_key "engine:pkcs11:pkcs11:object=NGINX_KEY";
        ssl_protocols TLSv1.2 TLSv1.3; # Dropping SSLv3, ref: POODLE
        # ssl_ciphers YOUR_CIPHERS
        ssl_prefer_server_ciphers on;

        #...
        #...

}

Configurer NGINX pour écouter le trafic TLS

Modifiez le fichier /etc/nginx/sites-enabled/default pour écouter le trafic TLS. Annulez la mise en commentaire de la configuration SSL dans le bloc server. La modification obtenue doit ressembler à l'exemple suivant:

server {
        listen 80 default_server;
        listen [::]:80 default_server;

        # SSL configuration
        listen 443 ssl default_server;
        listen [::]:443 ssl default_server;

        # ...
        # ...
}

Fournir des variables d'environnement au service NGINX

Exécutez la commande suivante :

sudo systemctl edit nginx.service

Dans l'éditeur obtenu, ajoutez les lignes suivantes et remplacez le LIBPATH par la valeur de l'emplacement d'installation ; libkmsp11.so:

[Service]
Environment="GRPC_ENABLE_FORK_SUPPORT=1"
Environment="KMS_PKCS11_CONFIG=/etc/nginx/pkcs11-config.yaml"
Environment="PKCS11_MODULE_PATH=LIBPATH/libkmsp11-1.0-linux-amd64/libkmsp11.so"

Après avoir configuré ces valeurs, vous devrez exécuter la commande suivante pour les rendre disponibles:

sudo systemctl daemon-reload

Redémarrer NGINX avec le déchargement TLS

Exécutez la commande suivante pour que NGINX redémarre et utilise les configuration:

sudo systemctl start nginx

Remarque : Si des erreurs s'affichent au redémarrage, vérifiez /var/log/nginx/error.log et /var/log/kmsp11/ pour en savoir plus.

Tester si NGINX utilise le transfert TLS vers votre Cloud HSM

Utilisez le openssl s_client pour tester la connexion à votre serveur NGINX en en exécutant la commande suivante:

openssl s_client -connect localhost:443

Le client doit terminer le handshake SSL et le mettre en pause. Le client attend une entrée de votre part comme suit:

# completes SSL handshake
# ...
# ...
# ...
    Verify return code: 18 (self signed certificate)
# ...
    Max Early Data: 0
---
read R BLOCK

# When the client pauses, it’s waiting for instructions.
# Have the client get the index.html file in the root path (“/”), by typing the following:

GET /

# Press enter.
# You should now see the default NGINX index.html file.

Vos journaux d'audit devraient maintenant afficher les opérations effectuées sur votre clé NGINX_KEY. Pour afficher les journaux, accédez à Cloud Logging dans votre console Cloud. Dans le projet que vous utilisez, ajoutez le filtre suivant :

resource.type="cloudkms_cryptokeyversion"

Après avoir exécuté la requête, vous devriez voir des opérations de clés asymétriques dans votre Clé NGINX_KEY.

Configurations facultatives

Vous devrez peut-être créer un équilibreur de charge réseau passthrough externe pour exposer votre serveur NGINX avec une adresse IP externe.

Si vous devez utiliser NGINX comme proxy inverse avec équilibrage de charge, envisagez de mettre à jour le fichier de configuration NGINX. En savoir plus sur configurer NGINX en tant que proxy inverse en lisant Haute disponibilité entièrement active pour NGINX Plus sur Google Cloud Plate-forme.

Étapes suivantes

Vous avez maintenant configuré votre serveur NGINX pour utiliser le déchargement TLS Cloud HSM.