Azure Security Keyvault Keys Dotnet

1---
2name: azure-security-keyvault-keys-dotnet
3description: |
4  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".
5package: Azure.Security.KeyVault.Keys
6---
7 
8# Azure.Security.KeyVault.Keys (.NET)
9 
10Client library for managing cryptographic keys in Azure Key Vault and Managed HSM.
11 
12## Installation
13 
14```bash
15dotnet add package Azure.Security.KeyVault.Keys
16dotnet add package Azure.Identity
17```
18 
19**Current Version**: 4.7.0 (stable)
20 
21## Environment Variables
22 
23```bash
24KEY_VAULT_NAME=<your-key-vault-name>
25# Or full URI
26AZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net
27```
28 
29## Client Hierarchy
30 
31```
32KeyClient (key management)
33├── CreateKey / CreateRsaKey / CreateEcKey
34├── GetKey / GetKeys
35├── UpdateKeyProperties
36├── DeleteKey / PurgeDeletedKey
37├── BackupKey / RestoreKey
38└── GetCryptographyClient() → CryptographyClient
39 
40CryptographyClient (cryptographic operations)
41├── Encrypt / Decrypt
42├── WrapKey / UnwrapKey
43├── Sign / Verify
44└── SignData / VerifyData
45 
46KeyResolver (key resolution)
47└── Resolve(keyId) → CryptographyClient
48```
49 
50## Authentication
51 
52### DefaultAzureCredential (Recommended)
53 
54```csharp
55using Azure.Identity;
56using Azure.Security.KeyVault.Keys;
57 
58var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
59var kvUri = $"https://{keyVaultName}.vault.azure.net";
60 
61var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());
62```
63 
64### Service Principal
65 
66```csharp
67var credential = new ClientSecretCredential(
68    tenantId: "<tenant-id>",
69    clientId: "<client-id>",
70    clientSecret: "<client-secret>");
71 
72var client = new KeyClient(new Uri(kvUri), credential);
73```
74 
75## Key Management
76 
77### Create Keys
78 
79```csharp
80// Create RSA key
81KeyVaultKey rsaKey = await client.CreateKeyAsync("my-rsa-key", KeyType.Rsa);
82Console.WriteLine($"Created key: {rsaKey.Name}, Type: {rsaKey.KeyType}");
83 
84// Create RSA key with options
85var rsaOptions = new CreateRsaKeyOptions("my-rsa-key-2048")
86{
87    KeySize = 2048,
88    HardwareProtected = false, // true for HSM-backed
89    ExpiresOn = DateTimeOffset.UtcNow.AddYears(1),
90    NotBefore = DateTimeOffset.UtcNow,
91    Enabled = true
92};
93rsaOptions.KeyOperations.Add(KeyOperation.Encrypt);
94rsaOptions.KeyOperations.Add(KeyOperation.Decrypt);
95 
96KeyVaultKey rsaKey2 = await client.CreateRsaKeyAsync(rsaOptions);
97 
98// Create EC key
99var ecOptions = new CreateEcKeyOptions("my-ec-key")
100{
101    CurveName = KeyCurveName.P256,
102    HardwareProtected = true // HSM-backed
103};
104KeyVaultKey ecKey = await client.CreateEcKeyAsync(ecOptions);
105 
106// Create Oct (symmetric) key for wrap/unwrap
107var octOptions = new CreateOctKeyOptions("my-oct-key")
108{
109    KeySize = 256,
110    HardwareProtected = true
111};
112KeyVaultKey octKey = await client.CreateOctKeyAsync(octOptions);
113```
114 
115### Retrieve Keys
116 
117```csharp
118// Get specific key (latest version)
119KeyVaultKey key = await client.GetKeyAsync("my-rsa-key");
120Console.WriteLine($"Key ID: {key.Id}");
121Console.WriteLine($"Key Type: {key.KeyType}");
122Console.WriteLine($"Version: {key.Properties.Version}");
123 
124// Get specific version
125KeyVaultKey keyVersion = await client.GetKeyAsync("my-rsa-key", "version-id");
126 
127// List all keys
128await foreach (KeyProperties keyProps in client.GetPropertiesOfKeysAsync())
129{
130    Console.WriteLine($"Key: {keyProps.Name}, Enabled: {keyProps.Enabled}");
131}
132 
133// List key versions
134await foreach (KeyProperties version in client.GetPropertiesOfKeyVersionsAsync("my-rsa-key"))
135{
136    Console.WriteLine($"Version: {version.Version}, Created: {version.CreatedOn}");
137}
138```
139 
140### Update Key Properties
141 
142```csharp
143KeyVaultKey key = await client.GetKeyAsync("my-rsa-key");
144 
145key.Properties.ExpiresOn = DateTimeOffset.UtcNow.AddYears(2);
146key.Properties.Tags["environment"] = "production";
147 
148KeyVaultKey updatedKey = await client.UpdateKeyPropertiesAsync(key.Properties);
149```
150 
151### Delete and Purge Keys
152 
153```csharp
154// Start delete operation
155DeleteKeyOperation operation = await client.StartDeleteKeyAsync("my-rsa-key");
156 
157// Wait for deletion to complete (required before purge)
158await operation.WaitForCompletionAsync();
159Console.WriteLine($"Deleted key scheduled purge date: {operation.Value.ScheduledPurgeDate}");
160 
161// Purge immediately (if soft-delete is enabled)
162await client.PurgeDeletedKeyAsync("my-rsa-key");
163 
164// Or recover deleted key
165KeyVaultKey recoveredKey = await client.StartRecoverDeletedKeyAsync("my-rsa-key");
166```
167 
168### Backup and Restore
169 
170```csharp
171// Backup key
172byte[] backup = await client.BackupKeyAsync("my-rsa-key");
173await File.WriteAllBytesAsync("key-backup.bin", backup);
174 
175// Restore key
176byte[] backupData = await File.ReadAllBytesAsync("key-backup.bin");
177KeyVaultKey restoredKey = await client.RestoreKeyBackupAsync(backupData);
178```
179 
180## Cryptographic Operations
181 
182### Get CryptographyClient
183 
184```csharp
185// From KeyClient
186KeyVaultKey key = await client.GetKeyAsync("my-rsa-key");
187CryptographyClient cryptoClient = client.GetCryptographyClient(
188    key.Name, 
189    key.Properties.Version);
190 
191// Or create directly with key ID
192CryptographyClient cryptoClient = new CryptographyClient(
193    new Uri("https://myvault.vault.azure.net/keys/my-rsa-key/version"),
194    new DefaultAzureCredential());
195```
196 
197### Encrypt and Decrypt
198 
199```csharp
200byte[] plaintext = Encoding.UTF8.GetBytes("Secret message to encrypt");
201 
202// Encrypt
203EncryptResult encryptResult = await cryptoClient.EncryptAsync(
204    EncryptionAlgorithm.RsaOaep256, 
205    plaintext);
206Console.WriteLine($"Encrypted: {Convert.ToBase64String(encryptResult.Ciphertext)}");
207 
208// Decrypt
209DecryptResult decryptResult = await cryptoClient.DecryptAsync(
210    EncryptionAlgorithm.RsaOaep256, 
211    encryptResult.Ciphertext);
212string decrypted = Encoding.UTF8.GetString(decryptResult.Plaintext);
213Console.WriteLine($"Decrypted: {decrypted}");
214```
215 
216### Wrap and Unwrap Keys
217 
218```csharp
219// Key to wrap (e.g., AES key)
220byte[] keyToWrap = new byte[32]; // 256-bit key
221RandomNumberGenerator.Fill(keyToWrap);
222 
223// Wrap key
224WrapResult wrapResult = await cryptoClient.WrapKeyAsync(
225    KeyWrapAlgorithm.RsaOaep256, 
226    keyToWrap);
227 
228// Unwrap key
229UnwrapResult unwrapResult = await cryptoClient.UnwrapKeyAsync(
230    KeyWrapAlgorithm.RsaOaep256, 
231    wrapResult.EncryptedKey);
232```
233 
234### Sign and Verify
235 
236```csharp
237// Data to sign
238byte[] data = Encoding.UTF8.GetBytes("Data to sign");
239 
240// Sign data (computes hash internally)
241SignResult signResult = await cryptoClient.SignDataAsync(
242    SignatureAlgorithm.RS256, 
243    data);
244 
245// Verify signature
246VerifyResult verifyResult = await cryptoClient.VerifyDataAsync(
247    SignatureAlgorithm.RS256, 
248    data, 
249    signResult.Signature);
250Console.WriteLine($"Signature valid: {verifyResult.IsValid}");
251 
252// Or sign pre-computed hash
253using var sha256 = SHA256.Create();
254byte[] hash = sha256.ComputeHash(data);
255 
256SignResult signHashResult = await cryptoClient.SignAsync(
257    SignatureAlgorithm.RS256, 
258    hash);
259```
260 
261## Key Resolver
262 
263```csharp
264using Azure.Security.KeyVault.Keys.Cryptography;
265 
266var resolver = new KeyResolver(new DefaultAzureCredential());
267 
268// Resolve key by ID to get CryptographyClient
269CryptographyClient cryptoClient = await resolver.ResolveAsync(
270    new Uri("https://myvault.vault.azure.net/keys/my-key/version"));
271 
272// Use for encryption
273EncryptResult result = await cryptoClient.EncryptAsync(
274    EncryptionAlgorithm.RsaOaep256, 
275    plaintext);
276```
277 
278## Key Rotation
279 
280```csharp
281// Rotate key (creates new version)
282KeyVaultKey rotatedKey = await client.RotateKeyAsync("my-rsa-key");
283Console.WriteLine($"New version: {rotatedKey.Properties.Version}");
284 
285// Get rotation policy
286KeyRotationPolicy policy = await client.GetKeyRotationPolicyAsync("my-rsa-key");
287 
288// Update rotation policy
289policy.ExpiresIn = "P90D"; // 90 days
290policy.LifetimeActions.Add(new KeyRotationLifetimeAction
291{
292    Action = KeyRotationPolicyAction.Rotate,
293    TimeBeforeExpiry = "P30D" // Rotate 30 days before expiry
294});
295 
296await client.UpdateKeyRotationPolicyAsync("my-rsa-key", policy);
297```
298 
299## Key Types Reference
300 
301| Type | Purpose |
302|------|---------|
303| `KeyClient` | Key management operations |
304| `CryptographyClient` | Cryptographic operations |
305| `KeyResolver` | Resolve key ID to CryptographyClient |
306| `KeyVaultKey` | Key with cryptographic material |
307| `KeyProperties` | Key metadata (no crypto material) |
308| `CreateRsaKeyOptions` | RSA key creation options |
309| `CreateEcKeyOptions` | EC key creation options |
310| `CreateOctKeyOptions` | Symmetric key options |
311| `EncryptResult` | Encryption result |
312| `DecryptResult` | Decryption result |
313| `SignResult` | Signing result |
314| `VerifyResult` | Verification result |
315| `WrapResult` | Key wrap result |
316| `UnwrapResult` | Key unwrap result |
317 
318## Algorithms Reference
319 
320### Encryption Algorithms
321| Algorithm | Key Type | Description |
322|-----------|----------|-------------|
323| `RsaOaep` | RSA | RSA-OAEP |
324| `RsaOaep256` | RSA | RSA-OAEP-256 |
325| `Rsa15` | RSA | RSA 1.5 (legacy) |
326| `A128Gcm` | Oct | AES-128-GCM |
327| `A256Gcm` | Oct | AES-256-GCM |
328 
329### Signature Algorithms
330| Algorithm | Key Type | Description |
331|-----------|----------|-------------|
332| `RS256` | RSA | RSASSA-PKCS1-v1_5 SHA-256 |
333| `RS384` | RSA | RSASSA-PKCS1-v1_5 SHA-384 |
334| `RS512` | RSA | RSASSA-PKCS1-v1_5 SHA-512 |
335| `PS256` | RSA | RSASSA-PSS SHA-256 |
336| `ES256` | EC | ECDSA P-256 SHA-256 |
337| `ES384` | EC | ECDSA P-384 SHA-384 |
338| `ES512` | EC | ECDSA P-521 SHA-512 |
339 
340### Key Wrap Algorithms
341| Algorithm | Key Type | Description |
342|-----------|----------|-------------|
343| `RsaOaep` | RSA | RSA-OAEP |
344| `RsaOaep256` | RSA | RSA-OAEP-256 |
345| `A128KW` | Oct | AES-128 Key Wrap |
346| `A256KW` | Oct | AES-256 Key Wrap |
347 
348## Best Practices
349 
3501. **Use Managed Identity** — Prefer `DefaultAzureCredential` over secrets
3512. **Enable soft-delete** — Protect against accidental deletion
3523. **Use HSM-backed keys** — Set `HardwareProtected = true` for sensitive keys
3534. **Implement key rotation** — Use automatic rotation policies
3545. **Limit key operations** — Only enable required `KeyOperations`
3556. **Set expiration dates** — Always set `ExpiresOn` for keys
3567. **Use specific versions** — Pin to versions in production
3578. **Cache CryptographyClient** — Reuse for multiple operations
358 
359## Error Handling
360 
361```csharp
362using Azure;
363 
364try
365{
366    KeyVaultKey key = await client.GetKeyAsync("my-key");
367}
368catch (RequestFailedException ex) when (ex.Status == 404)
369{
370    Console.WriteLine("Key not found");
371}
372catch (RequestFailedException ex) when (ex.Status == 403)
373{
374    Console.WriteLine("Access denied - check RBAC permissions");
375}
376catch (RequestFailedException ex)
377{
378    Console.WriteLine($"Key Vault error: {ex.Status} - {ex.Message}");
379}
380```
381 
382## Required RBAC Roles
383 
384| Role | Permissions |
385|------|-------------|
386| Key Vault Crypto Officer | Full key management |
387| Key Vault Crypto User | Use keys for crypto operations |
388| Key Vault Reader | Read key metadata |
389 
390## Related SDKs
391 
392| SDK | Purpose | Install |
393|-----|---------|---------|
394| `Azure.Security.KeyVault.Keys` | Keys (this SDK) | `dotnet add package Azure.Security.KeyVault.Keys` |
395| `Azure.Security.KeyVault.Secrets` | Secrets | `dotnet add package Azure.Security.KeyVault.Secrets` |
396| `Azure.Security.KeyVault.Certificates` | Certificates | `dotnet add package Azure.Security.KeyVault.Certificates` |
397| `Azure.Identity` | Authentication | `dotnet add package Azure.Identity` |
398 
399## Reference Links
400 
401| Resource | URL |
402|----------|-----|
403| NuGet Package | https://www.nuget.org/packages/Azure.Security.KeyVault.Keys |
404| API Reference | https://learn.microsoft.com/dotnet/api/azure.security.keyvault.keys |
405| Quickstart | https://learn.microsoft.com/azure/key-vault/keys/quick-create-net |
406| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys |
407