.NET 用 AWS Encryption SDK - AWS Encryption SDK
インストールおよび構築デバッグAWS KMS キーリング必要な暗号化コンテキスト CMM

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

.NET 用 AWS Encryption SDK

.NET 用 AWS Encryption SDK は、C# やその他の.NET プログラミング言語でアプリケーションを作成する開発者向けのクライアント側の暗号化ライブラリです。Windows、macOS、Linux でサポートされています。

AWS Encryption SDK の プログラミング言語 実装は、すべて完全に相互運用可能です。ただし、AWS Encryption SDK for .NET のバージョン 4.x で必要な暗号化コンテキスト CMM を使用してデータを暗号化をする場合、AWS Encryption SDK for .NET のバージョン 4.x または AWS Encryption SDK for Java のバージョン 3.x でのみ復号化できます。

注記

AWS Encryption SDK for .NET のバージョン 4.0.0 は、AWS Encryption SDK のメッセージ仕様とは異なります。そのため、バージョン 4.0.0 で暗号化されたメッセージは、AWS Encryption SDK for .NET のバージョン 4.0.0 以降でのみ復号化できます。その他のプログラミング言語実装では復号化できません。

AWS Encryption SDK for .NET のバージョン 4.0.1 は、AWS Encryption SDK のメッセージ仕様に従ってメッセージを作成するため、他のプログラミング言語実装と相互運用できます。デフォルトでは、バージョン 4.0.1 はバージョン 4.0.0 で暗号化されたメッセージを読み取ることができます。ただし、バージョン 4.0.0 で暗号化されたメッセージを復号化したくない場合は、NetV4_0_0_RetryPolicy プロパティを指定してクライアントがこれらのメッセージを読み取らないようにすることができます。詳細については、GitHub の aws-encryption-sdk-dafny リポジトリにある「v4.0.1 release notes」を参照してください。

.NET 用 AWS Encryption SDK は、AWS Encryption SDK の他のプログラミング言語実装と次の点で異なります。

.NET 用 AWS Encryption SDK には、AWS Encryption SDK の他の言語実装バージョン 2.0.x で導入されたセキュリティ機能がすべて含まれています。ただし、.NET 用 AWS Encryption SDK を使用して 2.0.x より前のバージョンの AWS Encryption SDK の他言語実装によって暗号化されたデータを復号化する場合、コミットメント・ポリシーを調整する必要がある場合があります。詳細については、「コミットメントポリシーの設定方法」を参照してください。

.NET 用 AWS Encryption SDK は、仕様、それを実装するコード、およびそれらをテストするための証明を記述する正式な検証言語である Dafny の AWS Encryption SDK の製品です。その結果、機能の正確性を保証するフレームワークに、AWS Encryption SDK の機能を実装するライブラリができあがりました。

詳細はこちら

  • 代替アルゴリズムスイートの指定、暗号化されたデータキーの制限、AWS KMS マルチリージョンキーの使用など、AWS Encryption SDK でのオプションの設定方法を示す例については、「AWS Encryption SDK の設定」を参照してください。

  • .NET 用 AWS Encryption SDK を使用したプログラミングの詳細については、「GitHub の aws-encryption-sdk-python リポジトリ」の「aws-encryption-sdk-net ディレクトリ」を参照してください。

トピック

.NET 用 AWS Encryption SDK のインストール

.NET 用 AWS Encryption SDK は NuGet のAWS.Cryptography.EncryptionSDKパッケージとして入手可能です。.NET 用 AWS Encryption SDK のインストールとビルドの詳細については、aws-encryption-sdk-net リポジトリの「README.md」ファイルを参照してください。

バージョン 3.x

.NET 用 AWS Encryption SDK のバージョン 3.x は、Windows 上でのみ.NET Framework 4.5.2 — 4.8 をサポートしています。サポートされているすべてのオペレーティングシステムで、.NET Core 3.0 以降と.NET 5.0 以降をサポートします。

バージョン 4.x

.NET 用 AWS Encryption SDK のバージョン 4.x は、.NET 6.0 と.NET Framework net48 以降をサポートしています。

.NET 用 AWS Encryption SDK では、AWS Key Management Service (AWS KMS) キーを使用していない場合でも AWS SDK for .NET が必要です。NuGet パッケージと共にインストールされます。ただし、AWS KMS キーを使用する場合を除き、.NET 用 AWS Encryption SDK では AWS アカウント、AWS 認証情報、または AWS サービスとのやり取りは必要ありません。AWS アカウントが必要な場合、設定する方法については、「AWS KMS での AWS Encryption SDK の使用」を参照してください。

