.NET 用 AWS Encryption SDK の例

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

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

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

「.NET 用 AWS Encryption SDK」でのデータの暗号化

この例では、データを暗号化するための基本的なパターンを示しています。　 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 の両方で同じです。

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 クライアントを作成するには、「AWS SDK for .NET」で AmazonKeyManagementServiceClient クラスをインスタンス化します。パラメータなしで AmazonKeyManagementServiceClient() コンストラクタを呼び出すと、デフォルト値でクライアントが作成されます。

.NET 用 AWS Encryption SDK での暗号化に使用される AWS KMS キーリングでは、キー ID、キー ARN、エイリアス名、またはエイリアス ARN を使用して KMS キーを識別できます。復号化に使用する 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: 暗号化コンテキストを定義します。　

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

注記

.NET 用 AWS Encryption SDK のバージョン 4.x の場合、必要な暗号化コンテキスト 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: プレーンテキストを暗号化します。

AWS Encryption SDK の Encrypt() メソッドを使用して、定義したキーリングを使用してプレーンテキストを暗号化します。

この Encrypt() メソッドが返す EncryptOutput には、暗号化されたメッセージ (Ciphertext)、暗号化コンテキスト、アルゴリズムスイートを取得するメソッドがあります。

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

ステップ 7: 暗号化されたメッセージを取得します。

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

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

var encryptedMessage = encryptOutput.Ciphertext;

「.NET 用 AWS Encryption SDK」では、Strict モードで復号化

ベストプラクティスでは、データを復号する際に使用するキーを指定することを推奨していますが、これは 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: キーリング用の入力オブジェクトを作成します。　

キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。　 「.NET 用 AWS Encryption SDK」の各キーリングメソッドには、対応する入力オブジェクトがあります。　 この例では、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 プロパティは 暗号化されたメッセージ を表します。これには、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

.NET 用 AWS Encryption SDK のバージョン 3.x の 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");
}

「.NET 用 AWS Encryption SDK」でディスカバリーキーリングによる復号化

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

.NET 用 AWS Encryption SDK には、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: キーリング用の入力オブジェクトを作成します。

キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。　 「.NET 用 AWS Encryption SDK」の各キーリングメソッドには、対応する入力オブジェクトがあります。　 この例では、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 メンバーです。

.NET 用 AWS Encryption SDK のバージョン 4.x では、オプションの 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

.NET 用 AWS Encryption SDK のバージョン 3.x の 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");
}