AWS Encryption SDK の設定 - AWS Encryption SDK
プログラミング言語の選択ラッピングキーの選択マルチリージョン AWS KMS keys の使用アルゴリズムスイートを選択する暗号化されたデータキーの制限検出フィルターの作成コミットメントポリシーの設定ストリーミングデータの操作データキーのキャッシュ

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

AWS Encryption SDK の設定

AWS Encryption SDK は簡単に使用できるように設計されています。AWS Encryption SDK にはいくつかの設定オプションがありますが、ほとんどのアプリケーションで実用的で安全なデフォルト値が慎重に選択されています。ただし、パフォーマンスを改善するために構成を調整したり、設計にカスタム機能を追加したりしたい場合があります。

実装を設定するときは、AWS Encryption SDK のベストプラクティスを確認し、そのできるだけ多くを実装してください。

プログラミング言語の選択

AWS Encryption SDK は、複数のプログラミング言語で使用できます。言語の実装は、完全に相互運用可能で、同じ機能を提供するように設計されていますが、異なる方法で実装される可能性があります。通常は、アプリケーションと互換性のあるライブラリを使用します。ただし、特定の実装用にプログラミング言語を選択することもできます。例えば、キーリングを操作する場合は、AWS Encryption SDK for C または AWS Encryption SDK for JavaScript を選択できます。

ラッピングキーの選択

AWS Encryption SDK では、各メッセージを暗号化するために一意の対称データキーが生成されます。データキーキャッシュを使用していない場合は、データキーの設定、管理、使用は必要ありません。これは AWS Encryption SDK によって行われます。

ただし、各データキーを暗号化するには、1 つ以上のラッピングキーを選択する必要があります。AWS Encryption SDK では、さまざまなサイズの AES 対称キーと RSA 非対称キーがサポートされます。AWS Key Management Service (AWS KMS) 対称暗号化 AWS KMS keys もサポートされます。ラッピングキーの安全性と耐久性についてはお客様が責任を負うため、AWS KMS などのハードウェアセキュリティモジュールまたはキーインフラストラクチャサービスで暗号化キーを使用することをお勧めします。

暗号化と復号化のラッピングキーを指定するには、キーリング (C および JavaScript) またはマスターキープロバイダー (Java、Python、AWS Encryption CLI) を使用します。同じタイプまたは異なるタイプのラッピングキーを 1 つまたは複数指定できます。複数のラッピングキーを使用してデータキーをラップする場合、各ラッピングキーは同じデータキーのコピーを暗号化します。暗号化されたデータキー (ラッピングキーごとに 1 つ) は、AWS Encryption SDK が返す暗号化されたメッセージに、暗号化されたデータと共に保存されます。データを復号するには、AWS Encryption SDK では、まずラッピングキーの 1 つを使用して、暗号化されたデータキーを復号する必要があります。

キーリングまたはマスターキープロバイダーで AWS KMS key を指定するには、サポートされている AWS KMS キー識別子を使用します。AWS KMS キーのキー識別子の詳細については、AWS Key Management Service デベロッパーガイドの「キー識別子」を参照してください。

  • AWS Encryption SDK for Java、AWS Encryption SDK for JavaScript、AWS Encryption SDK for Python、または AWS 暗号化 CLI を使用して暗号化する場合は、任意の有効なキー識別子 (キー ID、キー ARN、エイリアス名、またはエイリアス ARN) を KMS キーに使用できます。AWS Encryption SDK for C で暗号化する場合は、キー ID またはキー ARN のみを使用できます。

    暗号化時に KMS キーのエイリアス名またはエイリアス ARN を指定する場合、AWS Encryption SDK は、そのエイリアスに現在関連付けられているキー ARN を保存します。エイリアスは保存されません。エイリアスの変更は、データキーの復号に使用される KMS キーには影響しません。

  • Strict モード (特定のラッピングキーを指定するモード) で復号する場合は、キー ARN を使用して AWS KMS keys を指定する必要があります。この要件は、AWS Encryption SDK のすべての言語の実装に適用されます。

    AWS KMS キーリングで暗号化すると、AWS Encryption SDK は AWS KMS key のキー ARN を、暗号化されたデータキーのメタデータに保存します。Strict モードで復号すると、AWS Encryption SDK は、同じキー ARN がキーリング (またはマスターキープロバイダー) に表示されることを確認してから、ラッピングキーを使用して暗号化されたデータキーを復号しようとします。別のキー識別子を使用すると、AWS Encryption SDK は識別子が同じキーを参照していても、AWS KMS key を認識または使用しません。

キーリング内のラッピングキーとして Raw AES キー または raw RSA キーペア を指定するには、名前空間と名前を指定する必要があります。マスターキープロバイダーでは、Provider ID が名前空間と同等であり、Key ID は名前に相当します。復号化する際には、暗号化時に使用したものとまったく同じ名前空間と名前を、各 raw ラッピングキーに使用する必要があります。別の名前空間または名前を使用すると、AWS Encryption SDK は、キーマテリアルが同じであっても、ラッピングキーを認識または使用しません。

マルチリージョン AWS KMS keys の使用

AWS Encryption SDK では、AWS Key Management Service (AWS KMS) マルチリージョンキーをラッピングキーとして使用できます。1 つの AWS リージョン でマルチリージョンキーを使用して暗号化する場合は、別の AWS リージョン で関連マルチリージョンキーを使用して復号できます。マルチリージョンキーは、AWS Encryption SDK のバージョン 2.3.x、および AWS Encryption CLI のバージョン 3.0.x からサポートされます。

AWS KMS のマルチリージョンキーはさまざまな AWS リージョン における一連の AWS KMS keys であり、キーマテリアルとキー ID は同じです。これらの関連キーは、さまざまなリージョンで同じキーであるかのように使用できます。マルチリージョンのキーでは、AWS KMS のクロスリージョン呼び出しを行わずにあるリージョンで暗号化し、別のリージョンで復号化する必要がある一般的な災害対策およびバックアップシナリオがサポートされます。マルチリージョンキーの詳細については、「AWS Key Management Service デベロッパーガイド」の「マルチリージョンキーを使用する」を参照してください。

