AWS Encryption SDK の例NET

次の例は、 AWS Encryption SDK の でプログラミングするときに使用する基本的なコーディングパターンを示していますNET。具体的には、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。次に、各メソッドを呼び出す前に、メソッドの入力を定義するオブジェクトをインスタンス化します。これは、 AWS SDK for .NETで使用するコーディングパターンとよく似ています。

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

for でのプログラミングのその他の例については AWS Encryption SDK NET、 のaws-encryption-sdk-dafnyリポジトリの aws-encryption-sdk-net ディレクトリにある例を参照してください GitHub。

AWS Encryption SDK の でデータを暗号化する。NET

この例では、データを暗号化するための基本的なパターンを示しています。　 1 つの AWS KMS ラッピングキーで保護されているデータキーを使用して小さなファイルを暗号化します。

ステップ 1: AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。

まず、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。の メソッドを使用して、データを AWS Encryption SDK 暗号化および復号します。マテリアルプロバイダライブラリのメソッドを使用して、データを保護するキーを指定するキーリングを作成します。

AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化する方法は、 AWS Encryption SDK 用の のバージョン 3.x と 4.x によって異なります。NET以下の手順はすべて、 のバージョン 3.x と 4.x AWS Encryption SDK の両方で同じですNET。

Version 3.x

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

Version 4.x

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

ステップ 2: キーリング用の入力オブジェクトを作成します。

キーリングを作成する各メソッドには、対応する入力オブジェクトクラスがあります。たとえば、CreateAwsKmsKeyring() メソッドの入力オブジェクトを作成するには、CreateAwsKmsKeyringInput クラスのインスタンスを作成します。

このキーリングの入力ではジェネレータキー が指定されていませんが、 KmsKeyId パラメータで指定された単一のKMSキーはジェネレータキーです。データを暗号化するデータキーを生成し、暗号化します。

この入力オブジェクトには、 KMS キー AWS リージョン の 用の AWS KMS クライアントが必要です。 AWS KMS クライアントを作成するには、 でAmazonKeyManagementServiceClientクラスをインスタンス化します AWS SDK for .NET。パラメータなしで AmazonKeyManagementServiceClient() コンストラクタを呼び出すと、デフォルト値でクライアントが作成されます。

AWS Encryption SDK の で暗号化するために使用される AWS KMS キーリングではNET、KMSキー ID、キー 、エイリアス名、またはエイリアス を使用してキーを識別できますARN。 ARN復号に使用される AWS KMS キーリングでは、キーを使用して各KMSキーARNを識別する必要があります。暗号化キーリングを復号化に再利用する場合は、すべてのKMSキーにキーARN識別子を使用します。

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()メソッドは 1 つのKMSキーのみを使用します。

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

ステップ 4: 暗号化コンテキストを定義します。　

暗号化コンテキストはオプションですが、 の暗号化オペレーションの要素として強く推奨されます AWS Encryption SDK。1 つ以上の非シークレットキーと値のペアを定義できます。

注記

for のバージョン 4.x では AWS Encryption SDK NET、必要な暗号化コンテキスト を使用して、すべての暗号化リクエストで暗号化コンテキストCMMを要求できます。

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"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: 暗号化されたメッセージを取得します。

AWS Encryption SDK の Decrypt()メソッド。NET はEncryptOutputインスタンスCiphertextのメンバーを取得します。

EncryptOutput オブジェクトの Ciphertext メンバーは 暗号化されたメッセージ であり、暗号化されたデータ、暗号化されたデータキー、メタデータ (暗号化コンテキストを含む) を含むポータブルオブジェクトです。暗号化されたメッセージを長期間安全に保管したり、Decrypt() メソッドに送信してプレーンテキストを復元することもできます。

var encryptedMessage = encryptOutput.Ciphertext;

AWS Encryption SDK の で厳密なモードで復号する。NET

ベストプラクティスでは、データを復号する際に使用するキーを指定することを推奨していますが、これは Strict モードと呼ばれるオプションです。 AWS Encryption SDK は、KMSキーリングで指定したキーのみを使用して暗号文を復号します。復号化キーリング内のキーには、データを暗号化したキーが少なくとも 1 つ含まれている必要があります。　

この例では、 AWS Encryption SDK の を使用して、厳密なモードで復号化する基本的なパターンを示していますNET。

ステップ 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 の の各キーリングメソッドにはNET、対応する入力オブジェクトがあります。この例では、CreateAwsKmsKeyring() メソッドを使用してキーリングを作成しているため、入力用の CreateAwsKmsKeyringInput クラスをインスタンス化しています。

復号キーリングでは、キーを使用してKMSキーARNを識別する必要があります。

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 プロパティは 暗号化されたメッセージ を表します。これには、 AWS Encryption SDK がメッセージの復号化に必要な暗号化されたデータ、暗号化されたデータキー、メタデータが含まれます。

for のバージョン 4.x では AWS Encryption SDK NET、オプションの 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 のバージョン 3.x AWS Encryption SDK の Decrypt()メソッド。NET は暗号化コンテキストを使用しません。暗号化されたメッセージのメタデータから暗号化コンテキストの値を取得します。ただし、プレーンテキストを返したり使用したりする前に、暗号文の復号に使用した暗号化コンテキストに、暗号化時に指定した暗号化コンテキストが含まれていることを確認することがベストプラクティスです。

暗号化に使用した暗号化コンテキストが、暗号文の復号に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名でアルゴリズムスイートを使用している場合、デジタル署名を含む暗号化コンテキストにペア 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 の で検出キーリングを使用して復号する。NET

復号化のKMSキーを指定するのではなく、キーを指定しないキーリングである検出KMSキーリング を提供 AWS KMS できます。検出キーリングを使用すると、発信者がキーに対する AWS Encryption SDK 復号アクセス許可を持っている場合、KMS暗号化されたキーを使用してデータを復号できます。ベストプラクティスとして、使用できるKMSキーを特定のパーティション AWS アカウント のキーに制限する検出フィルターを追加します。

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 の の各キーリングメソッドにはNET、対応する入力オブジェクトがあります。この例では、CreateAwsKmsDiscoveryKeyring() メソッドを使用してキーリングを作成しているため、入力用の CreateAwsKmsDiscoveryKeyringInput クラスをインスタンス化しています。

List<string> accounts = new List<string> { "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 のバージョン 4.x では AWS Encryption SDK NET、オプションの 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

AWS Encryption SDK 用の のバージョン 3.x のDecrypt()メソッド。NET は の暗号化コンテキストを取りません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");
}