.NET 用 Azure Key Vault キークライアントライブラリ - バージョン 4.5.0

[アーティクル]
04/03/2023

Azure Key Vault は、データを暗号化するためのキーのセキュリティで保護されたストレージを提供するクラウドサービスです。複数のキーと同じキーの複数のバージョンを Azure Key Vaultに保持できます。 Azure Key Vaultの暗号化キーは、JSON Web キー (JWK) オブジェクトとして表されます。

Azure Key Vault Managed HSM は、FIPS 140-2 レベル 3 の検証済み HSM を使用してクラウドアプリケーションの暗号化キーを保護できるようにする、フルマネージドの高可用性シングルテナント標準準拠クラウドサービスです。

Azure Key Vault キーライブラリクライアントは、RSA キーと楕円曲線 (EC) キーをサポートしており、それぞれに対応するハードウェアセキュリティモジュール (HSM) がサポートされています。キーとそのバージョンを作成、取得、更新、削除、消去、バックアップ、復元、および一覧表示する操作が提供されます。

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用の Azure Key Vault キークライアントライブラリをインストールします。

dotnet add package Azure.Security.KeyVault.Keys

前提条件

Azure サブスクリプション。
既存の Azure Key Vault。 Azure Key Vaultを作成する必要がある場合は、Azure Portal または Azure CLI を使用できます。
RBAC (推奨) またはアクセス制御を使用した既存の Azure Key Vaultへの承認。

標準Key Vault リソースを作成する場合は、次の CLI コマンドを実行して、と <your-key-vault-name> を独自の一意の名前に置き換えます<your-resource-group-name>。

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Managed HSM リソースを作成する場合は、次の CLI コマンドを実行します。

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

取得 <your-user-object-id> するには、次の CLI コマンドを実行します。

az ad user show --id <your-user-principal> --query id

クライアントを認証する

Azure Key Vault サービスと対話するには、KeyClient クラスのインスタンスを作成する必要があります。ポータルで "DNS 名" と表示される コンテナー URL と、クライアントオブジェクトをインスタンス化するための資格情報が必要です。

次に示す例では、を DefaultAzureCredential使用します。これは、マネージド ID 認証を利用するローカルの開発環境や運用環境など、ほとんどのシナリオに適しています。また、運用環境での認証にはマネージド ID を使用することをお勧めします。さまざまな認証方法とそれに対応する資格情報の種類の詳細については、 Azure ID のドキュメントを参照してください。

以下に DefaultAzureCredential 示すプロバイダー、または Azure SDK で提供されているその他の資格情報プロバイダーを使用するには、まず Azure.Identity パッケージをインストールする必要があります。

dotnet add package Azure.Identity

マネージド HSM をアクティブにする

このセクションは、Managed HSM を作成する場合にのみ適用されます。 HSM をアクティブにするまでは、データプレーンのコマンドはすべて無効です。キーを作成することはできず、ロールを割り当てることもできません。 HSM をアクティブにできるのは、create コマンドの実行時に割り当てられた指定された管理者だけです。 HSM をアクティブにするには、セキュリティドメインをダウンロードする必要があります。

HSM をアクティブにするための要件は次のとおりです。

最低 3 つの RSA キーペア (最大 10 個)
セキュリティドメインの暗号化を解除するために必要なキーの最小数 (クォーラム) の指定

HSM をアクティブにするには、少なくとも 3 つ (最大 10 個) の RSA 公開キーを HSM に送信する必要があります。 HSM は、それらのキーでセキュリティドメインを暗号化して返します。このセキュリティドメインが正常にダウンロードされると、HSM を使用する準備が整います。加えて、クォーラムの指定も必要となります。クォーラムは、セキュリティドメインの暗号化を解除するために必要な秘密キーの最小数です。

次の例は、openssl を使用して 3 つの自己署名証明書を生成する方法を示しています。

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

セキュリティドメインをダウンロードして、マネージド HSM をアクティブにするには、az keyvault security-domain download コマンドを使用します。次の例では、3 つの RSA キーペアを使用し (このコマンドには公開キーのみが必要です)、クォーラムを 2 に設定します。

az keyvault security-domain download --hsm-name <your-key-vault-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json

KeyClient の作成

をインスタンス化 DefaultAzureCredential してクライアントに渡します。トークン資格情報の同じインスタンスは、同じ ID で認証する場合は、複数のクライアントで使用できます。

// Create a new key client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new KeyClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new key using the key client.
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

// Retrieve a key using the key client.
key = client.GetKey("key-name");

CryptographyClient の作成

Azure Key VaultでをKeyVaultKey作成したら、CryptographyClient を作成することもできます。

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
CryptographyClient cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

主要な概念

KeyVaultKey

