Azure Key Vault Keys SDK Acceptance Criteria (.NET)

SDK: Azure.Security.KeyVault.KeysRepository: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.KeysNuGet Package: https://www.nuget.org/packages/Azure.Security.KeyVault.Keys/Purpose: Skill testing acceptance criteria for validating generated code correctness

---

1. Imports

1.1 ✅ CORRECT: Client Imports

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

1.2 ✅ CORRECT: Model Imports for Key Options

using Azure.Security.KeyVault.Keys;
// CreateRsaKeyOptions, CreateEcKeyOptions, etc. are in the main namespace

1.3 ❌ INCORRECT: Wrong import paths

// WRONG - Cryptography client is in .Cryptography namespace
using Azure.Security.KeyVault.Keys;
var cryptoClient = new CryptographyClient(keyId, credential); // CryptographyClient not imported

// WRONG - Using old Microsoft.Azure.KeyVault package
using Microsoft.Azure.KeyVault;

// WRONG - Using KeyVault.Secrets namespace for keys
using Azure.Security.KeyVault.Secrets;

---

2. Authentication

2.1 ✅ CORRECT: DefaultAzureCredential (Recommended)

var client = new KeyClient(
    vaultUri: new Uri("https://my-vault.vault.azure.net/"),
    credential: new DefaultAzureCredential());

2.2 ✅ CORRECT: Environment Variables for Vault URI

string vaultUrl = Environment.GetEnvironmentVariable("AZURE_KEYVAULT_URL")
    ?? throw new InvalidOperationException("AZURE_KEYVAULT_URL not set");

var client = new KeyClient(new Uri(vaultUrl), new DefaultAzureCredential());

2.3 ❌ INCORRECT: Hardcoded vault URL or credentials

// WRONG - hardcoded vault URL in production code
var client = new KeyClient(
    vaultUri: new Uri("https://production-vault.vault.azure.net/"),
    credential: new DefaultAzureCredential());

// WRONG - using deprecated authentication
var client = new KeyClient(
    vaultUri: new Uri(vaultUrl),
    credential: new InteractiveBrowserCredential()); // Not recommended for production

---

3. KeyClient Operations

3.1 ✅ CORRECT: Create RSA Key (Sync)

// Create a basic RSA key
KeyVaultKey key = client.CreateKey("rsa-key-name", KeyType.Rsa);

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);

// Create with specific options
var rsaOptions = new CreateRsaKeyOptions("rsa-key-with-options", hardwareProtected: false)
{
    KeySize = 2048,
    ExpiresOn = DateTimeOffset.UtcNow.AddYears(1)
};
KeyVaultKey rsaKey = client.CreateRsaKey(rsaOptions);

3.2 ✅ CORRECT: Create EC Key (Sync)

var ecOptions = new CreateEcKeyOptions("ec-key-name", hardwareProtected: false)
{
    CurveName = KeyCurveName.P256
};
KeyVaultKey ecKey = client.CreateEcKey(ecOptions);

3.3 ✅ CORRECT: Retrieve Key

KeyVaultKey key = client.GetKey("key-name");

Console.WriteLine(key.Name);
Console.WriteLine(key.KeyType);
Console.WriteLine(key.Properties.Version);

3.4 ✅ CORRECT: Update Key Properties

KeyVaultKey key = client.GetKey("key-name");

// Modify properties
key.Properties.Tags["environment"] = "production";
key.Properties.ExpiresOn = DateTimeOffset.UtcNow.AddYears(2);

KeyVaultKey updatedKey = client.UpdateKeyProperties(key.Properties);

3.5 ✅ CORRECT: List Keys

Pageable<KeyProperties> allKeys = client.GetPropertiesOfKeys();

foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

3.6 ✅ CORRECT: Delete and Purge Key

DeleteKeyOperation operation = client.StartDeleteKey("key-name");

// Wait for completion before purging
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);
    operation.UpdateStatus();
}

DeletedKey deletedKey = operation.Value;
Console.WriteLine($"Deleted: {deletedKey.Name} on {deletedKey.DeletedOn}");

// Purge if soft-delete is enabled
client.PurgeDeletedKey(deletedKey.Name);

3.7 ❌ INCORRECT: Not waiting for delete operation

// WRONG - attempting to purge without waiting for delete to complete
DeleteKeyOperation operation = client.StartDeleteKey("key-name");
client.PurgeDeletedKey("key-name"); // Will fail - key not yet deleted

---

4. CryptographyClient Operations

4.1 ✅ CORRECT: Get CryptographyClient from KeyClient

KeyVaultKey key = client.CreateKey("crypto-key", KeyType.Rsa);

// Get CryptographyClient from the KeyClient (recommended)
CryptographyClient cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

4.2 ✅ CORRECT: Encrypt and Decrypt

byte[] plaintext = Encoding.UTF8.GetBytes("Sensitive data to encrypt");

// Encrypt
EncryptResult encryptResult = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep256, plaintext);
byte[] ciphertext = encryptResult.Ciphertext;

// Decrypt
DecryptResult decryptResult = cryptoClient.Decrypt(EncryptionAlgorithm.RsaOaep256, ciphertext);
string decryptedText = Encoding.UTF8.GetString(decryptResult.Plaintext);

4.3 ✅ CORRECT: Sign and Verify

// For signing, you typically sign a hash (digest) of the data
byte[] data = Encoding.UTF8.GetBytes("Data to sign");
using var sha256 = SHA256.Create();
byte[] digest = sha256.ComputeHash(data);

