翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS Encryption SDK .NET 用
AWS Encryption SDK for .NET は、C\$1 やその他の .NET プログラミング言語でアプリケーションを記述している開発者向けのクライアント側の暗号化ライブラリです。Windows、macOS、Linux でサポートされています。
**注記**
AWS Encryption SDK for .NET のバージョン 4.0.0 がメッセージ仕様から逸脱しています AWS Encryption SDK 。その結果、バージョン 4.0.0 で暗号化されたメッセージは、.NET AWS Encryption SDK 用 のバージョン 4.0.0 以降でのみ復号できます。その他のプログラミング言語実装では復号化できません。
AWS Encryption SDK for .NET のバージョン 4.0.1 は、 AWS Encryption SDK メッセージ仕様に従ってメッセージを書き込み、他のプログラミング言語の実装と相互運用できます。デフォルトでは、バージョン 4.0.1 はバージョン 4.0.0 で暗号化されたメッセージを読み取ることができます。ただし、バージョン 4.0.0 で暗号化されたメッセージを復号化したくない場合は、[https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) プロパティを指定してクライアントがこれらのメッセージを読み取らないようにすることができます。詳細については、GitHub の aws-encryption-sdk リポジトリにある [v4.0.1 リリースノート](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1)を参照してください。
AWS Encryption SDK for .NET は、以下の点 AWS Encryption SDK で の他のプログラミング言語実装とは異なります。
+ [データキーキャッシュ](data-key-caching.md) はサポートされていません
**注記**
AWS Encryption SDK for .NET のバージョン 4.*x* は、代替の暗号化マテリアルキャッシュソリューションである[AWS KMS 階層キーリング](use-hierarchical-keyring.md)をサポートしています。
+ ストリーミングデータはサポートしていません
+ .NET 用 AWS Encryption SDK から [ログ記録やスタックトレースはありません](#dot-net-debugging)
+ [が必要です AWS SDK for .NET](#dot-net-install)
AWS Encryption SDK for .NET には、 の他の言語実装のバージョン 2.0.*x* 以降で導入されたすべてのセキュリティ機能が含まれています AWS Encryption SDK。ただし、 AWS Encryption SDK for .NET を使用して、 の 2.0.*x* より前のバージョンの別の言語実装によって暗号化されたデータを復号する場合は AWS Encryption SDK、[コミットメントポリシー](concepts.md#commitment-policy)を調整する必要がある場合があります。詳細については、「[コミットメントポリシーの設定方法](migrate-commitment-policy.md#migrate-commitment-step1)」を参照してください。
AWS Encryption SDK for .NET は、仕様を記述する正式な検証言語である [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK の の製品であり、実装するコード、およびテストするための証明です。その結果、機能の正確性を保証するフレームワークに、 AWS Encryption SDK の機能を実装するライブラリができあがりました。
**詳細はこちら**
+ 代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
+ AWS Encryption SDK for .NET を使用したプログラミングの詳細については、GitHub の aws-encryption-sdk リポジトリの [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/) ディレクトリを参照してください。
**Topics**
+ [インストールおよび構築](#dot-net-install)
+ [デバッグ](#dot-net-debugging)
+ [例](dot-net-examples.md)
## AWS Encryption SDK for .NET のインストール
AWS Encryption SDK for .NET は NuGet の [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)パッケージとして利用できます。for .NET AWS Encryption SDK のインストールと構築の詳細については、 `aws-encryption-sdk-net`リポジトリの [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) ファイルを参照してください。
**バージョン 3.x**
AWS Encryption SDK for .NET のバージョン 3.*x* は、Windows でのみ .NET Framework 4.5.2 – 4.8 をサポートしています。サポートされているすべてのオペレーティングシステムで、.NET Core 3.0 以降と.NET 5.0 以降をサポートします。
**バージョン 4.x**
AWS Encryption SDK for .NET のバージョン 4.*x* は、.NET 6.0 および .NET Framework net48 以降をサポートしています。バージョン 4.*x* には AWS SDK for .NET v3 が必要です。
**バージョン 5.x**
AWS Encryption SDK for .NET のバージョン 5.*x* は、.NET 6.0 および .NET Framework net48 以降をサポートしています。バージョン 5.*x* には、マテリアルプロバイダーライブラリ (MPL) のバージョン 2.*x* と AWS SDK for .NET v4 が必要です。
AWS Encryption SDK for .NET では、 AWS Key Management Service (AWS KMS) キーを使用していない場合 SDK for .NET でも、 が必要です。NuGet パッケージと共にインストールされます。ただし、 AWS KMS キーを使用している場合を除き、 AWS Encryption SDK for .NET では AWS アカウント、、 AWS 認証情報、または AWS サービスとのインタラクションは必要ありません。必要に応じて AWS アカウントを設定する方法については、「」を参照してください[AWS Encryption SDK での の使用 AWS KMS](getting-started.md)。
## for .NET AWS Encryption SDK のデバッグ
AWS Encryption SDK for .NET はログを生成しません。for .NET AWS Encryption SDK の例外は例外メッセージを生成しますが、スタックトレースは生成されません。
デバッグしやすいように、 SDK for .NETへのログ記録を必ず有効にしてください。からのログとエラーメッセージ SDK for .NET は、 で発生したエラーを for .NET AWS Encryption SDK のエラー SDK for .NET と区別するのに役立ちます。 SDK for .NET ログ記録については、「 *AWS SDK for .NET デベロッパーガイド*」の[AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)」を参照してください。(このトピックを確認するには、**[.NET Framework コンテンツを開く]** セクションを展開してください)。
# AWS Encryption SDK for .NET の例
次の例は、 AWS Encryption SDK for .NET でプログラミングするときに使用する基本的なコーディングパターンを示しています。具体的には、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。次に、各メソッドを呼び出す前に、メソッドの入力を定義するオブジェクトをインスタンス化します。これは、 SDK for .NETで使用するコーディングパターンとよく似ています。
代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
for .NET を使用したプログラミングのその他の例については、GitHub AWS Encryption SDK の`aws-encryption-sdk`リポジトリの `aws-encryption-sdk-net` ディレクトリにある[例](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples)を参照してください。
## AWS Encryption SDK for .NET でのデータの暗号化
この例では、データを暗号化するための基本的なパターンを示しています。 1 つのラ AWS KMS ッピングキーで保護されたデータキーを使用して小さなファイルを暗号化します。
ステップ 1: AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。
まず、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。のメソッドを使用して、データを AWS Encryption SDK 暗号化および復号します。マテリアルプロバイダライブラリのメソッドを使用して、データを保護するキーを指定するキーリングを作成します。
AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化する方法は、.NET AWS Encryption SDK 用 のバージョン 3.*x* と 4.*x* で異なります。次の手順はすべて、.NET AWS Encryption SDK 用 のバージョン 3.*x* と 4.*x* の両方で同じです。
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングを作成する各メソッドには、対応する入力オブジェクトクラスがあります。たとえば、`CreateAwsKmsKeyring()` メソッドの入力オブジェクトを作成するには、`CreateAwsKmsKeyringInput` クラスのインスタンスを作成します。
このキーリングの入力では [ジェネレータキー](use-kms-keyring.md#kms-keyring-encrypt) は指定されていませんが、`KmsKeyId` パラメータで指定される単一の KMS キーはジェネレータキーとなります。データを暗号化するデータキーを生成し、暗号化します。
この入力オブジェクトには、KMS キー AWS リージョン の 用の AWS KMS クライアントが必要です。 AWS KMS クライアントを作成するには、 で `AmazonKeyManagementServiceClient` クラスをインスタンス化します SDK for .NET。パラメータなしで `AmazonKeyManagementServiceClient()` コンストラクタを呼び出すと、デフォルト値でクライアントが作成されます。
.NET AWS Encryption SDK 用 で暗号化するために使用される AWS KMS キーリングでは、キー ID、キー ARN、エイリアス名、またはエイリアス ARN を使用して [KMS キーを識別](use-kms-keyring.md#kms-keyring-id)できます。復号に使用される AWS KMS キーリングでは、キー ARN を使用して各 KMS キーを識別する必要があります。復号に暗号化キーリングを再利用する場合は、すべての KMS キーにキー ARN ID を使用します。
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
ステップ 3: キーリングを作成します。
キーリングを作成するには、キーリング入力オブジェクトを使用してキーリングメソッドを呼び出します。この例では、KMS キーを 1 つだけ取得する、この `CreateAwsKmsKeyring()` メソッドを使用しています。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
ステップ 4: 暗号化コンテキストを定義します。
[暗号化コンテキスト](concepts.md#encryption-context)はオプションですが、 の暗号化オペレーションでは強く推奨されます AWS Encryption SDK。1 つ以上の非シークレットキーと値のペアを定義できます。
.NET AWS Encryption SDK 用 のバージョン 4.*x* では、必要な暗号化コンテキスト [CMM を使用して、すべての暗号化リクエストで暗号化コンテキスト](configure.md#config-required-encryption-context-cmm)を要求できます。
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
ステップ 5: 暗号化用の入力オブジェクトを作成します。
`Encrypt()` メソッドを呼び出す前に、`EncryptInput` クラスのインスタンスを作成します。
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
ステップ 6: プレーンテキストを暗号化します。
の `Encrypt()`メソッド AWS Encryption SDK を使用して、定義したキーリングを使用してプレーンテキストを暗号化します。
この `Encrypt() ` メソッドが返す `EncryptOutput` には、暗号化されたメッセージ (`Ciphertext`)、暗号化コンテキスト、アルゴリズムスイートを取得するメソッドがあります。
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
ステップ 7: 暗号化されたメッセージを取得します。
for .NET AWS Encryption SDK の `Decrypt()`メソッドは、`EncryptOutput`インスタンス`Ciphertext`のメンバーを取得します。
`EncryptOutput` オブジェクトの `Ciphertext` メンバーは [暗号化されたメッセージ](concepts.md#message) であり、暗号化されたデータ、暗号化されたデータキー、メタデータ (暗号化コンテキストを含む) を含むポータブルオブジェクトです。暗号化されたメッセージを長期間安全に保管したり、`Decrypt()` メソッドに送信してプレーンテキストを復元することもできます。
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## for .NET での厳密なモードで AWS Encryption SDK の復号化
ベストプラクティスでは、データを復号する際に使用するキーを指定することを推奨していますが、これは Strict モードと呼ばれるオプションです。 AWS Encryption SDK は、キーリングで指定した KMS キーのみを使用して暗号文を復号します。復号化キーリング内のキーには、データを暗号化したキーが少なくとも 1 つ含まれている必要があります。
この例は、.NET 用 AWS Encryption SDK による Strict モードでの復号化の基本パターンを示しています。
ステップ 1: AWS Encryption SDK および マテリアルプロバイダーライブラリをインスタンス化します。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。 AWS Encryption SDK for .NET の各キーリングメソッドには、対応する入力オブジェクトがあります。この例では、`CreateAwsKmsKeyring()` メソッドを使用してキーリングを作成しているため、入力用の `CreateAwsKmsKeyringInput` クラスをインスタンス化しています。
復号キーリングでは、キー ARN を使用して KMS キー を指定する必要があります。
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
ステップ 3: キーリングを作成します。
復号化キーリングを作成するために、この例では `CreateAwsKmsKeyring()` メソッドとキーリング入力オブジェクトを使用します。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
ステップ 4: 復号化用の入力オブジェクトを作成します。
`Decrypt()` メソッドの入力オブジェクトを作成するには、`DecryptInput` クラスをインスタンス化します。
`DecryptInput()` コンストラクタの `Ciphertext` パラメータは、`Encrypt()` メソッドが返した `EncryptOutput` オブジェクトの `Ciphertext` メンバーを受け取ります。`Ciphertext` プロパティは [暗号化されたメッセージ](concepts.md#message) を表します。これには、 AWS Encryption SDK がメッセージの復号化に必要な暗号化されたデータ、暗号化されたデータキー、メタデータが含まれます。
.NET AWS Encryption SDK 用 のバージョン 4.*x* では、オプションの `EncryptionContext`パラメータを使用して、 `Decrypt()`メソッドで暗号化コンテキストを指定できます。
この `EncryptionContext` パラメータを使用して、暗号化時に使用された暗号化コンテキストが、暗号文の復号化に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名付きアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
ステップ 5: 暗号文を復号化します。
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
ステップ 6: 暗号化コンテキストを確認します — バージョン 3.x
for .NET のバージョン 3.*x* AWS Encryption SDK の `Decrypt()`メソッドは、暗号化コンテキストを使用しません。暗号化されたメッセージのメタデータから暗号化コンテキストの値を取得します。ただし、プレーンテキストを返したり使用したりする前に、暗号文の復号に使用した暗号化コンテキストに、暗号化時に指定した暗号化コンテキストが含まれていることを確認することがベストプラクティスです。
暗号化に使用した暗号化コンテキストが、暗号文の復号に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名でアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## AWS Encryption SDK for .NET の検出キーリングを使用した復号
復号化に KMS キーを指定するのではなく、KMS キーを指定しないキーリングである AWS KMS ディスカバリーキーリングを提供できます。検出キーリングを使用すると、発信者がキーに対する復号アクセス許可を持っている限り、 AWS Encryption SDK は暗号化された KMS キーを使用してデータを復号できます。ベストプラクティスとして、 AWS アカウント 特定のパーティションで使用できる KMS キーを制限する検出フィルターを追加します。
AWS Encryption SDK for .NET には、 AWS KMS クライアントを必要とする基本的な検出キーリングと、1 つ以上の を指定する必要がある検出マルチキーリングが用意されています AWS リージョン。クライアントとリージョンはどちらも、暗号化されたメッセージの復号化に使用できる KMS キーを制限します。 どちらのキーリングの入力オブジェクトにも、推奨ディスカバリーフィルターが適用されます。
次の例は、 AWS KMS ディスカバリーキーリングとディスカバリーフィルターを使用してデータを復号化するパターンを示しています。
ステップ 1: AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。 AWS Encryption SDK for .NET の各キーリングメソッドには、対応する入力オブジェクトがあります。この例では、`CreateAwsKmsDiscoveryKeyring()` メソッドを使用してキーリングを作成しているため、入力用の `CreateAwsKmsDiscoveryKeyringInput` クラスをインスタンス化しています。
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
ステップ 3: キーリングを作成します。
復号化キーリングを作成するために、この例では `CreateAwsKmsDiscoveryKeyring()` メソッドとキーリング入力オブジェクトを使用します。
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
ステップ 4: 復号化用の入力オブジェクトを作成します。
`Decrypt()` メソッドの入力オブジェクトを作成するには、`DecryptInput` クラスをインスタンス化します。`Ciphertext` パラメータの値は、`Encrypt()` メソッドが返す `EncryptOutput` オブジェクトの `Ciphertext` メンバーです。
for .NET のバージョン 4.*x* AWS Encryption SDK では、オプションの `EncryptionContext`パラメータを使用して、 `Decrypt()`メソッドで暗号化コンテキストを指定できます。
この `EncryptionContext` パラメータを使用して、暗号化時に使用された暗号化コンテキストが、暗号文の復号化に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名付きアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
ステップ 5: 暗号化コンテキストを確認します — バージョン 3.x
for .NET のバージョン 3.*x* AWS Encryption SDK の `Decrypt()`メソッドは、 で暗号化コンテキストを使用しません`Decrypt()`。暗号化されたメッセージのメタデータから暗号化コンテキストの値を取得します。ただし、プレーンテキストを返したり使用したりする前に、暗号文の復号に使用した暗号化コンテキストに、暗号化時に指定した暗号化コンテキストが含まれていることを確認することがベストプラクティスです。
暗号化で使用された暗号化コンテキストが、暗号文の復号に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名でアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```