Azure Key Vaultでは、複数のキーの種類とアルゴリズムがサポートされており、価値の高いキーにハードウェアセキュリティモジュール (HSM) を使用できます。

KeyClient

KeyClient同期操作と非同期操作の両方を提供するが SDK に存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。をKeyClient初期化したら、Azure Key Vaultでプライマリリソースの種類を操作できます。

CryptographyClient

CryptographyClient同期操作と非同期操作の両方を提供するが SDK に存在し、アプリケーションのユースケースに基づいてクライアントを選択できます。を初期化CryptographyClientしたら、それを使用して、Azure Key Vaultに格納されているキーを使用して暗号化操作を実行できます。

スレッドセーフ

すべてのクライアントインスタンスメソッドがスレッドセーフであり、相互に独立していることを保証します (ガイドライン)。これにより、スレッド間であっても、クライアントインスタンスの再利用に関する推奨事項が常に安全になります。

その他の概念

例

Azure.Security.KeyVault.Keys パッケージでは、同期 API と非同期 API がサポートされています。

次のセクションでは、上記で作成したをclient使用したいくつかのコードスニペットについて説明します。最も一般的な Azure Key Vault サービス関連のタスクの一部を説明します。

非同期の例

キーを非同期的に作成する
キーを非同期的に一覧表示する
キーを非同期的に削除する

キーの作成

Azure Key Vaultに格納するキーを作成します。同じ名前のキーが既に存在する場合は、新しいバージョンのキーが作成されます。

// Create a key. Note that you can specify the type of key
// i.e. Elliptic curve, Hardware Elliptic Curve, RSA
KeyVaultKey key = client.CreateKey("key-name", KeyType.Rsa);

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

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = client.CreateRsaKey(rsaCreateKey);

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

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = client.CreateEcKey(echsmkey);

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

キーの取得

GetKeyは、以前に Azure Key Vaultに格納されているキーを取得します。

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

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

既存のキーを更新する

UpdateKeyPropertiesは、以前に Azure Key Vaultに格納されているキーを更新します。

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

// You can specify additional application-specific metadata in the form of tags.
key.Properties.Tags["foo"] = "updated tag";

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

Console.WriteLine(updatedKey.Name);
Console.WriteLine(updatedKey.Properties.Version);
Console.WriteLine(updatedKey.Properties.UpdatedOn);

キーの削除

StartDeleteKeyは、Azure Key Vaultに以前に格納されているキーを削除する実行時間の長い操作を開始します。操作の完了を待たずに、キーをすぐに取得できます。 Azure Key Vaultで論理的な削除が有効になっていない場合、この操作によってキーが完全に削除されます。

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

DeletedKey key = operation.Value;
Console.WriteLine(key.Name);
Console.WriteLine(key.DeletedOn);

キーを削除して消去する

キーの消去または回復を試みる前に、実行時間の長い操作が完了するまで待つ必要があります。

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

// You only need to wait for completion if you want to purge or recover the key.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedKey key = operation.Value;
client.PurgeDeletedKey(key.Name);

キーを一覧表示します。

この例では、指定した Azure Key Vault内のすべてのキーを一覧表示します。

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

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

暗号化と暗号化解除

この例では、をCryptographyClient作成し、それを使用して Azure Key Vaultのキーを使用して暗号化と暗号化解除を行います。

// Create a new cryptography client using the same Key Vault or Managed HSM endpoint, service version,
// and options as the KeyClient created earlier.
var cryptoClient = client.GetCryptographyClient(key.Name, key.Properties.Version);

byte[] plaintext = Encoding.UTF8.GetBytes("A single block of plaintext");

// encrypt the data using the algorithm RSAOAEP
EncryptResult encryptResult = cryptoClient.Encrypt(EncryptionAlgorithm.RsaOaep, plaintext);

// decrypt the encrypted data.
DecryptResult decryptResult = cryptoClient.Decrypt(EncryptionAlgorithm.RsaOaep, encryptResult.Ciphertext);

キーを非同期的に作成する

非同期 API は、同期に対応する API と同じですが、非同期メソッドの一般的な "Async" サフィックスを使用してを返し、Task を返します。

// Create a key of any type
KeyVaultKey key = await client.CreateKeyAsync("key-name", KeyType.Rsa);

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

// Create a software RSA key
var rsaCreateKey = new CreateRsaKeyOptions("rsa-key-name", hardwareProtected: false);
KeyVaultKey rsaKey = await client.CreateRsaKeyAsync(rsaCreateKey);

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

// Create a hardware Elliptic Curve key
// Because only premium Azure Key Vault supports HSM backed keys , please ensure your Azure Key Vault
// SKU is premium when you set "hardwareProtected" value to true
var echsmkey = new CreateEcKeyOptions("ec-key-name", hardwareProtected: true);
KeyVaultKey ecKey = await client.CreateEcKeyAsync(echsmkey);

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

