Share via

Azure 受控 HSM TLS 卸載庫

  • 發行項

Azure 受控 HSM 提供 TLS 卸載程式庫，其與 PKCS#11 2.40 版相容。 Azure 受控 HSM 不支援 PKCS#11 規格中列出的所有函式；相反地，對於只使用 F5 (BigIP) 和 Nginx 的 SSL/TLS 卸載，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) 需要解決方案，才能將 PKCS#11 屬性儲存在 Azure Key Vault 金鑰物件上。 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 – 必須設定為服務主體的應用程式 (用戶端) 識別碼
  • MHSM_CLIENT_SECRET – 必須設定為服務主體的密碼 (用戶端密碼)

對於受控識別，不需要上述環境變數。

  • 使用 --identity 引數，透過 mhsm_p11_create_key 工具啟用受控識別。
  • 使用者指派受控識別的 client_id 應該在 MHSM 組態檔 (mhsm-pkcs11.conf) 中引用。 如果未提供使用者指派受控識別的 client_id，則會將其視為系統指派的受控識別。

金鑰建立工具會在建立時隨機產生金鑰的名稱。 為了方便起見，系統會將完整的 Azure Key Vault 金鑰識別碼和金鑰名稱列印到主控台。

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://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

金鑰建立工具的 --label 引數會為所產生的私密和公用金鑰指定所需的 CKA_LABEL。 通常需要這些屬性才能設定支援的 TLS 卸載解決方案 (例如 nginx SSL 組態設定 `ssl_certificate_key')。

您需要透過 Azure CLI 變更任何角色指派的金鑰名稱。

存取控制

TLS 卸載程式庫會將 C_FindObjectsInit 轉譯為 Azure Key Vault REST API 呼叫，其會在 /keys 範圍運作。 MHSM 服務需要此範圍的讀取權限，TLS 卸載程式庫使用者才能針對透過金鑰建立工具建立的金鑰授權尋找作業。

如需 Azure 受控 HSM 本機 RBAC 的詳細資訊，請參閱：

下一節說明為 TLS 卸載程式庫服務主體和受控識別實作存取控制的不同方法。

TLS 卸載服務主體

TLS 卸載服務主體是由使用 TLS 卸載程式庫來存取金鑰的應用程式所使用，而且透過角色指派至少應具有下列權限：

  • 受控 HSM 中所有金鑰的 KeyRead 權限
  • TLS 卸載所需金鑰的 KeySign 權限

管理員使用者

管理使用者將會建立自訂角色定義和角色指派。 因此，管理使用者應該指派給 "/" 範圍的下列其中一個內建角色：

  • 受控 HSM 密碼編譯人員
  • 受控 HSM 原則管理員
  • 受控 HSM 管理員

金鑰產生服務主體

金鑰產生服務主體會與金鑰建立工具 (mhsm_p11_create_key) 搭配使用，以產生 TLS 卸載金鑰。 此服務主體應該指派給 "/keys" 範圍的「受控 HSM 密碼編譯使用者」角色。

Azure CLI

Azure CLI 可用來執行角色指派等工作。

寬鬆方法

寬鬆方法比較簡單，而且適合用於 Azure 受控 HSM 專用於 TLS 卸載時。

將密碼編譯使用者角色指派給 "/keys" 範圍的 TLS 卸載服務主體。 這會為 TLS 卸載服務主體提供產生金鑰並尋找金鑰進行 TLS 卸載的權限。

az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

針對受控識別，指定命令引數，如下所示：

az keyvault role assignment create --hsm-name ContosoMHSM \
      --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 ContosoMHSM --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 ContosoMHSM  \
--role "TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

連線快取

為了改善對受控 HSM 服務的簽署呼叫效能，TLS 卸載程式庫會快取其對受控 HSM 服務伺服器的 TLS 連線。 根據預設，TLS 卸載程式庫最多快取 20 個 TLS 連線。 連線快取可以透過 MHSM 組態檔 (mhsm-pkcs11.conf) 來控制。

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

停用

如果此值為 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 – 必須設定為服務主體的應用程式 (用戶端) 識別碼
  • MHSM_CLIENT_SECRET – 必須設定為服務主體的密碼 (用戶端密碼)

金鑰建立工具會在建立時隨機產生金鑰的名稱。 為了方便起見，系統會將完整的 Azure Key Vault 金鑰識別碼和金鑰名稱列印到主控台。

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://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

金鑰建立工具的 --label 引數會為所產生的私密和公用金鑰指定所需的 CKA_LABEL。 通常需要這些屬性才能設定支援的 TLS 卸載解決方案 (例如 nginx SSL 組態設定 `ssl_certificate_key')。

如果您打算實作金鑰的細微存取，則需要金鑰名稱。

實作無金鑰 TLS

有兩種方法可產生金鑰及使用金鑰進行無金鑰 TLS：更簡單、更寬鬆的方法，以及可提供更佳安全性的細微方法。 這些方法在實作投入量和安全性強制執行方面有所不同。

更簡單的方法

  1. 建立 TLS 卸載程式庫的服務主體 (例如 TLSOffload ServicePrincipal)
  2. 將「受控 HSM 密碼編譯使用者」角色指派給 "/keys" 範圍的 TLS 卸載服務主體。 
    az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys
  3. 遵循如何使用 TLS 卸載程式庫產生金鑰中的步驟，產生具有必要標籤的金鑰。
  4. 將 TLS 伺服器設定為使用受控 HSM TLS 卸載程式庫作為 PKCS#11 介面程式庫
  5. 使用金鑰標籤和 TLS 卸載服務主體認證來設定 TLS 伺服器 (例如 nginx SSL 組態設定 `ssl_certificate_key')

細微方法

  1. 建立具有下列角色的管理使用者 (例如 TLSOffloadAdminUser)：
    • “/” 範圍的「受控 HSM 密碼編譯官」角色
  2. 為 TLS 卸載金鑰產生建立金鑰產生服務主體 (例如 TLSOffloadKeyGenServicePrincipal)，並指派下列角色：
    • “/keys” 範圍的「受控 HSM 密碼編譯使用者」角色。
  3. 建立 TLS 卸載的服務主體 (例如 TLSOffload ServicePrincipal)
  4. 管理使用者會建立下列自訂角色定義：
    az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'
  5. 遵循「如何使用 TLS 卸載程式庫產生金鑰」以產生具有必要標籤的金鑰。 產生金鑰時，使用金鑰產生服務主體 (例如 TLSOffloadKeyGenServicePrincipal)。 請記下金鑰標籤和金鑰名稱。 例如：
    • 金鑰標籤：tlsKey
    • 金鑰名稱：p11-6a2155dc40c94367a0f97ab452dc216f
  6. 管理使用者會將下列角色指派給 TLS 卸載服務主體
    • "/keys" 範圍的「TLS 程式庫使用者讀取角色」角色
    • "/keys/{金鑰名稱}" 範圍的「受控 HSM 密碼編譯使用者」角色
    az keyvault role assignment create --hsm-name ContosoMHSM  \
--role " TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal @contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
  7. 將 TLS 伺服器設定為使用 Azure 受控 HSM TLS 卸載程式庫作為 PKCS#11 介面程式庫
  8. 使用金鑰標籤和 TLS 卸載服務主體認證來設定 TLS 伺服器 (例如 nginx SSL 組態設定 `ssl_certificate_key')

下一步