在 OpenSSL 中使用 Cloud HSM 金鑰

本指南提供操作說明，說明如何在 Debian 11 (Bullseye) 上設定 OpenSSL，以便使用 Cloud HSM 金鑰。即使您使用的是其他作業系統或環境，這些操作說明通常也適用，但請注意，可能會有些微差異。

需求條件

下載程式庫的發布版本即可開始使用。如要進一步瞭解 PKCS #11 程式庫，請參閱使用手冊。

開始前，請先安裝 libengine-pkcs11-openssl 套件。

sudo apt-get update
sudo apt-get install libengine-pkcs11-openssl

設定

設定 PKCS11_MODULE_PATH 環境變數。

為了讓 openssl 使用 PKCS #11 程式庫，請設定 PKCS11_MODULE_PATH 環境變數：

export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"

如要永久設定環境變數，請執行下列指令，將 export PKCS11_MODULE_PATH="/path/to/libkmsp11.so" 新增至 /etc/profile：

echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee -a /etc/profile

PKCS #11 程式庫設定

PKCS #11 程式庫需要 YAML 設定檔來尋找 Cloud KMS 資源。YAML 至少必須設定一個 PKCS #11 權杖。

如果您將 OpenSSL 與其他可能會分支的程序 (例如 Apache 或 Nginx) 搭配使用，請務必確認 refresh_interval_secs 欄位未設定，或已設為 0。

設定檔範例：

---
tokens:
  - key_ring: "projects/my-project/locations/us-central1/keyRings/my-keyring"

有了這項設定，程式庫中就會提供 my-keyring 中的所有非對稱簽署和解密金鑰。

您必須設定設定檔的權限，讓只有檔案擁有者可以寫入檔案。將 KMS_PKCS11_CONFIG 指向設定檔：

export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"

同樣地，您可以將這項設定新增至 /etc/profile，即可永久保留這項設定。

echo 'export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml"' | sudo tee -a /etc/profile

執行 OpenSSL 指令

在正確設定引擎和程式庫後，您現在可以在 OpenSSL 指令中使用引擎。

建立非對稱簽名時，請注意 Cloud KMS 金鑰只能使用單一摘要。舉例來說，使用 EC_SIGN_P256_SHA256 演算法的 CryptoKeyVersion 一律必須搭配 SHA-256 摘要使用。這會對應至 OpenSSL 中的 -sha256 旗標。需要 SHA-384 或 SHA-512 摘要的金鑰應搭配 -sha384 或 -sha512 旗標使用。

注意： 使用 Cloud KMS 金鑰建立非對稱式簽名時，如果演算法以 RSA_PSS 開頭，OpenSSL 通常需要額外的選項：-sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:digest。

建立新的簽名

假設已設定的金鑰環中含有名為 foo 的金鑰，請使用下列指令在 bar.txt 上建立簽名：

openssl dgst -sha256 -engine pkcs11 -keyform engine -sign pkcs11:object=foo bar.txt

這個指令的輸出內容是未格式化的二進位檔。

該指令假設您使用的是採用 SHA-256 摘要的金鑰，因此使用了 -sha256 引數。-sha384 或 -sha512 選項適合使用這些摘要類型的 Cloud HSM 金鑰。

針對 RSA-PSS 金鑰，請務必使用先前討論的 -sigopt 選項。

建立新的憑證簽署要求

您也可以為 Cloud HSM 簽署金鑰產生憑證簽署要求 (CSR)。如果憑證授權單位要求您提供 CSR，以便產生新的憑證來簽署程式碼，或保護 TLS 網頁工作階段，這項功能就很實用。

openssl req -new -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.csr

注意： 請只為具有 ASYMMETRIC_SIGN 用途的 Cloud KMS 加密編譯金鑰建立 CSR。此外，請務必使用正確的摘要演算法和 -sigopt 選項，以便為鍵類型設定。

產生新的自行簽署憑證

如要進行本機開發和測試，您可以為 Cloud HSM 簽署金鑰使用自行簽署的憑證。自行簽署的憑證也適用於 SAML 權杖簽署。

openssl req -new -x509 -days 3650 -subj '/CN=test/' -sha256 -engine pkcs11 \
  -keyform engine -key pkcs11:object=foo > my-request.crt

注意： Cloud KMS CryptoKey 的自行簽署憑證只能用於 ASYMMETRIC_SIGN 用途。此外，請務必使用正確的摘要演算法和 -sigopt 選項，以便為金鑰類型提供服務。

使用 PKCS #11 Spy 排解問題

PKCS #11 Spy 是開放原始碼工具，可記錄透過 PKCS #11 介面進行互動的內容。這項工具會位於應用程式和 PKCS #11 程式庫之間，並記錄所有發出的呼叫。這項設定在疑難排解時相當實用，

注意： 請勿在敏感工作負載中使用 PKCS #11 Spy。設定完成後，PKCS #11 Spy 就能觀察與 HSM 的所有互動。

如要使用 PKCS #11 Spy，您必須先安裝 opensc 套件。opensc 套件包含 PKCS #11 Spy。如要確認已安裝 opensc，請執行下列指令：

sudo apt-get install opensc

接著，執行下列指令，設定 PKCS11_MODULE_PATH 環境變數，將 OpenSSL 指向 PKCS #11 Spy 程式庫：

export PKCS11_MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so

最後，請設定 PKCS11SPY 和 PKCS11SPY_OUTPUT 環境變數，將 PKCS #11 Spy 指向 Cloud HSM PKCS #11 程式庫。如要設定這些環境變數，請執行下列指令：

export PKCS11SPY="/path/to/libkmsp11.so"
# Optional, stderr will be used for logging if not set
export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log"