将 Cloud HSM 密钥与 OpenSSL 结合使用

本指南介绍了如何设置 OpenSSL 以在 Debian 11 (Bullseyes) 上使用 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 CryptoKey 创建 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"