マルチリージョンキーをサポートするため、AWS Encryption SDK には、AWS KMS マルチリージョン対応キーリングおよびマスターキープロバイダーが含まれています。各プログラミング言語の新しいマルチリージョン対応シンボルでは、単一リージョンキーとマルチリージョンキーの両方がサポートされます。

  • 単一リージョンキーの場合、マルチリージョン対応シンボルは、単一リージョン AWS KMS キーリングとマスターキープロバイダーのように動作します。データを暗号化した単一リージョンキーを使用してのみ、暗号化テキストの復号が試されます。

  • マルチリージョンキーの場合、マルチリージョン対応シンボルは、データを暗号化した同じマルチリージョンキーまたは関連するリージョン内の関連するマルチリージョン キーを使用して、暗号文の復号化を試みます。

複数の KMS キーを使用するマルチリージョン対応キーリングおよびマスターキープロバイダーでは、複数の単一リージョンキーとマルチリージョンキーを指定できます。ただし、関連するマルチリージョンキーのセットごとに 1 つのキーしか指定できません。同じキー ID で複数のキー識別子を指定すると、コンストラクタの呼び出しは失敗します。

標準のシングルリージョン AWS KMS キーリングとマスターキープロバイダーでは、マルチリージョンキーを使用することもできます。ただし、暗号化と復号には、同じリージョンで同じマルチリージョンキーを使用する必要があります。単一リージョンキーリングとマスターキープロバイダーは、データを暗号化したキーを使用してのみ、暗号化テキストを復号しようとします。

次の例は、マルチリージョンキーおよび新しいマルチリージョン対応キーリングとマスターキープロバイダーを使用して、データを暗号化および復号化する方法を示しています。次の例では、us-east-1 リージョンでデータを暗号化し、各リージョンで関連するマルチリージョンキーを使用して us-west-2 リージョンでデータを復号します。これらの例を実行する前に、マルチリージョンキー ARN の例を、自分の AWS アカウント で有効な値に置き換えてください。

C

マルチリージョンキーを使用して暗号化するには、Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() メソッドを使用してキーリングをインスタンス化します。マルチリージョンキーを指定してください。

この簡単な例には、暗号化コンテキストが含まれていません。C で暗号化コンテキストを使用する例については、「文字列の暗号化と復号」を参照してください。

詳しい例については、GitHub の AWS Encryption SDK for C リポジトリの「kms_multi_region_keys.cpp」を参照してください。

/* Encrypt with a multi-Region KMS key in us-east-1 */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";   

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_east_1);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Encrypt the data
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, ciphertext, ciphertext_buf_sz, &ciphertext_len, plaintext, plaintext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

米国東部 (バージニア北部) (us-east-1) リージョンのマルチリージョンキーを使用して暗号化するには、マルチリージョンキーのキー識別子と指定したリージョンの AWS KMS クライアントを使用して、CreateAwsKmsMrkKeyringInputオブジェクトをインスタンス化します。次に、CreateAwsKmsMrkKeyring() メソッドを使用してキーリングを作成します。

この CreateAwsKmsMrkKeyring() メソッドは、正確に 1 つのマルチリージョンキーを持つキーリングを作成します。マルチリージョンキーを含む複数のラッピングキーを使用して暗号化するには、CreateAwsKmsMrkMultiKeyring() メソッドを使用します。

完全な例については、「GitHub の .NET 用 AWS Encryption SDK リポジトリ」の「AwsKmsMrkKeyringExample.cs」を参照してください。

//Encrypt with a multi-Region KMS key in us-east-1 Region

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


// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
string mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Create the keyring
// You can specify the Region or get the Region from the key ARN
var createMrkEncryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USEast1),
    KmsKeyId = mrkUSEast1
};
var mrkEncryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkEncryptKeyringInput);

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

// Encrypt your plaintext data.
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = mrkEncryptKeyring,
    EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

この例では、us-east-1 リージョンにおいてマルチリージョンキーで hello.txt ファイルを暗号化します。この例ではリージョン要素を持つキー ARN を指定しているため、この例では、--wrapping-keys パラメータの region 属性を使用しません。

ラッピングキーのキー ID がリージョンを指定しない場合は、--wrapping-keys の region 属性を使用して --wrapping-keys key=$keyID region=us-east-1 などのリージョンを指定します。

# Encrypt with a multi-Region KMS key in us-east-1 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSEast1=arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$mrkUSEast1 \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --output .
Java

マルチリージョンキーで暗号化するには、AwsKmsMrkAwareMasterKeyProvider をインスタンス化し、マルチリージョンキーを指定します。

完全な例については、「GitHub の AWS Encryption SDK for Java リポジトリ」の「BasicMultiRegionKeyEncryptionExample.java」を参照してください。

//Encrypt with a multi-Region KMS key in us-east-1 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Multi-Region keys have a distinctive key ID that begins with 'mrk'
// Specify a multi-Region key in us-east-1
final String mrkUSEast1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate an AWS KMS master key provider in strict mode for multi-Region keys
// Configure it to encrypt with the multi-Region key in us-east-1
final AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .buildStrict(mrkUSEast1);

// Create an encryption context
final Map<String, String> encryptionContext = Collections.singletonMap("Purpose", "Test");

// Encrypt your plaintext data
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> encryptResult = crypto.encryptData(
    kmsMrkProvider,
    encryptionContext,
    sourcePlaintext);
byte[] ciphertext = encryptResult.getResult();
JavaScript Browser

マルチリージョンキーを使用して暗号化するには、buildAwsKmsMrkAwareStrictMultiKeyringBrowser() メソッドを使用してキーリングを作成し、マルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_simple.ts」を参照してください。

/* Encrypt with a multi-Region KMS key in us-east-1 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The AWS Encryption SDK for JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-east-1 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const encryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsEastKey,
    clientProvider,
  })


/* Set the encryption context */
const context = {
    purpose: 'test',
  }

/* Test data to encrypt */
const cleartext = new Uint8Array([1, 2, 3, 4, 5])

/* Encrypt the data */
const { result } = await encrypt(encryptKeyring, cleartext, {
    encryptionContext: context,
  })
JavaScript Node.js

マルチリージョンキーを使用して暗号化するには、buildAwsKmsMrkAwareStrictMultiKeyringNode() メソッドを使用してキーリングを作成し、マルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_simple.ts」を参照してください。

