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 從公開儲存庫中收錄這些內容。

檢舉或申請下架