Azure.Security.KeyVault.Keys (.NET)

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

Installation

dotnet

add

package Azure.Security.KeyVault.Keys

dotnet

add

package Azure.Identity

Current Version

4.7.0 (stable) Environment Variables KEY_VAULT_NAME = < your-key-vault-name

Or full URI

AZURE_KEYVAULT_URL

https:// < vault-name

.vault.azure.net 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 DefaultAzureCredential (Recommended) using Azure . Identity ; using Azure . Security . KeyVault . Keys ; var keyVaultName = Environment . GetEnvironmentVariable ( "KEY_VAULT_NAME" ) ; var kvUri = $"https:// { keyVaultName } .vault.azure.net" ; var client = new KeyClient ( new Uri ( kvUri ) , new DefaultAzureCredential ( ) ) ; Service Principal var credential = new ClientSecretCredential ( tenantId : "" , clientId : "" , clientSecret : "" ) ; var client = new KeyClient ( new Uri ( kvUri ) , credential ) ; Key Management Create Keys // Create RSA key KeyVaultKey rsaKey = await client . CreateKeyAsync ( "my-rsa-key" , KeyType . Rsa ) ; Console . WriteLine ( $"Created key: { rsaKey . Name } , Type: { rsaKey . KeyType } " ) ; // Create RSA key with options var 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 key var 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/unwrap var octOptions = new CreateOctKeyOptions ( "my-oct-key" ) { KeySize = 256 , HardwareProtected = true } ; KeyVaultKey octKey = await client . CreateOctKeyAsync ( octOptions ) ; Retrieve Keys // 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 version KeyVaultKey keyVersion = await client . GetKeyAsync ( "my-rsa-key" , "version-id" ) ; // List all keys await foreach ( KeyProperties keyProps in client . GetPropertiesOfKeysAsync ( ) ) { Console . WriteLine ( $"Key: { keyProps . Name } , Enabled: { keyProps . Enabled } " ) ; } // List key versions await foreach ( KeyProperties version in client . GetPropertiesOfKeyVersionsAsync ( "my-rsa-key" ) ) { Console . WriteLine ( $"Version: { version . Version } , Created: { version . CreatedOn } " ) ; } Update Key Properties 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 // Start delete operation DeleteKeyOperation 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 key KeyVaultKey recoveredKey = await client . StartRecoverDeletedKeyAsync ( "my-rsa-key" ) ; Backup and Restore // Backup key byte [ ] backup = await client . BackupKeyAsync ( "my-rsa-key" ) ; await File . WriteAllBytesAsync ( "key-backup.bin" , backup ) ; // Restore key byte [ ] backupData = await File . ReadAllBytesAsync ( "key-backup.bin" ) ; KeyVaultKey restoredKey = await client . RestoreKeyBackupAsync ( backupData ) ; Cryptographic Operations Get CryptographyClient // From KeyClient KeyVaultKey key = await client . GetKeyAsync ( "my-rsa-key" ) ; CryptographyClient cryptoClient = client . GetCryptographyClient ( key . Name , key . Properties . Version ) ; // Or create directly with key ID CryptographyClient cryptoClient = new CryptographyClient ( new Uri ( "https://myvault.vault.azure.net/keys/my-rsa-key/version" ) , new DefaultAzureCredential ( ) ) ; Encrypt and Decrypt byte [ ] plaintext = Encoding . UTF8 . GetBytes ( "Secret message to encrypt" ) ; // Encrypt EncryptResult encryptResult = await cryptoClient . EncryptAsync ( EncryptionAlgorithm . RsaOaep256 , plaintext ) ; Console . WriteLine ( $"Encrypted: { Convert . ToBase64String ( encryptResult . Ciphertext ) } " ) ; // Decrypt DecryptResult decryptResult = await cryptoClient . DecryptAsync ( EncryptionAlgorithm . RsaOaep256 , encryptResult . Ciphertext ) ; string decrypted = Encoding . UTF8 . GetString ( decryptResult . Plaintext ) ; Console . WriteLine ( $"Decrypted: { decrypted } " ) ; Wrap and Unwrap Keys // Key to wrap (e.g., AES key) byte [ ] keyToWrap = new byte [ 32 ] ; // 256-bit key RandomNumberGenerator . Fill ( keyToWrap ) ; // Wrap key WrapResult wrapResult = await cryptoClient . WrapKeyAsync ( KeyWrapAlgorithm . RsaOaep256 , keyToWrap ) ; // Unwrap key UnwrapResult unwrapResult = await cryptoClient . UnwrapKeyAsync ( KeyWrapAlgorithm . RsaOaep256 , wrapResult . EncryptedKey ) ; Sign and Verify // Data to sign byte [ ] data = Encoding . UTF8 . GetBytes ( "Data to sign" ) ; // Sign data (computes hash internally) SignResult signResult = await cryptoClient . SignDataAsync ( SignatureAlgorithm . RS256 , data ) ; // Verify signature VerifyResult verifyResult = await cryptoClient . VerifyDataAsync ( SignatureAlgorithm . RS256 , data , signResult . Signature ) ; Console . WriteLine ( $"Signature valid: { verifyResult . IsValid } " ) ; // Or sign pre-computed hash using var sha256 = SHA256 . Create ( ) ; byte [ ] hash = sha256 . ComputeHash ( data ) ; SignResult signHashResult = await cryptoClient . SignAsync ( SignatureAlgorithm . RS256 , hash ) ; Key Resolver using Azure . Security . KeyVault . Keys . Cryptography ; var resolver = new KeyResolver ( new DefaultAzureCredential ( ) ) ; // Resolve key by ID to get CryptographyClient CryptographyClient cryptoClient = await resolver . ResolveAsync ( new Uri ( "https://myvault.vault.azure.net/keys/my-key/version" ) ) ; // Use for encryption EncryptResult result = await cryptoClient . EncryptAsync ( EncryptionAlgorithm . RsaOaep256 , plaintext ) ; Key Rotation // Rotate key (creates new version) KeyVaultKey rotatedKey = await client . RotateKeyAsync ( "my-rsa-key" ) ; Console . WriteLine ( $"New version: { rotatedKey . Properties . Version } " ) ; // Get rotation policy KeyRotationPolicy policy = await client . GetKeyRotationPolicyAsync ( "my-rsa-key" ) ; // Update rotation policy policy . ExpiresIn = "P90D" ; // 90 days policy . LifetimeActions . Add ( new KeyRotationLifetimeAction { Action = KeyRotationPolicyAction . Rotate , TimeBeforeExpiry = "P30D" // Rotate 30 days before expiry } ) ; await client . UpdateKeyRotationPolicyAsync ( "my-rsa-key" , policy ) ; Key Types Reference Type Purpose KeyClient Key management operations CryptographyClient Cryptographic operations KeyResolver Resolve key ID to CryptographyClient KeyVaultKey Key with cryptographic material KeyProperties Key metadata (no crypto material) CreateRsaKeyOptions RSA key creation options CreateEcKeyOptions EC key creation options CreateOctKeyOptions Symmetric key options EncryptResult Encryption result DecryptResult Decryption result SignResult Signing result VerifyResult Verification result WrapResult Key wrap result UnwrapResult Key unwrap result Algorithms Reference Encryption Algorithms Algorithm Key Type Description RsaOaep RSA RSA-OAEP RsaOaep256 RSA RSA-OAEP-256 Rsa15 RSA RSA 1.5 (legacy) A128Gcm Oct AES-128-GCM A256Gcm Oct AES-256-GCM Signature Algorithms Algorithm Key Type Description RS256 RSA RSASSA-PKCS1-v1_5 SHA-256 RS384 RSA RSASSA-PKCS1-v1_5 SHA-384 RS512 RSA RSASSA-PKCS1-v1_5 SHA-512 PS256 RSA RSASSA-PSS SHA-256 ES256 EC ECDSA P-256 SHA-256 ES384 EC ECDSA P-384 SHA-384 ES512 EC ECDSA P-521 SHA-512 Key Wrap Algorithms Algorithm Key Type Description RsaOaep RSA RSA-OAEP RsaOaep256 RSA RSA-OAEP-256 A128KW Oct AES-128 Key Wrap A256KW Oct AES-256 Key Wrap Best Practices Use Managed Identity — Prefer DefaultAzureCredential over secrets Enable soft-delete — Protect against accidental deletion Use HSM-backed keys — Set HardwareProtected = true for sensitive keys Implement key rotation — Use automatic rotation policies Limit key operations — Only enable required KeyOperations Set expiration dates — Always set ExpiresOn for keys Use specific versions — Pin to versions in production Cache CryptographyClient — Reuse for multiple operations Error Handling 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 Role Permissions Key Vault Crypto Officer Full key management Key Vault Crypto User Use keys for crypto operations Key Vault Reader Read key metadata Related SDKs SDK Purpose Install Azure.Security.KeyVault.Keys Keys (this SDK) dotnet add package Azure.Security.KeyVault.Keys Azure.Security.KeyVault.Secrets Secrets dotnet add package Azure.Security.KeyVault.Secrets Azure.Security.KeyVault.Certificates Certificates dotnet add package Azure.Security.KeyVault.Certificates Azure.Identity Authentication dotnet add package Azure.Identity Reference Links Resource URL NuGet Package https://www.nuget.org/packages/Azure.Security.KeyVault.Keys API Reference https://learn.microsoft.com/dotnet/api/azure.security.keyvault.keys Quickstart https://learn.microsoft.com/azure/key-vault/keys/quick-create-net GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys When to Use This skill is applicable to execute the workflow or actions described in the overview.