//Encrypt with a multi-Region KMS key in us-east-1 Region

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the AWS Encryption SDK client
const { encrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Test string to encrypt */
const cleartext = 'asdf'

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsEastKey =
    'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkEncryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsEastKey,
  })

/* Specify an encryption context */
const context = {
    purpose: 'test',
  }

/* Create an encryption keyring */
const { result } = await encrypt(mrkEncryptKeyring, cleartext, {
    encryptionContext: context,
  })
Python

AWS KMS マルチリージョンキーを使用して暗号化するには、MRKAwareStrictAwsKmsMasterKeyProvider() メソッドを使用してマルチリージョンキーを指定します。

詳しい例については、GitHubの AWS Encryption SDK for Python リポジトリの「mrk_aware_kms_provider.py」を参照してください。

* Encrypt with a multi-Region KMS key in us-east-1 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Specify a multi-Region key in us-east-1
mrk_us_east_1 = "arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_east_1]
)

# Set the encryption context
encryption_context = {
        "purpose": "test"
    }

# Encrypt your plaintext data
ciphertext, encrypt_header = client.encrypt(
        source=source_plaintext,
        encryption_context=encryption_context,
        key_provider=strict_mrk_key_provider
)

次に、暗号化テキストを us-west-2 リージョンに移動します。暗号化テキストを再暗号化する必要はありません。

us-west-2 リージョンにおいて Strict モードで暗号化テキストを復号するには、us-west-2 リージョンにおいて関連するマルチリージョンキーのキー ARN を使用して、マルチリージョン対応シンボルをインスタンス化します。別のリージョン (暗号化した us-east-1 を含む) で関連するマルチリージョンキーのキー ARN を指定した場合、マルチリージョン対応シンボルは、その AWS KMS key のクロスリージョン呼び出しを行います。

Strict モードで復号する場合、マルチリージョン対応シンボルにはキー ARN が必要です。関連するマルチリージョンキーの各セットからキー ARN を 1 つだけ受け付けます。

これらの例を実行する前に、マルチリージョンキー ARN の例を、自分の AWS アカウント で有効な値に置き換えてください。

C

マルチリージョンキーを使用して Strict モードで暗号化するには、Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() メソッドを使用してキーリングをインスタンス化します。ローカル (us-west-2) リージョンで、関連するマルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for C リポジトリの「kms_multi_region_keys.cpp」を参照してください。

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Initialize a multi-Region keyring */
const char *mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";    

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder().Build(mrk_us_west_2);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_ENCRYPT, mrk_keyring);

aws_cryptosdk_session_set_commitment_policy(session,
    COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

aws_cryptosdk_keyring_release(mrk_keyring);

/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

1 つのマルチリージョンキーを使用して Strict モードで復号するには、入力の組立や暗号化用のキーリングの作成に使用したものと同じコンストラクターとメソッドを使用します。関連するマルチリージョンキーのキー ARN と、米国西部 (オレゴン) (us-west-2) リージョンの AWS KMS クライアントを使用して、CreateAwsKmsMrkKeyringInput オブジェクトをインスタンス化します。次に、この CreateAwsKmsMrkKeyring() メソッドを使用して 1 つのマルチリージョン KMS キーでマルチリージョンキーリングを作成します。

完全な例については、「GitHub の .NET 用 AWS Encryption SDK リポジトリ」の「AwsKmsMrkKeyringExample.cs」を参照してください。

// Decrypt with a related multi-Region KMS key in us-west-2 Region

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

// Specify the key ARN of the multi-Region key in us-west-2
string mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Instantiate the keyring input
// You can specify the Region or get the Region from the key ARN
var createMrkDecryptKeyringInput = new CreateAwsKmsMrkKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    KmsKeyId = mrkUSWest2
};

