使用 Cloud HSM 金鑰搭配 pkcs11-tool

本指南提供範例 pkcs11-tool 指令，可在 Debian 11 (Bullseye) 上使用 PKCS #11 程式庫的 Cloud HSM 金鑰。這些操作說明中的指令可能需要根據作業系統或 Linux 發行版進行變更。

事前準備

請先完成「使用 OpenSSL 搭配 Cloud HSM 金鑰」中的步驟，再繼續操作。

使用對稱式加密與解密

以下各節說明如何使用對稱加密金鑰、OpenSSL 和 pkcs11-tool 進行加密和解密。

事前準備

  1. 建立 Cloud HSM 原始對稱式加密金鑰。如要建立 Cloud HSM 金鑰，請在建立新金鑰時將「防護等級」設為「HSM」。

  2. 請記下您為金鑰選擇的原始對稱加密演算法。每個演算法都有自己的填充、初始化向量和其他已驗證資料規定。

  3. 建立包含要加密資料的輸入檔案。

加密

如要加密文字檔案，請執行下列指令：

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

更改下列內容：

  • PATH_TO_LIBKMSP11_SO：PKCS#11 模組的路徑，例如 /usr/local/lib/libkmsp11.so。
  • MECHANISM：要使用的機制，取決於鍵值演算法，例如 AES-CBC-PAD。
  • HSM_KEY_NAME：用於加密的 Cloud HSM 金鑰名稱。
  • INITIALIZATION_VECTOR：要用於加密的初始化向量值。
  • INPUT_TEXT_FILE_PATH：要加密的輸入檔案路徑。
  • ENCRYPTED_TEXT_FILE_PATH：您要儲存加密文字檔的路徑。

解密

如要解密文字檔，請執行下列指令：

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

更改下列內容：

  • PATH_TO_LIBKMSP11_SO：PKCS#11 模組的路徑，例如 /usr/local/lib/libkmsp11.so。
  • MECHANISM：要使用的機制，取決於鍵演算法，例如 ECDSA。
  • HSM_KEY_NAME：用於加密要解密的檔案的 Cloud HSM 金鑰名稱。
  • INITIALIZATION_VECTOR：要用於加密的初始化向量值。
  • ENCRYPTED_TEXT_FILE_PATH：要解密的檔案路徑。
  • DECRYPTED_TEXT_FILE_PATH：要儲存解密文字檔案的路徑。

使用非對稱式加密和解密

以下各節說明如何使用非對稱加密金鑰、OpenSSL 和 pkcs11-tool 進行加密和解密。

事前準備

  1. 建立 Cloud HSM 非對稱式解密金鑰，並下載其公開金鑰。

  2. 建立含有文字的輸入檔案。

    echo Hello World! >> input.txt

加密

如要加密文字檔案，請執行下列指令：

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

更改下列內容：

  • INPUT_TEXT_FILE_PATH：要加密的輸入檔案路徑。
  • PUBLIC_KEY：公開金鑰的路徑。
  • ENCRYPTED_TEXT_FILE_PATH：您要儲存加密文字檔案的路徑。

解密

如要解密文字檔，請執行下列指令：

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

更改下列內容：

  • PATH_TO_LIBKMSP11_SO：PKCS#11 模組的路徑 (path/to/libkmsp11.so)。
  • HSM_KEY_NAME：Cloud HSM 金鑰的名稱，對應用於加密文字檔的公開金鑰。
  • ENCRYPTED_TEXT_FILE_PATH：要解密的檔案路徑。
  • OUTPUT_TEXT_FILE_PATH：要儲存解密輸出內容的路徑。

簽署及驗證

以下各節說明如何使用非對稱簽署金鑰和 pkcs11-tool 進行簽署和驗證。

事前準備

  1. 建立 Cloud HSM 非對稱式簽署金鑰。

  2. 建立檔案，其中包含要簽署的雜湊輸入資料。

簽名

如要為文字檔案簽署，請執行下列指令：

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

更改下列內容：

  • PATH_TO_LIBKMSP11_SO：PKCS#11 模組的路徑，例如 path/to/libkmsp11.so。
  • HSM_KEY_NAME：您要用於簽署的 Cloud HSM 金鑰名稱。
  • MECHANISM：根據金鑰演算法，要使用的機制。例如：ECDSA。
  • INPUT_TEXT_FILE_PATH：您要簽署的輸入檔案路徑。
  • OUTPUT_SIGNATURE_FILE_PATH：您要儲存簽名檔案的路徑。

驗證

如要驗證簽章檔案，請執行下列指令：

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

更改下列內容：

  • PATH_TO_LIBKMSP11_SO：PKCS#11 模組的路徑，例如 path/to/libkmsp11.so。
  • HSM_KEY_NAME：用於產生要驗證的簽章的 Cloud HSM 金鑰名稱。
  • MECHANISM：根據金鑰演算法，要使用的機制。例如：ECDSA。
  • INPUT_TEXT_FILE_PATH：先前簽署檔案的路徑。
  • SIGNATURE_FILE_PATH：簽名檔案的路徑。