Usar uma chave do Cloud HSM com pkcs11-tool

Este guia fornece exemplos de comandos pkcs11-tool para usar uma chave do Cloud HSM no Debian 11 (Bullseye) usando a biblioteca PKCS #11. Os comandos incluídos nestas instruções podem exigir alterações com base na sua distribuição do SO ou Linux.

Antes de começar

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

Usar criptografia e descriptografia simétricas

As seções a seguir mostram como criptografar e descriptografar usando uma chave de criptografia simétrica, o OpenSSL e a ferramenta pkcs11.

Pré-requisitos

Crie uma chave de criptografia simétrica bruta do Cloud HSM. Para criar uma chave do Cloud HSM, defina o Nível de proteção como HSM ao criar uma nova chave.
Anote o algoritmo bruto de criptografia simétrica escolhido para a chave. Cada algoritmo tem os próprios requisitos de padding, vetores de inicialização e dados autenticados adicionais.
Crie um arquivo de entrada que contenha os dados que você quer criptografar.

Criptografar

Para criptografar um arquivo de texto, execute o seguinte comando:

pkcs11-tool --module PATH_TO_LIBKMSP11_SO --encrypt \
    --mechanism MECHANISM \
    --slot 0 \
    --label HSM_KEY_NAME \
    --iv INITIALIZATION_VECTOR \
    --input-file INPUT_TEXT_FILE_PATH \
    --output-file ENCRYPTED_TEXT_FILE_PATH

Substitua:

PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo, /usr/local/lib/libkmsp11.so.
MECHANISM: o mecanismo a ser usado, com base no algoritmo de chave, por exemplo, AES-CBC-PAD.
HSM_KEY_NAME: o nome da chave do Cloud HSM a ser usada para criptografia.
INITIALIZATION_VECTOR: o valor do vetor de inicialização a ser usado como parte da criptografia.
INPUT_TEXT_FILE_PATH: o caminho para o arquivo de entrada que você quer criptografar.
ENCRYPTED_TEXT_FILE_PATH: o caminho em que você quer salvar o arquivo de texto criptografado.

Decrypt

Para descriptografar um arquivo de texto, execute o seguinte comando:

pkcs11-tool --module PATH_TO_LIBKMSP11_SO --decrypt \
    --mechanism MECHANISM \
    --slot 0 \
    --label HSM_KEY_NAME \
    --iv INITIALIZATION_VECTOR \
    --input-file ENCRYPTED_TEXT_FILE_PATH \
    --output-file DECRYPTED_TEXT_FILE_PATH

Substitua:

PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo, /usr/local/lib/libkmsp11.so.
MECHANISM: o mecanismo a ser usado, com base no algoritmo de chave, por exemplo, ECDSA.
HSM_KEY_NAME: o nome da chave do Cloud HSM usada para criptografar o arquivo que você quer descriptografar.
INITIALIZATION_VECTOR: o valor do vetor de inicialização a ser usado como parte da criptografia.
ENCRYPTED_TEXT_FILE_PATH: o caminho para o arquivo que você quer descriptografar.
DECRYPTED_TEXT_FILE_PATH: o caminho em que você quer salvar o arquivo de texto descriptografado.

Usar criptografia e descriptografia assimétricas

As seções a seguir mostram como criptografar e descriptografar usando uma chave de criptografia assimétrica, OpenSSL e a ferramenta pkcs11.

Pré-requisitos

Crie uma chave de descriptografia assimétrica do Cloud HSM e faça o download da chave pública dela.

Observação: para criar uma chave do Cloud HSM no console do Google Cloud, altere o Nível de proteção para HSM ao criar uma nova chave.
Crie um arquivo de entrada com texto.
```
echo Hello World! >> input.txt
```

Criptografar

Para criptografar um arquivo de texto, execute o seguinte comando:

openssl pkeyutl -in INPUT_TEXT_FILE_PATH -encrypt -pubin \
    -inkey PUBLIC_KEY \
    -pkeyopt rsa_padding_mode:oaep \
    -pkeyopt rsa_oaep_md:sha256 \
    -pkeyopt rsa_mgf1_md:sha256 > ENCRYPTED_TEXT_FILE_PATH

Substitua:

INPUT_TEXT_FILE_PATH: o caminho para o arquivo de entrada que você quer criptografar.
PUBLIC_KEY: o caminho para a chave pública.
ENCRYPTED_TEXT_FILE_PATH: o caminho em que você quer salvar o arquivo de texto criptografado.

Decrypt

Para descriptografar um arquivo de texto, execute o seguinte comando:

pkcs11-tool --module PATH_TO_LIBKMSP11_SO \
    --decrypt --mechanism RSA-PKCS-OAEP --slot 0 --hash-algorithm=sha256 \
    --mgf MGF1-SHA256 --label HSM_KEY_NAME --type privkey \
    -i ENCRYPTED_TEXT_FILE_PATH \
    -o OUTPUT_TEXT_FILE_PATH

Substitua:

PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11 (path/to/libkmsp11.so).
HSM_KEY_NAME: o nome da chave do Cloud HSM que corresponde à chave pública usada para criptografar o arquivo de texto.
ENCRYPTED_TEXT_FILE_PATH: o caminho para o arquivo que você quer descriptografar.
OUTPUT_TEXT_FILE_PATH: o caminho em que você quer salvar a saída descriptografada.

Assinar e verificar

As seções a seguir mostram como assinar e verificar usando uma chave de assinatura assimétrica e pkcs11-tool.

Pré-requisitos

Crie uma chave de assinatura assimétrica do Cloud HSM.

Observação: para criar uma chave do Cloud HSM no console do Google Cloud, altere o Nível de proteção para HSM ao criar uma nova chave.
Crie um arquivo com os dados de entrada com hash que você quer assinar.

Assinar

Para assinar um arquivo de texto, execute o seguinte comando:

pkcs11-tool --module PATH_TO_LIBKMSP11_SO --sign \
   --mechanism MECHANISM \
   --slot 0 \
   --label HSM_KEY_NAME \
   -i INPUT_TEXT_FILE_PATH \
   -o OUTPUT_SIGNATURE_FILE_PATH

Substitua:

PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo, path/to/libkmsp11.so.
HSM_KEY_NAME: o nome da chave do Cloud HSM que você quer usar para assinatura.
MECHANISM: o mecanismo a ser usado, com base no algoritmo de chave. Por exemplo, ECDSA.
INPUT_TEXT_FILE_PATH: o caminho para o arquivo de entrada que você quer assinar.
OUTPUT_SIGNATURE_FILE_PATH: o caminho em que você quer salvar o arquivo de assinatura.

Verificar

Para verificar um arquivo de assinatura, execute o seguinte comando:

pkcs11-tool --module PATH_TO_LIBKMSP11_SO --verify \
   --mechanism MECHANISM \
   --slot 0 \
   --label HSM_KEY_NAME \
   -i INPUT_TEXT_FILE_PATH \
   --signature-file SIGNATURE_FILE_PATH

Substitua:

PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo, path/to/libkmsp11.so.
HSM_KEY_NAME: o nome da chave do Cloud HSM que foi usada para gerar a assinatura que você quer verificar.
MECHANISM: o mecanismo a ser usado, com base no algoritmo de chave. Por exemplo, ECDSA.
INPUT_TEXT_FILE_PATH: o caminho para o arquivo que foi assinado anteriormente.
SIGNATURE_FILE_PATH: o caminho para o arquivo de assinatura.