// Create the multi-Region keyring        
var mrkDecryptKeyring = materialProviders.CreateAwsKmsMrkKeyring(createMrkDecryptKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDecryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

us-west-2 リージョンで関連するマルチリージョンキーを使用して復号するには、--wrapping-keys パラメータの key 属性を使用してキー ARN を指定します。

# Decrypt with a related multi-Region KMS key in us-west-2 Region

# To run this example, replace the fictitious key ARN with a valid value.
$ mrkUSWest2=arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$mrkUSWest2 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

Strict モードで復号するには、AwsKmsMrkAwareMasterKeyProvider をインスタンス化し、ローカル (us-west-2) リージョンで関連するマルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for Java リポジトリの「BasicMultiRegionKeyEncryptionExample.java」を参照してください。

// Decrypt with a related multi-Region KMS key in us-west-2 Region

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();

// Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field.
String mrkUSWest2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab";

// Use the multi-Region method to create the master key provider
// in strict mode
AwsKmsMrkAwareMasterKeyProvider kmsMrkProvider = AwsKmsMrkAwareMasterKeyProvider.builder()
    .buildStrict(mrkUSWest2);

// Decrypt your ciphertext
CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto.decryptData(
        kmsMrkProvider,
        ciphertext);
byte[] decrypted = decryptResult.getResult();
JavaScript Browser

Strict モードで復号するには、buildAwsKmsMrkAwareStrictMultiKeyringBrowser() メソッドを使用してキーリングを作成し、ローカル (us-west-2) リージョンで関連するマルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_simple.ts」を参照してください。

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import {
  buildAwsKmsMrkAwareStrictMultiKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate an AWS KMS client 
 * The AWS Encryption SDK for JavaScript gets the Region from the key ARN
 */
const clientProvider = (region: string) => new KMS({ region, credentials })


/* Specify a multi-Region key in us-west-2 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Instantiate the keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringBrowser({
    generatorKeyId: multiRegionUsWestKey,
    clientProvider,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDecryptKeyring, result)
JavaScript Node.js

Strict モードで復号するには、buildAwsKmsMrkAwareStrictMultiKeyringNode() メソッドを使用してキーリングを作成し、ローカル (us-west-2) リージョンで関連するマルチリージョンキーを指定します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_simple.ts」を参照してください。

/* Decrypt with a related multi-Region KMS key in us-west-2 Region */

import { buildClient } from '@aws-crypto/client-node'

/* Instantiate the client
const { decrypt } = buildClient(
  CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)

/* Multi-Region keys have a distinctive key ID that begins with 'mrk'
 * Specify a multi-Region key in us-east-1
 */
const multiRegionUsWestKey =
    'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'

/* Create an AWS KMS keyring */
const mrkDecryptKeyring = buildAwsKmsMrkAwareStrictMultiKeyringNode({
    generatorKeyId: multiRegionUsWestKey,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(decryptKeyring, result)
Python

Strict モードで復号化するには、MRKAwareStrictAwsKmsMasterKeyProvider() メソッドを使用して、マスターキープロバイダーを作成します。ローカル (us-west-2) リージョンで、関連するマルチリージョンキーを指定します。

詳しい例については、GitHubの AWS Encryption SDK for Python リポジトリの「mrk_aware_kms_provider.py」を参照してください。

# Decrypt with a related multi-Region KMS key in us-west-2 Region

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# Related multi-Region keys have the same key ID. Their key ARNs differs only in the Region field
mrk_us_west_2 = "arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"

# Use the multi-Region method to create the master key provider
# in strict mode
strict_mrk_key_provider = MRKAwareStrictAwsKmsMasterKeyProvider(
        key_ids=[mrk_us_west_2]
)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=strict_mrk_key_provider
)

AWS KMS マルチリージョンのキーを使用して、検出モードで復号化することもできます。検出モードで復号する場合は、AWS KMS keys を指定しません。(シングルリージョンの AWS KMS 検出キーリングについては、「AWS KMS 検出キーリングの使用」を参照してください。)

マルチリージョンキーで暗号化した場合、検出モードのマルチリージョン対応シンボルは、ローカルリージョン内の関連するマルチリージョンキーを使用して復号しようとします。何も存在しない場合、呼び出しは失敗します。検出モードの場合、AWS Encryption SDK では、暗号化に使用されるマルチリージョンキーのクロスリージョン呼び出しは試行されません。

注記

検出モードでマルチリージョン対応シンボルを使用してデータを暗号化すると、暗号化操作に失敗します。

次の例では、検出モードでマルチリージョン対応シンボルを使用して復号する方法を示します。AWS KMS key を指定しないため、AWS Encryption SDK はリージョンを別のソースから取得する必要があります。可能であれば、ローカルリージョンを明示的に指定します。そうでない場合、AWS Encryption SDK は、使用中のプログラミング言語の AWS SDK で設定されたリージョンからローカルリージョンを取得します。

これらの例を実行する前に、アカウント ID とマルチリージョンキー ARN の例を、自分の AWS アカウント で有効な値に置き換えてください。

C

マルチリージョンキーを使用して検出モードで復号するには、キーリングを構築する Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder() メソッドと検出フィルターを構築する Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder() メソッドを使用します。ローカルリージョンを指定するには、ClientConfiguration を定義して AWS KMS クライアントにそれを指定します。

詳しい例については、GitHub の AWS Encryption SDK for C リポジトリの「kms_multi_region_keys.cpp」を参照してください。

/* Decrypt in discovery mode with a multi-Region KMS key */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct a discovery filter for the account and partition. The
 *  filter is optional, but it's a best practice that we recommend.
 */
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();

/* Create an AWS KMS client in the desired region. */
const char *region = "us-west-2";

Aws::Client::ClientConfiguration client_config;
client_config.region = region;
const std::shared_ptr<Aws::KMS::KMSClient> kms_client =
    Aws::MakeShared<Aws::KMS::KMSClient>("AWS_SAMPLE_CODE", client_config);

struct aws_cryptosdk_keyring *mrk_keyring = 
    Aws::Cryptosdk::KmsMrkAwareSymmetricKeyring::Builder()
        .WithKmsClient(kms_client)
        .BuildDiscovery(region, discovery_filter);

/* Create a session; release the keyring */
struct aws_cryptosdk_session *session =
    aws_cryptosdk_session_new_from_keyring_2(aws_default_allocator(), AWS_CRYPTOSDK_DECRYPT, mrk_keyring);

aws_cryptosdk_keyring_release(mrk_keyring);
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
/* Decrypt the ciphertext 
 *   aws_cryptosdk_session_process_full is designed for non-streaming data
 */
aws_cryptosdk_session_process_full(
    session, plaintext, plaintext_buf_sz, &plaintext_len, ciphertext, ciphertext_len));

/* Clean up the session */
aws_cryptosdk_session_destroy(session);
C# / .NET

「.NET 用 AWS Encryption SDK」でマルチリージョン対応の検出キーリングを作成するには、特定の AWS リージョン の AWS KMS クライアントを取る CreateAwsKmsMrkDiscoveryKeyringInput オブジェクトと、KMS キーを特定の AWS パーティションとアカウントに制限するオプションの検出フィルターをインスタンス化します。次に、入力オブジェクトを使用して CreateAwsKmsMrkDiscoveryKeyring() メソッドを呼び出します。完全な例については、「GitHub の .NET 用 AWS Encryption SDK リポジトリ」の「AwsKmsMrkDiscoveryKeyringExample.cs」を参照してください。

マルチリージョン対応ディスカバリーキーリングを複数 AWS リージョン で作成するには、CreateAwsKmsMrkDiscoveryMultiKeyring() メソッドを使用してマルチキーリングを作成するか、CreateAwsKmsMrkDiscoveryKeyring() を使用して複数のマルチリージョン対応の検出キーリングを作成し、その CreateMultiKeyring() メソッドを使用してそれらをマルチキーリングに結合します。

例については、「AwsKmsMrkDiscoveryMultiKeyringExample.cs」を参照してください。

// Decrypt in discovery mode with a multi-Region KMS key

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

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

// Instantiate the discovery filter
DiscoveryFilter mrkDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}

// Create the keyring
var createMrkDiscoveryKeyringInput = new CreateAwsKmsMrkDiscoveryKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(RegionEndpoint.USWest2),
    DiscoveryFilter = mrkDiscoveryFilter
};
var mrkDiscoveryKeyring = materialProviders.CreateAwsKmsMrkDiscoveryKeyring(createMrkDiscoveryKeyringInput);


// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = mrkDiscoveryKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI

検出モードで復号するには、--wrapping-keys パラメータの discovery 属性を使用します。discovery-account 属性と discovery-partition 属性により、検出フィルタが作成されます。この検出フィルタはオプションですが、推奨されています。

