Use a Cloud HSM key with pkcs11-tool

This guide provides sample pkcs11-tool commands to use a Cloud HSM key on Debian 11 (Bullseye) using the PKCS #11 library. The commands included in these instructions might require changes based on your OS or Linux distribution.

Before you begin

Before continuing, complete the steps in Using a Cloud HSM key with OpenSSL.

Encrypt and decrypt with OpenSSL and pkcs11-tool

Prerequisite

Create a Cloud HSM Asymmetric Decryption key and download its public key.

Note: To create a Cloud HSM key in the Google Cloud console, change the Protection level to HSM while creating a new key.
Create an input file with some text.
```
echo Hello World! >> input.txt
```

Encrypt

To encrypt a text file, run the following command:

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

Replace the following:

INPUT_TEXT_FILE_PATH: the path to the input file you want to encrypt.
PUBLIC_KEY: the path to the public key.
ENCRYPTED_TEXT_FILE_PATH: the path where you want to save the encrypted text file.

Decrypt

To decrypt a text file, run the following command:

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

Replace the following:

PATH_TO_LIBKMSP11_SO: the path to the PKCS#11 module (path/to/libkmsp11.so).
HSM_KEY_NAME: the name of the Cloud HSM key which corresponds to the public key used to encrypt the text file.
ENCRYPTED_TEXT_FILE_PATH: the path to the file you want to decrypt.
OUTPUT_TEXT_FILE_PATH: the path where you want to save the decrypted output.

Sign and verify with pkcs11-tool

Prerequisite

Create a Cloud HSM Asymmetric Sign key.

Note: To create a Cloud HSM key in the Google Cloud console, change the Protection level to HSM while creating a new key.
Create a file with the hashed input data you want to sign.

Sign

To sign a text file, run the following command:

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

Replace the following:

PATH_TO_LIBKMSP11_SO: the path to the PKCS#11 module, for example path/to/libkmsp11.so.
HSM_KEY_NAME: the name of the Cloud HSM key that you want to use for signing.
MECHANISM: the mechanism to be used, based on the key algorithm. For example, ECDSA.
INPUT_TEXT_FILE_PATH: the path to the input file you want to sign.
OUTPUT_SIGNATURE_FILE_PATH: the path where you want to save the signature file.

Verify

To verify a signature file, run the following command:

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

Replace the following:

PATH_TO_LIBKMSP11_SO: the path to the PKCS#11 module, for example path/to/libkmsp11.so.
HSM_KEY_NAME: the name of the Cloud HSM key that was used to generate the signature that you want to verify.
MECHANISM: the mechanism to be used, based on the key algorithm. For example, ECDSA.
INPUT_TEXT_FILE_PATH: the path to the file that was previously signed.
SIGNATURE_FILE_PATH: the path to the signature file.