快速入门：适用于 .NET 的 Azure Key Vault 托管 HSM 客户端库

入门使用 Azure Key Vault 托管 HSM 的 .NET 客户端库。托管 HSM 是一种完全托管、高度可用、符合标准的单租户云服务，可用于使用 FIPS 140-3 级别 3 验证的 HSM 来保护云应用程序的加密密钥。有关托管 HSM 的详细信息，请查看概述。

在本快速入门中，你将了解如何使用 .NET 客户端库访问和执行托管 HSM 中的密钥的加密操作。

托管 HSM 客户端库资源：

API 参考文档 | 库源代码 | 软件包

先决条件

一个Azure订阅。免费创建一个。
预配和激活的托管 HSM。请参阅 Quickstart：使用 Azure CLI 预配和激活托管 HSM。
在托管 HSM 中创建的密钥。请参阅托管 HSM 中的“管理密钥”。
具有托管标识的Azure资源（例如 VM、应用服务或Azure Functions），或者使用Azure CLI进行本地开发。
必须为托管标识分配适当的托管 HSM 本地 RBAC 角色。请参阅安全访问托管的 HSM。

.NET 6 SDK 或更高版本

设置本地环境

本快速入门使用Azure Identity库与Azure CLI对Azure服务进行身份验证。开发人员还可以使用Visual Studio或Visual Studio Code对调用进行身份验证。有关详细信息，请参阅使用Azure标识客户端库对客户端进行身份验证。

az login运行命令以登录：

az login

创建新的.NET控制台应用

在命令外壳中，运行以下命令以创建名为 mhsm-console-app 的项目：
```
dotnet new console --name mhsm-console-app
```
切换到新创建的 mhsm-console-app 目录：
```
cd mhsm-console-app
```

安装软件包

安装Azure标识和Key Vault密钥客户端库：

dotnet add package Azure.Identity
dotnet add package Azure.Security.KeyVault.Keys

创建示例代码

将 Program.cs 的内容替换为以下代码。将 <hsm-name> 替换为托管 HSM 名称，并将 <key-name> 替换为现有的密钥名称。

using Azure.Identity;
using Azure.Security.KeyVault.Keys;
using Azure.Security.KeyVault.Keys.Cryptography;

// Use DefaultAzureCredential for automatic credential selection
// Works with managed identities in Azure, and developer credentials locally
var credential = new DefaultAzureCredential();

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

// Get a key reference
string keyName = "<key-name>";
Console.WriteLine($"Retrieving key '{keyName}' from Managed HSM...");
KeyVaultKey key = await keyClient.GetKeyAsync(keyName);
Console.WriteLine($"Key retrieved. Key type: {key.KeyType}");

// Perform cryptographic operations
var cryptoClient = new CryptographyClient(key.Id, credential);

// Encrypt data
byte[] plaintext = System.Text.Encoding.UTF8.GetBytes("Hello, Managed HSM!");
Console.WriteLine($"\nOriginal text: {System.Text.Encoding.UTF8.GetString(plaintext)}");

EncryptResult encryptResult = await cryptoClient.EncryptAsync(EncryptionAlgorithm.RsaOaep256, plaintext);
Console.WriteLine($"Encrypted (base64): {Convert.ToBase64String(encryptResult.Ciphertext)}");

// Decrypt data
DecryptResult decryptResult = await cryptoClient.DecryptAsync(EncryptionAlgorithm.RsaOaep256, encryptResult.Ciphertext);
Console.WriteLine($"Decrypted text: {System.Text.Encoding.UTF8.GetString(decryptResult.Plaintext)}");

Console.WriteLine("\nDone!");

运行应用程序

使用 dotnet run 命令运行应用程序：

dotnet run

此时会看到与下面类似的输出：

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

Original text: Hello, Managed HSM!
Encrypted (base64): <encrypted-data>
Decrypted text: Hello, Managed HSM!

Done!

了解数据

使用 DefaultAzureCredential 进行身份验证

DefaultAzureCredential 根据环境自动选择相应的凭据：

环境	使用的凭据
Azure VM、应用服务、函数	系统分配的或用户分配的托管标识
Azure Kubernetes 服务	工作负载标识
地方发展	Azure CLI、Visual Studio 或 VS Code 凭据
CI/CD 管道	工作负荷标识联合或服务主体

凭证按顺序检查这些来源：

环境变量
工作负载标识
托管标识
Azure CLI
Azure PowerShell
Visual Studio/VS Code 凭据

对于Azure中的生产工作负荷，强烈建议使用托管标识，因为它们完全消除了凭据管理。

关键操作

该 KeyClient 类提供以下方法：

创建、获取、更新和删除密钥
列出密钥和密钥版本
备份和还原密钥

该 CryptographyClient 类提供加密操作：

加密和解密数据
签名和验证签名
包装和解包密钥

分配托管 HSM 角色

若要使您的应用程序访问密钥，请将适当的本地 RBAC 角色分配给您的托管 HSM 标识:

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

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

若需了解角色和权限的更多信息，请参阅托管 HSM 本地 RBAC 内置角色。

清理资源

如果不再需要资源组和所有相关资源，请将其删除：

az group delete --name <resource-group>

警告

删除资源组会将托管 HSM 置于软删除状态。托管 HSM 将继续计费，直到被清理为止。请参阅托管 HSM 软删除和清除保护

后续步骤

Last updated on 2026-04-22

通过