将 Cloud HSM 密钥与 OpenSSL 结合使用

本指南介绍了如何设置 OpenSSL 以在 Debian 11 (Bullseyes) 上使用 Cloud HSM 密钥。即使您使用的是其他操作系统或环境,相关说明通常也适用,但要注意它们可能会略有不同。

要求

下载该库的版本以开始使用。请参阅用户指南

在开始之前,请安装 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"
echo 'export PKCS11_MODULE_PATH="/path/to/libkmsp11.so"' | sudo tee /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 /etc/profile

运行 OpenSSL 命令

正确配置引擎和库后,您现在可以在 OpenSSL 命令中使用引擎。

创建非对称签名时,请注意 Cloud KMS 密钥只能使用单个摘要。例如,具有算法 EC_SIGN_P256_SHA256 的 CryptoKeyVersion 必须始终与 SHA-256 摘要结合使用。这对应于 OpenSSL 中的 -sha256 标志。需要 SHA-384 或 SHA-512 摘要的密钥应与 -sha384-sha512 标志结合使用。

创建新签名

假设您配置的密钥环中存在名为 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

生成新的自签名证书

对于本地开发和测试,您可以为 Cloud HSM 签名密钥使用自签名证书。自签名证书对于 SAML 令牌签名也很有用。

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