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

Before you begin

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

Use symmetric encryption and decryption

The following sections show you how to encrypt and decrypt using a symmetricencryption key, OpenSSL, and pkcs11-tool.

Prerequisites

1. Create a Cloud HSMraw symmetric encryptionkey. To create a Cloud HSM key, settheProtection level toHSM while creating a new key.

2. Make note of the raw symmetric encryption algorithm that you choose forthe key. Each algorithm has its own requirements forpadding, initialization vectors, and additional authenticated data.

3. Create an input file that contains the data that you want to encrypt.

Encrypt

To encrypt a text file, run the following command:

pkcs11-tool --modulePATH_TO_LIBKMSP11_SO --encrypt \    --mechanismMECHANISM \    --slot 0 \    --labelHSM_KEY_NAME \    --ivINITIALIZATION_VECTOR \    --input-fileINPUT_TEXT_FILE_PATH \    --output-fileENCRYPTED_TEXT_FILE_PATH

Replace the following:

• PATH_TO_LIBKMSP11_SO: the path to the PKCS#11module—for example,/usr/local/lib/libkmsp11.so.
• MECHANISM: the mechanism to be used, based on the keyalgorithm—for example,AES-CBC-PAD.
• HSM_KEY_NAME: the name of the Cloud HSM keyto use for encryption.
• INITIALIZATION_VECTOR: the value of the initializationvector to be used as part of the encryption.
• INPUT_TEXT_FILE_PATH: the path to the input file you wantto encrypt.
• ENCRYPTED_TEXT_FILE_PATH: the path where you want to savethe encrypted text file.

Decrypt

To decrypt a text file, run the following command:

pkcs11-tool --modulePATH_TO_LIBKMSP11_SO --decrypt \    --mechanismMECHANISM \    --slot 0 \    --labelHSM_KEY_NAME \    --ivINITIALIZATION_VECTOR \    --input-fileENCRYPTED_TEXT_FILE_PATH \    --output-fileDECRYPTED_TEXT_FILE_PATH

Replace the following:

• PATH_TO_LIBKMSP11_SO: the path to the PKCS#11module—for example,/usr/local/lib/libkmsp11.so.
• MECHANISM: the mechanism to be used, based on the keyalgorithm—for example,ECDSA.
• HSM_KEY_NAME: the name of the Cloud HSM keythat was used to encrypt the file that you want to decrypt.
• INITIALIZATION_VECTOR: the value of the initializationvector to be used as part of the encryption.
• ENCRYPTED_TEXT_FILE_PATH: the path to the file you wantto decrypt.
• DECRYPTED_TEXT_FILE_PATH: the path where you want to savethe decrypted text file.

Use asymmetric encryption and decryption

The following sections show you how to encrypt and decrypt using an asymmetricencryption key, OpenSSL, and pkcs11-tool.

Prerequisites

1. Create a Cloud HSMAsymmetric Decryptionkey anddownload its publickey.

   Note: To create a Cloud HSM key in the Google Cloud console, changetheProtection level toHSM while creating a new key.

2. Create an input file with some text.

   echoHelloWorld! >>input.txt

Encrypt

To encrypt a text file, run the following command:

openssl pkeyutl -inINPUT_TEXT_FILE_PATH -encrypt -pubin \    -inkeyPUBLIC_KEY \    -pkeyopt rsa_padding_mode:oaep \    -pkeyopt rsa_oaep_md:sha256 \    -pkeyopt rsa_mgf1_md:sha256 >ENCRYPTED_TEXT_FILE_PATH

pkcs11-tool--modulePATH_TO_LIBKMSP11_SO\--decrypt--mechanismRSA-PKCS-OAEP--slot0--hash-algorithm=sha256\--mgfMGF1-SHA256--labelHSM_KEY_NAME--typeprivkey\-iENCRYPTED_TEXT_FILE_PATH\-oOUTPUT_TEXT_FILE_PATH

1. Create a Cloud HSMAsymmetric Sign key.

   Note: To create a Cloud HSM key in the Google Cloud console, change theProtection level toHSM while creating a new key.

2. Create a file with the hashed input data you want to sign.

Sign

To sign a text file, run the following command:

pkcs11-tool--modulePATH_TO_LIBKMSP11_SO--sign\--mechanismMECHANISM\--slot0\--labelHSM_KEY_NAME\-iINPUT_TEXT_FILE_PATH\-oOUTPUT_SIGNATURE_FILE_PATH

pkcs11-tool--modulePATH_TO_LIBKMSP11_SO--verify\--mechanismMECHANISM\--slot0\--labelHSM_KEY_NAME\-iINPUT_TEXT_FILE_PATH\--signature-fileSIGNATURE_FILE_PATH