Como usar uma chave do Cloud HSM com o OpenSSL

Neste guia, fornecemos instruções para configurar o OpenSSL para usar uma chave do Cloud HSM no Debian 11 (Bullseye). Essas instruções geralmente são aplicáveis mesmo que você esteja usando outro SO ou ambiente, mas pode haver pequenas diferenças.

Requisitos

Faça o download de uma versão da biblioteca para começar. Para saber mais sobre a biblioteca PKCS #11, consulte o guia do usuário.

Antes de começar, instale o pacote libengine-pkcs11-openssl.

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

Configuração

Como definir a variável de ambiente PKCS11_MODULE_PATH.

Para que openssl use nossa biblioteca PKCS #11, defina a variável de ambiente PKCS11_MODULE_PATH:

export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"

Para definir permanentemente a variável de ambiente, adicione export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" a /etc/profile executando o seguinte comando:

echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile

Configuração da biblioteca PKCS #11

A biblioteca PKCS #11 requer um arquivo de configuração YAML para localizar os recursos do Cloud KMS. O YAML precisa, no mínimo, configurar um único token PKCS #11.

Se você estiver usando o OpenSSL com outro processo que pode acabar bifurcando (por exemplo, Apache ou Nginx), você também precisa garantir que o campo refresh_interval_secs permaneça não definido ou definido como 0.

Arquivo de configuração de amostra:

---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"

Com essa configuração, todas as chaves de assinatura e descriptografia assimétricas no my-keyring estarão disponíveis na biblioteca.

É preciso definir as permissões no arquivo de configuração para que ele seja gravável apenas pelo proprietário do arquivo. Aponte KMS_PKCS11_CONFIG para seu arquivo de configuração:

export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

Mais uma vez, você pode tornar essa configuração permanente adicionando-a a /etc/profile.

echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile

Como executar comandos do OpenSSL

Depois de configurar corretamente o mecanismo e a biblioteca, você poderá usá-lo nos comandos do OpenSSL.

Ao criar assinaturas assimétricas, lembre-se de que as chaves do Cloud KMS são restritas para usar um único resumo. Por exemplo, uma CryptoKeyVersion com o algoritmo EC_SIGN_P256_SHA256 precisa ser usada sempre com um resumo SHA-256. Isso corresponde à sinalização -sha256 no OpenSSL. As chaves que exigem resumos SHA-384 ou SHA-512 devem ser usadas com as sinalizações -sha384 ou -sha512.

Criar uma nova assinatura

Supondo que há uma chave chamada foo no keyring configurado, use o seguinte comando para criar uma assinatura sobre bar.txt:

openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt

A saída deste comando é um binário não formatado.

Esse comando presume que você está usando uma chave que recebe um resumo SHA-256, portanto, o argumento -sha256 foi usado. As opções -sha384 ou -sha512 são apropriadas para chaves do Cloud HSM que usam esses tipos de resumo.

Para uma chave RSA-PSS, lembre-se de usar as opções -sigopt discutidas anteriormente.

Criar uma nova solicitação de assinatura de certificado

Também é possível gerar uma solicitação de assinatura de certificado (CSR, na sigla em inglês) para uma chave de assinatura do Cloud HSM. Isso será útil se a autoridade de certificação exigir uma CSR para gerar um novo certificado para assinatura de código ou para proteger sessões da Web TLS.

openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.csr

Gerar um novo certificado autoassinado

Para desenvolvimento e testes locais, é possível usar um certificado autoassinado para uma chave de assinatura do Cloud HSM. Os certificados autoassinados também são úteis para a assinatura do token SAML.

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.crt

Como solucionar problemas com o PKCS #11 Spy

O PKCS #11 Spy é uma ferramenta de código aberto que registra o conteúdo das interações em uma interface do PKCS no 11. Ele faz isso ficando entre o aplicativo e a biblioteca PKCS #11 e registrando todas as chamadas feitas. Isso pode ser útil para a solução de problemas.

Para usar o PKCS #11 Spy, é necessário ter o pacote opensc instalado. O pacote opensc contém PKCS #11 Spy. Para garantir que o opensc esteja instalado, execute o seguinte comando:

sudo apt-get install opensc

Em seguida, defina a variável de ambiente PKCS11_MODULE_PATH para apontar o OpenSSL na biblioteca de espionagem PKCS #11 executando o seguinte comando:

export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so

Por fim, aponte o PKCS #11 Spy para a biblioteca do Cloud HSM PKCS #11 definindo as variáveis de ambiente PKCS11SPY e PKCS11SPY_OUTPUT. Para definir essas variáveis de ambiente, execute os seguintes comandos:

export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"