Azure Security Keyvault Keys Dotnet

作者 microsoft354361d83247MIT收录于 2026年10月8日更新于 2026年10月8日

Azure Key Vault Keys SDK for .NET. Client library for managing cryptographic keys in Azure Key Vault and Managed HSM. Use for key creation, rotation, encryption, decryption, signing, and verification. Triggers: "Key Vault keys", "KeyClient", "CryptographyClient", "RSA key", "EC key", "encrypt decrypt .NET", "key rotation", "HSM".

AI 生成的概览

介绍如何使用 Azure Key Vault Keys .NET SDK 管理和使用加密密钥的参考指南。

功能
该技能提供 Azure.Security.KeyVault.Keys .NET 客户端库的说明和代码示例。内容涵盖创建、获取、更新、删除、备份和轮换 RSA、EC 及对称密钥,以及加密、解密、包装、解包、签名和验证等加密操作。它还说明了身份验证方式、密钥类型、算法、RBAC 角色和错误处理。
适用场景
适用于编写在 Azure Key Vault 或 Managed HSM 中管理密钥的 .NET 代码,或通过 KeyClient、CryptographyClient 或 KeyResolver 执行加密操作。适合涉及密钥创建、轮换、加密、签名或验证的任务。
运行要求
需要 .NET SDK 以及 Azure.Security.KeyVault.Keys 和 Azure.Identity NuGet 包。需要 Azure Key Vault 或 Managed HSM 实例、网络访问,以及 DefaultAzureCredential、托管标识或服务主体等凭据,并具备相应的 RBAC 角色。该技能不包含脚本,仅为说明和代码示例。

Azure.Security.KeyVault.Keys (.NET)

Client library for managing cryptographic keys in Azure Key Vault and Managed HSM.

Installation

bash
dotnet add package Azure.Security.KeyVault.Keysdotnet add package Azure.Identity

Current Version: 4.7.0 (stable)

Environment Variables

bash
KEY_VAULT_NAME=<your-key-vault-name>  # Required: Key Vault nameAZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net  # Optional: full Key Vault URLAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Client Hierarchy

KeyClient (key management)├── CreateKey / CreateRsaKey / CreateEcKey├── GetKey / GetKeys├── UpdateKeyProperties├── DeleteKey / PurgeDeletedKey├── BackupKey / RestoreKey└── GetCryptographyClient() → CryptographyClient
CryptographyClient (cryptographic operations)├── Encrypt / Decrypt├── WrapKey / UnwrapKey├── Sign / Verify└── SignData / VerifyData
KeyResolver (key resolution)└── Resolve(keyId) → CryptographyClient

Authentication

Microsoft Entra Token Credential

csharp
using Azure.Identity;using Azure.Security.KeyVault.Keys;
var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");var kvUri = $"https://{keyVaultName}.vault.azure.net";
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes// var credential = new ManagedIdentityCredential();var client = new KeyClient(new Uri(kvUri), credential);

Service Principal

csharp
var credential = new ClientSecretCredential(    tenantId: "<tenant-id>",    clientId: "<client-id>",    clientSecret: "<client-secret>");
var client = new KeyClient(new Uri(kvUri), credential);

Key Management

Create Keys

csharp
// Create RSA keyKeyVaultKey rsaKey = await client.CreateKeyAsync("my-rsa-key", KeyType.Rsa);Console.WriteLine($"Created key: {rsaKey.Name}, Type: {rsaKey.KeyType}");
// Create RSA key with optionsvar rsaOptions = new CreateRsaKeyOptions("my-rsa-key-2048"){    KeySize = 2048,    HardwareProtected = false, // true for HSM-backed    ExpiresOn = DateTimeOffset.UtcNow.AddYears(1),    NotBefore = DateTimeOffset.UtcNow,    Enabled = true};rsaOptions.KeyOperations.Add(KeyOperation.Encrypt);rsaOptions.KeyOperations.Add(KeyOperation.Decrypt);
KeyVaultKey rsaKey2 = await client.CreateRsaKeyAsync(rsaOptions);
// Create EC keyvar ecOptions = new CreateEcKeyOptions("my-ec-key"){    CurveName = KeyCurveName.P256,    HardwareProtected = true // HSM-backed};KeyVaultKey ecKey = await client.CreateEcKeyAsync(ecOptions);
// Create Oct (symmetric) key for wrap/unwrapvar octOptions = new CreateOctKeyOptions("my-oct-key"){    KeySize = 256,    HardwareProtected = true};KeyVaultKey octKey = await client.CreateOctKeyAsync(octOptions);

Retrieve Keys

