使用 Azure CLI 管理受控 HSM

發行項
03/08/2024

注意

Key Vault 支援兩種類型的資源：保存庫和受控 HSM。本文與受控 HSM 有關。如果您想要瞭解如何管理保存庫，請參閱使用 Azure CLI 管理金鑰保存庫。

如需受控 HSM 的概觀，請參閱什麼是受控 HSM？

如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。

必要條件

若要完成本文中的步驟，您必須具有下列項目︰

訂閱 Microsoft Azure。如果您沒有帳戶，您可以註冊免費試用。
Azure CLI 2.25.0 版或更新版本。執行 az --version 以尋找版本。如果您需要安裝或升級，請參閱安裝 Azure CLI 模組。
訂用帳戶中的受控 HSM。請參閱快速入門：使用 Azure CLI 佈建並啟動受控 HSM，以佈建並啟動受控 HSM。

Azure Cloud Shell

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。您可以使用 Bash 或 PowerShell 搭配 Cloud Shell，與 Azure 服務共同使用。您可以使用 Cloud Shell 預先安裝的命令，執行本文提到的程式碼，而不必在本機環境上安裝任何工具。

要啟動 Azure Cloud Shell：

選項	範例/連結
選取程式碼或命令區塊右上角的 [試試看]。選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。

若要使用 Azure Cloud Shell：

啟動 Cloud Shell。
選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。
透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。
選取 Enter 鍵執行程式碼或命令。

若要使用 CLI 登入 Azure，您可以輸入：

az login

如需透過 CLI 登入選項的詳細資訊，請參閱使用 Azure CLI 登入

注意

下列所有命令都會顯示兩種使用方法。其中一個使用 --hsm-name 和 --name （適用於密鑰名稱）參數，另一個使用 --id 參數，您可以在其中指定整個 URL，包括適當的密鑰名稱。當呼叫端（使用者或應用程式）在控制平面上沒有讀取存取權，且只在數據平面上限制存取時，後者會很有用。

注意

某些與金鑰數據的互動需要特定的本機 RBAC 許可權。如需內建本機 RBAC 角色和許可權的完整清單，請參閱受控 HSM 本機 RBAC 內建角色。若要將這些許可權指派給使用者，請參閱保護受控 HSM 的存取

建立 HSM 金鑰

注意

無法匯出產生或匯入受控 HSM 的金鑰。如需關鍵可移植性和持久性，請參閱建議的最佳做法。

使用 az keyvault key create 命令來建立金鑰。

建立 RSA 金鑰

下列範例示範如何建立 3072 位 RSA 金鑰，該密鑰僅用於 wrapKey、unwrapKey 作業（--ops）。

az keyvault key create --hsm-name ContosoMHSM --name myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

## OR
# Note the key name (myrsakey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey --ops wrapKey unwrapKey --kty RSA-HSM --size 3072

請注意，作業 get 只會傳回公鑰和金鑰屬性。它不會傳回私鑰（如果是非對稱金鑰，或金鑰數據（如果是對稱金鑰）。

建立EC金鑰

下列範例示範如何建立具有 P-256 曲線的 EC 金鑰，該曲線將僅用於簽署和驗證作業（--ops），並具有兩個標籤，使用方式和 appname。標籤可協助您將其他元數據新增至金鑰以進行追蹤和管理。

az keyvault key create --hsm-name ContosoMHSM --name myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

## OR
# Note the key name (myec256key) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myec256key --ops sign verify  --tags ‘usage=signing] appname=myapp’ --kty EC-HSM --curve P-256

建立256位對稱金鑰

下列範例示範如何建立 256 位對稱密鑰，該金鑰僅用於 加密和解密 作業（--ops）。

az keyvault key create --hsm-name ContosoMHSM --name myaeskey --ops encrypt decrypt  --tags --kty oct-HSM --size 256

## OR
# Note the key name (myaeskey) in the URI