リージョンを指定するには、このコマンドに --wrapping-keys パラメータの region 属性を含めます。

# Decrypt in discovery mode with a multi-Region KMS key

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                                     region=us-west-2 \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

ローカルリージョンを指定するには、builder().withDiscoveryMrkRegion パラメータを使用します。そうでない場合、AWS Encryption SDK は、AWS SDK for Java で設定されたリージョンからローカルリージョンを取得します。

詳しい例については、「GitHub の AWS Encryption SDK for Java リポジトリ」の「DiscoveryMultiRegionDecryptionExample.java」を参照してください。

// Decrypt in discovery mode with a multi-Region KMS key

// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .build();
                
DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);

AwsKmsMrkAwareMasterKeyProvider mrkDiscoveryProvider = AwsKmsMrkAwareMasterKeyProvider
    .builder()
    .withDiscoveryMrkRegion(Region.US_WEST_2)
    .buildDiscovery(discoveryFilter);

// Decrypt your ciphertext
final CryptoResult<byte[], AwsKmsMrkAwareMasterKey> decryptResult = crypto
    .decryptData(mrkDiscoveryProvider, ciphertext);
JavaScript Browser

対称マルチリージョンキーを使用して検出モードで復号するには、AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser() メソッドを使用します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_discovery.ts」を参照してください。

/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-browser'


/* Instantiate an AWS Encryption SDK client */
const { decrypt } = buildClient()

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2', credentials })


/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }


/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringBrowser({
    client,
    discoveryFilter,
  })


/* Decrypt the data */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, ciphertext)
JavaScript Node.js

対称マルチリージョンキーを使用して検出モードで復号するには、AwsKmsMrkAwareSymmetricDiscoveryKeyringNode() メソッドを使用します。

詳しい例については、GitHub の AWS Encryption SDK for JavaScript リポジトリの「kms_multi_region_discovery.ts」を参照してください。

/* Decrypt in discovery mode with a multi-Region KMS key */

import {
  AwsKmsMrkAwareSymmetricDiscoveryKeyringNode,
  buildClient,
  CommitmentPolicy,
  KMS,
} from '@aws-crypto/client-node'

/* Instantiate the Encryption SDK client
const { decrypt } = buildClient()

/* Instantiate the KMS client with an explicit Region */
const client = new KMS({ region: 'us-west-2' })

/* Create a discovery filter */
const discoveryFilter = { partition: 'aws', accountIDs: ['111122223333'] }

/* Create an AWS KMS discovery keyring */
const mrkDiscoveryKeyring = new AwsKmsMrkAwareSymmetricDiscoveryKeyringNode({
    client,
    discoveryFilter,
  })

/* Decrypt your ciphertext */
const { plaintext, messageHeader } = await decrypt(mrkDiscoveryKeyring, result)
Python

マルチリージョンキーを使用して検出モードで復号するには、MRKAwareDiscoveryAwsKmsMasterKeyProvider() メソッドを使用します。

詳しい例については、GitHubの AWS Encryption SDK for Python リポジトリの「mrk_aware_kms_provider.py」を参照してください。

# Decrypt in discovery mode with a multi-Region KMS key

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient()

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

# Use the multi-Region method to create the master key provider
# in discovery mode
mrk_discovery_key_provider = MRKAwareDiscoveryAwsKmsMasterKeyProvider(**decrypt_kwargs)

# Decrypt your ciphertext
plaintext, _ = client.decrypt(
        source=ciphertext, 
        key_provider=mrk_discovery_key_provider
)

アルゴリズムスイートを選択する

AWS Encryption SDK では、複数の対称および非対称暗号化アルゴリズムが、指定したラッピングキーでデータキーを暗号化するためにサポートされます。ただし、これらのデータキーを使用してデータを暗号化する場合、AWS Encryption SDK では、キー取得、デジタル署名、キーコミットメントを含む AES-GCM アルゴリズムを使用する推奨アルゴリズムスイートがデフォルトになります。デフォルトのアルゴリズムスイートはほとんどのアプリケーションに適している可能性がありますが、代替アルゴリズムスイートを選択できます。例えば、一部の信頼モデルは、デジタル署名を含まないアルゴリズムスイートによって満たされます。AWS Encryption SDK でサポートされるアルゴリズムスイートについては、「AWS Encryption SDK でサポートされているアルゴリズムスイート」を参照してください。

以下の例では、暗号化時に代替アルゴリズムスイートを選択する方法を示します。これらの例では、キー取得とキーコミットメントを含むがデジタル署名を含まない推奨 AES-GCM アルゴリズムスイートを選択します。デジタル署名を含まないアルゴリズムスイートで暗号化する場合は、復号時に署名なし専用の復号化モードを使用します。このモードは、署名付き暗号化テキストを検出すると失敗し、ストリーミング復号化時に最も役立ちます。

C

代替アルゴリズムスイートを AWS Encryption SDK for C で指定するには、CMM を明示的に作成する必要があります。次に、CMM および選択したアルゴリズムスイートで aws_cryptosdk_default_cmm_set_alg_id を使用します。

/* Specify an algorithm suite without signing */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);

/* To set an alternate algorithm suite, create an cryptographic 
   materials manager (CMM) explicitly
 */
struct aws_cryptosdk_cmm *cmm = aws_cryptosdk_default_cmm_new(aws_default_allocator(), kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 

/* Specify the algorithm suite for the CMM */
aws_cryptosdk_default_cmm_set_alg_id(cmm, ALG_AES256_GCM_HKDF_SHA512_COMMIT_KEY);
    
/* Construct the session with the CMM, 
   then release the CMM reference 
 */
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(alloc, AWS_CRYPTOSDK_ENCRYPT, cmm);
aws_cryptosdk_cmm_release(cmm);

/* Encrypt the data 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session, 
                          ciphertext, 
                          ciphertext_buf_sz, 
                          &ciphertext_len, 
                          plaintext, 
                          plaintext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}

デジタル署名なしで暗号化されたデータを復号化する場合は、AWS_CRYPTOSDK_DECRYPT_UNSIGNED を使用します。署名付き暗号化テキストが検出されると、復号は失敗します。

/* Decrypt unsigned streaming data */

/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
    
/* Create a session for decrypting with the AWS KMS keyring
   Then release the keyring reference
 */
struct aws_cryptosdk_session *session =
        aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT_UNSIGNED, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring); 
   