csharp
// Get specific key (latest version)KeyVaultKey key = await client.GetKeyAsync("my-rsa-key");Console.WriteLine($"Key ID: {key.Id}");Console.WriteLine($"Key Type: {key.KeyType}");Console.WriteLine($"Version: {key.Properties.Version}");
// Get specific versionKeyVaultKey keyVersion = await client.GetKeyAsync("my-rsa-key", "version-id");
// List all keysawait foreach (KeyProperties keyProps in client.GetPropertiesOfKeysAsync()){    Console.WriteLine($"Key: {keyProps.Name}, Enabled: {keyProps.Enabled}");}
// List key versionsawait foreach (KeyProperties version in client.GetPropertiesOfKeyVersionsAsync("my-rsa-key")){    Console.WriteLine($"Version: {version.Version}, Created: {version.CreatedOn}");}

Update Key Properties

csharp
KeyVaultKey key = await client.GetKeyAsync("my-rsa-key");
key.Properties.ExpiresOn = DateTimeOffset.UtcNow.AddYears(2);key.Properties.Tags["environment"] = "production";
KeyVaultKey updatedKey = await client.UpdateKeyPropertiesAsync(key.Properties);

Delete and Purge Keys

csharp
// Start delete operationDeleteKeyOperation operation = await client.StartDeleteKeyAsync("my-rsa-key");
// Wait for deletion to complete (required before purge)await operation.WaitForCompletionAsync();Console.WriteLine($"Deleted key scheduled purge date: {operation.Value.ScheduledPurgeDate}");
// Purge immediately (if soft-delete is enabled)await client.PurgeDeletedKeyAsync("my-rsa-key");
// Or recover deleted keyKeyVaultKey recoveredKey = await client.StartRecoverDeletedKeyAsync("my-rsa-key");

Backup and Restore

csharp
// Backup keybyte[] backup = await client.BackupKeyAsync("my-rsa-key");await File.WriteAllBytesAsync("key-backup.bin", backup);
// Restore keybyte[] backupData = await File.ReadAllBytesAsync("key-backup.bin");KeyVaultKey restoredKey = await client.RestoreKeyBackupAsync(backupData);

Cryptographic Operations

Get CryptographyClient

csharp
// From KeyClientKeyVaultKey key = await client.GetKeyAsync("my-rsa-key");CryptographyClient cryptoClient = client.GetCryptographyClient(    key.Name,     key.Properties.Version);
// Or create directly with key IDCryptographyClient cryptoClient = new CryptographyClient(    new Uri("https://myvault.vault.azure.net/keys/my-rsa-key/version"),    new DefaultAzureCredential());

Encrypt and Decrypt

csharp
byte[] plaintext = Encoding.UTF8.GetBytes("Secret message to encrypt");
// EncryptEncryptResult encryptResult = await cryptoClient.EncryptAsync(    EncryptionAlgorithm.RsaOaep256,     plaintext);Console.WriteLine($"Encrypted: {Convert.ToBase64String(encryptResult.Ciphertext)}");
// DecryptDecryptResult decryptResult = await cryptoClient.DecryptAsync(    EncryptionAlgorithm.RsaOaep256,     encryptResult.Ciphertext);string decrypted = Encoding.UTF8.GetString(decryptResult.Plaintext);Console.WriteLine($"Decrypted: {decrypted}");

Wrap and Unwrap Keys

csharp
// Key to wrap (e.g., AES key)byte[] keyToWrap = new byte[32]; // 256-bit keyRandomNumberGenerator.Fill(keyToWrap);
// Wrap keyWrapResult wrapResult = await cryptoClient.WrapKeyAsync(    KeyWrapAlgorithm.RsaOaep256,     keyToWrap);
// Unwrap keyUnwrapResult unwrapResult = await cryptoClient.UnwrapKeyAsync(    KeyWrapAlgorithm.RsaOaep256,     wrapResult.EncryptedKey);

Sign and Verify

csharp
// Data to signbyte[] data = Encoding.UTF8.GetBytes("Data to sign");
// Sign data (computes hash internally)SignResult signResult = await cryptoClient.SignDataAsync(    SignatureAlgorithm.RS256,     data);
// Verify signatureVerifyResult verifyResult = await cryptoClient.VerifyDataAsync(    SignatureAlgorithm.RS256,     data,     signResult.Signature);Console.WriteLine($"Signature valid: {verifyResult.IsValid}");
// Or sign pre-computed hashusing var sha256 = SHA256.Create();byte[] hash = sha256.ComputeHash(data);
SignResult signHashResult = await cryptoClient.SignAsync(    SignatureAlgorithm.RS256,     hash);

Key Resolver

