azure-security-keyvault-keys-dotnet

Azure.Security.KeyVault.Keys (.NET)

Azure Key Vault および Managed HSM で暗号化キーを管理するためのクライアントライブラリです。

変更を加える前に、Vault／Managed HSM の機能、テナント／RBAC、キー名／バージョン、ライフサイクルの適用範囲を確認してください。対称 Oct キーやハードウェア保護には、対応するサービス／ティアが必要です。通常の Vault ですべての例が動作するとは限りません。キー操作は、実際のアルゴリズムに適合している必要があります。RSA の Encrypt／Decrypt オプションを限定した場合、許可された対応する操作を追加しない限り、署名やラップには使用できません。暗号文／署名とともにバージョン ID を保持し、データで不要になるまで古いキーを保持してください。バックアップファイルは機密情報であり、サービスによる復元には制限があります。RSA は小さなペイロード向けです。大量のデータには、認証付きエンベロープ暗号化を使用してください。

インストール

dotnet add package Azure.Security.KeyVault.Keys
dotnet add package Azure.Identity

SDK のバージョン例：4.7.0。対象プロジェクトでサポートされているパッケージのバージョン／API を確認してください。

環境変数

KEY_VAULT_NAME=<your-key-vault-name>
# Or full URI
AZURE_KEYVAULT_URL=https://<vault-name>.vault.azure.net

クライアント階層

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

認証

DefaultAzureCredential（推奨）

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());

サービスプリンシパル

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

var client = new KeyClient(new Uri(kvUri), credential);

キー管理

キーの作成

// 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);

キーの取得

// 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}");
}

キーのプロパティの更新

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);

キーの削除と消去

// 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 is a separate irreversible operation, subject to purge protection.
// await client.PurgeDeletedKeyAsync("my-rsa-key");

// Or recover deleted key
RecoverDeletedKeyOperation recovery = await client.StartRecoverDeletedKeyAsync("my-rsa-key");
await recovery.WaitForCompletionAsync();
KeyVaultKey recoveredKey = recovery.Value;

バックアップと復元

// 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);

暗号化操作

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());

暗号化と復号

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);
// Consume decrypted plaintext without logging it.

キーのラップとアンラップ

// 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);

署名と検証

// 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);

キーリゾルバー

using Azure.Security.KeyVault.Keys.Cryptography;

var resolver = new KeyResolver(new DefaultAzureCredential());

// Resolve key by ID to get CryptographyClient
var resolvedKey = await resolver.ResolveAsync(
    new Uri("https://myvault.vault.azure.net/keys/my-key/version"));

// The resolver returns a key-encryption-key interface for wrap/unwrap.
// For Encrypt/Decrypt, construct CryptographyClient with a validated key ID.

キーのローテーション

// 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);

キーの種類のリファレンス

種類	用途
KeyClient	キー管理操作
CryptographyClient	暗号化操作
KeyResolver	キー ID を CryptographyClient に解決
KeyVaultKey	暗号化素材を含むキー
KeyProperties	キーのメタデータ（暗号化素材なし）
CreateRsaKeyOptions	RSA キーの作成オプション
CreateEcKeyOptions	EC キーの作成オプション
CreateOctKeyOptions	対称キーのオプション
EncryptResult	暗号化の結果
DecryptResult	復号の結果
SignResult	署名の結果
VerifyResult	検証の結果
WrapResult	キーラップの結果
UnwrapResult	キーアンラップの結果

アルゴリズムのリファレンス

暗号化アルゴリズム

アルゴリズム	キーの種類	説明
RsaOaep	RSA	RSA-OAEP
RsaOaep256	RSA	RSA-OAEP-256
Rsa15	RSA	RSA 1.5（レガシー）
A128Gcm	Oct	AES-128-GCM
A256Gcm	Oct	AES-256-GCM

署名アルゴリズム

アルゴリズム	キーの種類	説明
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

キーラップアルゴリズム

アルゴリズム	キーの種類	説明
RsaOaep	RSA	RSA-OAEP
RsaOaep256	RSA	RSA-OAEP-256
A128KW	Oct	AES-128 キーラップ
A256KW	Oct	AES-256 キーラップ

ベストプラクティス

1. マネージド ID を使用する — シークレットよりも DefaultAzureCredential を優先します
2. 論理的な削除を有効にする — 誤削除から保護します
3. HSM で保護されたキーを使用する — 機密性の高いキーには HardwareProtected = true を設定します
4. キーのローテーションを実装する — 自動ローテーションポリシーを使用します
5. キー操作を制限する — 必要な KeyOperations だけを有効にします
6. 有効期限を設定する — キーには必ず ExpiresOn を設定します
7. 特定のバージョンを使用する — 本番環境ではバージョンを固定します
8. CryptographyClient をキャッシュする — 複数の操作で再利用します

エラー処理

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}");
}

必要な RBAC ロール

ロール	権限
Key Vault Crypto Officer	キー管理の全操作
Key Vault Crypto User	暗号化操作でのキーの使用
Key Vault Reader	キーのメタデータの読み取り

関連 SDK

SDK	目的	インストール
Azure.Security.KeyVault.Keys	キー（この SDK）	dotnet add package Azure.Security.KeyVault.Keys
Azure.Security.KeyVault.Secrets	シークレット	dotnet add package Azure.Security.KeyVault.Secrets
Azure.Security.KeyVault.Certificates	証明書	dotnet add package Azure.Security.KeyVault.Certificates
Azure.Identity	認証	dotnet add package Azure.Identity

参考リンク

リソース	URL
NuGet パッケージ	https://www.nuget.org/packages/Azure.Security.KeyVault.Keys
API リファレンス	https://learn.microsoft.com/dotnet/api/azure.security.keyvault.keys
クイックスタート	https://learn.microsoft.com/azure/key-vault/keys/quick-create-net
GitHub ソース	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Keys

使用する場面

このスキルは、概要で説明されているワークフローやアクションを実行する際に適用できます。

制限事項

• このスキルは、タスクが上記の説明された範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。