次の方法で共有


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

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) | API リファレンス ドキュメント | 製品ドキュメント | サンプル | 移行ガイド

作業の開始

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

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

dotnet add package Azure.Security.KeyVault.Keys

前提条件

標準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 foreachAsyncPageable<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 キーを操作するためのコード例を次に示します。

    • 対称キーのラップとラップ解除

その他のドキュメント

共同作成

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

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

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

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

インプレッション数