csharp
using Azure.Security.KeyVault.Keys.Cryptography;
var resolver = new KeyResolver(new DefaultAzureCredential());
// Resolve key by ID to get CryptographyClientCryptographyClient cryptoClient = await resolver.ResolveAsync(    new Uri("https://myvault.vault.azure.net/keys/my-key/version"));
// Use for encryptionEncryptResult result = await cryptoClient.EncryptAsync(    EncryptionAlgorithm.RsaOaep256,     plaintext);

Key Rotation

csharp
// Rotate key (creates new version)KeyVaultKey rotatedKey = await client.RotateKeyAsync("my-rsa-key");Console.WriteLine($"New version: {rotatedKey.Properties.Version}");
// Get rotation policyKeyRotationPolicy policy = await client.GetKeyRotationPolicyAsync("my-rsa-key");
// Update rotation policypolicy.ExpiresIn = "P90D"; // 90 dayspolicy.LifetimeActions.Add(new KeyRotationLifetimeAction{    Action = KeyRotationPolicyAction.Rotate,    TimeBeforeExpiry = "P30D" // Rotate 30 days before expiry});
await client.UpdateKeyRotationPolicyAsync("my-rsa-key", policy);

Key Types Reference

TypePurpose
KeyClientKey management operations
CryptographyClientCryptographic operations
KeyResolverResolve key ID to CryptographyClient
KeyVaultKeyKey with cryptographic material
KeyPropertiesKey metadata (no crypto material)
CreateRsaKeyOptionsRSA key creation options
CreateEcKeyOptionsEC key creation options
CreateOctKeyOptionsSymmetric key options
EncryptResultEncryption result
DecryptResultDecryption result
SignResultSigning result
VerifyResultVerification result
WrapResultKey wrap result
UnwrapResultKey unwrap result

Algorithms Reference

Encryption Algorithms

AlgorithmKey TypeDescription
RsaOaepRSARSA-OAEP
RsaOaep256RSARSA-OAEP-256
Rsa15RSARSA 1.5 (legacy)
A128GcmOctAES-128-GCM
A256GcmOctAES-256-GCM

Signature Algorithms

AlgorithmKey TypeDescription
RS256RSARSASSA-PKCS1-v1_5 SHA-256
RS384RSARSASSA-PKCS1-v1_5 SHA-384
RS512RSARSASSA-PKCS1-v1_5 SHA-512
PS256RSARSASSA-PSS SHA-256
ES256ECECDSA P-256 SHA-256
ES384ECECDSA P-384 SHA-384
ES512ECECDSA P-521 SHA-512

Key Wrap Algorithms

AlgorithmKey TypeDescription
RsaOaepRSARSA-OAEP
RsaOaep256RSARSA-OAEP-256
A128KWOctAES-128 Key Wrap
A256KWOctAES-256 Key Wrap

Best Practices

  1. Use Managed Identity — Prefer DefaultAzureCredential over secrets
  2. Enable soft-delete — Protect against accidental deletion
  3. Use HSM-backed keys — Set HardwareProtected = true for sensitive keys
  4. Implement key rotation — Use automatic rotation policies
  5. Limit key operations — Only enable required KeyOperations
  6. Set expiration dates — Always set ExpiresOn for keys
  7. Use specific versions — Pin to versions in production
  8. Cache CryptographyClient — Reuse for multiple operations

Error Handling

csharp
using Azure;
try{    KeyVaultKey key = await client.GetKeyAsync("my-key");}catch (RequestFailedException ex) when (ex.Status == 404){    Console.WriteLine("Key not found");}catch (RequestFailedException ex) when (ex.Status == 403){    Console.WriteLine("Access denied - check RBAC permissions");}catch (RequestFailedException ex){    Console.WriteLine($"Key Vault error: {ex.Status} - {ex.Message}");}

Required RBAC Roles

RolePermissions
Key Vault Crypto OfficerFull key management
Key Vault Crypto UserUse keys for crypto operations
Key Vault ReaderRead key metadata

Related SDKs

SDKPurposeInstall
Azure.Security.KeyVault.KeysKeys (this SDK)dotnet add package Azure.Security.KeyVault.Keys
Azure.Security.KeyVault.SecretsSecretsdotnet add package Azure.Security.KeyVault.Secrets
Azure.Security.KeyVault.CertificatesCertificatesdotnet add package Azure.Security.KeyVault.Certificates
Azure.IdentityAuthenticationdotnet add package Azure.Identity

Reference Links

来源与署名

来源:microsoft/skills位于.github/plugins/azure-sdk-dotnet/skills/azure-security-keyvault-keys-dotnet提交354361d

许可证: MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架