if (!session) {
    return AWS_OP_ERR;
}
    
/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 1);
  
/* Decrypt 
   Use aws_cryptosdk_session_process_full with non-streaming data
 */
    if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(
                          session,                          
                          plaintext,
                          plaintext_buf_sz,
                          &plaintext_len,
                          ciphertext,
                          ciphertext_len)) {
    aws_cryptosdk_session_destroy(session);
    return AWS_OP_ERR;
}
C# / .NET

「.NET 用 AWS Encryption SDK」で代替アルゴリズムスイートを指定するには、EncryptInput オブジェクトの AlgorithmSuiteId プロパティを指定します。.NET 用 AWS Encryption SDK には、好みのアルゴリズムスイートを識別するために使用できる 定数 が含まれています。

このライブラリはストリーミングデータをサポートしていないため、.NET 用 AWS Encryption SDK にはストリーミング復号化時に署名付き暗号文を検出するメソッドがありません。

// Specify an algorithm suite without signing

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

// Create the keyring
var keyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(keyringInput);

// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
    Plaintext = plaintext,
    Keyring = keyring,
    AlgorithmSuiteId = AlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
AWS Encryption CLI

hello.txt ファイルを暗号化するときには、--algorithm パラメータを使用して、デジタル署名のないアルゴリズムスイートを指定します。

# Specify an algorithm suite without signing

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --encrypt \
                     --input hello.txt \
                     --wrapping-keys key=$keyArn \
                     --algorithm AES_256_GCM_HKDF_SHA512_COMMIT_KEY \
                     --metadata-output ~/metadata \
                     --encryption-context purpose=test \
                     --commitment-policy require-encrypt-require-decrypt \
                     --output hello.txt.encrypted \
                     --decode

復号するとき、この例では --decrypt-unsigned パラメータを使用します。特に入力と出力を常にストリーミングする CLI で署名なし暗号化テキストを復号化するためには、このパラメータが推奨されます。

# Decrypt unsigned streaming data

# To run this example, replace the fictitious key ARN with a valid value.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab

$ aws-encryption-cli --decrypt-unsigned \
                     --input hello.txt.encrypted \
                     --wrapping-keys key=$keyArn \
                     --max-encrypted-data-keys 1 \
                     --commitment-policy require-encrypt-require-decrypt \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --output .
Java

代替アルゴリズムスイートを指定するには、AwsCrypto.builder().withEncryptionAlgorithm() メソッドを使用します。この例では、デジタル署名のない代替アルゴリズムスイートを指定します。

// Specify an algorithm suite without signing

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
    .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
    .withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
    .build();

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

// Create a master key provider in strict mode
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
    .buildStrict(awsKmsKey);
    
// Create an encryption context to identify this ciphertext
        Map<String, String> encryptionContext = Collections.singletonMap("Example", "FileStreaming");

// Encrypt your plaintext data
CryptoResult<byte[], KmsMasterKey> encryptResult = crypto.encryptData(
    masterKeyProvider,
    sourcePlaintext,
    encryptionContext);
byte[] ciphertext = encryptResult.getResult();

復号化のためにデータをストリーミングする場合は、createUnsignedMessageDecryptingStream() メソッドを使用し、復号しているすべての暗号化テキストが署名なしであることを保証します。

// Decrypt unsigned streaming data

// Instantiate the client
AwsCrypto crypto = AwsCrypto.builder()
  .withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
  .withMaxEncryptedDataKeys(1)
  .build();

// Create a master key provider in strict mode
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
  .buildStrict(awsKmsKey);

// Decrypt the encrypted message
FileInputStream in = new FileInputStream(srcFile + ".encrypted");  
CryptoInputStream<KmsMasterKey> decryptingStream = crypto.createUnsignedMessageDecryptingStream(masterKeyProvider, in);
  
// Return the plaintext data
// Write the plaintext data to disk
FileOutputStream out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
JavaScript Browser

代替アルゴリズムスイートを指定するには、AlgorithmSuiteIdentifier 列挙値を含む suiteId パラメータを使用します。

// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key 
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

復号化するときは、標準の decrypt メソッドを使用します。ブラウザの AWS Encryption SDK for JavaScript には decrypt-unsigned モードがありません。ブラウザでストリーミングがサポートされないためです。

// Decrypt unsigned streaming data

// Instantiate the client 
const { decrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringBrowser({ generatorKeyId })

// Decrypt the encrypted message 
const { plaintext, messageHeader } = await decrypt(keyring, ciphertextMessage)
JavaScript Node.js

代替アルゴリズムスイートを指定するには、AlgorithmSuiteIdentifier 列挙値を含む suiteId パラメータを使用します。

// Specify an algorithm suite without signing

// Instantiate the client 
const { encrypt } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Specify a KMS key
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";

// Create a keyring with the KMS key
const keyring = new KmsKeyringNode({ generatorKeyId })

// Encrypt your plaintext data 
const { result } = await encrypt(keyring, cleartext, { suiteId: AlgorithmSuiteIdentifier.ALG_AES256_GCM_IV12_TAG16_HKDF_SHA512_COMMIT_KEY, encryptionContext: context, })

デジタル署名なしで暗号化されたデータを復号化する場合は、decryptUnsignedMessageStream を使用します。このメソッドは、署名付き暗号化テキストを検出すると失敗します。

// Decrypt unsigned streaming data

// Instantiate the client 
const { decryptUnsignedMessageStream } = buildClient( CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT )

// Create a keyring with the same KMS key used to encrypt
const generatorKeyId = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"; 
const keyring = new KmsKeyringNode({ generatorKeyId })

// Decrypt the encrypted message 
const outputStream = createReadStream(filename) .pipe(decryptUnsignedMessageStream(keyring))
Python

代替暗号化アルゴリズムを指定するには、Algorithm 列挙値を含む algorithm パラメータを使用します。

# Specify an algorithm suite without signing

# Instantiate a client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Encrypt the plaintext using an alternate algorithm suite
ciphertext, encrypted_message_header = client.encrypt(
    algorithm=Algorithm.AES_256_GCM_HKDF_SHA512_COMMIT_KEY, source=source_plaintext, key_provider=kms_key_provider
)

デジタル署名なしで暗号化されたメッセージを復号化する場合、特にストリーミングしながら復号化する場合は、decrypt-unsigned ストリーミングモードを使用します。

# Decrypt unsigned streaming data

# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
                                                max_encrypted_data_keys=1)

