Usar uma chave do Cloud HSM para offloading de TLS com o NGINX

Neste guia, fornecemos instruções para configurar o NGINX para usar uma chave do Cloud HSM para descarregamento de TLS no Debian 11 (Bullseye). Talvez seja necessário modificar esses comandos para trabalhar com seu SO ou distribuição do Linux.

Observação: o término de TLS com o Nginx é compatível apenas com chaves do algoritmo de assinatura digital de curva elíptica (ECDSA, na sigla em inglês).

Você encontra uma versão do blueprint deste tutorial baseada no Terraform no repositório kms-solutions do GitHub.

Casos de uso

Usar uma chave do Cloud HSM com o NGINX para descarregamento de TLS ajuda a atender às seguintes necessidades de segurança empresarial:

• Você quer que o servidor da Web NGINX descarregue operações criptográficas TLS para o Cloud HSM.
• Você não quer armazenar a chave privada do certificado no sistema de arquivos local da instância do Compute Engine que hospeda seu aplicativo da Web.
• Você precisa atender aos requisitos regulamentares em que os aplicativos voltados ao público precisam ter certificados protegidos por um HSM com certificação FIPS 140-2 Nível 3.
• Você quer usar o NGINX para criar um proxy reverso com encerramento de TLS para proteger seu aplicativo da Web.

Antes de começar

Antes de continuar, conclua as etapas em Como usar uma chave do Cloud HSM com o OpenSSL.

Após a conclusão da configuração do OpenSSL, verifique se uma versão recente do nginx está instalada:

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

Observação: o nginx 1.18.0-6.1 e versões mais recentes são compatíveis com o esquema de URI PKCS #11 (RFC 7512). Talvez seja necessário fazer upgrade do pacote nginx instalado anteriormente.

Recomendações de configuração de segurança

Proteja a instância que está hospedando o NGINX com as seguintes recomendações:

1. Siga as instruções para criar e ativar contas de serviço para instâncias e hospedar o NGINX.

   1. Atribua os seguintes papéis:
      • roles/cloudkms.signerVerifier
      • roles/cloudkms.viewer

2. Configure as políticas da organização da seguinte maneira para limitar os IPs externos e a criação de chaves de conta de serviço.

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

3. Crie uma sub-rede personalizada que ative o Acesso privado do Google.

4. Configurar regras de firewall.

   • Crie regras de firewall do IAP somente para SSH.

5. Crie uma VM do Linux e configure-a da seguinte maneira:

   • Selecione a conta de serviço correta que você criou.
   • Selecione a rede que você criou antes.
     • Adicione os rótulos adequados a todas as regras de firewall.
     • Verifique se o campo "IP externo" da sub-rede está definido como none.

6. Conceda à sua identidade o papel Usuário do túnel protegido pelo IAP (roles/iap.tunnelResourceAccessor) na instância.

   • Saiba mais em Configuração da IAP para computação.

Criar e configurar uma chave de assinatura do Cloud HSM

As próximas seções detalham as etapas necessárias para criar e configurar uma chave de assinatura do Cloud HSM.

Criar uma chave de assinatura hospedada no Cloud HSM

Crie uma chave de assinatura EC-P256-SHA256 do Cloud HSM no seu projetoGoogle Cloud , no keyring que você configurou anteriormente para o 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"

Observação: verifique se a conta de serviço do Compute Engine tem as permissões corretas do Identity and Access Management (IAM) no keyring para poder usá-lo.

Conectar-se à VM usando SSH e IAP

Conecte-se à VM usando SSH e IAP com o seguinte comando:

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

Se você tiver um problema, confirme se usou a flag --tunnel-through-iap. Além disso, confirme se você tem o papel de usuário do túnel protegido por IAP (roles/iap.tunnelResourceAccessor) na instância para a identidade autenticada com a CLI gcloud.

Criar um certificado com o OpenSSL

Para um ambiente de produção, crie uma solicitação de assinatura de certificado (CSR). Saiba mais lendo o exemplo para gerar uma CSR. Forneça a CSR à autoridade de certificação (CA) para que ela possa criar um certificado para você. Use o certificado fornecido pela CA nas seções subsequentes.

Por exemplo, gere um certificado autoassinado com a chave de assinatura do Cloud HSM. Para isso, o OpenSSL permite usar URIs PKCS #11 em vez de um caminho regular, identificando a chave pelo rótulo. Para chaves do Cloud KMS, o rótulo é o nome da 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

Substitua:

• CERTIFICATE_NAME: um nome para o certificado.
• DIGEST_FLAG: o algoritmo de resumo usado pela chave de assinatura assimétrica. Use -sha256, -sha384 ou -sha512, dependendo da chave.
• PKCS_KEY_TYPE: o tipo de identificador usado para identificar a chave. Para usar a versão mais recente da chave, use pkcs11:object com o nome dela. Para usar uma versão de chave específica, use pkcs11:id com o ID de recurso completo da versão da chave.
• KEY_IDENTIFIER: um identificador da chave. Se você estiver usando pkcs11:object, use o nome da chave, por exemplo, NGINX_KEY. Se você estiver usando pkcs11:id, use o ID completo do recurso da chave ou da versão da chave. Por exemplo, projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/NGINX_KEY/cryptoKeyVersions/KEY_VERSION.
• CA_CERT: o caminho em que você quer salvar o arquivo de certificado.

Se o comando falhar, é possível que PKCS11_MODULE_PATH tenha sido definido incorretamente ou que você não tenha as permissões corretas para usar a chave de assinatura do Cloud KMS.

Agora você terá um certificado como este:

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

Instalar o certificado para NGINX

Execute os comandos a seguir para criar um local onde colocar seu certificado público:

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

Configurar seu ambiente para usar a biblioteca PKCS #11

As próximas seções detalham as etapas necessárias para preparar e testar seu ambiente.

Preparar configurações de biblioteca para o NGINX

Permita que o NGINX registre as operações do mecanismo PKCS #11 com a biblioteca usando o seguinte:

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

Crie um arquivo de configuração de biblioteca vazio com as permissões adequadas para NGINX.

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

Edite o arquivo de configuração vazio e adicione a configuração necessária, conforme mostrado no snippet a seguir:

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

Testar a configuração do OpenSSL

Execute este comando:

openssl engine -tt -c -v pkcs11

A resposta será semelhante a esta:

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

Configurar o NGINX para usar o Cloud HSM

Permita o descarregamento de TLS editando alguns arquivos NGINX. Primeiro, edite o arquivo /etc/nginx/nginx.conf em dois lugares para adicionar algumas diretivas e configurar o NGINX para usar o PKCS nº 11.

Depois do bloco event e antes do bloco http, adicione as seguintes diretivas:

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

No mesmo arquivo /etc/nginx/nginx.conf, configure as diretivas SSL para usar seu certificado e a chave privada dele no Cloud HSM. No bloco http, adicione os seguintes atributos:

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.

O arquivo /etc/nginx/nginx.conf vai ficar assim:

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;

        #...
        #...

}

Configurar o NGINX para detectar tráfego TLS

Edite o arquivo /etc/nginx/sites-enabled/default para detectar o tráfego TLS. Remova a marca de comentário da configuração SSL no bloco server. A mudança resultante será semelhante ao exemplo a seguir:

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

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

        # ...
        # ...
}

Fornecer variáveis de ambiente ao serviço NGINX

Execute este comando:

sudo systemctl edit nginx.service

No editor resultante, adicione as seguintes linhas e substitua LIBPATH pelo valor do local em que você instalou 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"

Depois de configurar esses valores, execute o comando a seguir para disponibilizá-los:

sudo systemctl daemon-reload

Reiniciar o NGINX com o descarregamento de TLS

Execute o comando a seguir para que o NGINX seja reiniciado e use a configuração atualizada:

sudo systemctl start nginx

Observação: se você encontrar erros ao reiniciar, verifique /var/log/nginx/error.log e /var/log/kmsp11/ para mais detalhes.

Teste o NGINX usando o descarregamento de TLS para o Cloud HSM

Use o openssl s_client para testar a conexão com o servidor NGINX executando o seguinte comando:

openssl s_client -connect localhost:443

O cliente conclui o handshake de SSL e aguarda sua entrada:

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

Os registros de auditoria agora vão mostrar operações na sua chave NGINX_KEY. Para conferir os registros, acesse o Cloud Logging no console do Google Cloud . No projeto que você está usando, adicione o seguinte filtro:

resource.type="cloudkms_cryptokeyversion"

Depois de executar a consulta, você verá as operações de chave assimétrica na sua chave NGINX_KEY.

Configurações opcionais

Talvez seja necessário criar um balanceador de carga de rede de passagem externa para expor o servidor NGINX com um IP externo.

Se você precisar usar o NGINX como um proxy reverso com balanceamento de carga, considere atualizar o arquivo de configuração do NGINX. Saiba mais sobre como configurar o NGINX como um proxy reverso lendo HA totalmente ativo para NGINX Plus na plataforma Google Cloud.

Próximas etapas

Agora você configurou o servidor NGINX para usar o descarregamento de TLS no Cloud HSM.