キーを非同期的に一覧表示する

キーの一覧表示はメソッドのGetPropertiesOfKeysAsync待機に依存しませんが、ステートメントで使用できるをawait foreach返AsyncPageable<KeyProperties>します。

AsyncPageable<KeyProperties> allKeys = client.GetPropertiesOfKeysAsync();

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

キーを非同期的に削除する

キーを消去する前に非同期的に削除する場合は、操作のメソッドを WaitForCompletionAsync 待機できます。既定では、このループは無期限にループしますが、を渡 CancellationTokenすことで取り消すことができます。

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

// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

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

トラブルシューティング

さまざまな障害シナリオを診断する方法の詳細については、トラブルシューティングガイドを参照してください。

全般

.NET SDK を使用して Azure Key Vault キークライアントライブラリと対話すると、サービスによって返されるエラーは、REST API 要求に返されるのと同じ HTTP 状態コードに対応します。

たとえば、Azure Key Vaultに存在しないキーを取得しようとすると、404"Not Found" を示すエラーが返されます。

try
{
    KeyVaultKey key = client.GetKey("some_key");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

操作のクライアント要求 ID など、追加情報がログに記録されていることがわかります。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"KeyNotFound","message":"Key not found: some_key"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

次の手順

この GitHub リポジトリには、いくつかの Azure Key Vault キークライアントライブラリサンプルが用意されています。これらのサンプルでは、Azure Key Vaultの操作中に一般的に発生するその他のシナリオのコード例を示します。

Sample1_HelloWorld.md - 次を含む Azure Key Vaultを使用する場合:
- キーの作成
- 既存のキーを取得する
- 既存のキーを更新する
- キーの削除
Sample2_BackupAndRestore.md - Azure Key Vault キーを操作するコードスニペットが含まれます。
- キーのバックアップと回復
Sample3_GetKeys.md - Azure Key Vault キーを操作するためのコード例を次に示します。
- キーの作成
- Key Vault内のすべてのキーを一覧表示する
- Key Vaultのキーを更新する
- 指定したキーのバージョンを一覧表示する
- Key Vaultからキーを削除する
- Key Vaultで削除されたキーを一覧表示する
Sample4_EncryptDecrypt.md - Azure Key Vault キーを使用して暗号化操作を実行するためのコード例を次に示します。
- CryptographyClient を使用したデータの暗号化と暗号化解除
Sample5_SignVerify.md - Azure Key Vault キーを操作するためのコード例を次に示します。
- 事前計算済みのダイジェストに署名し、署名と検証を使用して署名を確認する
- SignData と VerifyData を使用して生データに署名し、署名を確認する
Sample6_WrapUnwrap.md - Azure Key Vault キーを操作するためのコード例を次に示します。
- 対称キーのラップとラップ解除

その他のドキュメント

Azure Key Vaultの詳細なドキュメントについては、API リファレンスドキュメントを参照してください。
Secrets クライアントライブラリについては、「 Secrets クライアントライブラリ」を参照してください。
証明書クライアントライブラリについては、「証明書クライアントライブラリ」を参照してください。

共同作成

これらのライブラリの構築、テスト、および貢献の詳細については、 CONTRIBUTING.md を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

.NET 用 Azure Key Vault キークライアントライブラリ - バージョン 4.5.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

マネージド HSM をアクティブにする

KeyClient の作成

CryptographyClient の作成

主要な概念

KeyVaultKey

KeyClient

CryptographyClient

スレッドセーフ

その他の概念

例

同期の例

非同期の例

キーの作成

キーの取得

既存のキーを更新する

キーの削除

キーを削除して消去する

キーを一覧表示します。

暗号化と暗号化解除

キーを非同期的に作成する

キーを非同期的に一覧表示する

キーを非同期的に削除する

トラブルシューティング

全般

次の手順

その他のドキュメント

共同作成

フィードバック

その他のリソース

.NET 用 Azure Key Vault キー クライアント ライブラリ - バージョン 4.5.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

マネージド HSM をアクティブにする

KeyClient の作成

CryptographyClient の作成

主要な概念

KeyVaultKey

KeyClient

CryptographyClient

スレッド セーフ

その他の概念

例

同期の例

非同期の例

キーの作成

キーの取得

既存のキーを更新する

キーの削除

キーを削除して消去する

キーを一覧表示します。

暗号化と暗号化解除

キーを非同期的に作成する

キーを非同期的に一覧表示する

キーを非同期的に削除する

トラブルシューティング

全般

次の手順

その他のドキュメント

共同作成

フィードバック

その他のリソース

.NET 用 Azure Key Vault キークライアントライブラリ - バージョン 4.5.0

スレッドセーフ