“创建自己的密钥”规范

本文介绍将受 HSM 保护的密钥从客户的本地 HSM 导入 Key Vault 的规范。

方案

Key Vault 客户希望将密钥从 Azure 外部的本地 HSM 安全地传输到支持 Azure Key Vault 的 HSM。 此过程称为自带密钥（BYOK）。

需要满足以下要求：

• 以纯文本形式在 HSM 外部传输的密钥永远不会存在。
• 在 HSM 外部，要传输的密钥始终受 Azure Key Vault HSM 中保存的密钥的保护。

术语

密钥交换密钥：在导入 BYOK 密钥的密钥保管库中生成的 HSM 支持的密钥。 此 KEK 必须具有以下属性：

• 它是 RSA-HSM 密钥（4096 位、3072 位或 2048 位）。
• 它具有固定的 key_ops（仅 import），你只能在 BYOK 期间使用。
• 它必须位于导入目标密钥的同一保管库中。

用户步骤

若要执行密钥传输，用户将执行以下步骤：

1. 生成 KEK。
2. 检索 KEK 的公钥。
3. 使用 HSM 供应商提供的 BYOK 工具将 KEK 导入目标 HSM，并导出受 KEK 保护的目标密钥。
4. 将受保护的目标密钥导入 Azure Key Vault。

客户使用 HSM 供应商提供的 BYOK 工具和文档来完成步骤 3。 它生成一个密钥传输 Blob 文件（.byok 文件）。

HSM 约束

现有 HSM 可能会对所管理的密钥应用约束，包括：

• 可能需要将 HSM 配置为允许基于密钥包装的导出。
• 可能需要将目标密钥标记为 CKA_EXTRACTABLE，以便 HSM 允许受控导出。
• 在某些情况下，可能需要将 KEK 和包装密钥标记为CKA_TRUSTED，这样就可以使用它在 HSM 中包装密钥。

源 HSM 的配置通常超出此规范的范围。 Microsoft 期望 HSM 供应商生成 BYOK 工具随附的文档，以包含此类配置步骤。

生成 KEK

使用 az keyvault key create 命令来创建一个具有导入作为密钥操作的 KEK。 请注意此命令返回的密钥标识符 kid 。

az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM

检索 KEK 的公钥

下载 KEK 的公钥部分并将其存储在 PEM 文件中。

az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem

使用 HSM 供应商提供的 BYOK 工具生成密钥传输 Blob

使用 HSM 供应商提供的 BYOK 工具来创建密钥传输 Blob（将其存储为 .byok 文件）。 该工具将 KEK 公钥作为 .pem 文件作为其输入之一。

密钥传输 Blob对象

Microsoft计划使用 PKCS#11 CKM_RSA_AES_KEY_WRAP机制将目标密钥传输到 Azure Key Vault。 此机制生成单个 Blob，更重要的是，这两个 HSM 处理中间 AES 密钥，并保证它是临时的。 此机制目前在某些 HSM 中不可用，但将CKM_AES_KEY_WRAP_PAD与 AES 密钥结合使用来保护目标密钥，并使用 CKM_RSA_PKCS_OAEP创建等效 blob 来保护 AES 密钥。

目标密钥明文依赖于密钥类型：

• 对于 RSA 密钥，私钥采用符合 ASN.1 DER 编码 [RFC3447] 的格式，并封装在 PKCS#8 [RFC5208] 中。
• 对于 EC 密钥，私钥使用 ASN.1 DER 编码，并包装在 PKCS#8 [RFC5208] 中[参见 RFC5915]。
• 对于八进制键，密钥使用原始字节。

此过程使用CKM_RSA_AES_KEY_WRAP机制转换纯文本键的字节数：

• 该过程生成临时 oct 密钥，并使用包装 RSA 密钥和带 SHA1 的 RSA-OAEP 对其进行加密。
• 此过程使用八进制密钥和带填充的 AES 密钥包装来加密编码的纯文本密钥。
• 该过程连接加密的 oct 密钥和加密的纯文本密钥，以生成最终的密码文本 blob。

传输 blob 格式使用 JSON Web 加密压缩序列化（RFC7516）主要用作将所需元数据传送到服务以正确解密的工具。

如果使用CKM_RSA_AES_KEY_WRAP_PAD，传输 blob 的 JSON 序列化为：

{
  "schema_version": "1.0.0",
  "header":
  {
    "kid": "<key identifier of the KEK>",
    "alg": "dir",
    "enc": "CKM_RSA_AES_KEY_WRAP"
  },
  "ciphertext":"BASE64URL(<ciphertext contents>)",
  "generator": "BYOK tool name and version; source HSM name and firmware version"
}

• kid = KEK 的密钥标识符。 对于 Key Vault 的密钥，其表现如下： https://ContosoKeyVaultHSM.vault.azure.cn/keys/mykek/eba63d27e4e34e028839b53fac905621
• alg = 算法。
• dir = 直接模式。 引用的 kid 直接保护了密码文本，这准确地表示了CKM_RSA_AES_KEY_WRAP。
• generator = 一个信息字段，表示 BYOK 工具和源 HSM 制造商和型号的名称和版本。 使用此信息进行故障排除和支持。

将 JSON Blob 存储在具有.byok扩展名的文件中，以便在使用Add-AzKeyVaultKey（PowerShell）或az keyvault key import（CLI）命令时，Azure PowerShell 或 CLI 客户端能正确处理它。

上传密钥传输 blob 以导入 HSM 密钥

若要导入密钥，请将密钥传输 Blob（“.byok”文件）传输到联机工作站，然后运行 az keyvault key import 命令。 此命令将 Blob 作为新的 HSM 支持的密钥导入 Key Vault。

若要导入 RSA 密钥，请使用以下命令：

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops encrypt decrypt

若要导入 EC 密钥，请指定密钥类型和曲线名称。

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --kty EC-HSM --curve-name "P-256" --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops sign verify

运行此命令时，它会发送 REST API 请求，如下所示：

PUT https://contosokeyvaulthsm.vault.azure.cn/keys/ContosoFirstHSMKey?api-version=7.0

导入 RSA 密钥时的请求正文：

{
  "key": {
    "kty": "RSA-HSM",
    "key_ops": [
      "decrypt",
      "encrypt"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

导入 EC 密钥时的请求正文：

{
  "key": {
    "kty": "EC-HSM",
    "crv": "P-256",
    "key_ops": [
      "sign",
      "verify"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

key_hsm 值是 KeyTransferPackage-ContosoFirstHSMkey.byok 文件的全部内容，以 Base64 格式编码。

参考

• Key Vault 开发人员指南

后续步骤

• 分步 BYOK 说明： 将受 HSM 保护的密钥导入 Key Vault（BYOK）