Usa una chiave Cloud HSM per l'offloading TLS con NGINX

Questa guida fornisce le istruzioni per configurare NGINX in modo da utilizzare una Chiave Cloud HSM per l'offloading TLS su Debian 11 (Bullseye). Potresti dover modificare questi comandi in modo che funzionino con il tuo sistema operativo o la tua distribuzione Linux.

Nota: la terminazione TLS con Nginx è supportata solo per la curva ellittica Chiavi dell'algoritmo di firma digitale (ECDSA).

Puoi trovare una versione del progetto basata su Terraform di questo tutorial nel Repository GitHub di kms-solutions.

Casi d'uso

L'utilizzo di una chiave Cloud HSM con NGINX per l'offloading TLS per soddisfare le seguenti esigenze di sicurezza aziendale:

• Il server web NGINX deve scaricare la crittografia TLS operazioni in Cloud HSM.
• Non conviene archiviare la chiave privata del certificato nel file system locale dell'istanza Compute Engine che ospita il tuo sito web un'applicazione.
• Devi soddisfare i requisiti normativi nei casi in cui le applicazioni rivolte al pubblico richiedono che i certificati siano protetti da un HSM con livello FIPS 140-2 3.
• Vuoi utilizzare NGINX per creare un proxy inverso con TLS per proteggere la tua applicazione web.

Prima di iniziare

Prima di continuare, completa i passaggi Utilizzo di una chiave Cloud HSM con OpenSSL.

Una volta completata la configurazione di OpenSSL, assicurati che sia installata una versione recente di nginx installato:

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

Nota: nginx 1.18.0-6.1 e versioni successive supportano lo schema URI PKCS #11 (RFC 7512). Potresti dover eseguire l'upgrade pacchetto nginx installato.

Suggerimenti per la configurazione di sicurezza

Proteggi l'istanza che ospita NGINX con quanto segue raccomandazioni:

1. Segui le istruzioni per creare e abilitare account di servizio per di archiviazione per ospitare NGINX.

   1. Assegna i seguenti ruoli:
      • roles/cloudkms.signerVerifier
      • roles/cloudkms.viewer

2. Configura i criteri dell'organizzazione come segue per limitare IP esterni e creazione di chiavi degli account di servizio.

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

3. Crea una subnet personalizzata che abilita accesso privato Google.

4. Configura le regole del firewall.

   • Crea regole firewall IAP solo per SSH.

5. Crea una VM Linux e configurala come segue:

   • Seleziona l'account di servizio corretto che hai creato in precedenza.
   • Seleziona la rete creata in precedenza.
     • Aggiungi le etichette appropriate per qualsiasi regola firewall.
     • Assicurati che il campo "IP esterno" della subnet sia impostato su none.

6. Concedi la tua identità all'utente del tunnel con protezione IAP (roles/iap.tunnelResourceAccessor) nell'istanza.

   • Scopri di più, leggi l'articolo sulla configurazione di IAP per il computing.

Crea e configura una chiave di firma ospitata da Cloud KMS

Le sezioni seguenti descrivono i passaggi necessari per creare e configurare una chiave di firma ospitata in Cloud KMS.

Crea una chiave di firma ospitata da Cloud KMS

Crea una chiave di firma EC-P256-SHA256 di Cloud KMS nel tuo Progetto Google Cloud, nel keyring configurato in precedenza per 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"

Nota: assicurati che l'account di servizio Compute Engine sia corretto autorizzazioni IAM (Identity and Access Management) sul keyring per poterlo utilizzare.

Accedi tramite SSH alla VM tramite IAP

Accedi tramite SSH alla VM utilizzando IAP con il seguente comando:

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

Se riscontri un problema, verifica di aver utilizzato il flag --tunnel-through-iap. Inoltre, verifica di disporre del ruolo Utente del tunnel con protezione IAP (roles/iap.tunnelResourceAccessor) nell'istanza per l'identità autenticata con l'interfaccia a riga di comando gcloud.

Creare un certificato con OpenSSL

Per un ambiente di produzione, crea una richiesta di firma del certificato (CSR). Impara leggi l'esempio per generare una richiesta CSR. Fornisci la CSR alla tua autorità di certificazione (CA) in modo che possa creare un certificato per te. Utilizza il certificato fornito dalla tua CA nelle sezioni successive.

Ad esempio, puoi generare un certificato autofirmato con il Chiave di firma ospitata da Cloud KMS. Per farlo, OpenSSL ti consente di utilizzare URI PKCS #11 invece di un percorso regolare, che identifica la chiave in base alla relativa etichetta (per le chiavi Cloud KMS, l'etichetta è il nome della 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

Sostituisci quanto segue:

• CERTIFICATE_NAME: un nome per il certificato.
• DIGEST_FLAG: l'algoritmo digest utilizzato dalla firma asimmetrica chiave. Usa -sha256, -sha384 o -sha512, a seconda della chiave.
• PKCS_KEY_TYPE: il tipo di identificatore utilizzato per identificare la chiave. Per usare la versione più recente della chiave, usa pkcs11:object con il nome della chiave. A una versione specifica della chiave, usa pkcs11:id con l'ID risorsa completo e la versione della chiave.
• KEY_IDENTIFIER: un identificatore per la chiave. Se utilizzi pkcs11:object, utilizza il nome della chiave, ad esempio NGINX_KEY. Se usi pkcs11:id, usa l'ID risorsa completo della chiave o della chiave dell'immagine, ad esempio projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/NGINX_KEY/cryptoKeyVersions/KEY_VERSION.
• CA_CERT: il percorso in cui vuoi salvare il certificato .

Se il comando non riesce, PKCS11_MODULE_PATH potrebbe essere stato impostato in modo errato. o potresti non disporre delle autorizzazioni corrette per utilizzare Cloud KMS chiave di firma.

Ora dovresti avere un certificato simile al seguente:

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

Installa il certificato per NGINX

Esegui questi comandi per creare una posizione in cui posizionare il pubblico certificato:

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

Configura il tuo ambiente per utilizzare la libreria PKCS #11

Le sezioni successive descrivono i passaggi necessari per preparare e testare l'ambiente.

Prepara le configurazioni della libreria per NGINX

Consenti a NGINX di registrare le operazioni del motore PKCS #11 con con i seguenti elementi:

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

Crea un file di configurazione della libreria vuoto con le autorizzazioni appropriate per NGINX.

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

Modifica il file di configurazione vuoto e aggiungi la configurazione necessaria come mostrato in seguente snippet:

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

Test della configurazione OpenSSL

Esegui questo comando:

openssl engine -tt -c -v pkcs11

Dovresti vedere un output simile al seguente:

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

Configura NGINX per utilizzare Cloud HSM

Consenti l'offloading TLS modificando alcuni file NGINX. Innanzitutto, modifica /etc/nginx/nginx.conf file in due posizioni per aggiungere alcune istruzioni da configurare NGINX per utilizzare PKCS #11.

Dopo il blocco event e prima del blocco http, aggiungi quanto segue :

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

Nello stesso file /etc/nginx/nginx.conf, configura le istruzioni SSL per l'utilizzo del tuo e la relativa chiave privata in Cloud HSM. Nel blocco http, aggiungi il i seguenti attributi:

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.

Il file /etc/nginx/nginx.conf dovrebbe avere il seguente aspetto:

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;

        #...
        #...

}

Configura NGINX per ascoltare il traffico TLS

Modifica il file /etc/nginx/sites-enabled/default per rimanere in ascolto del traffico TLS. Rimuovi il commento dalla configurazione SSL nel blocco server. La modifica risultante dovrebbe avere l'aspetto del seguente esempio:

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

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

        # ...
        # ...
}

Fornisci variabili di ambiente al servizio NGINX

Esegui questo comando:

sudo systemctl edit nginx.service

Nell'editor risultante, aggiungi le seguenti righe e sostituisci LIBPATH con il valore relativo alla posizione in cui hai installato l'app 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"

Dopo aver configurato questi valori, devi eseguire il comando seguente per rendili disponibili:

sudo systemctl daemon-reload

Riavvia NGINX con TLS Offloading

Esegui il seguente comando per riavviare NGINX e utilizzare la configurazione aggiornata:

sudo systemctl start nginx

Nota: se visualizzi errori al riavvio, controlla /var/log/nginx/error.log e /var/log/kmsp11/ per ulteriori dettagli.

Verifica che NGINX utilizzi il trasferimento TLS al tuo Cloud HSM

Usa openssl s_client per testare la connessione al server NGINX esegui questo comando:

openssl s_client -connect localhost:443

Il client deve completare l'handshake SSL e metterlo in pausa. Il cliente è in attesa di un tuo feedback, come mostrato di seguito:

# 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.

I log di controllo ora dovrebbero mostrare le operazioni per la chiave NGINX_KEY. Per visualizzare i log, vai a Cloud Logging nella console Cloud. Nel progetto che hai utilizzato, aggiungi il seguente filtro:

resource.type="cloudkms_cryptokeyversion"

Dopo aver eseguito la query, dovresti vedere le operazioni con le chiavi asimmetriche NGINX_KEY chiave.

Configurazioni facoltative

Potrebbe essere necessario creare un bilanciatore del carico di rete passthrough esterno per il tuo server NGINX con un IP esterno.

Se devi utilizzare NGINX come proxy inverso con il bilanciamento del carico, valuta la possibilità di aggiornare il file di configurazione NGINX. Scopri di più su configurando NGINX come proxy inverso leggendo HA completamente attiva per NGINX Plus su Google Cloud Piattaforma.

Passaggi successivi

Ora hai configurato il tuo server NGINX in modo da utilizzare l'offloading TLS per la risoluzione dei problemi di Google Cloud HSM.