// Sign the digest
SignResult signResult = cryptoClient.Sign(SignatureAlgorithm.RS256, digest);
byte[] signature = signResult.Signature;

// Verify the signature
VerifyResult verifyResult = cryptoClient.Verify(SignatureAlgorithm.RS256, digest, signature);
Console.WriteLine($"Signature valid: {verifyResult.IsValid}");

4.4 ✅ CORRECT: Wrap and Unwrap Key

byte[] keyToWrap = new byte[32]; // e.g., AES-256 key
RandomNumberGenerator.Fill(keyToWrap);

// Wrap the key
WrapResult wrapResult = cryptoClient.WrapKey(KeyWrapAlgorithm.RsaOaep256, keyToWrap);
byte[] wrappedKey = wrapResult.EncryptedKey;

// Unwrap the key
UnwrapResult unwrapResult = cryptoClient.UnwrapKey(KeyWrapAlgorithm.RsaOaep256, wrappedKey);
byte[] unwrappedKey = unwrapResult.Key;

4.5 ❌ INCORRECT: Wrong algorithm for key type

// WRONG - Using RSA algorithm with EC key
KeyVaultKey ecKey = client.CreateEcKey(new CreateEcKeyOptions("ec-key"));
CryptographyClient cryptoClient = client.GetCryptographyClient(ecKey.Name, ecKey.Properties.Version);

// This will fail - RSA-OAEP doesn't work with EC keys
EncryptResult result = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep, plaintext);

---

5. Async Variants

5.1 ✅ CORRECT: Async Key Operations

// Create key asynchronously
KeyVaultKey key = await client.CreateKeyAsync("async-key", KeyType.Rsa);

// Get key asynchronously
key = await client.GetKeyAsync("async-key");

// List keys asynchronously
AsyncPageable<KeyProperties> allKeys = client.GetPropertiesOfKeysAsync();
await foreach (KeyProperties keyProperties in allKeys)
{
    Console.WriteLine(keyProperties.Name);
}

5.2 ✅ CORRECT: Async Delete with WaitForCompletion

DeleteKeyOperation operation = await client.StartDeleteKeyAsync("key-name");

// Wait for completion asynchronously
await operation.WaitForCompletionAsync();

DeletedKey key = operation.Value;
await client.PurgeDeletedKeyAsync(key.Name);

5.3 ✅ CORRECT: Async Cryptography Operations

EncryptResult encryptResult = await cryptoClient.EncryptAsync(
    EncryptionAlgorithm.RsaOaep256, plaintext);

DecryptResult decryptResult = await cryptoClient.DecryptAsync(
    EncryptionAlgorithm.RsaOaep256, encryptResult.Ciphertext);

---

6. Error Handling

6.1 ✅ CORRECT: Handle RequestFailedException

try
{
    KeyVaultKey key = await client.GetKeyAsync("non-existent-key");
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    Console.WriteLine($"Key not found: {ex.Message}");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Key Vault error: {ex.Status} - {ex.Message}");
}

6.2 ❌ INCORRECT: Swallowing exceptions

// WRONG - empty catch block hides errors
try
{
    KeyVaultKey key = await client.GetKeyAsync("key-name");
}
catch (Exception)
{
    // Silent failure
}

---

7. Best Practices

7.1 ✅ CORRECT: Reuse Client Instance

// Create once and reuse - clients are thread-safe
public class KeyVaultService
{
    private readonly KeyClient _client;

    public KeyVaultService(string vaultUrl)
    {
        _client = new KeyClient(new Uri(vaultUrl), new DefaultAzureCredential());
    }

    public async Task<KeyVaultKey> GetKeyAsync(string keyName) =>
        await _client.GetKeyAsync(keyName);
}

7.2 ✅ CORRECT: Use Key Versioning

// List all versions of a key
AsyncPageable<KeyProperties> versions = client.GetPropertiesOfKeyVersionsAsync("key-name");

await foreach (KeyProperties version in versions)
{
    Console.WriteLine($"Version: {version.Version}, Created: {version.CreatedOn}");
}

// Get specific version
KeyVaultKey specificVersion = await client.GetKeyAsync("key-name", "version-id");

7.3 ❌ INCORRECT: Creating new client for each operation

// WRONG - wasteful to create new client for each operation
public async Task<KeyVaultKey> GetKey(string keyName)
{
    var client = new KeyClient(new Uri(vaultUrl), new DefaultAzureCredential());
    return await client.GetKeyAsync(keyName);
}

---

8. HSM-Protected Keys

8.1 ✅ CORRECT: Create HSM-Protected Key

// Requires Premium tier Azure Key Vault
var rsaHsmOptions = new CreateRsaKeyOptions("rsa-hsm-key", hardwareProtected: true)
{
    KeySize = 2048
};
KeyVaultKey hsmKey = await client.CreateRsaKeyAsync(rsaHsmOptions);

// Verify it's HSM-protected
Console.WriteLine($"Key Type: {hsmKey.KeyType}"); // Should be "RSA-HSM"

8.2 ❌ INCORRECT: Assuming HSM without Premium tier

// WRONG - HSM keys require Premium tier; this will fail on Standard tier
var hsmOptions = new CreateRsaKeyOptions("hsm-key", hardwareProtected: true);
KeyVaultKey key = await client.CreateRsaKeyAsync(hsmOptions); // Fails on Standard tier