Este guia fornece comandos pkcs11-tool de exemplo para usar uma chave do Cloud HSM no
Debian 11 (Bullseye) através da biblioteca PKCS #11. Os comandos incluídos nestas instruções podem exigir alterações com base no seu SO ou distribuição Linux.
Antes de começar
Antes de continuar, conclua os passos em Usar uma chave de HSM na nuvem com o OpenSSL.
Use encriptação e desencriptação simétricas
As secções seguintes mostram como encriptar e desencriptar através de uma chave de encriptação simétrica, do OpenSSL e do pkcs11-tool.
Pré-requisitos
Crie uma chave de encriptação simétrica não processada do Cloud HSM. Para criar uma chave do Cloud HSM, defina o Nível de proteção como HSM ao criar uma nova chave.
Tome nota do algoritmo de encriptação simétrica não processado que escolher para a chave. Cada algoritmo tem os seus próprios requisitos para preenchimento, vetores de inicialização e dados autenticados adicionais.
Crie um ficheiro de entrada que contenha os dados que quer encriptar.
Encriptar
Para encriptar um ficheiro 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 o seguinte:
PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo,/usr/local/lib/libkmsp11.so.MECHANISM: o mecanismo a usar, com base no algoritmo da chave, por exemplo,AES-CBC-PAD.HSM_KEY_NAME: o nome da chave do Cloud HSM a usar para a encriptação.INITIALIZATION_VECTOR: o valor do vetor de inicialização a usar como parte da encriptação.INPUT_TEXT_FILE_PATH: o caminho para o ficheiro de entrada que quer encriptar.ENCRYPTED_TEXT_FILE_PATH: o caminho onde quer guardar o ficheiro de texto encriptado.
Desencriptar
Para desencriptar um ficheiro 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 o seguinte:
PATH_TO_LIBKMSP11_SO: o caminho para o módulo PKCS#11, por exemplo,/usr/local/lib/libkmsp11.so.MECHANISM: o mecanismo a usar, com base no algoritmo da chave, por exemplo,ECDSA.HSM_KEY_NAME: o nome da chave do Cloud HSM que foi usada para encriptar o ficheiro que quer desencriptar.INITIALIZATION_VECTOR: o valor do vetor de inicialização a usar como parte da encriptação.ENCRYPTED_TEXT_FILE_PATH: o caminho para o ficheiro que quer desencriptar.DECRYPTED_TEXT_FILE_PATH: o caminho onde quer guardar o ficheiro de texto desencriptado.
Use encriptação e desencriptação assimétricas
As secções seguintes mostram como encriptar e desencriptar através de uma chave de encriptação assimétrica, do OpenSSL e da pkcs11-tool.
Pré-requisitos
Crie uma chave de descifragem assimétrica do Cloud HSM e transfira a respetiva chave pública.
Crie um ficheiro de entrada com algum texto.
echo Hello World! >> input.txt
Encriptar
Para encriptar um ficheiro 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 o seguinte:
INPUT_TEXT_FILE_PATH: o caminho para o ficheiro de entrada que quer encriptar.PUBLIC_KEY: o caminho para a chave pública.ENCRYPTED_TEXT_FILE_PATH: o caminho onde quer guardar o ficheiro de texto encriptado.
Desencriptar
Para desencriptar um ficheiro 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 o seguinte:
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 encriptar o ficheiro de texto.ENCRYPTED_TEXT_FILE_PATH: o caminho para o ficheiro que quer desencriptar.OUTPUT_TEXT_FILE_PATH: o caminho onde quer guardar o resultado descifrado.
Assine e valide
As secções seguintes mostram como assinar e validar através de uma chave de assinatura assimétrica e da ferramenta pkcs11.
Pré-requisitos
Crie uma chave de assinatura assimétrica do Cloud HSM.
Crie um ficheiro com os dados de entrada com hash que quer assinar.
Assinar
Para assinar um ficheiro 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 o seguinte:
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 quer usar para assinar.MECHANISM: o mecanismo a usar, com base no algoritmo da chave. Por exemplo,ECDSA.INPUT_TEXT_FILE_PATH: o caminho para o ficheiro de entrada que quer assinar.OUTPUT_SIGNATURE_FILE_PATH: o caminho onde quer guardar o ficheiro de assinatura.
Validar
Para validar um ficheiro 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 o seguinte:
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 quer validar.MECHANISM: o mecanismo a usar, com base no algoritmo da chave. Por exemplo,ECDSA.INPUT_TEXT_FILE_PATH: o caminho para o ficheiro que foi assinado anteriormente.SIGNATURE_FILE_PATH: o caminho para o ficheiro de assinatura.