# Create a master key provider in strict mode
aws_kms_key = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
aws_kms_strict_master_key_provider = StrictAwsKmsMasterKeyProvider(
        key_ids=[aws_kms_key]
)

# Decrypt with decrypt-unsigned
with open(ciphertext_filename, "rb") as ciphertext, open(cycled_plaintext_filename, "wb") as plaintext:
    with client.stream(mode="decrypt-unsigned", 
                       source=ciphertext, 
                       key_provider=master_key_provider) as decryptor:
        for chunk in decryptor:
            plaintext.write(chunk)

# Verify that the encryption context
assert all(
   pair in decryptor.header.encryption_context.items() for pair in encryptor.header.encryption_context.items()
)
return ciphertext_filename, cycled_plaintext_filename

暗号化されたデータキーの制限

暗号化されたメッセージ内の暗号化されたデータキーの数を制限できます。このベストプラクティス機能は、暗号化時に誤って構成されたキーリングを検出したり、復号時に悪意のある暗号化テキストを検出したりするのに役立ちます。不必要でコストがかかり、潜在的に網羅的な方法によって、キーインフラストラクチャを呼び出すことも防止できます。信頼できない送信元からのメッセージを復号する場合は、暗号化されたデータキーを制限することが最も重要です。

ほとんどの暗号化されたメッセージには、暗号化で使用されるラッピングキーごとに 1 つの暗号化されたデータキーがありますが、暗号化されたメッセージには最大 65,535 個の暗号化されたデータキーを含めることができます。悪意のあるアクターは、何千もの暗号化されたデータキーを使用して暗号化されたメッセージを構築し、いずれも復号できなくする可能性があります。その結果、AWS Encryption SDK は、メッセージ内の暗号化されたデータキーを使い果たすまで、暗号化された各データキーを復号しようとします。

暗号化されたデータキーを制限するには、MaxEncryptedDataKeys パラメータを使用します。このパラメータは、AWS Encryption SDK のバージョン 1.9.x および 2.2.x 以降のすべてのサポート対象プログラミング言語で使用できます。これはオプションで、暗号化時および復号時に有効です。次の例では、3 つの異なるラッピングキーで暗号化されたデータを復号化します。MaxEncryptedDataKeys の値は 3 に設定します。

C
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();

/* Construct an AWS KMS keyring */
struct aws_cryptosdk_keyring *kms_keyring = 
      Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn1, { key_arn2, key_arn3 });

/* Create a session */
struct aws_cryptosdk_session *session = 
    aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);

/* Limit encrypted data keys */
aws_cryptosdk_session_set_max_encrypted_data_keys(session, 3);
  
/* Decrypt */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(session,
    plaintext_output,
    plaintext_buf_sz_output,
    &plaintext_len_output,
    ciphertext_input,
    ciphertext_len_input,
    &ciphertext_consumed_output);
assert(aws_cryptosdk_session_is_done(session));
assert(ciphertext_consumed == ciphertext_len);
C# / .NET

「.NET 用 AWS Encryption SDK」の暗号化データキーを制限するには、「.NET 用 AWS Encryption SDK」のクライアントをインスタンス化し、 オプション MaxEncryptedDataKeys パラメータを希望の値に設定します。次に、設定した AWS Encryption SDK インスタンスで Decrypt() メソッドを呼び出します。

// Decrypt with limited data keys

// Instantiate the material providers
var materialProviders =
    AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();

// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
    MaxEncryptedDataKeys = 3
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);

// Create the keyring
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var createKeyringInput = new CreateAwsKmsKeyringInput
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsKeyId = keyArn
};
var decryptKeyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);

// Decrypt the ciphertext
var decryptInput = new DecryptInput
{
    Ciphertext = ciphertext,
    Keyring = decryptKeyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
AWS Encryption CLI
# Decrypt with limited encrypted data keys

$ aws-encryption-cli --decrypt \
    --input hello.txt.encrypted \
    --wrapping-keys key=$key_arn1 key=$key_arn2 key=$key_arn3 \
    --buffer \
    --max-encrypted-data-keys 3 \
    --encryption-context purpose=test \
    --metadata-output ~/metadata \
    --output .
Java
// Construct a client with limited encrypted data keys
final AwsCrypto crypto = AwsCrypto.builder()
  .withMaxEncryptedDataKeys(3)
  .build();

// Create an AWS KMS master key provider
final KmsMasterKeyProvider keyProvider = KmsMasterKeyProvider.builder()
      .buildStrict(keyArn1, keyArn2, keyArn3);
   
// Decrypt
final CryptoResult<byte[], KmsMasterKey> decryptResult = crypto.decryptData(keyProvider, ciphertext)
JavaScript Browser
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

declare const credentials: {
  accessKeyId: string
  secretAccessKey: string
  sessionToken: string
}
const clientProvider = getClient(KMS, {
  credentials: { accessKeyId, secretAccessKey, sessionToken }
})

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  clientProvider,
  keyIds: [keyArn1, keyArn2, keyArn3],
})

// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
JavaScript Node.js
// Construct a client with limited encrypted data keys
const { encrypt, decrypt } = buildClient({ maxEncryptedDataKeys: 3 })

// Create an AWS KMS keyring
const keyring = new KmsKeyringBrowser({
  keyIds: [keyArn1, keyArn2, keyArn3],
})
  
// Decrypt
const { plaintext, messageHeader } = await decrypt(keyring, ciphertext)
Python
# Instantiate a client with limited encrypted data keys
client = aws_encryption_sdk.EncryptionSDKClient(max_encrypted_data_keys=3)

# Create an AWS KMS master key provider
master_key_provider = aws_encryption_sdk.StrictAwsKmsMasterKeyProvider(
    key_ids=[key_arn1, key_arn2, key_arn3])

# Decrypt
plaintext, header = client.decrypt(source=ciphertext, key_provider=master_key_provider)

