共用方式為

快速入門：Azure Key Vault 託管 HSM 用戶端庫 (JavaScript)

開始使用 Azure Key Vault 的 JavaScript 管理式 HSM 用戶端函式庫。 完整管理的 HSM 是一種高可用性的單租戶雲端服務，符合標準規範，可讓您使用 FIPS 140-3 等級 3 驗證的 HSM 來保護您的雲端應用程式的加密密鑰。 欲了解更多管理型HSM的資訊，請參閱 概述。

在這個快速入門中，你將學習如何利用 JavaScript 客戶端函式庫存取並執行受管型 HSM 金鑰的密碼學操作。

受管理的 HSM 用戶端函式庫資源：

API 參考文件 | 程式庫原始碼 | Package（npm）

先決條件

設定您的本機環境

此快速入門使用Azure身份函式庫搭配Azure CLI來認證Azure服務。 開發者也可使用 Visual Studio Code 來驗證通話。 欲了解更多資訊，請參閱 Authenticate the client with Azure Identity 客戶端函式庫。

登入 Azure

執行 az login 登入指令：

az login

建立專案資料夾並初始化

  1. 建立一個專案資料夾並導航到裡面：

    mkdir mhsm-js-app && cd mhsm-js-app

  2. 初始化專案：

    npm init -y

安裝套件

安裝 Azure Identity 和 金鑰保存庫 Keys 用戶端函式庫：

npm install @azure/identity @azure/keyvault-keys

建立範例程式碼

建立一個以以下代碼命名的 index.js 檔案。 將<hsm-name>替換為你的 Managed HSM 名稱，並將<key-name>替換為現有的金鑰名稱。

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

async function main() {
    // Use DefaultAzureCredential for automatic credential selection
    const credential = new DefaultAzureCredential();

    // Connect to Managed HSM - replace with your HSM URI
    const hsmUri = "https://<hsm-name>.managedhsm.azure.net";
    const keyClient = new KeyClient(hsmUri, credential);

    // Get a key reference
    const keyName = "<key-name>";
    console.log(`Retrieving key '${keyName}' from Managed HSM...`);
    const key = await keyClient.getKey(keyName);
    console.log(`Key retrieved. Key type: ${key.keyType}`);

    // Perform cryptographic operations
    const cryptoClient = new CryptographyClient(key, credential);

    // Encrypt data
    const plaintext = Buffer.from("Hello, Managed HSM!");
    console.log(`\nOriginal text: ${plaintext.toString()}`);

    const encryptResult = await cryptoClient.encrypt("RSA-OAEP-256", plaintext);
    console.log(`Encrypted (base64): ${encryptResult.result.toString("base64").substring(0, 64)}...`);

    // Decrypt data
    const decryptResult = await cryptoClient.decrypt("RSA-OAEP-256", encryptResult.result);
    console.log(`Decrypted text: ${decryptResult.result.toString()}`);

    console.log("\nDone!");
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

執行應用程式

執行應用程式：

node index.js

您應該會看到類似下列的輸出：

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): NWE4ZjNiMmMxZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNGM...
Decrypted text: Hello, Managed HSM!

Done!

了解程式碼

使用 DefaultAzureCredential 進行認證

DefaultAzureCredential 會根據您的環境自動選擇合適的憑證：

環境 使用的憑證
Azure VM、App Service、Functions 由系統或使用者指派的管理識別
Azure Kubernetes Service 工作負載身份識別
本地開發 Azure CLI、Visual Studio 或 VS Code 憑證
CI/CD 管線 工作負載身分識別同盟或服務主體

憑證會依序檢查這些來源：

  1. 環境變數
  2. 工作負載身份識別
  3. 受管理的識別
  4. Azure CLI
  5. Azure PowerShell
  6. Visual Studio / VS Code 憑證

對於 Azure 的生產工作負載，強烈建議使用受管理身份，因為它們完全消除了憑證管理。

主要行動

該 KeyClient 類別提供以下方法：

  • 建立、取得、更新和刪除金鑰
  • 列出鍵與其版本
  • 備份與還原金鑰

該 CryptographyClient 類別提供密碼學運算：

  • 加密與解密資料
  • 簽署並驗證簽名
  • 包裝和解除包裝金鑰

指派受管型 HSM 角色

為了讓你的應用程式可以存取金鑰，請為你的受管身份指派適當的 Managed HSM 本地 RBAC 角色。 將<vm-name>、<resource-group>和<hsm-name>取代為您的實際值。

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

欲了解更多角色與權限資訊，請參閱 受管型 HSM 本地 RBAC 內建角色。

清理資源

不再需要時，刪除資源群組及所有相關資源：

az group delete --name <resource-group>

警告

刪除資源群組會將受控 HSM 置於軟刪除狀態。 管理型 HSM 會繼續被計費，直到被清除為止。 請參閱受控 HSM 虛刪除和清除保護

下一步

  • Last updated on