本指南介绍了如何设置 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