AWS Encryption SDK for .NET の例

まず、 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 の両方で同じです。

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

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

この入力オブジェクトには、KMS キー AWS リージョン の 用の AWS KMS クライアントが必要です。 AWS KMS クライアントを作成するには、 で AmazonKeyManagementServiceClient クラスをインスタンス化します SDK for .NET。パラメータなしで 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
};

キーリングを作成するには、キーリング入力オブジェクトを使用してキーリングメソッドを呼び出します。この例では、KMS キーを 1 つだけ取得する、この CreateAwsKmsKeyring() メソッドを使用しています。

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

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

// Define the encryption context
var encryptionContext = new Dictionary<string, string>()
{
    {"purpose", "test"}
};

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

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

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

var encryptOutput = encryptionSdk.Encrypt(encryptInput);

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

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

var encryptedMessage = encryptOutput.Ciphertext;

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

キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。　 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
};

復号化キーリングを作成するために、この例では CreateAwsKmsKeyring() メソッドとキーリング入力オブジェクトを使用します。

var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);

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

var decryptOutput = encryptionSdk.Decrypt(decryptInput);

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

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

キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。　 AWS Encryption SDK for .NET の各キーリングメソッドには、対応する入力オブジェクトがあります。この例では、CreateAwsKmsDiscoveryKeyring() メソッドを使用してキーリングを作成しているため、入力用の CreateAwsKmsDiscoveryKeyringInput クラスをインスタンス化しています。

List<string> accounts = new List<string> { "111122223333" };

var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    DiscoveryFilter = new DiscoveryFilter()
    {
        AccountIds = accounts,
        Partition = "aws"
    }
};

復号化キーリングを作成するために、この例では CreateAwsKmsDiscoveryKeyring() メソッドとキーリング入力オブジェクトを使用します。

var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);

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

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