Azure 托管 HSM TLS 卸载库

Azure Managed HSM 提供支持 PKCS#11 版本 2.40 的 TLS 卸载库。 Azure托管 HSM 不支持 PKCS#11 规范中列出的所有功能;相反，TLS 卸载库支持一组有限的机制和接口函数，用于使用 F5（BigIP）和 Nginx 进行 SSL/TLS 卸载，主要是为了在 TLS 握手期间生成 TLS 服务器证书密钥并生成数字签名。

有关更多信息，请参阅 Azure 托管的 HSM TLS 卸载库 GitHub。

TLS 卸载库在内部使用 Azure Key Vault REST API 与 Azure 托管 HSM 交互。

开始

PKCS#11 属性

若要与 PKCS#11 正确集成，请生成密钥（通过 C_GenerateKeyPair），并查找密钥对象（通过 C_FindObjectsInit/C_FindObjects），需要一个解决方案来存储 Azure Key Vault 键对象的 PKCS#11 属性。 TLS 卸载库将这些必需的 PKCS#11 属性转换为Azure Key Vault标记。

这些“属性标记”具有特殊前缀：

p11_pri_{P11 属性名称} - 私钥属性
p11_pub_{P11 属性名称} - 公钥属性

TLS 卸载库正确设置Azure Key Vault密钥操作和密钥生存期属性，以便服务可以适当地对生成的密钥强制实施这些限制。这些属性也会像其他 PKCS#11 属性一样存储为标记，以支持查询功能。

使用 TLS 卸载库的应用程序将使用一个或多个 PKCS#11 属性来定位和使用密钥对象。

警告

TLS 卸载库及其标记生成的密钥可通过 Azure Key Vault REST API 进行访问。使用 Azure Key Vault REST API 操作这些 P11 属性标记可能会中断 TLS 卸载库应用程序。

密钥生成

TLS 卸载库包括 mhsm_p11_create_key 这一密钥创建工具。在不带任何命令行参数的情况下运行该工具时，系统会显示该工具的正确用法。

密钥创建工具需要一个服务主体，该服务主体被分配到“/keys”范围内的“托管 HSM 加密用户”角色。

该密钥创建工具将从环境变量 MHSM_CLIENT_ID 和 MHSM_CLIENT_SECRET 读取服务主体凭据：

MHSM_CLIENT_ID - 必须设置为服务主体的应用程序（客户端）ID
MHSM_CLIENT_SECRET - 必须设置为服务主体的密码（客户端密码）

对于托管标识，不需要上述环境变量。

使用 --identity 参数通过 mhsm_p11_create_key 工具启用托管标识。
应在 MHSM 配置文件 (mhsm-pkcs11.conf) 中引用用户分配的托管标识的 client_id。如果未提供用户分配的托管标识的 client_id，它会将其视为系统分配的托管标识。

该密钥创建工具将在创建密钥时随机为其生成名称。为了方便起见，完整Azure Key Vault密钥 ID 和密钥名称将打印到控制台。

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully. \
Managed HSM Key ID: https://<hsm-name>.managedhsm.chinacloudapi.cn/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

该密钥创建工具的 --label 参数将为生成的私钥和公钥指定所需的 CKA_LABEL。这些属性通常是配置支持的 TLS 卸载解决方案时的必需属性（例如 nginx SSL 配置设置“ssl_certificate_key”）。

你需要通过Azure CLI更改任何角色分配的密钥名称。

访问控制

TLS 卸载库将C_FindObjectsInit转换为在 /keys 范围内运行的Azure Key Vault REST API 调用。 MHSM 服务需要 TLS 卸载库用户在此范围内具有读取权限，以便授权执行通过密钥创建工具创建的密钥的查找操作。

有关 Azure Managed HSM 的本地 RBAC 详细信息，请参阅：

以下部分介绍了为 TLS 卸载库服务主体和托管标识实现访问控制的不同方法。

TLS 卸载服务主体

TLS 卸载服务主体由使用 TLS 卸载库访问密钥的应用程序使用，且应通过角色分配至少获得以下权限：

