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

Neste guia, fornecemos instruções para configurar o NGINX para usar um Chave do Cloud HSM para descarregamento de TLS no Debian 11 (Bullseye). Talvez seja necessário modifique esses comandos para que funcionem com sua distribuição do SO ou Linux.

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

Uma versão de blueprint baseada no Terraform deste tutorial está disponível em repositório do GitHub kms-solutions.

Casos de uso

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

• Você quer que seu servidor da Web NGINX descarregue o servidor criptográfico TLS no Cloud HSM.
• Você não quer armazenar a chave privada do certificado no sistema de arquivos local da instância do Compute Engine que está hospedando seu site para o aplicativo.
• Você precisa atender aos requisitos regulamentares quando os aplicativos voltados para o público precisam que os certificados sejam protegidos por um HSM com certificação FIPS 140-2 3.
• Você quer usar o NGINX para criar um proxy reverso com TLS para proteger seu aplicativo da Web.

Antes de começar

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

Após a configuração do OpenSSL terminar, verifique se uma versão recente do nginx foi instalado:

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

Observação: nginx 1.18.0-6.1 e versões mais recentes oferecem suporte ao esquema de URI PKCS #11 (RFC 7512). Talvez seja necessário fazer upgrade instalou o pacote nginx.

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

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

1. Siga as instruções para criar e ativar contas de serviço para instâncias para 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 IPs externos e a criação de chaves de contas de serviço.

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

3. Crie uma sub-rede personalizada que permita 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 anteriormente.
   • Selecione a rede que você criou anteriormente.
     • Adicione rótulos apropriados para todas as regras de firewall.
     • Verifique se a sub-rede tem o "IP externo" definido como none.

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

   • Saiba mais lendo Configuração do IAP para computação.

Criar e configurar uma chave de assinatura hospedada no Cloud KMS

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

Criar uma chave de assinatura hospedada no Cloud KMS

Crie uma chave de assinatura EC-P256-SHA256 do Cloud KMS no seu projeto do Google 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 de gerenciamento de identidade e acesso (IAM) corretas no keyring para poder usá-las.

Estabeleça uma conexão SSH com sua VM usando o IAP

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

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

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

Criar um certificado com o OpenSSL

Para um ambiente de produção, crie uma solicitação de assinatura de certificado (CSR). Aprender leia o exemplo para gerar uma CSR. Forneça a CSR à autoridade certificadora (AC) para que ela possa criar um certificado para você. Use o certificado fornecido pela AC nas seções seguintes.

Por exemplo, é possível gerar um certificado autoassinado com o Chave de assinatura hospedada no Cloud KMS. Para isso, o OpenSSL permite que você use URIs PKCS #11 em vez de um caminho regular, identificando a chave pelo rótulo Para chaves do Cloud KMS, o marcador é 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 assinatura assimétrica de dados. 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 da chave. 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 para a chave. Se você usa pkcs11:object, use o nome da chave, por exemplo, NGINX_KEY. Se você estiver usando pkcs11:id, use o ID de recurso completo 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 certificado. .

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

Agora você terá um certificado como este:

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

Instale seu certificado para o NGINX

Execute os comandos a seguir para criar um local para publicar seu certificado:

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

Configurar o ambiente para usar a biblioteca PKCS #11

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

Preparar configurações de biblioteca para o NGINX

Permita que o NGINX registre as operações do mecanismo PKCS no 11 com o com 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 apropriadas 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 offloading de TLS editando alguns arquivos do NGINX. Primeiro, edite o /etc/nginx/nginx.conf em dois locais para adicionar algumas diretivas e configurar NGINX para usar PKCS #11.

Após o bloco event e antes do bloco http, adicione o seguinte 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 suas e a chave privada dele no Cloud HSM. No bloco http, adicione o 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;

        # ...
        # ...
}

Forneça as variáveis de ambiente para o serviço NGINX

Execute este comando:

sudo systemctl edit nginx.service

No editor resultante, adicione as seguintes linhas e substitua as LIBPATH pelo valor do local em que você fez a instalação. 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 seguinte comando para disponibilizá-los:

sudo systemctl daemon-reload

Reiniciar o NGINX com o descarregamento de TLS

Execute o comando a seguir para que o NGINX reinicie e use o atualizado configuração:

sudo systemctl start nginx

Observação :se aparecer algum erro na reinicialização, verifique o /var/log/nginx/error.log e /var/log/kmsp11/ para mais detalhes.

O teste NGINX usa o descarregamento de TLS para o Cloud HSM

usar 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 deve concluir o handshake de SSL e pausar. O cliente está aguardando sua resposta, conforme mostrado a seguir:

# 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 mostrarão as operações para a chave NGINX_KEY. Para conferir os registros, acesse o Cloud Logging no console do Cloud. No projeto que você está usando, adicione o seguinte filtro:

resource.type="cloudkms_cryptokeyversion"

Depois de executar a consulta, serão exibidas operações de chave assimétrica na sua Tecla NGINX_KEY.

Configurações opcionais

Talvez seja necessário criar um balanceador de carga de rede de passagem externa para exponha o servidor NGINX a 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 configurar o NGINX como um proxy reverso lendo Alta disponibilidade total para NGINX Plus no Google Cloud Google Cloud Platform.

Próximas etapas

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