.NET 用 AWS Encryption SDK のデバッグ

.NET 用 AWS Encryption SDK はログは生成しません。.NET 用 AWS Encryption SDK の例外では、例外メッセージは生成されますが、スタックトレースは生成されません。

デバッグしやすいように、AWS SDK for .NET へのログ記録を必ず有効にしてください。AWS SDK for .NET のログとエラーメッセージは、「AWS SDK for .NET」で発生するエラーと「.NET 用 AWS Encryption SDK」で発生するエラーとを区別するのに役立ちます。AWS SDK for .NET ロギングのヘルプについては、「AWS SDK for .NET 開発者ガイド」の「AWSLogging」を参照してください。(このトピックを確認するには、[.NET Framework コンテンツを開く] セクションを展開してください)。

「.NET 用 AWS Encryption SDK」の AWS KMS キーリング

「.NET 用 AWS Encryption SDK」の基本の AWS KMS キーリングは、1 つの KMS キーしか使用しません。また、AWS KMS クライアントも必要になり、KMS キーの AWS リージョン 用にクライアントを設定する機会ができます。

1 つ以上の AWS KMS ラッピングキーを含むキーリングを作成するには、マルチキーリングを使用します。.NET 用 AWS Encryption SDK には、1 つ以上の AWS KMS キーを使用する特殊なマルチキーリングと、サポートされているタイプの 1 つ以上のキーリングを使用する標準のマルチキーリングがあります。プログラマーの中には、すべてのキーリングの作成にマルチキーリングメソッドを使用することを好む人もおり、.NET 用 AWS Encryption SDK はその戦略をサポートしています。

.NET 用 AWS Encryption SDK には、AWS KMS マルチリージョンキー を含む、すべての一般的なユースケースに対応する、基本的なシングルキーキーリングとマルチキーリングが用意されています。

たとえば、1 つの AWS KMS キーで AWS KMS キーリングを作成するには、CreateAwsKmsKeyring() メソッドを使用できます。

Version 3.x

次の例では、.NET 用 AWS Encryption SDK のバージョン 3.x を使用し、指定されたキーを含むリージョンのデフォルト AWS KMS クライアントを作成します。

// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

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

// Create the keyring
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
Version 4.x

次の例では、.NET 用 AWS Encryption SDK のバージョン 4.x を使用し、指定されたキーを含むリージョンの AWS KMS クライアントを作成します。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsArn
};

// Create the keyring
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);

1 つ以上の AWS KMS キーを含むキーリングを作成するには、CreateAwsKmsMultiKeyring() メソッドを使用します。この例では AWS KMS キーを 2 つ使用しています。1 つの KMS キーを指定するには、Generator パラメータのみを使用します。追加の KMS キーを指定する KmsKeyIds パラメータはオプションです。

このキーリングの入力には AWS KMS クライアントは必要ありません。代わりに、AWS Encryption SDK はキーリングの KMS キーで表される各リージョンのデフォルト AWS KMS クライアントを使用します。たとえば、Generator パラメータの値によって識別される KMS キーが米国西部 (オレゴン) リージョン (us-west-2) にある場合、AWS Encryption SDK はその us-west-2 リージョンのデフォルト AWS KMS クライアントを作成します。AWS KMS クライアントをカスタマイズする必要がある場合は、CreateAwsKmsKeyring() メソッドを使用します。

次の例では、.NET 用 AWS Encryption SDK バージョン 4.x と CreateAwsKmsKeyring() メソッドを使用し、AWS KMS クライアントをカスタマイズします。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());

string generatorKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
List<string> additionalKeys = new List<string> { "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321" };

// Instantiate the keyring input object
var createEncryptKeyringInput = new CreateAwsKmsMultiKeyringInput
{
    Generator = generatorKey,
    KmsKeyIds = additionalKeys
};

var kmsEncryptKeyring = materialProviders.CreateAwsKmsMultiKeyring(createEncryptKeyringInput);

.NET 用 AWS Encryption SDK バージョン 4.x は、対称暗号化 (SYMMETRIC_DEFAULT) または非対称 RSA KMS キーを使用する AWS KMS キーリングをサポートしています。非対称 RSA KMS キーで作成された AWS KMS キーリングには、1 つのキーペアしか含めることができません。

非対称 RSA AWS KMS キーリングで暗号化する場合、kms: GenerateDataKey や kms: Encrypt は必要ありません。キーリングを作成するときに、暗号化に使用するパブリックキーマテリアルを指定する必要があるからです。AWS KMS このキーリングで暗号化する場合、 呼び出しは行われません。非対称 RSA AWS KMS キーリングで復号化するには、kms: Decrypt 権限が必要です。