对托管 HSM 中所有密钥的 KeyRead 权限
用于 TLS 卸载所需密钥的 KeySign 许可权限

管理员用户

管理员用户将创建自定义角色定义和角色分配。因此，应在“/”范围内为管理员用户分配以下内置角色之一：

托管硬件安全模块加密管理员
托管硬件安全模块 (HSM) 策略管理员
托管 HSM 管理员

密钥生成服务主体

密钥生成服务主体与密钥创建工具 (mhsm_p11_create_key) 一起用于生成 TLS 卸载密钥。对于此服务主体，应在“/keys”范围内为其分配“托管 HSM 加密用户”角色。

Azure CLI

Azure CLI可用于执行角色分配等任务。

宽松方法

宽松方法更简单，适合在专用于 TLS 卸载的 Azure 托管 HSM 时使用。

请在“/keys”范围内为 TLS 卸载服务主体分配“加密用户”角色。这可为 TLS 卸载服务主体提供生成并查找密钥的权限，以便其完成 TLS 卸载。

az keyvault role assignment create --hsm-name <hsm-name> \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys

对于托管身份，指定命令参数，如下所示:

az keyvault role assignment create --hsm-name <hsm-name> \
      --role "Managed HSM Crypto User"  \
       --assignee-object-id <object-id>  \
       --assignee-principal-type MSI \
       --scope /keys

颗粒化方法

细粒度方法实现了精细的访问控制。它需要两个服务主体（TLS 卸载服务主体和密钥生成服务主体），以及一个管理员用户。

目的是限制 TLS 卸载服务主体的权限，以支持 TLS 卸载所需的最低权限。用户必须拥有读取其他密钥的权限，以支持该库的 C_FindObject* 函数。

TLS 卸载库用户读取权限

实现精细方法的第一步是创建自定义角色。此操作仅需执行一次。

具有托管 HSM 加密官、托管 HSM 管理员或托管 HSM 策略管理员角色之一的管理员用户将创建一个自定义的“TLS 库用户读取角色”角色定义：

az keyvault role definition create --hsm-name <hsm-name> --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": [] \
}'

生成密钥

可以使用密钥生成服务主体和密钥创建工具 (mhsm_p11_create_key) 来生成密钥。

授予权限

管理员用户将为 TLS 卸载服务主体分配以下角色。

在“/keys”范围内分配“TLS 库用户读取角色”
在“/keys/{密钥名称}”范围内分配“管理的 HSM 加密用户”角色

在以下示例中，密钥名称为“p11-6a2155dc40c94367a0f97ab452dc216f”。

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "TLS Library User Read Role"  \
--assignee <service-principal-id>  \
--scope /keys

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

连接缓存

为了提高对托管 HSM 服务的签名请求的处理性能，TLS 卸载库会缓存其与托管 HSM 服务服务器的 TLS 连接。默认情况下，TLS 卸载库最多缓存 20 个 TLS 连接。可以通过 MHSM 配置文件 (mhsm-pkcs11.conf) 控制连接缓存。

"ConnectionCache": {
        "Disable": false, 
        "MaxConnections": 20
}

Disable

如果此值为 true，则将禁用连接缓存。默认情况下，它是启用的。

MaxConnections

指定缓存的最大连接数。最大连接限制应根据应用程序使用的并发 PKCS11 会话数进行配置。应用程序通常会创建 PKCS11 会话池，并使用它们从线程池并行生成签名请求。 MaxConnections 应与应用程序生成的并发签名请求数匹配。

每秒签名请求数 (RPS) 取决于并发请求数和缓存的连接数。如果并发 PKCS11 签名请求数低于此限制，那么即使指定更高的数字或使用默认限制，也不会提高签名请求每秒处理率 (RPS)。实现标准 B1 HSM 池突发模式的最大并发连接数约为 30，具体取决于实例类型。但应尝试使用不同的数值来找出最佳的并发连接数。

请参阅应用程序文档或联系应用程序供应商，详细了解应用程序如何使用 PKCS11 库。

使用 TLS 卸载库

生成密钥