az keyvault key create --id https://ContosoMHSM.managedhsm.azure.net/keys/myaeskey --ops encrypt decrypt  --tags ‘usage=signing] appname=myapp’ --kty oct-HSM --size 256

檢視索引鍵屬性和標籤

使用 az keyvault key show 命令來檢視索引鍵的屬性、版本和標記。

az keyvault key show --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key show --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

列出索引鍵

使用 az keyvault key list 命令來列出受控 HSM 內的所有金鑰。

az keyvault key list --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list --id https://ContosoMHSM.managedhsm.azure.net/

刪除金鑰

使用 az keyvault key delete 命令從受控 HSM 刪除金鑰。請注意，虛刪除一律開啟。因此，已刪除的金鑰會保持已刪除狀態，而且可以復原，直到密鑰清除（永久刪除）且無法復原的保留天數為止。

az keyvault key delete --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key delete --id https://ContosoMHSM.managedhsm.azure.net/keys/myrsakey

列出已刪除的金鑰

使用 az keyvault key list-deleted 命令來列出受控 HSM 中已刪除狀態的所有金鑰。

az keyvault key list-deleted --hsm-name ContosoHSM

## OR
# use full URI

az keyvault key list-deleted --id https://ContosoMHSM.managedhsm.azure.net/

復原 (取消刪除) 已刪除的金鑰

使用 az keyvault key list-deleted 命令來列出受控 HSM 中已刪除狀態的所有金鑰。如果您需要在復原已刪除的金鑰時使用 --id 參數來復原金鑰（undelete），您必須記 recoveryId 下從 az keyvault key list-deleted 命令取得之已刪除密鑰的值。

az keyvault key recover --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

清除（永久刪除）金鑰

使用 az keyvault key purge 命令清除金鑰（永久刪除）。

注意

如果受控 HSM 已啟用清除保護，則不允許清除作業。金鑰會在保留期間通過時自動清除。

az keyvault key purge --hsm-name ContosoHSM --name myrsakey

## OR
# Note the key name (myaeskey) in the URI

az keyvault key purge --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey

建立單一金鑰備份

使用 az keyvault key backup 來建立金鑰備份。備份檔是加密的 Blob，會以密碼編譯方式系結至來源 HSM 的安全性網域。它只能在共用相同安全性網域的 HSM 中還原。深入瞭解安全性網域。

az keyvault key backup --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key backup --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey  --file myrsakey.backup

從備份還原單一金鑰

使用 az keyvault key restore 來還原單一金鑰。建立備份的來源 HSM 必須與還原金鑰的目標 HSM 共用相同的安全性網域。

注意

如果具有相同名稱的金鑰處於作用中或刪除狀態，還原將不會成功。

az keyvault key restore --hsm-name ContosoHSM --name myrsakey --file myrsakey.backup

## OR
# Note the key name (myaeskey) in the URI

az keyvault key restore --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --file myrsakey.backup

從檔案匯入金鑰

使用 az keyvault key import 命令從檔案匯入金鑰（僅限 RSA 和 EC）。憑證檔案必須具有私鑰，且必須使用 PEM 編碼方式（如 RFCs 1421、1422、1422 、1423、1424 中所定義）。

az keyvault key import --hsm-name ContosoHSM --name myrsakey --pem-file mycert.key --password 'mypassword'

## OR
# Note the key name (myaeskey) in the URI

az keyvault key recover --id https://ContosoMHSM.managedhsm.azure.net/deletedKeys/myrsakey --pem-file mycert.key --password 'mypassword'

若要將金鑰從內部部署 HSM 匯入受控 HSM，請參閱將受 HSM 保護的金鑰匯入受控 HSM （BYOK）

下一步

如需金鑰保存庫命令的完整 Azure CLI 參考，請參閱金鑰保存庫 CLI 參考。
如需程式設計參考，請參閱 Azure 金鑰保存庫開發人員指南
深入瞭解受控 HSM 角色管理
深入瞭解受控 HSM 最佳做法