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 mais detalhes 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 pela interface PKCS #11. Ele faz isso ficando entre o aplicativo e na 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 o espião PKCS #11. 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 para a
biblioteca PKCS #11 Spy executando o seguinte comando:
export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Por fim, aponte PKCS #11 Spy para a biblioteca do Cloud HSM PKCS #11 definindo o
Variáveis de ambiente PKCS11SPY e PKCS11SPY_OUTPUT. Para definir esses ambientes
, 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"