検出フィルターの作成

KMS キーで暗号化されたデータを復号化する場合、Strict モード で復号化する、つまり、使用するラッピングキーを指定したキーのみに制限するのがベストプラクティスです。ただし、必要に応じて、ラッピングキーを一切指定しない検出モードで復号化することもできます。このモードでは、AWS KMS は、その KMS キーの所有者またはアクセス権を持つユーザーに関係なく、暗号化した KMS キーを使用して、暗号化されたデータキーを復号化できます。

検出モードで復号化する必要がある場合は、使用できる KMS キーを指定した AWS アカウント および パーティション 内のものに制限する検出フィルターを常に使用することをお勧めします。検出フィルターはオプションですが、ベストプラクティスです。

次の表を使用して、検出フィルターのパーティション値を決定します。　

リージョン パーティション
AWS リージョン aws
中国リージョン aws-cn
AWS GovCloud (US) Regions aws-us-gov

このセクションの例では、検出フィルターの作成方法を示します。コードを使用する前に、サンプル値を AWS アカウント およびパーティションの有効な値に置き換えます。

C

詳しい例については、「AWS Encryption SDK for C」の「kms_discovery.cpp」を参照してください。

/* Create a discovery filter for an AWS account and partition */
    
const char *account_id = "111122223333";
const char *partition = "aws";
const std::shared_ptr<Aws::Cryptosdk::KmsKeyring::DiscoveryFilter> discovery_filter =
    Aws::Cryptosdk::KmsKeyring::DiscoveryFilter::Builder(partition).AddAccount(account_id).Build();
C# / .NET

詳細な例については、「.NET 用 AWS Encryption SDK」の「DiscoveryFilterExample.cs」を参照してください。

// Create a discovery filter for an AWS account and partition

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

DiscoveryFilter exampleDiscoveryFilter = new DiscoveryFilter()
{
    AccountIds = account,
    Partition = "aws"
}
AWS Encryption CLI
# Decrypt in discovery mode with a discovery filter

$ aws-encryption-cli --decrypt \
                     --input hello.txt.encrypted \
                     --wrapping-keys discovery=true \ 
                                     discovery-account=111122223333 \
                                     discovery-partition=aws \
                     --encryption-context purpose=test \
                     --metadata-output ~/metadata \
                     --max-encrypted-data-keys 1 \
                     --buffer \
                     --output .
Java

詳しい例については、「AWS Encryption SDK for Java」の「DiscoveryDecryptionExample.java」を参照してください。

// Create a discovery filter for an AWS account and partition

DiscoveryFilter discoveryFilter = new DiscoveryFilter("aws", 111122223333);
JavaScript (Node and Browser)

詳細な例については、「AWS Encryption SDK for JavaScript」の「kms_filtered_discovery.ts」(Node.js) と「kms_multi_region_discovery.ts」(ブラウザ) を参照してください。

/* Create a discovery filter for an AWS account and partition */
const discoveryFilter = { 
  accountIDs: ['111122223333'], 
  partition: 'aws',
}
Python

詳しい例については、「AWS Encryption SDK for Python」の「discovery_kms_provider.py」を参照してください。

# Create the discovery filter and specify the region
decrypt_kwargs = dict(
        discovery_filter=DiscoveryFilter(account_ids="111122223333", partition="aws"),
        discovery_region="us-west-2",
    )

コミットメントポリシーの設定

コミットメントポリシーは、アプリケーションがキーコミットメントで暗号化および復号化を行うかどうかを決定する構成設定です。キーコミットメントによる暗号化と復号化は、AWS Encryption SDK のベストプラクティスです。

コミットメントポリシーの設定と調整は、AWS Encryption SDK のバージョン 1.7.x 以前からバージョン 2.0.x 以降に 移行 する上で重要なステップです。この進行状況については、「移行のトピック」で詳しく説明されています。

AWS Encryption SDK の最新バージョン (バージョン 2.0.x 以降)、RequireEncryptRequireDecrypt におけるデフォルトのコミットメントポリシー値は、ほとんどの状況に最適です。ただし、キーコミットなしで暗号化された暗号文を復号する必要がある場合は、コミットメントポリシーを RequireEncryptAllowDecrypt に変更する必要がある場合があります。各プログラミング言語でコミットメントポリシーを設定する方法の例については、「コミットメントポリシーの設定」を参照してください。

ストリーミングデータの操作

復号化のためにデータをストリーミングするとき、AWS Encryption SDK は、整合性チェックが完了した後、デジタル署名を検証する前に復号化されたプレーンテキストを返します。署名が検証されるまでプレーンテキストを返したり使用したりしないようにするには、復号化プロセス全体が完了するまで、ストリーミングされたプレーンテキストをバッファリングすることをお勧めします。

この問題が発生するのは、復号化のために暗号化テキストをストリーミングしているときに、デフォルトのアルゴリズムスイートなど、デジタル署名を含むアルゴリズムスイートを使用している場合のみです。

バッファリングを容易にするために、Node.js の AWS Encryption SDK for JavaScript など、一部の AWS Encryption SDK 言語実装には、復号メソッドの一部としてバッファリング機能が含まれています。入力と出力を常にストリーミングする AWS Encryption CLI では、バージョン 1.9.x と 2.2.x で --buffer パラメータが導入されました。他の言語実装では、既存のバッファリング機能を使用できます。(.NET 用 AWS Encryption SDK はストリーミングをサポートしません。)

デジタル署名のないアルゴリズムスイートを使用している場合は、必ず各言語実装で decrypt-unsigned 機能を使用してください。この機能では暗号化テキストが復号されますが、署名付き暗号化テキストを検出すると失敗します。詳細については、「アルゴリズムスイートを選択する」を参照してください。

データキーのキャッシュ

一般に、データキーの再利用は推奨されませんが、AWS Encryption SDK にはデータキーキャッシュオプションがあり、データキーが制限付きで再利用できるようになります。データキーキャッシュでは、一部のアプリケーションのパフォーマンスが向上し、キーインフラストラクチャの呼び出しが減ります。本番環境でデータキーキャッシュを使用する前に、セキュリティしきい値を調整してテストし、データキーを再利用することのメリットがデメリットを上回っていることを確認してください。