「攜帶您自己的金鑰」規格

發行項
08/08/2024

此文件描述從客戶的內部部署 HSM 將受 HSM 保護的金鑰匯入 Key Vault 的規格。

案例

Key Vault 客戶想要從其位於 Azure 外的內部部署 HSM 將金鑰安全地傳輸至 HSM 支援的 Azure Key Vault。匯入在 Key Vault 外產生之金鑰的程序，稱為「攜帶您自己的金鑰」(BYOK)。

以下是需求：

要傳輸的金鑰從未以純文字的形式存在於 HSM 之外。
在 HSM 之外，要傳輸的金鑰一律受到保存在 Azure Key Vault HSM 中的金鑰所保護

詞彙

金鑰名稱	索引鍵類型	來源	描述
金鑰交換金鑰 (KEK)	RSA	Azure Key Vault HSM	在 Azure Key Vault 中產生的 HSM 支援 RSA 金鑰組
包裝金鑰	AES	廠商 HSM	由 HSM 於內部部署產生的 [暫時性] AES 金鑰
目標金鑰	RSA、EC、AES (僅限受控 HSM)	廠商 HSM	要傳輸至 Azure Key Vault HSM 的金鑰

金鑰交換金鑰：客戶在將匯入 BYOK 金鑰的金鑰保存庫中產生的 HSM 支援金鑰。此 KEK 必須具有下列屬性：

其為 RSA-HSM 金鑰 (4096 位元或 3072 位元或 2048 位元)
其將會有固定的 key_ops (「僅限」‘import’)，這將允許其「僅可」於 BYOK 期間使用
必須位於將匯入目標金鑰的相同保存庫中

使用者步驟

若要執行金鑰傳輸，使用者需執行下列步驟：

產生 KEK。
擷取 KEK 的公開金鑰。
使用 HSM 廠商提供的 BYOK 工具，將 KEK 匯入目標 HSM，並匯出 KEK 所保護的目標金鑰。
將受保護的目標金鑰匯入 Azure Key Vault。

客戶可以使用 HSM 廠商所提供的 BYOK 工具和文件來完成步驟 3。其會產生金鑰傳輸 Blob (".byok" 檔案)。

HSM 條件約束

現有的 HSM 可能會對其所管理的金鑰套用條件約束，包括：

HSM 可能必須加以設定來允許金鑰包裝型匯出
目標金鑰可能必須標示為 CKA_EXTRACTABLE，HSM 才能允許控制的匯出
在某些情況下，KEK 和包裝金鑰可能需要標示為 CKA_TRUSTED，這可讓它用來將金鑰包裝在 HSM 中。

來源 HSM 的設定通常是在此規格的範圍之外。 Microsoft 預期 HSM 廠商會提供 BYOK 工具隨附的文件，以包括任何這類設定步驟。

注意

您可以使用其他介面來執行這些步驟，例如 Azure PowerShell 和 Azure 入口網站。其也可以使用 Key Vault SDK 中的對等函式來以程式設計方式執行。

產生 KEK

使用 az keyvault key create 命令來建立 KEK 並將金鑰作業設定為匯入。記下從下列命令傳回的金鑰識別碼 'kid'。

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

注意

服務支援不同的 KEK 長度；例如，Azure SQL 只支援 2048 或 3072 個位元組的金鑰長度。如需詳細資訊，請參閱服務的文件。

擷取 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，而且更重要的是，中繼 AES 金鑰是由兩個 HSM 處理，並保證是暫時的。此機制目前無法在某些 HSM 中使用，但使用 AES 金鑰搭配 CKM_AES_KEY_WRAP_PAD 來保護目標金鑰，並使用 CKM_RSA_PKCS_OAEP 來保護 AES 金鑰能產生對等的 Blob。

目標金鑰純文字取決於金鑰類型：

針對 RSA 金鑰，會是包裝在 PKCS#8 [RFC5208] 中的私密金鑰 ASN.1 DER 編碼 [RFC3447]
針對 EC 金鑰，會是包裝在 PKCS#8 [RFC5208] 中的私密金鑰 ASN.1 DER 編碼 [RFC5915]
針對八位元金鑰，會是金鑰的原始位元組

接著會使用 CKM_RSA_AES_KEY_WRAP 機制來轉換純文字金鑰的位元組：

系統會產生暫時性 AES 金鑰，並使用搭配 SHA1 之 RSA-OAEP 的包裝 RSA 金鑰來加密。
編碼的純文字金鑰是使用 AES 金鑰 (使用 AES 金鑰包裝搭配填補) 來加密的。
系統會串連加密的 AES 金鑰和加密的純文字金鑰以產生最終的加密文字 Blob。

傳輸 Blob 的格式主要會使用 JSON Web Encryption Compact Serialization (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 = key identifier of KEK (KEK 的金鑰識別碼)。針對 Key Vault 金鑰，其看起來像這樣：https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = algorithm (演算法)。
dir = Direct mode (直接模式)，也就是會使用所參考的 kid 來直接保護加密文字，其為 CKM_RSA_AES_KEY_WRAP 的正確表示
generator = 表示 BYOK 工具的名稱和版本，以及來源 HSM 製造商和型號的資訊欄位。此資訊的目的是要用於疑難排解和支援。

JSON Blob 會儲存在副檔名為 ".byok" 的檔案中，使 Azure PowerShell/CLI 用戶端會在使用 ‘Add-AzKeyVaultKey’ (PSH) 或 ‘az keyvault key import’ (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 --byok-file --kty EC-HSM --curve-name "P-256" KeyTransferPackage-ContosoFirstHSMkey.byok --ops sign verify

執行上述命令時，會導致傳送如下所示的 REST API 要求：

PUT https://contosokeyvaulthsm.vault.azure.net/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)

共用方式為