TLS 卸载库包括 mhsm_p11_create_key 这一密钥创建工具。在不带任何命令行参数的情况下运行该工具时，系统会显示该工具的正确用法。

密钥创建工具需要一个服务主体，该服务主体被分配到“/keys”范围内的“托管 HSM 加密用户”角色。

该密钥创建工具将从环境变量 MHSM_CLIENT_ID 和 MHSM_CLIENT_SECRET 读取服务主体凭据。

MHSM_CLIENT_ID - 必须设置为服务主体的应用程序（客户端）ID
MHSM_CLIENT_SECRET - 必须设置为服务主体的密码（客户端密码）

该密钥创建工具将在创建密钥时随机为其生成名称。为了方便起见，完整的Azure Key Vault密钥 ID 和密钥名称将打印到控制台。

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully.
Managed HSM Key ID: https://<hsm-name>.managedhsm.chinacloudapi.cn/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

如果计划实现对密钥的精细访问，则需要密钥名称。

实现无密钥 TLS

生成密钥并使用密钥来实现无密钥 TLS 的方法有两种：一种是较简单、较宽松的方法，另一种则是较精细的方法；后者可提供更出色的安全性。这些方法在实现的工作量和安全措施的实施方面存在差异。

较简单的方法

为 TLS 卸载库创建服务主体（例如 TLSOffload ServicePrincipal）

在“/keys”范围内为 TLS 卸载服务主体分配“托管 HSM 密钥加密用户”角色。

az keyvault role assignment create --hsm-name <hsm-name> \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys

按照如何使用 TLS 卸载库生成密钥中的步骤生成具有所需标签的密钥。
将 TLS 服务器配置为使用托管 HSM TLS 卸载库作为 PKCS#11 接口库
使用密钥标签和 TLS 卸载服务主体凭据配置 TLS 服务器（例如，nginx SSL 配置设置“ssl_certificate_key”）

颗粒化方法

创建具有以下角色的管理员用户（例如 TLSOffloadAdminUser）：
- “/” 范围内的“托管 HSM 加密员”角色
为 TLS 卸载密钥生成创建密钥生成服务主体（例如 TLSOffloadKeyGenServicePrincipal），并分配以下角色：
- “/keys”范围内的“托管 HSM 加密用户”角色。
为 TLS 卸载创建服务主体（例如 TLSOffload ServicePrincipal）

管理员用户创建以下自定义角色定义：

az keyvault role definition create --hsm-name <hsm-name> --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'

按照《如何使用 TLS 卸载库生成密钥》中的说明生成具有所需标签的密钥。生成密钥时，请使用密钥生成服务主体（例如，TLSOffloadKeyGenServicePrincipal）。记下密钥标签和密钥名称。例如：
- 密钥标签：tlsKey
- 密钥名称：p11-6a2155dc40c94367a0f97ab452dc216f

管理员用户将以下角色分配给 TLS 卸载服务主体

“/keys”范围内的“TLS 库用户读取角色”
“/keys/{密钥名称}”范围内的“受管 HSM 加密用户”角色

az keyvault role assignment create --hsm-name <hsm-name>  \
--role " TLS Library User Read Role"  \
--assignee <service-principal-id>  \
--scope /keys

az keyvault role assignment create --hsm-name <hsm-name>  \
--role "Managed HSM Crypto User"  \
--assignee <service-principal-id>  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

将 TLS 服务器配置为使用 Azure 托管 HSM TLS 卸载库作为 PKCS#11 接口库
使用密钥标签和 TLS 卸载服务主体凭据配置 TLS 服务器（例如，nginx SSL 配置设置“ssl_certificate_key”）

后续步骤

Last updated on 2026-04-22

Azure 托管 HSM TLS 卸载库

开始

PKCS#11 属性

密钥生成

访问控制

TLS 卸载服务主体

管理员用户

密钥生成服务主体

Azure CLI

宽松方法

颗粒化方法

TLS 卸载库用户读取权限

生成密钥

授予权限

连接缓存

使用 TLS 卸载库

生成密钥

实现无密钥 TLS

较简单的方法

颗粒化方法

后续步骤

其他资源