非対称 RSA AWS KMS キーリングを作成するには、非対称 RSA KMS キーのパブリックキーとプライベートキー ARN を提示する必要があります。パブリックキーは PEM でエンコードされている必要があります。次の例では、非対称 RSA キーペアを使用して AWS KMS キーリングを作成します。

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
var publicKey = new MemoryStream(Encoding.UTF8.GetBytes(AWS KMS RSA public key));

// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsRsaKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = AWS KMS RSA private key ARN,
    PublicKey = publicKey,
    EncryptionAlgorithm = EncryptionAlgorithmSpec.RSAES_OAEP_SHA_256
};

// Create the keyring
var kmsRsaKeyring = mpl.CreateAwsKmsRsaKeyring(createKeyringInput);

バージョン 4.x で必要な暗号化コンテキスト

.NET 用 AWS Encryption SDK のバージョン 4.x の場合、必要な暗号化コンテキスト CMM を使用して、暗号化操作で暗号化コンテキストを要求できます。暗号化コンテキストは、一連の非シークレットのキーと値のペアです。暗号化コンテキストは、暗号化されたデータに暗号化されてバインドされます。これにより、フィールドを復号するために同じ暗号化コンテキストが必要になります。必要な暗号化コンテキスト CMM を使用する場合、すべての暗号化および復号化の呼び出しに含める必要のある 暗号化コンテキストキー (必須キー) を 1 つ以上指定できます。

注記

必要な暗号化コンテキスト CMM は AWS Encryption SDK for Java のバージョン 3.x とのみ相互運用可能です。その他のプログラミング言語実装とは相互運用できません。必要な暗号化コンテキスト CMM を使用してデータを暗号化する場合、AWS Encryption SDK for Java のバージョン 3.x または AWS Encryption SDK for .NET のバージョン 4.x でのみ復号化できます。

暗号化時、AWS Encryption SDK は必要なすべての暗号化コンテキストキーが、指定した暗号化コンテキストに含まれていることを検証します。AWS Encryption SDK は、指定した暗号化コンテキストに署名します。必須キーではないキーと値のペアのみがシリアル化され、暗号化操作によって返される暗号化メッセージのヘッダーにプレーンテキストで保存されます。

復号化時には、必要なキーを表すすべてのキーと値のペアを含む暗号化コンテキストを提供する必要があります。AWS Encryption SDK は、この暗号化コンテキストと、暗号化されたメッセージのヘッダーに保存されているキーと値のペアを使用して、暗号化操作で指定した元の暗号化コンテキストを再構築します。AWS Encryption SDK が元の暗号化コンテキストを再構築できない場合、復号化操作は失敗します。誤った値を持つ必要なキーを含むキーと値のペアを供給すると、暗号化されたメッセージは復号化できません。暗号化時に指定したのと同じキーと値のペアを供給する必要があります。

重要

暗号化のコンテキストで必要なキーにどの値を選択するかを慎重に検討してください。復号化時には、同じキーとそれに対応する値を再度提供できる必要があります。必要なキーを再現できない場合、暗号化されたメッセージは復号化できません。

次の例では、必要な暗号化コンテキスト CMM を使用して AWS KMS キーリングを初期化します。

var encryptionContext = new Dictionary<string, string>()
{
    {"encryption", "context"},
    {"is not", "secret"},
    {"but adds", "useful metadata"},
    {"that can help you", "be confident that"},
    {"the data you are handling", "is what you think it is"}
};

// Instantiate the AWS Encryption SDK and material providers
var esdk =  new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
        
// Instantiate the keyring input object
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = kmsKey
};
 
// Create the keyring 
var kmsKeyring = mpl.CreateAwsKmsKeyring(createKeyringInput);
        
var createCMMInput = new CreateRequiredEncryptionContextCMMInput
{
    UnderlyingCMM = mpl.CreateDefaultCryptographicMaterialsManager(new CreateDefaultCryptographicMaterialsManagerInput{Keyring = kmsKeyring}),
    // If you pass in a keyring but no underlying cmm, it will result in a failure because only cmm is supported.
    RequiredEncryptionContextKeys = new List<string>(encryptionContext.Keys)
};
 
// Create the required encryption context CMM
var requiredEcCMM = mpl.CreateRequiredEncryptionContextCMM(createCMMInput);

AWS KMS キーリングを使用する場合、.NET 用 AWS Encryption SDK は、また暗号化コンテキストを使用して、キーリングが AWS KMS に行う呼び出しに追加認証データ (AAD) を提供します。