翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# の移行 AWS Encryption SDK
は、相互運用可能な複数の[プログラミング言語の実装](programming-languages.md) AWS Encryption SDK をサポートしています。各実装は、GitHub のオープンソースリポジトリで開発されています。[ベストプラクティス](best-practices.md)として、言語ごとに最新バージョンの AWS Encryption SDK を使用することをお勧めします。
のバージョン 2.0.*x* 以降から最新バージョン AWS Encryption SDK に安全にアップグレードできます。ただし、 の 2.0.*x* バージョンでは、重要な新しいセキュリティ機能 AWS Encryption SDK が導入されていますが、その一部は大幅な変更が加えられています。1.7.x より前のバージョンからバージョン 2.0.x 以降へアップグレードするには、まず最新の 1.x バージョンにアップグレードする必要があります。このセクションのトピックは、変更を理解し、アプリケーションの正しいバージョンを選択し、 AWS Encryption SDKの最新バージョンに安全かつ正常に移行できるように設計されています。
の重要なバージョンについては AWS Encryption SDK、「」を参照してください[のバージョン AWS Encryption SDK](about-versions.md)。
**重要**
1.7.x より前のバージョンからバージョン 2.0.x 以降に直接アップグレードする場合は、最初に最新の 1.x バージョンをアップグレードしてから行ってください。バージョン 2.0.*x* 以降に直接アップグレードし、すべての新機能をすぐに有効にすると、 AWS Encryption SDK は古いバージョンの で暗号化された暗号文を復号できなくなります AWS Encryption SDK。
**注記**
for .NET AWS Encryption SDK の最も古いバージョンはバージョン 3.0.*x* です。 AWS Encryption SDK for .NET のすべてのバージョンは、 の 2.0.*x* で導入されたセキュリティのベストプラクティスをサポートしています AWS Encryption SDK。コードやデータを変更することなく、最新バージョンに安全にアップグレードできます。
AWS Encryption CLI: この移行ガイドを読むときは、Encryption CLI 1.8.*x* AWS の 1.7.*x* 移行手順と Encryption CLI 2.1.*x* の AWS 2.0.*x* 移行手順を使用します。詳細については、「[Encryption AWS CLI のバージョン](crypto-cli-versions.md)」を参照してください。
新しいセキュリティ機能は、もともと AWS Encryption CLI バージョン 1.7.*x* および 2.0.*x* でリリースされました。ただし、 AWS Encryption CLI バージョン 1.8.*x* はバージョン 1.7.*x* AWS に置き換わり、Encryption CLI 2.1.*x* は 2.0.*x* に置き換わります。詳細については、GitHub の [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) リポジトリで関連する[セキュリティアドバイザリ](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)を参照してください。
**新規のユーザー**
を初めて使用する場合は AWS Encryption SDK、プログラミング言語 AWS Encryption SDK の の最新バージョンをインストールします。デフォルト値は、署名による暗号化 AWS Encryption SDK、キー取得、 の[キーコミットメント](concepts.md#key-commitment)など、 のすべてのセキュリティ機能を有効にします。 AWS Encryption SDK
**現在のユーザー**
できるだけ早く現在のバージョンから利用可能な最新バージョンにアップグレードすることをお勧めします。のすべての 1.*x* バージョン AWS Encryption SDK は[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあり、一部のプログラミング言語のそれ以降のバージョンも同様です。プログラミング言語での AWS Encryption SDK のサポートとメンテナンスの状況の詳細については、「[サポートとメンテナンス](introduction.md#support)」を参照してください。
AWS Encryption SDK バージョン 2.0.*x* 以降では、データの保護に役立つ新しいセキュリティ機能が提供されます。ただし、 AWS Encryption SDK バージョン 2.0.*x* には、下位互換性のない重大な変更が含まれています。安全な移行を確実に行うには、まず現在のバージョンからプログラミング言語の最新の 1.x への移行から始めてください。最新 1.x バージョンが完全にデプロイされて正常に動作している場合は、バージョン 2.0.x 以降に安全に移行できます。この [2 段階のプロセス](migration-guide.md)は、特に分散アプリケーションでは重要です。
これらの変更の基盤となる AWS Encryption SDK セキュリティ機能の詳細については、 *AWS セキュリティブログ*の[「クライアント側の暗号化の改善: 明示的な KeyIds とキーコミットメント](https://aws.amazon.com/blogs/security/improved-client-side-encryption-explicit-keyids-and-key-commitment/)」を参照してください。
AWS Encryption SDK for Java での の使用に関するヘルプをお探し AWS SDK for Java 2.xですか? 「[前提条件](java.md#java-prerequisites)」を参照してください。
**Topics**
+ [を移行およびデプロイする方法 AWS Encryption SDK](migration-guide.md)
+ [AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)
+ [AWS KMS キーリングの更新](migrate-keyrings-v2.md)
+ [コミットメントポリシーの設定](migrate-commitment-policy.md)
+ [最新バージョンへの移行に関するトラブルシューティング](troubleshooting-migration.md)
# を移行およびデプロイする方法 AWS Encryption SDK
1.7.*x* より前の AWS Encryption SDK バージョンからバージョン 2.0.*x* 以降に移行する場合は、[キーコミットメント](concepts.md#key-commitment)による暗号化に安全に移行する必要があります。そうしないと、アプリケーションは復号できない暗号化テキストを検出します。 AWS KMS マスターキープロバイダーを使用している場合は、マスターキープロバイダーを厳格モードまたは検出モードで作成する新しいコンストラクタに更新する必要があります。
**注記**
このトピックは、 AWS Encryption SDK の以前のバージョンからバージョン 2.0.x 以降に移行するユーザーを対象としています。を初めて使用する場合は AWS Encryption SDK、すぐに利用可能な最新バージョンをデフォルト設定で使用できます。
読む必要がある暗号化テキストを復号化できない重大な状況を回避するには、複数の異なるステージで移行およびデプロイすることをお勧めします。各ステージを完了して完全にデプロイしたことを確認してから、次のステージを開始してください。これは、複数のホストがある分散アプリケーションでは特に重要です。
## ステージ 1: アプリケーションを最新 1.x バージョンに更新
ご使用のプログラミング言語の最新 1.x バージョンに更新します。慎重にテストし、変更をデプロイして、更新がすべての送信先ホストに反映されていることを確認してから、ステージ 2 を開始します。
**重要**
最新 1.x バージョンが AWS Encryption SDKのバージョン 1.7.x 以降であることを確認します。
の最新の 1.*x* バージョン AWS Encryption SDK は、 のレガシーバージョンと下位互換性 AWS Encryption SDK があり、バージョン 2.0.*x* 以降と下位互換性があります。これらはバージョン 2.0.x にある新機能が含まれていますが、この移行用に設計された安全なデフォルトが含まれています。これにより、必要に応じて AWS KMS マスターキープロバイダーをアップグレードし、キーコミットメントで暗号文を復号できるアルゴリズムスイートを使用して完全にデプロイできます。
+ レガシー AWS KMS マスターキープロバイダーのコンストラクタなど、非推奨の要素を置き換えます。[Python](https://docs.python.org/3/library/warnings.html) では、非推奨の警告をオンにしてください。最新 1.x バージョンで非推奨になったコード要素は、バージョン 2.0.x 以降で削除されます。
+ コミットメントポリシーを明示的に `ForbidEncryptAllowDecrypt` に設定してください。最新 1.x バージョンではこれが唯一の有効な値ですが、この設定は、このリリースで導入された API を使用する場合に必要です。これにより、バージョン 2.0.x 以降への移行時に、キーコミットメントなしで暗号化された暗号化テキストがアプリケーションで拒否されるのを防ぎます。詳細については、「[コミットメントポリシーの設定](migrate-commitment-policy.md)」を参照してください。
+ AWS KMS マスターキープロバイダーを使用する場合は、レガシーマスターキープロバイダーを、*厳格モード*と*検出モード*をサポートするマスターキープロバイダーに更新する必要があります。この更新は、 AWS Encryption SDK for Java、 AWS Encryption SDK for Python、および AWS Encryption CLI に必要です。Discovery モードでマスターキープロバイダーを使用する場合は、Discovery フィルターを実装して、使用するラッピングキーを特に AWS アカウントのものに制限することをお勧めします。この更新はオプションですが、お勧めの[ベストプラクティス](best-practices.md)です。詳細については、「[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)」を参照してください。
+ [AWS KMS 検出キーリング](use-kms-keyring.md#kms-keyring-discovery) を使用する場合は、復号化に使用するラッピングキーを特に AWS アカウントの制限する検出フィルターを含めることをお勧めします。この更新はオプションですが、お勧めの[ベストプラクティス](best-practices.md)です。詳細については、「[AWS KMS キーリングの更新](migrate-keyrings-v2.md)」を参照してください。
## ステージ 2: アプリケーションを最新バージョンに更新
最新 1.x バージョンをすべてのホストに正常にデプロイしたら、バージョン 2.0.x 以降にアップグレードできます。バージョン 2.0.*x* には、 のすべての以前のバージョンの重大な変更が含まれています AWS Encryption SDK。ただし、ステージ 1 で推奨されるコードの変更を行うと、最新バージョンに移行するときにエラーを回避できます。
最新バージョンに更新する前に、コミットメントポリシーを一貫して `ForbidEncryptAllowDecrypt` に設定していることを確認してください。次に、データ構成に応じて、自分のペースで `RequireEncryptAllowDecrypt` に移行してからデフォルト設定の `RequireEncryptRequireDecrypt` に移行できます。次のパターンのような一連の移行手順を推奨します。
1. 最初は[コミットメントポリシー](migrate-commitment-policy.md)を `ForbidEncryptAllowDecrypt` に設定します。 AWS Encryption SDK ではキーコミットメントによるメッセージを復号化できますが、キーコミットメントではまだ暗号化しません。
1. 準備ができたら、コミットメントポリシーを `RequireEncryptAllowDecrypt` に更新します。は、[キーコミットメント](concepts.md#key-commitment)を使用してデータの暗号化 AWS Encryption SDK を開始します。キーコミットメントを使用しているかどうかにかかわらず、暗号化テキストを復号化できます。
コミットメントポリシーを `RequireEncryptAllowDecrypt` に更新する前に、生成した暗号化テキストを復号するアプリケーションのホストを含め、すべてのホストに最新 1.x バージョンがデプロイされていることを確認します。バージョン 1.7.*x* AWS Encryption SDK より前のバージョンの では、キーコミットメントで暗号化されたメッセージを復号できません。
この時点でアプリケーションにメトリクスを追加し、キーコミットメントによらない暗号化テキストをまだ処理しているかどうかを調査することもお勧めします。これにより、いつコミットメントポリシー設定を `RequireEncryptRequireDecrypt` に更新しても安全かを判断できるようになります。Amazon SQS キュー内のメッセージを暗号化するアプリケーションなど、一部のアプリケーションでは、古いバージョンで暗号化されたすべての暗号化テキストが再暗号化または削除されるのに時間がかかることがあります。暗号化された S3 オブジェクトなどの他のアプリケーションでは、すべてのオブジェクトをダウンロード、再暗号化、および再アップロードする必要がある場合があります。
1. キーコミットメントなしで暗号化されたメッセージがないことが確認できたら、コミットメントポリシーを `RequireEncryptRequireDecrypt` に更新できます。この値により、キーコミットメントでデータが常に暗号化、復号化されます。この設定はデフォルトであるため、明示的に設定する必要はありませんが、推奨されています。明示的に設定すると、アプリケーションがキーコミットメントなしで暗号化された暗号化テキストを検出した場合に必要となる可能性のある[デバッグ](troubleshooting-migration.md)とロールバックが容易になります。
# AWS KMS マスターキープロバイダーの更新
の最新の 1.*x* バージョンに移行し AWS Encryption SDK、次にバージョン 2.0.*x* 以降に移行するには、レガシー AWS KMS マスターキープロバイダーを、[*厳格モード*または*検出モードで*](about-versions.md#changes-to-mkps)明示的に作成されたマスターキープロバイダーに置き換える必要があります。レガシーマスターキープロバイダーは、バージョン 1.7.*x* で非推奨となり、バージョン 2.0.*x* で削除されます。この変更は、[AWS Encryption SDK for Java](java.md)、[AWS Encryption SDK for Python](python.md)、[AWS Encryption CLI](crypto-cli.md) を使用するアプリケーションとスクリプトで必要となります。このセクションの例では、コードの更新方法について説明します。
**注記**
Python では、[非推奨の警告をオンにしてください](https://docs.python.org/3/library/warnings.html)。コードの更新が必要な部分を特定できるようになります。
AWS KMS マスターキー (マスターキープロバイダーではない) を使用している場合は、このステップをスキップできます。 AWS KMS マスターキーは廃止または削除されません。このマスターキーでは、指定したラッピングキーでのみ暗号化および復号化が行われます。
このセクションの例では、変更する必要があるコードの要素に焦点を当てています。更新されたコードの完全な例については、使用している[プログラミング言語](programming-languages.md)の GitHub リポジトリの例セクションを参照してください。また、これらの例では、通常、キー ARNsを使用して表現します AWS KMS keys。暗号化用のマスターキープロバイダーを作成するときは、任意の有効な AWS KMS [キー識別子](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)を使用して を表すことができます AWS KMS key 。復号用のマスターキープロバイダーを作成するときは、キー ARN を使用する必要があります。
**移行の詳細**
すべての AWS Encryption SDK ユーザーについて、 でのコミットメントポリシーの設定について説明します[コミットメントポリシーの設定](migrate-commitment-policy.md)。
AWS Encryption SDK for C および AWS Encryption SDK for JavaScript ユーザーについては、「」のキーリングのオプションの更新について説明します[AWS KMS キーリングの更新](migrate-keyrings-v2.md)。
**Topics**
+ [Strict モードへの移行](#migrate-mkp-strict-mode)
+ [Discovery モードへの移行](#migrate-mkp-discovery-mode)
## Strict モードへの移行
を最新の 1.*x* バージョンに更新したら AWS Encryption SDK、レガシーマスターキープロバイダーを strict モードでマスターキープロバイダーに置き換えます。Strict モードでは、暗号化時および復号化時に使用するラッピングキーを指定する必要があります。は、指定したラッピングキーのみ AWS Encryption SDK を使用します。非推奨のマスターキープロバイダーは、 AWS KMS keys 異なる リージョン AWS アカウント や リージョンなど、データキーを暗号化 AWS KMS key した を使用してデータを復号できます。
Strict モードのマスターキープロバイダーは、 AWS Encryption SDK バージョン 1.7.*x* で導入されています。1.7.*x* で非推奨となって 2.0.*x* で削除されるレガシーマスターキープロバイダーは置き換えられます。マスターキープロバイダーを strict モードで使用することが AWS Encryption SDK [ベストプラクティス](best-practices.md)です。
次のコードでは Strict モードでマスターキープロバイダーを作成し、暗号化と復号に使用できるようにしています。
------
#### [ Java ]
この例は、 AWS Encryption SDK for Javaのバージョン 1.6.2 以前を使用するアプリケーションのコードを表しています。
このコードは、 `KmsMasterKeyProvider.builder()`メソッドを使用して、ラッピングキー AWS KMS key として使用する AWS KMS マスターキープロバイダーをインスタンス化します。
```
// Create a master key provider
// Replace the example key ARN with a valid one
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.withKeysForEncryption(awsKmsKey)
.build();
```
この例は、 AWS Encryption SDK for Java のバージョン 1.7.*x* 以降を使用するアプリケーションのコードを表しています。詳しい例については、「[BasicEncryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/BasicEncryptionExample.java)」を参照してください。
前の例で使用した `Builder.build()` および `Builder.withKeysForEncryption()` メソッドは、バージョン 1.7.*x* で非推奨となり、バージョン 2.0.*x* で削除されます。
Strict モードのマスターキープロバイダーに更新するため、このコードでは非推奨メソッドの呼び出しを新しい `Builder.buildStrict()` メソッドの呼び出しに置き換えます。この例では、ラッピングキー AWS KMS key として 1 つを指定しますが、 `Builder.buildStrict()`メソッドは複数の のリストを取得できます AWS KMS keys。
```
// Create a master key provider in strict mode
// Replace the example key ARN with a valid one from your AWS アカウント.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
KmsMasterKeyProvider masterKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
```
------
#### [ Python ]
この例は、 AWS Encryption SDK for Pythonのバージョン 1.4.1 を使用するアプリケーションのコードを表しています。このコードでは `KMSMasterKeyProvider` を使用しますが、これはバージョン 1.7.*x* で非推奨となり、バージョン 2.0.*x* から削除されます。復号時には、 AWS KMS keys 指定した に関係なく、データキーを暗号化 AWS KMS key した が使用されます。
`KMSMasterKey` は非推奨にならず、削除されません。暗号化および復号時には、 AWS KMS key 指定した のみを使用します。
```
# Create a master key provider
# Replace the example key ARN with a valid one
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = KMSMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
この例は、 AWS Encryption SDK for Pythonのバージョン 1.7.*x* を使用するアプリケーションのコードを表しています。詳しい例については、「[basic\$1encryption.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/basic_encryption.py)」を参照してください。
Strict モードのマスターキープロバイダーに更新するため、このコードでは `KMSMasterKeyProvider()` の呼び出しを `StrictAwsKmsMasterKeyProvider()` の呼び出しに置き換えます。
```
# Create a master key provider in strict mode
# Replace the example key ARNs with valid values from your AWS アカウント
key_1 = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
key_2 = "arn:aws:kms:us-west-2:111122223333:key/0987dcba-09fe-87dc-65ba-ab0987654321"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
```
------
#### [ AWS Encryption CLI ]
この例では、Encryption CLI バージョン 1.1.7 AWS 以前を使用して暗号化および復号する方法を示します。
バージョン 1.1.7 以前では、暗号化時に AWS KMS keyなどの 1 つ以上のマスターキー (*ラッピングキー*) を指定します。復号化時には、カスタムのマスターキープロバイダーを使用していない限り、ラッピングキーを指定することはできません。 AWS Encryption CLI は、データキーを暗号化した任意のラッピングキーを使用できます。
```
\\ Replace the example key ARN with a valid one
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--master-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
この例では、Encryption CLI バージョン 1.7.*x* AWS 以降を使用して暗号化および復号する方法を示します。完全な例については、「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。
`--master-keys` パラメータはバージョン 1.7.*x* で非推奨となり、バージョン 2.0.*x* で削除されます。これは `--wrapping-keys` パラメータに置き換わり、すべての暗号化コマンドと復号コマンドに必要となります。このパラメータでは、Strict モードと Discovery モードがサポートされます。厳格モードは、意図したラッピングキーを使用することを保証する AWS Encryption SDK ベストプラクティスです。
*Strict モード*にアップグレードするには、`--wrapping-keys`パラメータの **key** 属性を使用して、暗号化時および復号時のラッピングキーを指定します。
```
\\ Replace the example key ARN with a valid value
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
## Discovery モードへの移行
バージョン 1.7.*x* 以降では、マスターキープロバイダーに AWS KMS *strict モード*を使用する、つまり暗号化および復号時にラッピングキーを指定するの AWS Encryption SDK [がベストプラクティス](best-practices.md)です。暗号化するときは、常にラッピングキーを指定する必要があります。ただし、復号 AWS KMS keys のための のキー ARNs の指定が実用的でない場合があります。たとえば、エイリアスを使用して暗号化 AWS KMS keys 時に を識別する場合、復号時にキー ARNs を一覧表示する必要がある場合、エイリアスの利点が失われます。また、Discovery モードのマスターキープロバイダーは元のマスターキープロバイダーと同様に動作するため、移行戦略の一部として一時的にそれを使用し、後で Strict モードのマスターキープロバイダーにアップグレードできます。
このような場合は、マスターキープロバイダーを *Discovery モード*で使用できます。これらのマスターキープロバイダーではラッピングキーを指定できないため、暗号化には使用できません。復号時には、データキーを暗号化したラッピングキーを使用できます。ただし、同じ動作をするレガシーマスターキープロバイダーとは異なり、Discovery モードで明示的に作成します。Discovery モードでマスターキープロバイダーを使用する場合、使用できるラッピングキーを特に AWS アカウントのものに制限できます。この検出フィルターはオプションですが、お勧めのベストプラクティスです。 AWS パーティションとアカウントの詳細については、「AWS 全般のリファレンス」の「[Amazon リソースネーム](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax)」を参照してください。
次の例では、暗号化用の Strict モードで AWS KMS マスターキープロバイダーを作成し、復号用の 検出モードで AWS KMS マスターキープロバイダーを作成します。Discovery モードのマスターキープロバイダーは、検出フィルターを使用して、復号に使用するラッピングキーを `aws` パーティションと特定の AWS アカウント例に制限します。この単純な例ではアカウントフィルターは必要ありませんが、あるアプリケーションがデータを暗号化し、別のアプリケーションがデータを復号化する場合に非常に有益なベストプラクティスです。
------
#### [ Java ]
この例は、 AWS Encryption SDK for Javaのバージョン 1.7.*x* 以降を使用するアプリケーションのコードを表しています。詳しい例については、[DiscoveryDecryptionExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/) を参照してください。
暗号化では Strict モードでマスターキープロバイダーをインスタンス化するために、この例では `Builder.buildStrict()` メソッドを使用します。復号では Discovery モードでマスターキープロバイダーをインスタンス化するため、`Builder.buildDiscovery()` メソッドを使用します。`Builder.buildDiscovery()` メソッドは、指定された AWS パーティションとアカウント AWS KMS keys で AWS Encryption SDK を `DiscoveryFilter`に制限する を取得します。
```
// Create a master key provider in strict mode for encrypting
// Replace the example alias ARN with a valid one from your AWS アカウント.
String awsKmsKey = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias";
KmsMasterKeyProvider encryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildStrict(awsKmsKey);
// Create a master key provider in discovery mode for decrypting
// Replace the example account IDs with valid values.
DiscoveryFilter accounts = new DiscoveryFilter("aws", Arrays.asList("111122223333", "444455556666"));
KmsMasterKeyProvider decryptingKeyProvider = KmsMasterKeyProvider.builder()
.buildDiscovery(accounts);
```
------
#### [ Python ]
この例は、 AWS Encryption SDK for Python のバージョン 1.7.*x* 以降を使用するアプリケーションのコードを表しています。詳しい例については、[discovery\$1kms\$1provider.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/discovery_kms_provider.py) を参照してください。
暗号化では Strict モードでマスターキープロバイダーを作成するために、この例では `StrictAwsKmsMasterKeyProvider` を使用します。復号のために検出モードでマスターキープロバイダーを作成するには、指定された AWS パーティションとアカウント AWS KMS keys で AWS Encryption SDK を に制限`DiscoveryFilter`する `DiscoveryAwsKmsMasterKeyProvider`で を使用します。
```
# Create a master key provider in strict mode
# Replace the example key ARN and alias ARNs with valid values from your AWS アカウント.
key_1 = "arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias"
key_2 = "arn:aws:kms:us-west-2:444455556666:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d"
aws_kms_master_key_provider = StrictAwsKmsMasterKeyProvider(
key_ids=[key_1, key_2]
)
# Create a master key provider in discovery mode for decrypting
# Replace the example account IDs with valid values
accounts = DiscoveryFilter(
partition="aws",
account_ids=["111122223333", "444455556666"]
)
aws_kms_master_key_provider = DiscoveryAwsKmsMasterKeyProvider(
discovery_filter=accounts
)
```
------
#### [ AWS Encryption CLI ]
この例では、Encryption CLI バージョン 1.7.*x* AWS 以降を使用して暗号化および復号する方法を示します。バージョン 1.7.*x* 以降は、`--wrapping-keys` パラメータが暗号化および復号化時に必要となります。`--wrapping-keys` パラメータでは、Strict モードと Discovery モードがサポートされます。完全な例については、「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。
この例では、暗号化時に必須のラッピングキーを指定します。復号化時には、`--wrapping-keys` パラメータの `discovery` 属性の値を `true` にして、*Discovery モード*を明示的に選択します。
が検出モードで AWS Encryption SDK 使用できるラッピングキーを特にそれらに制限するために AWS アカウント、この例では `--wrapping-keys`パラメータの 属性`discovery-partition`と `discovery-account` 属性を使用します。これらのオプションの属性は、`discovery` 属性を `true` に設定しているときに限って有効です。`discovery-partition` 属性と `discovery-account` 属性は一緒に使用する必要があります。単独では有効ではありません。
```
\\ Replace the example key ARN with a valid value
$ keyAlias=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
\\ Encrypt your plaintext data
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyAlias \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext
\\ Replace the example account IDs with valid values
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666 \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
# AWS KMS キーリングの更新
の AWS KMS キーリング[AWS Encryption SDK for C](c-language.md)、 [AWS Encryption SDK for .NET](dot-net.md)、および は、暗号化および復号時にラッピングキーを指定できるようにすることで[、ベストプラクティス](best-practices.md)[AWS Encryption SDK for JavaScript](javascript.md)をサポートしています。[AWS KMS 検出キーリング](use-kms-keyring.md#kms-keyring-discovery)を作成する場合は、明示的に作成します。
**注記**
for .NET AWS Encryption SDK の最も古いバージョンはバージョン 3.0.*x* です。 AWS Encryption SDK for .NET のすべてのバージョンは、 の 2.0.*x* で導入されたセキュリティのベストプラクティスをサポートしています AWS Encryption SDK。コードやデータを変更することなく、最新バージョンに安全にアップグレードできます。
を最新の 1.*x* バージョンに更新すると AWS Encryption SDK、[検出フィルター](use-kms-keyring.md#kms-keyring-discovery)を使用して、検出キー[AWS KMS リングまたはリージョン別検出キー](use-kms-keyring.md#kms-keyring-discovery)[AWS KMS リングが復号するときに](use-kms-keyring.md#kms-keyring-regional)使用するラッピングキーを制限できます AWS アカウント。検出キーリングのフィルタリングは AWS Encryption SDK [ベストプラクティス](best-practices.md)です。
このセクションの例では、検出フィルターを AWS KMS リージョン検出キーリングに追加する方法を示します。
**移行の詳細**
すべての AWS Encryption SDK ユーザーについて、 でのコミットメントポリシーの設定について説明します[コミットメントポリシーの設定](migrate-commitment-policy.md)。
AWS Encryption SDK for Java、 AWS Encryption SDK for Python、および AWS Encryption CLI ユーザーについては、 のマスターキープロバイダーに必要な更新について説明します[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)。
アプリケーションでは、コードは次のようなものになります。この例では、米国西部 (オレゴン) (us-west-2) リージョンのラッピングキーのみを使用する AWS KMS リージョン検出キーリングを作成します。この例では、1.7.*x* より前の AWS Encryption SDK バージョンのコードを表します。ただし、バージョン 1.7.*x* 以降でも有効です。
------
#### [ C ]
```
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery());
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser({ clientProvider, discovery })
```
------
#### [ JavaScript Node.js ]
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({ clientProvider, discovery })
```
------
バージョン 1.7.*x* 以降では、任意の検出キーリングに AWS KMS 検出フィルターを追加できます。この検出フィルター AWS Encryption SDK は、 AWS KMS keys が復号に使用できる を、指定されたパーティションとアカウント内のものに制限します。このコードを使用する前に、必要に応じてパーティションを変更し、サンプルアカウント ID を有効なアカウント ID に置き換えます。
------
#### [ C ]
詳しい例については、[kms\$1discovery.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/kms_discovery.cpp) を参照してください。
```
std::shared_ptr discovery_filter(
KmsKeyring::DiscoveryFilter::Builder("aws")
.AddAccount("111122223333")
.AddAccount("444455556666")
.Build());
struct aws_cryptosdk_keyring *kms_regional_keyring = Aws::Cryptosdk::KmsKeyring::Builder()
.WithKmsClient(create_kms_client(Aws::Region::US_WEST_2)).BuildDiscovery(discovery_filter));
```
------
#### [ JavaScript Browser ]
```
const clientProvider = getClient(KMS, { credentials })
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringBrowser(clientProvider, {
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
#### [ JavaScript Node.js ]
詳しい例については、[kms\$1filtered\$1discovery.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_filtered_discovery.ts) を参照してください。
```
const discovery = true
const clientProvider = limitRegions(['us-west-2'], getKmsClient)
const keyring = new KmsKeyringNode({
clientProvider,
discovery,
discoveryFilter: { accountIDs: ['111122223333', '444455556666'], partition: 'aws' }
})
```
------
# コミットメントポリシーの設定
[キーコミットメント](concepts.md#key-commitment)により、暗号化されたデータは常に同じプレーンテキストに復号化されるようになります。このセキュリティプロパティを提供するために、バージョン 1.7.*x* 以降、 はキーコミットメントを持つ新しい[アルゴリズムスイート](supported-algorithms.md) AWS Encryption SDK を使用します。データをキーコミットメントで暗号化および復号化するかどうかを決めるには、[コミットメントポリシー](concepts.md#commitment-policy)構成設定を使用します。キーコミットメントによるデータの暗号化と復号化は、[AWS Encryption SDK のベストプラクティス](best-practices.md)です。
コミットメントポリシーの設定は、 の最新の 1.*x* バージョンからバージョン 2.0.*x* 以降に移行 AWS Encryption SDK する移行プロセスの 2 番目のステップの重要な部分です。コミットメントポリシーを設定および変更したら、アプリケーションを徹底的にテストしてから本番環境にデプロイしてください。移行ガイダンスについては、「[を移行およびデプロイする方法 AWS Encryption SDK](migration-guide.md)」を参照してください。
バージョン 2.0.x 以降に、コミットメントポリシー設定には 3 つの有効な値があります。最新の 1.x バージョン (バージョン 1.7.x 以降) では、`ForbidEncryptAllowDecrypt` のみ有効です。
+ `ForbidEncryptAllowDecrypt` — はキーコミットメントで暗号化 AWS Encryption SDK できません。キーコミットメントが使用されているかどうかにかかわらず、暗号化された暗号化テキストを復号化できます。
最新の 1.x バージョンでは、これが唯一の有効な値です。これにより、キーコミットメントで復号化する準備が完全に整うまで、キーコミットメントで暗号化しないようになります。値を明示的に設定すると、バージョン 2.0.x 以降へアップグレード時にコミットメントポリシーが自動的に `require-encrypt-require-decrypt` へ変更されるのを防ぎます。その代わりに、[コミットメントポリシーを段階的に移行](#migrate-commitment-policy)できます。
+ `RequireEncryptAllowDecrypt` — AWS Encryption SDK は常にキーコミットメントで暗号化します。キーコミットメントが使用されているかどうかにかかわらず、暗号化された暗号化テキストを復号化できます。この値はバージョン 2.0.*x* で追加されました。
+ `RequireEncryptRequireDecrypt` — AWS Encryption SDK は常にキーコミットメントで暗号化および復号します。この値はバージョン 2.0.*x* で追加されました。バージョン 2.0.x 以降では、これがデフォルト値です。
最新の 1.x バージョンでは、唯一の有効なコミットメントポリシー値は `ForbidEncryptAllowDecrypt` です。バージョン 2.0.x 以降に移行した後、準備が整ったら、[コミットメントポリシーを段階的に変更](migration-guide.md)できます。すべてのメッセージがキーコミットメントで暗号化されることが確認できるまで、コミットメントポリシーを `RequireEncryptRequireDecrypt` に更新しないでください。
これらの例では、最新の 1.x バージョンおよび バージョン 2.0.x 以降でコミットメントポリシーを設定する方法を示します。この手法はプログラミング言語によって異なります。
**移行の詳細**
AWS Encryption SDK for Java、 AWS Encryption SDK for Python、および AWS Encryption CLI で、 のマスターキープロバイダーに必要な変更について説明します[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)。
AWS Encryption SDK for C および については AWS Encryption SDK for JavaScript、「」のキーリングのオプションの更新について説明します[AWS KMS キーリングの更新](migrate-keyrings-v2.md)。
## コミットメントポリシーの設定方法
コミットメントポリシーの設定に使用する手法は、言語実装ごとに若干異なります。以下の例ではその方法を示します。コミットメントポリシーを変更する前に、「[移行してデプロイする方法](migration-guide.md)」で多段階のアプローチを確認してください。
------
#### [ C ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for C、 `aws_cryptosdk_session_set_commitment_policy`関数を使用して、暗号化および復号セッションにコミットメントポリシーを設定します。設定したコミットメントポリシーは、そのセッションで呼び出されるすべての暗号化および復号オペレーションに適用されます。
`aws_cryptosdk_session_new_from_keyring` 関数および `aws_cryptosdk_session_new_from_cmm` 関数は、バージョン 1.7.*x* で非推奨となり、バージョン 2.0.*x* で削除されます。これらの関数は、セッションを返す `aws_cryptosdk_session_new_from_keyring_2` 関数および `aws_cryptosdk_session_new_from_cmm_2` 関数に置き換わります。
最新の 1.x バージョンで `aws_cryptosdk_session_new_from_keyring_2` および `aws_cryptosdk_session_new_from_cmm_2` を使用している場合は、`COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT` コミットメントポリシーの値で `aws_cryptosdk_session_set_commitment_policy` 関数を呼び出す必要があります。バージョン 2.0.x 以降では、この関数の呼び出しはオプションであり、すべての有効な値を取ります。バージョン 2.0.x 以降のデフォルトコミットポリシーは `COMMITMENT_POLICY_REQUIRE_ENCRYPT_REQUIRE_DECRYPT` です。
詳しい例については、[string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp) を参照してください。
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
/* Create an AWS KMS keyring */
const char * key_arn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
/* Create an encrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_session *encrypt_session = aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(encrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
...
/* Encrypt your data */
size_t plaintext_consumed_output;
aws_cryptosdk_session_process(encrypt_session,
ciphertext_output,
ciphertext_buf_sz_output,
ciphertext_len_output,
plaintext_input,
plaintext_len_input,
&plaintext_consumed_output)
...
/* Create a decrypt session with a CommitmentPolicy setting */
struct aws_cryptosdk_keyring *kms_keyring = Aws::Cryptosdk::KmsKeyring::Builder().Build(key_arn);
struct aws_cryptosdk_session *decrypt_session = *aws_cryptosdk_session_new_from_keyring_2(
alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
aws_cryptosdk_keyring_release(kms_keyring);
aws_cryptosdk_session_set_commitment_policy(decrypt_session,
COMMITMENT_POLICY_FORBID_ENCRYPT_ALLOW_DECRYPT);
/* Decrypt your ciphertext */
size_t ciphertext_consumed_output;
aws_cryptosdk_session_process(decrypt_session,
plaintext_output,
plaintext_buf_sz_output,
plaintext_len_output,
ciphertext_input,
ciphertext_len_input,
&ciphertext_consumed_output)
```
------
#### [ C\$1 / .NET ]
`require-encrypt-require-decrypt` 値は、.NET AWS Encryption SDK 用 のすべてのバージョンのデフォルトのコミットメントポリシーです。ベストプラクティスとして明示的に設定することもできますが、必須ではありません。ただし、 AWS Encryption SDK for .NET を使用して、キーコミットメント AWS Encryption SDK なしで の別の言語実装によって暗号化された暗号文を復号する場合は、コミットメントポリシーの値を `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または に変更する必要があります`FORBID_ENCRYPT_ALLOW_DECRYPT`。含まれていない場合、暗号文の復号は失敗します。
for AWS Encryption SDK .NET では、 のインスタンスにコミットメントポリシーを設定します AWS Encryption SDK。`CommitmentPolicy` パラメータを使用して`AwsEncryptionSdkConfig`オブジェクトをインスタンス化し、設定オブジェクトを使用して AWS Encryption SDK インスタンスを作成します。次に、設定済み AWS Encryption SDK インスタンスの メソッド`Encrypt()`と `Decrypt()`メソッドを呼び出します。
この例では、コミットメントポリシーを `require-encrypt-allow-decrypt` に設定します。
```
// Instantiate the material providers
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
// Configure the commitment policy on the AWS Encryption SDK instance
var config = new AwsEncryptionSdkConfig
{
CommitmentPolicy = CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT
};
var encryptionSdk = AwsEncryptionSdkFactory.CreateAwsEncryptionSdk(config);
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
var encryptionContext = new Dictionary()
{
{"purpose", "test"}encryptionSdk
};
var createKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
var keyring = materialProviders.CreateAwsKmsKeyring(createKeyringInput);
// Encrypt your plaintext data
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
// Decrypt your ciphertext
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = keyring
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
------
#### [ AWS Encryption CLI ]
Encryption CLI AWS でコミットメントポリシーを設定するには、 `--commitment-policy`パラメータを使用します。このパラメータはバージョン 1.8.*x* で導入されました。
最新の 1.x バージョンでは、`--encrypt` または `--decrypt` コマンドの `--wrapping-keys` パラメータを使用するときに、`forbid-encrypt-allow-decrypt` 値 を持つ `--commitment-policy` パラメータが必要です。そうでない場合、`--commitment-policy` パラメータは無効です。
バージョン 2.1.x 以降の場合、`--commitment-policy` パラメータはオプションであり、デフォルトで `require-encrypt-require-decrypt` 値になっており、キーコミットメントなしで暗号化された暗号化テキストは暗号化または復号されません。ただし、メンテナンスとトラブルシューティングに役立つように、すべての暗号化および復号呼び出しでコミットメントポリシーを明示的に設定することをお勧めします。
この例ではコミットメントポリシーを設定します。また、バージョン 1.8.*x* 以降、`--master-keys` パラメータを置き換える `--wrapping-keys` パラメータを使用します。詳細については、「[AWS KMS マスターキープロバイダーの更新](migrate-mkps-v2.md)」を参照してください。完全な例については、「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。
```
\\ 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
\\ Encrypt your plaintext data - no change to algorithm suite used
$ aws-encryption-cli --encrypt \
--input hello.txt \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--output .
\\ Decrypt your ciphertext - supports key commitment on 1.7 and later
$ aws-encryption-cli --decrypt \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy forbid-encrypt-allow-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--output .
```
------
#### [ Java ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for Java、 AWS Encryption SDK クライアントを表すオブジェクト`AwsCrypto`である のインスタンスにコミットメントポリシーを設定します。このコミットメントポリシーは、そのクライアントで呼び出されるすべての暗号化および復号オペレーションに適用されます。
コン`AwsCrypto()`ストラクタは の最新の 1.*x* バージョンでは廃止 AWS Encryption SDK for Java され、バージョン 2.0.*x* では削除されます。これは、新しい `Builder` クラス、`Builder.withCommitmentPolicy()` メソッド、`CommitmentPolicy` 列挙型に置き換わります。
最新 1.x バージョンでは、`Builder` クラスには `Builder.withCommitmentPolicy()` メソッドと `CommitmentPolicy.ForbidEncryptAllowDecrypt` 引数が必要です。バージョン 2.0.*x* 以降、`Builder.withCommitmentPolicy()` メソッドはオプションであり、デフォルト値は `CommitmentPolicy.RequireEncryptRequireDecrypt` です。
詳しい例については、「[SetCommitmentPolicyExample.java](https://github.com/aws/aws-encryption-sdk-java/blob/master/src/examples/java/com/amazonaws/crypto/examples/v2/SetCommitmentPolicyExample.java)」を参照してください。
```
// Instantiate the client
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.ForbidEncryptAllowDecrypt)
.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);
// Encrypt your plaintext data
CryptoResult encryptResult = crypto.encryptData(
masterKeyProvider,
sourcePlaintext,
encryptionContext);
byte[] ciphertext = encryptResult.getResult();
// Decrypt your ciphertext
CryptoResult decryptResult = crypto.decryptData(
masterKeyProvider,
ciphertext);
byte[] decrypted = decryptResult.getResult();
```
------
#### [ JavaScript ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for JavaScript、 AWS Encryption SDK クライアントをインスタンス化する新しい`buildClient`関数を呼び出すときにコミットメントポリシーを設定できます。`buildClient` 関数は、コミットメントポリシーを表す列挙値を取ります。更新された `encrypt` 関数と `decrypt` 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。
最新 1.x バージョンでは、`buildClient` 関数には `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` 引数が必要です。バージョン 2.0.*x* 以降、コミットメントポリシー引数はオプションであり、デフォルト値は `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT` です。
Node.js とブラウザのコードは、ブラウザが認証情報を設定するためのステートメントを必要とする点を除いて、この目的では同じです。
次の の例では、 AWS KMS キーリングを使用してデータを暗号化します。新しい `buildClient` 関数は、コミットメントポリシーを最新 1.x バージョンでのデフォルト値の `FORBID_ENCRYPT_ALLOW_DECRYPT` に設定します。`buildClient` が返すアップグレード済みの `encrypt` 関数と `decrypt` 関数では、設定したコミットメントポリシーが適用されます。
```
import { buildClient } from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// Create an AWS KMS keyring
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
// Encrypt your plaintext data
const { ciphertext } = await encrypt(keyring, plaintext, { encryptionContext: context })
// Decrypt your ciphertext
const { decrypted, messageHeader } = await decrypt(keyring, ciphertext)
```
------
#### [ Python ]
のバージョン 1.7.*x* 以降では AWS Encryption SDK for Python、 AWS Encryption SDK クライアントを表す新しいオブジェクト`EncryptionSDKClient`である のインスタンスにコミットメントポリシーを設定します。設定したコミットメントポリシーは、クライアントのインスタンスを使用するすべての `encrypt` 呼び出しと `decrypt` 呼び出しに適用されます。
最新 1.x バージョンでは、`EncryptionSDKClient` コンストラクタには `CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT` 列挙値が必要です。バージョン 2.0.*x* 以降、コミットメントポリシー引数はオプションであり、デフォルト値は `CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT` です。
この例では新しい `EncryptionSDKClient` コンストラクタを使用して、コミットメントポリシーを 1.7.*x* のデフォルト値に設定します。コンストラクタは、 AWS Encryption SDKを表すクライアントをインスタンス化します。このクライアントで、`encrypt`、`decrypt`、`stream` のいずれかのメソッドを呼び出すと、設定したコミットメントポリシーが適用されます。この例では、 `StrictAwsKmsMasterKeyProvider` クラスの新しいコンストラクタも使用します。このコンストラクタは、暗号化および復号 AWS KMS keys 時に を指定します。
詳しい例については、「[set\$1commitment.py](https://github.com/aws/aws-encryption-sdk-python/blob/master/examples/src/legacy/set_commitment.py)」を参照してください。
```
# Instantiate the client
client = aws_encryption_sdk.EncryptionSDKClient(commitment_policy=CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT)
// 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 your plaintext data
ciphertext, encrypt_header = client.encrypt(
source=source_plaintext,
encryption_context=encryption_context,
master_key_provider=aws_kms_strict_master_key_provider
)
# Decrypt your ciphertext
decrypted, decrypt_header = client.decrypt(
source=ciphertext,
master_key_provider=aws_kms_strict_master_key_provider
)
```
------
#### [ Rust ]
`require-encrypt-require-decrypt` 値は、 for AWS Encryption SDK Rust のすべてのバージョンのデフォルトのコミットメントポリシーです。ベストプラクティスとして明示的に設定することもできますが、必須ではありません。ただし、 AWS Encryption SDK for Rust を使用して、キーコミットメント AWS Encryption SDK なしで の別の言語実装によって暗号化された暗号文を復号する場合は、コミットメントポリシー値を `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または に変更する必要があります`FORBID_ENCRYPT_ALLOW_DECRYPT`。含まれていない場合、暗号文の復号は失敗します。
AWS Encryption SDK for Rust で、 のインスタンスにコミットメントポリシーを設定します AWS Encryption SDK。`comitment_policy` パラメータを使用して`AwsEncryptionSdkConfig`オブジェクトをインスタンス化し、設定オブジェクトを使用して AWS Encryption SDK インスタンスを作成します。次に、設定済み AWS Encryption SDK インスタンスの メソッド`Encrypt()`と `Decrypt()`メソッドを呼び出します。
この例では、コミットメントポリシーを `forbid-encrypt-allow-decrypt` に設定します。
```
// Configure the commitment policy on the AWS Encryption SDK instance
let esdk_config = AwsEncryptionSdkConfig::builder()
.commitment_policy(ForbidEncryptAllowDecrypt)
.build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
// Create an AWS KMS client
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
// Create your encryption context
let encryption_context = HashMap::from([
("encryption".to_string(), "context".to_string()),
("is not".to_string(), "secret".to_string()),
("but adds".to_string(), "useful metadata".to_string()),
("that can help you".to_string(), "be confident that".to_string()),
("the data you are handling".to_string(), "is what you think it is".to_string()),
]);
// Instantiate the material providers library
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create an AWS KMS keyring
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
// Encrypt your plaintext data
let plaintext = example_data.as_bytes();
let encryption_response = esdk_client.encrypt()
.plaintext(plaintext)
.keyring(kms_keyring.clone())
.encryption_context(encryption_context.clone())
.send()
.await?;
// Decrypt your ciphertext
let decryption_response = esdk_client.decrypt()
.ciphertext(ciphertext)
.keyring(kms_keyring)
// Provide the encryption context that was supplied to the encrypt method
.encryption_context(encryption_context)
.send()
.await?;
```
------
#### [ Go ]
```
import (
"context"
mpl "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygenerated"
mpltypes "aws/aws-cryptographic-material-providers-library/releases/go/mpl/awscryptographymaterialproviderssmithygeneratedtypes"
client "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygenerated"
esdktypes "github.com/aws/aws-encryption-sdk/awscryptographyencryptionsdksmithygeneratedtypes"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/kms"
)
// Instantiate the AWS Encryption SDK client
commitPolicyForbidEncryptAllowDecrypt := mpltypes.ESDKCommitmentPolicyForbidEncryptAllowDecrypt
encryptionClient, err := client.NewClient(esdktypes.AwsEncryptionSdkConfig{CommitmentPolicy: &commitPolicyForbidEncryptAllowDecrypt})
if err != nil {
panic(err)
}
// Create an AWS KMS client
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
kmsClient := kms.NewFromConfig(cfg, func(o *kms.Options) {
o.Region = KmsKeyRegion
})
// Optional: Create an encryption context
encryptionContext := map[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 material providers library
matProv, err := mpl.NewClient(mpltypes.MaterialProvidersConfig{})
if err != nil {
panic(err)
}
// Create an AWS KMS keyring
awsKmsKeyringInput := mpltypes.CreateAwsKmsKeyringInput{
KmsClient: kmsClient,
KmsKeyId: kmsKeyId,
}
awsKmsKeyring, err := matProv.CreateAwsKmsKeyring(context.Background(), awsKmsKeyringInput)
if err != nil {
panic(err)
}
// Encrypt your plaintext data
res, err := forbidEncryptClient.Encrypt(context.Background(), esdktypes.EncryptInput{
Plaintext: []byte(exampleText),
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
// Decrypt your ciphertext
decryptOutput, err := forbidEncryptClient.Decrypt(context.Background(), esdktypes.DecryptInput{
Ciphertext: res.Ciphertext,
EncryptionContext: encryptionContext,
Keyring: awsKmsKeyring,
})
if err != nil {
panic(err)
}
```
------
# 最新バージョンへの移行に関するトラブルシューティング
アプリケーションを のバージョン 2.0.*x* 以降に更新する前に AWS Encryption SDK、 の最新バージョンの 1.*x* に更新 AWS Encryption SDK し、完全にデプロイします。これにより、バージョン 2.0.x 以降への更新時に発生する可能性のあるほとんどのエラーを回避できます。例を含む詳細なガイダンスについては、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
**重要**
最新 1.x バージョンが AWS Encryption SDKのバージョン 1.7.x 以降であることを確認します。
**注記**
**AWS Encryption CLI**: このガイドの のバージョン 1.7.*x* へのリファレンスは、 Encryption CLI のバージョン 1.8.*x* AWS AWS Encryption SDK に適用されます。このガイドの のバージョン 2.0.*x* AWS への参照は、Encryption CLI の 2.1.*x* AWS Encryption SDK に適用されます。
新しいセキュリティ機能は、もともと AWS Encryption CLI バージョン 1.7.*x* および 2.0.*x* でリリースされました。ただし、 AWS Encryption CLI バージョン 1.8.*x* はバージョン 1.7.*x* AWS に置き換わり、Encryption CLI 2.1.*x* は 2.0.*x* に置き換わります。詳細については、GitHub の [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) リポジトリで関連する[セキュリティアドバイザリ](https://github.com/aws/aws-encryption-sdk-cli/security/advisories/GHSA-2xwp-m7mq-7q3r)を参照してください。
このトピックは、発生する可能性のある最も一般的なエラーを認識し、解決するのに役立つように設計されています。
**Topics**
+ [非推奨または削除されたオブジェクト](#deprecated-removed)
+ [構成の競合: コミットメントポリシーとアルゴリズムスイート](#configuration-conflict_1)
+ [構成の競合: コミットメントポリシーと暗号化テキスト](#configuration-conflict_2)
+ [キーコミットメントの検証の失敗](#commitment-failed)
+ [その他の暗号化の失敗](#encrypt-failed)
+ [その他の復号化の失敗](#decrypt-failed)
+ [ロールバックに関する考慮事項](#migration-rollback)
## 非推奨または削除されたオブジェクト
バージョン 2.0.*x* には、バージョン 1.7.*x* で非推奨になったレガシーコンストラクタ、メソッド、関数、クラスの削除など、いくつかの重大な変更が含まれています。コンパイラエラー、インポートエラー、構文エラー、記号が見つかりませんエラー (プログラミング言語に応じて) を回避するには、まずプログラミング言語の の最新バージョン 1.*x* AWS Encryption SDK にアップグレードします。(これはバージョン 1.7.x 以降である必要があります。) 最新 1.x バージョンを使用中、元のシンボルが削除される前に置換要素の使用を開始できます。
バージョン 2.0.x にすぐにアップグレードする必要がある場合は、使用中のプログラミング言語の[変更履歴を参照し](about-versions.md)、レガシーシンボルを変更履歴が推奨するシンボルに置き換えます。
## 構成の競合: コミットメントポリシーとアルゴリズムスイート
[コミットメントポリシー](concepts.md#commitment-policy)と競合するアルゴリズムスイートを指定した場合は、暗号化の呼び出しが*構成の競合*というエラーで失敗します。
このタイプのエラーを回避するには、アルゴリズムスイートを指定しないでください。デフォルトでは、 AWS Encryption SDK は、コミットメントポリシーと互換性のある最も安全なアルゴリズムを選択します。ただし、署名なしなどのアルゴリズムスイートを指定する必要がある場合は、コミットメントポリシーと互換性のあるアルゴリズムスイートを必ず選択してください。
| コミットメントポリシー | 互換性のあるアルゴリズムスイート |
| --- | --- |
| ForbidEncryptAllowDecrypt | 次のようにキーコミットメントの*ない*アルゴリズムスイートAES\$1256\$1GCM\$1IV12\$1TAG16\$1HKDF\$1SHA384\$1ECDSA\$1P384 ([03 78](algorithms-reference.md)) (署名付き) `AES_256_GCM_IV12_TAG16_HKDF_SHA256` ([01 78](algorithms-reference.md)) (署名なし) |
| RequireEncryptAllowDecryptRequireEncryptRequireDecrypt | 次のようにキーコミットメントの*ある*アルゴリズムスイートAES\$1256\$1GCM\$1HKDF\$1SHA512\$1COMMIT\$1KEY\$1ECDSA\$1P384 ([05 78](algorithms-reference.md)) (署名付き) `AES_256_GCM_HKDF_SHA512_COMMIT_KEY` ([04 78](algorithms-reference.md)) (署名なし) |
アルゴリズムスイートを指定していないときにこのエラーが発生した場合は、競合するアルゴリズムスイートが[暗号化マテリアルマネージャー](concepts.md#crypt-materials-manager) (CMM) によって選択されている可能性があります。デフォルト CMM では、競合するアルゴリズムスイートは選択されませんが、カスタム CMM はそれを選択する可能性があります。ヘルプについては、カスタム CMM のドキュメントを参照してください。
## 構成の競合: コミットメントポリシーと暗号化テキスト
`RequireEncryptRequireDecrypt` [コミットメントポリシー](concepts.md#commitment-policy)では、 AWS Encryption SDK は[キーコミットメント](concepts.md#key-commitment)なしで暗号化されたメッセージを復号できません。キーコミットメントなしでメッセージを復号 AWS Encryption SDK するように に要求すると、*設定の競合*エラーが返されます。
このエラーを回避するには、`RequireEncryptRequireDecrypt` コミットメントポリシーの設定前に、キーコミットメントなしで暗号化されたすべての暗号化テキストを復号してキーコミットメントありで再暗号化するか、別のアプリケーションによって処理してください。このエラーが発生した場合は、競合する暗号化テキストのエラーを返すか、コミットメントポリシーを一時的に `RequireEncryptAllowDecrypt` に変更できます。
まず最新 1.x バージョン (バージョン 1.7.x 以降) へにアップグレードせずに、1.7.x より前のバージョンからバージョン 2.0.x 以降へアップグレードしたためにこのエラーが発生した場合、バージョン 2.0.x 以降にアップグレードする前に、最新 1.x バージョンに[ロールバック](#migration-rollback)し、そのバージョンをすべてのホストにデプロイすることを検討してください。ヘルプについては、「[を移行およびデプロイする方法 AWS Encryption SDK](migration-guide.md)」を参照してください。
## キーコミットメントの検証の失敗
キーコミットメントで暗号化されたメッセージを復号するとき、「*キーコミットメントの検証に失敗しました*」というエラーメッセージが表示される場合があります。これは、[暗号化されたメッセージ](concepts.md#DEK)のデータキーがメッセージの一意のデータキーと同一ではないために復号呼び出しが失敗したことを示します。復号時にデータキーを検証すると、[キーコミットメント](concepts.md#key-commitment)により、複数のプレーンテキストが生成される可能性のあるメッセージを復号化しないように保護されます。
このエラーは、復号しようとした暗号化されたメッセージが、 AWS Encryption SDKによって返されなかったことを示します。これは、手動で作成されたメッセージであるか、データ破損の結果である可能性があります。このエラーが発生した場合、アプリケーションはメッセージを拒否して続行するか、新しいメッセージの処理を停止できます。
## その他の暗号化の失敗
暗号化は複数の理由で失敗する可能性があります。Discovery モードでは、[AWS KMS 検出キーリング](use-kms-keyring.md#kms-keyring-discovery)または[マスターキープロバイダー](migrate-mkps-v2.md)を使用してメッセージを暗号化できません。
[使用許可](use-kms-keyring.md#kms-keyring-permissions)のあるラッピングキーを含むキーリングまたはマスターキープロバイダーを暗号化に指定してください。アクセス許可の詳細については AWS KMS keys、「 *AWS Key Management Service デベロッパーガイド*[」の「キーポリシーの表示](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-viewing.html)」および[「 へのアクセスの確認 AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/determining-access.html)」を参照してください。
## その他の復号化の失敗
暗号化されたメッセージを復号化しようとして失敗した場合は、 AWS Encryption SDK がメッセージ内の暗号化されたデータキーを復号できなかった (またはしなかった) ことを示します。
ラッピングキーを指定するキーリングまたはマスターキープロバイダーを使用した場合、 は指定したラッピングキーのみ AWS Encryption SDK を使用します。意図したラッピングキーを使用していて、ラッピングキーの少なくとも 1 つに対する `kms:Decrypt` 権限があることを確認してください。を使用している場合は AWS KMS keys、フォールバックとして、[AWS KMS 検出モードで検出キーリング](use-kms-keyring.md#kms-keyring-discovery)または[マスターキープロバイダー](migrate-mkps-v2.md)を使用してメッセージを復号化できます。オペレーションが成功した場合は、プレーンテキストを返す前に、メッセージの復号に使用されるキーが信頼できるキーであることを確認します。
## ロールバックに関する考慮事項
アプリケーションがデータの暗号化または復号化に失敗した場合は、通常、コードシンボル、キーリング、マスターキープロバイダー、または[コミットメントポリシー](concepts.md#commitment-policy)を更新すると問題が解決することがあります。ただし、場合によっては、アプリケーションを以前のバージョンの AWS Encryption SDKにロールバックすることが最善であると判断することもあります。
ロールバックする必要がある場合は、注意して実行してください。1.7.*x* AWS Encryption SDK より前のバージョンの では、[キーコミットメント](concepts.md#key-commitment)で暗号化された暗号文を復号できません。
+ 最新 1.x バージョンから AWS Encryption SDK の前のバージョンにロールバックすることは、一般的には安全です。以前のバージョンでサポートされていないシンボルやオブジェクトを使用するには、コードに加えた変更を元に戻さなければならない場合があります。
+ バージョン 2.0.x 以降でキーコミットメントによる暗号化を開始した場合は (コミットメントポリシーを `RequireEncryptAllowDecrypt` に設定した場合は)、バージョン 1.7.x にロールバックできますが、それより前のバージョンにはロールバックできません。1.7.*x* AWS Encryption SDK より前のバージョンの では、[キーコミットメント](concepts.md#key-commitment)で暗号化された暗号文を復号できません。
すべてのホストがキーコミットメントで復号化できるようになる前に、誤ってキーコミットによる暗号化を有効にした場合は、ロールバックするのではなく、ロールアウトを続行することをお勧めします。メッセージが一時的であるか、安全にドロップできる場合は、メッセージの損失を伴うロールバックを検討してください。ロールバックが必要な場合は、すべてのメッセージを復号化して再暗号化するツールを作成することを検討してください。