Este guia fornece instruções para configurar o OpenSSL de modo a usar uma chave do Cloud HSM no Debian 11 (Bullseye). Estas instruções são geralmente aplicáveis mesmo que esteja a usar outro SO ou ambiente, mas tenha em atenção que podem existir ligeiras diferenças.
Requisitos
Transfira uma versão da biblioteca para começar. Para ver detalhes adicionais acerca da biblioteca PKCS #11, consulte o manual do utilizador.
Antes de começar, instale o pacote libengine-pkcs11-openssl.
sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl
Configuração
Definir a variável de ambiente PKCS11_MODULE_PATH.
Para que o openssl use a 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 ficheiro de configuração YAML para localizar recursos do Cloud KMS. O YAML tem de configurar, no mínimo, um único token PKCS #11.
Se estiver a usar o OpenSSL com outro processo que possa acabar por criar ramificações (por exemplo, o Apache ou o Nginx), também tem de garantir que o campo refresh_interval_secs permanece não definido ou está definido como 0.
Ficheiro de configuração de exemplo:
---
tokens:
- key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"
Com esta configuração, todas as chaves de assinatura e desencriptação assimétricas em my-keyring vão estar disponíveis na biblioteca.
Tem de definir as autorizações no ficheiro de configuração para que este seja gravável apenas pelo proprietário do ficheiro. Indique KMS_PKCS11_CONFIG para o seu ficheiro de configuração:
export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"
Mais uma vez, pode tornar esta definição permanente adicionando-a ao /etc/profile.
echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile
Executar comandos OpenSSL
Com o motor e a biblioteca configurados corretamente, já pode usar o motor em comandos do OpenSSL.
Quando criar assinaturas assimétricas, tenha em atenção que as chaves do Cloud KMS estão restritas à utilização de um único resumo. Por exemplo, uma CryptoKeyVersion com o algoritmo EC_SIGN_P256_SHA256 tem de ser sempre usada em conjunto com um resumo SHA-256. Isto corresponde à flag -sha256 no OpenSSL. As chaves que requerem resumos SHA-384 ou SHA-512 devem ser usadas com as flags -sha384 ou -sha512.
Crie uma nova assinatura
Supondo que existe uma chave denominada foo no seu conjunto de chaves 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
O resultado deste comando é binário não formatado.
Esse comando pressupõe que está a usar uma chave que usa um resumo SHA-256, pelo que foi usado o argumento -sha256. As opções -sha384 ou -sha512 seriam adequadas para chaves do Cloud HSM que usam esses tipos de resumo.
Para uma chave RSA-PSS, lembre-se de usar as opções -sigopt abordadas anteriormente.
Crie um novo pedido de assinatura de certificado
Também pode gerar um pedido de assinatura de certificado (CSR) para uma chave de assinatura do Cloud HSM. Isto é útil se a sua autoridade de certificação exigir um CSR para gerar um novo certificado para assinatura de código ou para proteger sessões Web TLS.
openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.csr
Gere um novo certificado autoassinado
Para o desenvolvimento e os testes locais, pode usar um certificado autoassinado para uma chave de assinatura do Cloud HSM. Os certificados autoassinados também são úteis para a assinatura de tokens SAML.
openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
-keyform engine -key pkcs11:object=foo > my-request.crt
Resolução de problemas com o PKCS #11 Spy
O PKCS #11 Spy é uma ferramenta de código aberto que regista o conteúdo das interações através de uma interface PKCS #11. Isto é feito através da colocação entre a aplicação e a biblioteca PKCS #11, e do registo de todas as chamadas feitas. Isto pode ser útil para resolver problemas.
Para usar o PKCS #11 Spy, tem de ter o pacote opensc instalado. O pacote opensc contém o PKCS #11 Spy. Para garantir que o opensc está instalado,
execute o seguinte comando:
sudo apt-get install opensc
Em seguida, defina a variável de ambiente PKCS11_MODULE_PATH para direcionar 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, direcione o PKCS #11 Spy para a biblioteca PKCS #11 do HSM na nuvem definindo as variáveis de ambiente PKCS11SPY e PKCS11SPY_OUTPUT. Para definir estas 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"