翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS Encryption SDK プログラミング言語
AWS Encryption SDK は、次のプログラミング言語で使用できます。言語実装はすべて相互運用可能です。ある言語実装で暗号化し、別の言語実装で復号できます。相互運用性は、言語の制約を受ける可能性があります。その場合の制約については、言語実装に関するトピックで説明します。また、暗号化および復号を行う場合は、互換性のあるキーリング、またはマスターキーとマスターキープロバイダーを使用する必要があります。詳細については、[キーリングの互換性](choose-keyring.md#keyring-compatibility) を参照してください
**Topics**
+ [C](c-language.md)
+ [.NET](dot-net.md)
+ [Go](go.md)
+ [Java](java.md)
+ [JavaScript](javascript.md)
+ [Python](python.md)
+ [Rust](rust.md)
+ [コマンドラインインターフェイス](crypto-cli.md)
# AWS Encryption SDK for C
AWS Encryption SDK for C は、C でアプリケーションを記述しているデベロッパー向けにクライアント側の暗号化ライブラリを提供します。また、 AWS Encryption SDK 高レベルのプログラミング言語で を実装するための基盤としても役立ちます。
のすべての実装と同様に AWS Encryption SDK、 は高度なデータ保護機能 AWS Encryption SDK for C を提供します。これには[エンベロープ暗号化](concepts.md#envelope-encryption)、追加の認証データ (AAD)、キー取得および署名で使用する 256 ビット AES-GCM などのセキュアで認証済みの対称キー[アルゴリズムスイート](concepts.md#crypto-algorithm)などが含まれます。
のすべての言語固有の実装 AWS Encryption SDK は完全に相互運用可能です。たとえば、 を使用してデータを暗号化 AWS Encryption SDK for C し、[AWS Encryption CLI](crypto-cli.md) を含む[サポートされている任意の言語実装](programming-languages.md)で復号できます。
AWS Encryption SDK for C では、 が AWS Key Management Service () とやり取り AWS SDK for C\$1\$1 する必要がありますAWS KMS。オプションの [AWS KMS キーリング](use-kms-keyring.md) を使用する場合にのみ、使用する必要があります。ただし、 AWS Encryption SDK には AWS KMS やその他の AWS サービスは必要ありません。
**詳細はこちら**
+ を使用したプログラミングの詳細については AWS Encryption SDK for C、[C の例](c-examples.md)、GitHub の [aws-encryption-sdk-c リポジトリ](https://github.com/aws/aws-encryption-sdk-c/)[の例](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples)、および [AWS Encryption SDK for C API ドキュメント](https://aws.github.io/aws-encryption-sdk-c/html/)を参照してください。
+ を使用して複数の で復号できるようにデータを AWS Encryption SDK for C 暗号化する方法については AWS リージョン、 AWS セキュリティブログの[AWS Encryption SDK 「C の を使用して複数のリージョンで暗号文を復号する方法](https://aws.amazon.com/blogs/security/how-to-decrypt-ciphertexts-multiple-regions-aws-encryption-sdk-in-c/)」を参照してください。
**Topics**
+ [インストール](c-language-installation.md)
+ [C SDK を使用する](c-language-using.md)
+ [例](c-examples.md)
# のインストール AWS Encryption SDK for C
AWS Encryption SDK for Cの最新バージョンをインストールします。
**注記**
2.0.0 より AWS Encryption SDK for C 前の のすべてのバージョンは[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.0.x 以降から AWS Encryption SDK for C の最新バージョンにコードやデータを変更せずに安全に更新できます。ただし、バージョン 2.0.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。1.7.x より前のバージョンから 2.0.x 以降のバージョンに更新するには、まず AWS Encryption SDK for Cの最新の 1.x バージョンに更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
をインストールして構築する詳細な手順は、[aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) リポジトリの AWS Encryption SDK for C [README ファイル](https://github.com/aws/aws-encryption-sdk-c/#readme)にあります。Amazon Linux、Ubuntu、macOS、およびWindowsプラットフォームで構築するための手順が含まれています。
開始前に、 AWS Encryption SDKで [AWS KMS キーリング](use-kms-keyring.md)を使用するかどうかを決定してください。 AWS KMS キーリングを使用する場合は、 をインストールする必要があります AWS SDK for C\$1\$1。[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) () を操作するには AWS SDK が必要ですAWS KMS。 AWS KMS キーリングを使用すると、 AWS Encryption SDK は AWS KMS を使用して、データを保護する暗号化キーを生成および保護します。
raw AES キーリング、raw RSA キーリング、キーリングを含まないマルチキーリングなど、別の AWS KMS キーリングタイプ AWS SDK for C\$1\$1 を使用している場合は、 をインストールする必要はありません。ただし、未加工のキーリングタイプを使用する場合は、独自の未加工のラッピングキーを生成して保護する必要があります。
インストールに問題がある場合は、`aws-encryption-sdk-c` リポジトリで[問題を提起](https://github.com/aws/aws-encryption-sdk-c/issues)するか、このページのフィードバックリンクのいずれかを使用してください。
# の使用 AWS Encryption SDK for C
このトピックでは、他のプログラミング言語の実装ではサポート AWS Encryption SDK for C されていない の機能の一部について説明します。
このセクションの例では、 AWS Encryption SDK for Cの[バージョン 2.0.*x*](about-versions.md) 以降の使用方法について説明します。前バージョンを使用する例については、GitHub の [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) リポジトリの[リリース](https://github.com/aws/aws-encryption-sdk-c/releases)リストで使用中のリリースを検索してください。
を使用したプログラミングの詳細については AWS Encryption SDK for C、[C の例](c-examples.md)、GitHub の [aws-encryption-sdk-c リポジトリ](https://github.com/aws/aws-encryption-sdk-c/)[の例](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples)、および [AWS Encryption SDK for C API ドキュメント](https://aws.github.io/aws-encryption-sdk-c/html/)を参照してください。
「[キーリング](choose-keyring.md)」も参照してください。
**Topics**
+ [データの暗号化と復号の流れ](#c-language-using-pattern)
+ [参照カウント](#c-language-using-release)
## データの暗号化と復号の流れ
を使用する場合は AWS Encryption SDK for C、次のようなパターンに従います。[キーリング](concepts.md#keyring)の作成、キーリングを使用する [CMM](concepts.md#crypt-materials-manager) の作成、CMM (およびキーリング) を使用するセッションの作成、セッションの処理。
1. エラー文字列をロード
C コードまたは C\$1\$1 コードで `aws_cryptosdk_load_error_strings()` メソッドを呼び出します。デバッグに非常に役立つエラー情報をロードします。
`main` メソッド内でなど、1 回だけ呼び出す必要があります。
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
2. キーリングを作成します。
データキーの暗号化に使用するラッピングキーで[キーリング](concepts.md#keyring)を設定します。この例では、1 つの[AWS KMS キーリング](use-kms-keyring.md)で キーリングを使用しますが AWS KMS key、代わりに任意のタイプのキーリングを使用できます。
AWS KMS key の暗号化キーリングで を識別するには AWS Encryption SDK for C、[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) または[エイリアス ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) を指定します。復号キーリングでは、キー ARN を使用する必要があります。詳細については、「[AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)」を参照してください。
```
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);
```
3. セッションを作成します。
では AWS Encryption SDK for C、セッションを使用して、サイズに関係なく、単一のプレーンテキストメッセージを**暗号化するか、単一の暗号テキストメッセージを復号します。セッションでは、そのプロセスを通じてメッセージの状態が維持されます。
アロケーター、キーリング、モード (`AWS_CRYPTOSDK_ENCRYPT` または `AWS_CRYPTOSDK_DECRYPT`) を使用してセッションを設定します。セッションのモードを変更する必要がある場合は、`aws_cryptosdk_session_reset` メソッドを使用します。
キーリングを使用してセッションを作成すると、 は自動的にデフォルトの暗号化マテリアルマネージャー (CMM) AWS Encryption SDK for C を作成します。このオブジェクトの作成、管理、破棄を行う必要はありません。
例えば、次のセッションでは、ステップ 1 で定義したアロケーターとキーリングを使用します。データを暗号化する場合は、モードは `AWS_CRYPTOSDK_ENCRYPT` です。
```
struct aws_cryptosdk_session * session = aws_cryptosdk_session_new_from_keyring_2(allocator, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
```
4. データを暗号化または復号します。
セッションでデータを処理するには、`aws_cryptosdk_session_process` メソッドを使用します。入力バッファがプレーンテキスト全体を保持するのに十分なサイズであり、出力バッファが暗号化テキスト全体を保持するのに十分なサイズである場合は、`aws_cryptosdk_session_process_full` を呼び出すことができます。ただし、ストリーミングデータを処理する必要がある場合は、`aws_cryptosdk_session_process` をループで呼び出すことができます。例については、[file\$1streaming.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/file_streaming.cpp) の例を参照してください。`aws_cryptosdk_session_process_full` は AWS Encryption SDK 、バージョン 1.9.*x* および 2.2.*x* で導入されています。
セッションでデータを暗号化するように設定されている場合、プレーンテキストフィールドは入力、暗号化テキストフィールドは出力を表します。`plaintext` フィールドは、暗号化するメッセージを保持しており、`ciphertext` フィールドは、暗号化メソッドによって返る[暗号化されたメッセージ](message-format.md)を取得します。
```
/* Encrypting data */
aws_cryptosdk_session_process_full(session,
ciphertext,
ciphertext_buffer_size,
&ciphertext_length,
plaintext,
plaintext_length)
```
セッションでデータを復号するように設定されている場合、暗号化テキストフィールドは入力、プレーンテキストフィールドは出力を表します。`ciphertext` フィールドは、暗号化メソッドより返る[暗号化されたメッセージ](message-format.md)を保持しており、`plaintext` フィールドは、復号メソッドより返るプレーンテキストメッセージを取得します。
データを復号するには、`aws_cryptosdk_session_process_full` メソッドを呼び出します。
```
/* Decrypting data */
aws_cryptosdk_session_process_full(session,
plaintext,
plaintext_buffer_size,
&plaintext_length,
ciphertext,
ciphertext_length)
```
## 参照カウント
メモリリークを防ぐために、作成したすべてのオブジェクトへの参照はオブジェクトの使用が完了したら解放するようにします。それ以外の場合は、最終的にメモリリークが発生します。SDK には、この作業を簡略化するメソッドがあります。
次のいずれかの子オブジェクトを使用して親オブジェクトを作成すると、親オブジェクトは子オブジェクトへの参照を作成して管理します。
+ [キーリング](concepts.md#keyring) (キーリングを使用したセッションの作成など)
+ デフォルトの[暗号化マテリアルマネージャー](concepts.md#crypt-materials-manager) (CMM) (デフォルトの CMM を使用したセッションやカスタム CMM の作成など)
+ [データキーキャッシュ](data-key-caching.md) (キーリングとキャッシュを使用したキャッシュ CMM の作成など)
子オブジェクトへの独立参照が必要でない限り、親オブジェクトを作成したら子オブジェクトへの参照はすぐに解放できます。親オブジェクトが破棄されると、残っている子オブジェクトへの参照は解放されます。このパターンでは、各オブジェクトへの参照を必要な期間だけ保持することができます。また、参照の未開放が原因でメモリリークが発生することもありません。
作成した子オブジェクトへの参照の明示的な解放は、お客様が行う必要があります。SDK が作成したオブジェクトへの参照の管理は、お客様が行う必要はありません。SDK がオブジェクト (`aws_cryptosdk_caching_cmm_new_from_keyring` メソッドがセッションに追加するデフォルトの CMM など) を作成する場合は、SDK がオブジェクトとその参照の作成と破棄を管理します。
次の例では、[キーリング](concepts.md#keyring)を使用してセッションを作成すると、セッションはキーリングへの参照を作成し、セッションが破棄されるまでその参照を管理します。キーリングへの追加の参照を管理する必要がない場合は、セッションを作成したら `aws_cryptosdk_keyring_release` メソッドを使用してキーリングオブジェクトを解放できます。このメソッドでは、キーリングの参照カウントは減少します。`aws_cryptosdk_session_destroy` を呼び出してセッションを破棄すると、セッションのキーリングへの参照は解放されます。
```
// The session gets a reference to the keyring.
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, keyring);
// After you create a session with a keyring, release the reference to the keyring object.
aws_cryptosdk_keyring_release(keyring);
```
複数のセッションでキーリングを再利用したり、CMM でアルゴリズムスイートを指定したりするなど、より複雑なタスクの場合は、オブジェクトへの独立参照を管理する必要があります。その場合は、解放のメソッドをすぐに呼び出さないでください。代わりに、セッションの破棄だけでなく、オブジェクトを使用しなくなったときにも参照を解放します。
この参照カウント手法は、[データキーキャッシュ](data-key-caching.md)用の CMM のキャッシングなど、代替 CMM を使用している場合にも機能します。キャッシュとキーリングからキャッシュ CMM を作成すると、キャッシュ CMM はその両方のオブジェクトへの参照を作成します。別のタスクでそれらが必要でない限り、キャッシュ CMM を作成したらキャッシュとキーリングへの独立参照はすぐに解放できます。その後、キャッシュ CMM を使用してセッションを作成するときに、キャッシュ CMM への参照を解放できます。
作成したオブジェクトへの参照の明示的な解放は、お客様が行う必要があります。メソッドが作成するオブジェクト (キャッシュ CMM の元になるデフォルトの CMM など) は、メソッドが管理します。
```
/ Create the caching CMM from a cache and a keyring.
struct aws_cryptosdk_cmm *caching_cmm = aws_cryptosdk_caching_cmm_new_from_keyring(allocator, cache, kms_keyring, NULL, 60, AWS_TIMESTAMP_SECS);
// Release your references to the cache and the keyring.
aws_cryptosdk_materials_cache_release(cache);
aws_cryptosdk_keyring_release(kms_keyring);
// Create a session with the caching CMM.
struct aws_cryptosdk_session *session = aws_cryptosdk_session_new_from_cmm_2(allocator, AWS_CRYPTOSDK_ENCRYPT, caching_cmm);
// Release your references to the caching CMM.
aws_cryptosdk_cmm_release(caching_cmm);
// ...
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK for C 例
次の例は、 AWS Encryption SDK for C を使用してデータを暗号化および復号する方法を示しています。
このセクションの例では、 AWS Encryption SDK for Cのバージョン 2.0.x 以降の使用方法について説明します。 前バージョンを使用する例については、GitHub の [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) リポジトリの[リリース](https://github.com/aws/aws-encryption-sdk-c/releases)リストで使用中のリリースを検索してください。
をインストールしてビルドすると AWS Encryption SDK for C、これらの例やその他の例のソースコードが `examples` サブディレクトリに含まれ、コンパイルされて `build` ディレクトリに組み込まれます。GitHub の [aws-encryption-sdk-c](https://github.com/aws/aws-encryption-sdk-c/) リポジトリの [examples](https://github.com/aws/aws-encryption-sdk-c/tree/master/examples) サブディレクトリで検索することもできます。
**Topics**
+ [文字列の暗号化と復号](#c-example-strings)
## 文字列の暗号化と復号
次の例は、 を使用して文字列を AWS Encryption SDK for C 暗号化および復号する方法を示しています。
この例では、 AWS KMS key [AWS Key Management Service (AWS KMS)](https://docs.aws.amazon.com/kms/latest/developerguide/) の を使用してデータ[AWS KMS キー](use-kms-keyring.md)を生成および暗号化するキーリングの一種である キーリングを使用しています。この例には C\$1\$1 で記述されたコードが含まれています。 AWS Encryption SDK for C では AWS SDK for C\$1\$1 、 AWS KMS キーリングを使用する AWS KMS ときに を呼び出す必要があります。raw AES キーリング AWS KMS、raw RSA キーリング、または キーリングを含まないマルチキーリングなど、 とやり取りしない AWS KMS キーリングを使用している場合、 AWS SDK for C\$1\$1 は必要ありません。
の作成については AWS KMS key、「 *AWS Key Management Service デベロッパーガイド*」の[「キーの作成](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)」を参照してください。 AWS KMS キーリング AWS KMS keys で を識別する方法については、「」を参照してください[AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)。
**完全なコードサンプルの参照**: [string.cpp](https://github.com/aws/aws-encryption-sdk-c/blob/master/examples/string.cpp)
**Topics**
+ [文字列の暗号化](#c-example-string-encrypt)
+ [文字列の復号](#c-example-string-decrypt)
### 文字列の暗号化
この例の最初の部分では、 AWS KMS キーリングと キーリング AWS KMS key を使用してプレーンテキスト文字列を暗号化します。
ステップ 1. エラー文字列をロード
C コードまたは C\$1\$1 コードで `aws_cryptosdk_load_error_strings()` メソッドを呼び出します。デバッグに非常に役立つエラー情報をロードします。
`main` メソッド内でなど、1 回だけ呼び出す必要があります。
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
ステップ 2: キーリングを作成します。
暗号化用の AWS KMS キーリングを作成します。この例のキーリングは 1 つで設定されていますが AWS KMS key、 AWS KMS keys 異なるアカウント AWS リージョン や異なるアカウントを含む AWS KMS keys複数の で AWS KMS キーリングを設定できます。
AWS KMS key の暗号化キーリングで を識別するには AWS Encryption SDK for C、[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) または[エイリアス ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) を指定します。復号キーリングでは、キー ARN を使用する必要があります。詳細については、「[AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)」を参照してください。
[AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)
複数の を使用してキーリングを作成するときは AWS KMS keys、プレーンテキストデータキーの生成と暗号化 AWS KMS key に使用される と、同じプレーンテキストデータキーを暗号化 AWS KMS keys する追加のオプションの配列を指定します。この場合、ジェネレーターのみを指定します AWS KMS key。
このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。
```
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);
```
ステップ 3: セッションを作成します。
アロケーター、モードの列挙子、キーリングを使用してセッションを作成します。
各セッションは、`AWS_CRYPTOSDK_ENCRYPT` モード (暗号化) または `AWS_CRYPTOSDK_DECRYPT` モード (復号) にする必要があります。既存のセッションのモードを変更するには、`aws_cryptosdk_session_reset` メソッドを使用します。
キーリングを使用してセッションを作成したら、SDK が提供する機能を使用してキーリングへの参照を解放できます。セッションは、その有効期間中、キーリングオブジェクトへの参照を保持します。セッションを破棄すると、キーリングオブジェクトやセッションオブジェクトへの参照が解放されます。この[参照カウント](c-language-using.md#c-language-using-release)方式は、メモリリークを防ぎ、オブジェクトが使用中に解放されないようにするために役立ちます。
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_ENCRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
ステップ 4: 暗号化コンテキストを設定します。
[暗号化コンテキスト](concepts.md#encryption-context)は、任意の、シークレットではない追加認証データです。暗号化時に暗号化コンテキストを指定すると、 は暗号化コンテキストを暗号化テキストに AWS Encryption SDK 暗号化バインドし、データの復号に同じ暗号化コンテキストが必要になります。暗号化コンテキストの使用はオプションですが、ベストプラクティスとして推奨します。
まず、暗号化コンテキスト文字列を含むハッシュテーブルを作成します。
```
/* Allocate a hash table for the encryption context */
int set_up_enc_ctx(struct aws_allocator *alloc, struct aws_hash_table *my_enc_ctx)
// Create encryption context strings
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key1, "Example");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value1, "String");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_key2, "Company");
AWS_STATIC_STRING_FROM_LITERAL(enc_ctx_value2, "MyCryptoCorp");
// Put the key-value pairs in the hash table
aws_hash_table_put(my_enc_ctx, enc_ctx_key1, (void *)enc_ctx_value1, &was_created)
aws_hash_table_put(my_enc_ctx, enc_ctx_key2, (void *)enc_ctx_value2, &was_created)
```
セッション内の暗号化コンテキストへの変更可能なポインタを取得します。次に、`aws_cryptosdk_enc_ctx_clone` 関数を使用して、暗号化コンテキストをセッションにコピーします。コピーを `my_enc_ctx` に保持しているため、データの復号後に値を検証することができます。
暗号化コンテキストはセッションの一部であり、セッション処理関数に渡されるパラメータではありません。これにより、メッセージ全体を暗号化するためにセッション処理関数が複数回呼び出された場合でも、必ずメッセージのすべてのセグメントに同じ暗号化コンテキストが使用されるようになります。
```
struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr_mut(session);
aws_cryptosdk_enc_ctx_clone(alloc, session_enc_ctx, my_enc_ctx)
```
ステップ 5: 文字列を暗号化します。
プレーンテキストの文字列を暗号化するには、暗号化モードのセッションで `aws_cryptosdk_session_process_full` メソッドを使用します。このメソッドは、 AWS Encryption SDK バージョン 1.9.*x* および 2.2.*x* で導入され、非ストリーミング暗号化と復号化用に設計されています。ストリーミングデータを処理するには、ループで `aws_cryptosdk_session_process` を呼び出します。
暗号化する場合、プレーンテキストフィールドは入力フィールド、暗号化テキストフィールドは出力フィールドです。処理が完了すると、`ciphertext_output` フィールドには、[暗号化されたメッセージ](concepts.md#message) (例: 実際の暗号化テキスト、暗号化されたデータキー、暗号化コンテキスト) が含まれます。この暗号化されたメッセージは、サポートされているプログラミング言語 AWS Encryption SDK の を使用して復号できます。
```
/* Gets the length of the plaintext that the session processed */
size_t ciphertext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
ciphertext_output,
ciphertext_buf_sz_output,
&ciphertext_len_output,
plaintext_input,
plaintext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 8;
}
```
ステップ 6: セッションをクリーンアップします。
最終ステップでは、CMM とキーリングへの参照を含むセッションを破棄します。
必要に応じて、セッションを破棄せずに、同じキーリングと CMM でセッションを再利用し、文字列の復号や、他のメッセージの暗号化または復号を行うことができます。復号のセッションを使用するには、`aws_cryptosdk_session_reset` メソッドを使用して、モードを `AWS_CRYPTOSDK_DECRYPT` に変更します。
### 文字列の復号
この例の 2 番目の部分では、元の文字列の暗号化テキストを含む暗号化されたメッセージを復号します。
ステップ 1: エラー文字列をロード
C コードまたは C\$1\$1 コードで `aws_cryptosdk_load_error_strings()` メソッドを呼び出します。デバッグに非常に役立つエラー情報をロードします。
`main` メソッド内でなど、1 回だけ呼び出す必要があります。
```
/* Load error strings for debugging */
aws_cryptosdk_load_error_strings();
```
ステップ 2: キーリングを作成します。
でデータを復号すると AWS KMS、暗号化 API が返した暗号化された[メッセージを](concepts.md#message)渡します。[Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) は を入力 AWS KMS key として受け取りません。代わりに、 は同じ AWS KMS を使用して AWS KMS key 、暗号化に使用した暗号文を復号します。ただし、 AWS Encryption SDK では、暗号化および復号 AWS KMS keys 時に で AWS KMS キーリングを指定できます。
復号では、暗号化されたメッセージの復号 AWS KMS keys に使用する のみを使用してキーリングを設定できます。たとえば、組織内の特定のロール AWS KMS key で使用される のみを使用してキーリングを作成するとします。復号キーリングに表示され AWS KMS key ない限り、 AWS Encryption SDK は を使用しません。指定したキーリング AWS KMS keys で を使用して暗号化されたデータキーを SDK が復号できない場合、キーリング AWS KMS keys の がデータキーの暗号化に使用されなかったか、呼び出し元にキーリング AWS KMS keys の を使用して復号するアクセス許可がないため、復号呼び出しは失敗します。
復号キーリング AWS KMS key に を指定する場合は、その[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) を使用する必要があります。[エイリアス ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-arn) は、暗号化キーリングでのみ許可されます。 AWS KMS キーリング AWS KMS keys で を識別する方法については、「」を参照してください[AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)。
この例では、文字列の暗号化 AWS KMS key に使用されるものと同じ で設定されたキーリングを指定します。このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。
```
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);
```
ステップ 3: セッションを作成します。
アロケーターとキーリングを使用してセッションを作成します。セッションを復号用に設定するには、セッションを `AWS_CRYPTOSDK_DECRYPT` モードに設定します。
キーリングを使用してセッションを作成したら、SDK が提供する機能を使用してキーリングへの参照を解放できます。セッションは、その有効期間中、キーリングオブジェクトへの参照を保持します。セッションを破棄すると、セッションとキーリングの両方が解放されます。この参照カウント方式は、メモリリークを防ぎ、オブジェクトが使用中に解放されないようにするために役立ちます。
```
struct aws_cryptosdk_session *session =
aws_cryptosdk_session_new_from_keyring_2(alloc, AWS_CRYPTOSDK_DECRYPT, kms_keyring);
/* When you add the keyring to the session, release the keyring object */
aws_cryptosdk_keyring_release(kms_keyring);
```
ステップ 4: 文字列を復号します。
文字列を復号するには、復号用に設定されているセッションで `aws_cryptosdk_session_process_full` メソッドを使用します。 AWS Encryption SDK バージョン 1.9.*x* および 2.2.*x* で導入されたこのメソッドは、非ストリーミングの暗号化および復号化のために設計されています。ストリーミングデータを処理するには、ループで `aws_cryptosdk_session_process` を呼び出します。
復号する際、暗号化テキストフィールドは入力フィールド、プレーンテキストフィールドは出力フィールドです。`ciphertext_input` フィールドには、返るメソッドを暗号化する[暗号化されたメッセージ](message-format.md)が含まれます。処理が完了すると、`plaintext_output` フィールドには、プレーンテキスト (復号された) 文字列が含まれます。
```
size_t plaintext_len_output;
if (AWS_OP_SUCCESS != aws_cryptosdk_session_process_full(session,
plaintext_output,
plaintext_buf_sz_output,
&plaintext_len_output,
ciphertext_input,
ciphertext_len_input)) {
aws_cryptosdk_session_destroy(session);
return 13;
}
```
ステップ 5: 暗号化コンテキストを確認します。
実際の暗号化コンテキスト (メッセージの復号に使用されたもの) に、メッセージの暗号化時に指定した暗号化コンテキストが含まれていることを確認します。[暗号化マテリアルマネージャー](concepts.md#crypt-materials-manager) (CMM) によって、メッセージの暗号化前に指定した暗号化コンテキストにペアが追加される場合があるため、実際の暗号化コンテキストには、追加のペアが含まれる場合があります。
では AWS Encryption SDK for C、SDK が返す暗号化されたメッセージに暗号化コンテキストが含まれているため、復号時に暗号化コンテキストを指定する必要はありません。ただし、プレーンテキストのメッセージが返る前に、復号関数を使用して、返った暗号化コンテキスト内のすべてのペアが、メッセージの復号に使用された暗号化コンテキスト内にあることを確認する必要があります。
まず、セッション内のハッシュテーブルへの読み取り専用ポインタを取得します。このハッシュテーブルには、メッセージの復号に使用された暗号化コンテキストが含まれています。
```
const struct aws_hash_table *session_enc_ctx = aws_cryptosdk_session_get_enc_ctx_ptr(session);
```
次に、暗号化時にコピーした `my_enc_ctx` ハッシュテーブル内の暗号化コンテキストをループします。暗号化に使用された `my_enc_ctx` ハッシュテーブルの各ペアが、復号に使用された `session_enc_ctx` ハッシュテーブルに表示されていることを確認します。キーが見つからない場合や、キーが別の値の場合は、処理を停止し、エラーメッセージを書き込みます。
```
for (struct aws_hash_iter iter = aws_hash_iter_begin(my_enc_ctx); !aws_hash_iter_done(&iter);
aws_hash_iter_next(&iter)) {
struct aws_hash_element *session_enc_ctx_kv_pair;
aws_hash_table_find(session_enc_ctx, iter.element.key, &session_enc_ctx_kv_pair)
if (!session_enc_ctx_kv_pair ||
!aws_string_eq(
(struct aws_string *)iter.element.value, (struct aws_string *)session_enc_ctx_kv_pair->value)) {
fprintf(stderr, "Wrong encryption context!\n");
abort();
}
}
```
ステップ 6: セッションをクリーンアップします。
暗号化コンテキストを確認したら、セッションは破棄、または再利用できます。セッションを再設定する必要がある場合は、`aws_cryptosdk_session_reset` メソッドを使用します。
```
aws_cryptosdk_session_destroy(session);
```
# AWS Encryption SDK .NET 用
AWS Encryption SDK for .NET は、C\$1 やその他の .NET プログラミング言語でアプリケーションを記述している開発者向けのクライアント側の暗号化ライブラリです。Windows、macOS、Linux でサポートされています。
**注記**
AWS Encryption SDK for .NET のバージョン 4.0.0 がメッセージ仕様から逸脱しています AWS Encryption SDK 。その結果、バージョン 4.0.0 で暗号化されたメッセージは、.NET AWS Encryption SDK 用 のバージョン 4.0.0 以降でのみ復号できます。その他のプログラミング言語実装では復号化できません。
AWS Encryption SDK for .NET のバージョン 4.0.1 は、 AWS Encryption SDK メッセージ仕様に従ってメッセージを書き込み、他のプログラミング言語の実装と相互運用できます。デフォルトでは、バージョン 4.0.1 はバージョン 4.0.0 で暗号化されたメッセージを読み取ることができます。ただし、バージョン 4.0.0 で暗号化されたメッセージを復号化したくない場合は、[https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples/NetV4_0_0Example.cs) プロパティを指定してクライアントがこれらのメッセージを読み取らないようにすることができます。詳細については、GitHub の aws-encryption-sdk リポジトリにある [v4.0.1 リリースノート](https://github.com/aws/aws-encryption-sdk/releases/tag/v4.0.1)を参照してください。
AWS Encryption SDK for .NET は、以下の点 AWS Encryption SDK で の他のプログラミング言語実装とは異なります。
+ [データキーキャッシュ](data-key-caching.md) はサポートされていません
**注記**
AWS Encryption SDK for .NET のバージョン 4.*x* は、代替の暗号化マテリアルキャッシュソリューションである[AWS KMS 階層キーリング](use-hierarchical-keyring.md)をサポートしています。
+ ストリーミングデータはサポートしていません
+ .NET 用 AWS Encryption SDK から [ログ記録やスタックトレースはありません](#dot-net-debugging)
+ [が必要です AWS SDK for .NET](#dot-net-install)
AWS Encryption SDK for .NET には、 の他の言語実装のバージョン 2.0.*x* 以降で導入されたすべてのセキュリティ機能が含まれています AWS Encryption SDK。ただし、 AWS Encryption SDK for .NET を使用して、 の 2.0.*x* より前のバージョンの別の言語実装によって暗号化されたデータを復号する場合は AWS Encryption SDK、[コミットメントポリシー](concepts.md#commitment-policy)を調整する必要がある場合があります。詳細については、「[コミットメントポリシーの設定方法](migrate-commitment-policy.md#migrate-commitment-step1)」を参照してください。
AWS Encryption SDK for .NET は、仕様を記述する正式な検証言語である [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK の の製品であり、実装するコード、およびテストするための証明です。その結果、機能の正確性を保証するフレームワークに、 AWS Encryption SDK の機能を実装するライブラリができあがりました。
**詳細はこちら**
+ 代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
+ AWS Encryption SDK for .NET を使用したプログラミングの詳細については、GitHub の aws-encryption-sdk リポジトリの [https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/) ディレクトリを参照してください。
**Topics**
+ [インストールおよび構築](#dot-net-install)
+ [デバッグ](#dot-net-debugging)
+ [例](dot-net-examples.md)
## AWS Encryption SDK for .NET のインストール
AWS Encryption SDK for .NET は NuGet の [https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK](https://www.nuget.org/packages/AWS.Cryptography.EncryptionSDK)パッケージとして利用できます。for .NET AWS Encryption SDK のインストールと構築の詳細については、 `aws-encryption-sdk-net`リポジトリの [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/#readme) ファイルを参照してください。
**バージョン 3.x**
AWS Encryption SDK for .NET のバージョン 3.*x* は、Windows でのみ .NET Framework 4.5.2 – 4.8 をサポートしています。サポートされているすべてのオペレーティングシステムで、.NET Core 3.0 以降と.NET 5.0 以降をサポートします。
**バージョン 4.x**
AWS Encryption SDK for .NET のバージョン 4.*x* は、.NET 6.0 および .NET Framework net48 以降をサポートしています。バージョン 4.*x* には AWS SDK for .NET v3 が必要です。
**バージョン 5.x**
AWS Encryption SDK for .NET のバージョン 5.*x* は、.NET 6.0 および .NET Framework net48 以降をサポートしています。バージョン 5.*x* には、マテリアルプロバイダーライブラリ (MPL) のバージョン 2.*x* と AWS SDK for .NET v4 が必要です。
AWS Encryption SDK for .NET では、 AWS Key Management Service (AWS KMS) キーを使用していない場合 SDK for .NET でも、 が必要です。NuGet パッケージと共にインストールされます。ただし、 AWS KMS キーを使用している場合を除き、 AWS Encryption SDK for .NET では AWS アカウント、、 AWS 認証情報、または AWS サービスとのインタラクションは必要ありません。必要に応じて AWS アカウントを設定する方法については、「」を参照してください[AWS Encryption SDK での の使用 AWS KMS](getting-started.md)。
## for .NET AWS Encryption SDK のデバッグ
AWS Encryption SDK for .NET はログを生成しません。for .NET AWS Encryption SDK の例外は例外メッセージを生成しますが、スタックトレースは生成されません。
デバッグしやすいように、 SDK for .NETへのログ記録を必ず有効にしてください。からのログとエラーメッセージ SDK for .NET は、 で発生したエラーを for .NET AWS Encryption SDK のエラー SDK for .NET と区別するのに役立ちます。 SDK for .NET ログ記録については、「 *AWS SDK for .NET デベロッパーガイド*」の[AWSLogging](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-config-other.html#config-setting-awslogging)」を参照してください。(このトピックを確認するには、**[.NET Framework コンテンツを開く]** セクションを展開してください)。
# AWS Encryption SDK for .NET の例
次の例は、 AWS Encryption SDK for .NET でプログラミングするときに使用する基本的なコーディングパターンを示しています。具体的には、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。次に、各メソッドを呼び出す前に、メソッドの入力を定義するオブジェクトをインスタンス化します。これは、 SDK for .NETで使用するコーディングパターンとよく似ています。
代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
for .NET を使用したプログラミングのその他の例については、GitHub AWS Encryption SDK の`aws-encryption-sdk`リポジトリの `aws-encryption-sdk-net` ディレクトリにある[例](https://github.com/aws/aws-encryption-sdk/tree/mainline/AwsEncryptionSDK/runtimes/net/Examples)を参照してください。
## AWS Encryption SDK for .NET でのデータの暗号化
この例では、データを暗号化するための基本的なパターンを示しています。 1 つのラ AWS KMS ッピングキーで保護されたデータキーを使用して小さなファイルを暗号化します。
ステップ 1: AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。
まず、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。のメソッドを使用して、データを AWS Encryption SDK 暗号化および復号します。マテリアルプロバイダライブラリのメソッドを使用して、データを保護するキーを指定するキーリングを作成します。
AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化する方法は、.NET AWS Encryption SDK 用 のバージョン 3.*x* と 4.*x* で異なります。次の手順はすべて、.NET AWS Encryption SDK 用 のバージョン 3.*x* と 4.*x* の両方で同じです。
```
// Instantiate the AWS Encryption SDK and material providers
var encryptionSdk = AwsEncryptionSdkFactory.CreateDefaultAwsEncryptionSdk();
var materialProviders =
AwsCryptographicMaterialProvidersFactory.CreateDefaultAwsCryptographicMaterialProviders();
```
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングを作成する各メソッドには、対応する入力オブジェクトクラスがあります。たとえば、`CreateAwsKmsKeyring()` メソッドの入力オブジェクトを作成するには、`CreateAwsKmsKeyringInput` クラスのインスタンスを作成します。
このキーリングの入力では [ジェネレータキー](use-kms-keyring.md#kms-keyring-encrypt) は指定されていませんが、`KmsKeyId` パラメータで指定される単一の KMS キーはジェネレータキーとなります。データを暗号化するデータキーを生成し、暗号化します。
この入力オブジェクトには、KMS キー AWS リージョン の 用の AWS KMS クライアントが必要です。 AWS KMS クライアントを作成するには、 で `AmazonKeyManagementServiceClient` クラスをインスタンス化します SDK for .NET。パラメータなしで `AmazonKeyManagementServiceClient()` コンストラクタを呼び出すと、デフォルト値でクライアントが作成されます。
.NET AWS Encryption SDK 用 で暗号化するために使用される AWS KMS キーリングでは、キー ID、キー ARN、エイリアス名、またはエイリアス ARN を使用して [KMS キーを識別](use-kms-keyring.md#kms-keyring-id)できます。復号に使用される AWS KMS キーリングでは、キー ARN を使用して各 KMS キーを識別する必要があります。復号に暗号化キーリングを再利用する場合は、すべての KMS キーにキー ARN ID を使用します。
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
ステップ 3: キーリングを作成します。
キーリングを作成するには、キーリング入力オブジェクトを使用してキーリングメソッドを呼び出します。この例では、KMS キーを 1 つだけ取得する、この `CreateAwsKmsKeyring()` メソッドを使用しています。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
ステップ 4: 暗号化コンテキストを定義します。
[暗号化コンテキスト](concepts.md#encryption-context)はオプションですが、 の暗号化オペレーションでは強く推奨されます AWS Encryption SDK。1 つ以上の非シークレットキーと値のペアを定義できます。
.NET AWS Encryption SDK 用 のバージョン 4.*x* では、必要な暗号化コンテキスト [CMM を使用して、すべての暗号化リクエストで暗号化コンテキスト](configure.md#config-required-encryption-context-cmm)を要求できます。
```
// Define the encryption context
var encryptionContext = new Dictionary()
{
{"purpose", "test"}
};
```
ステップ 5: 暗号化用の入力オブジェクトを作成します。
`Encrypt()` メソッドを呼び出す前に、`EncryptInput` クラスのインスタンスを作成します。
```
string plaintext = File.ReadAllText("C:\\Documents\\CryptoTest\\TestFile.txt");
// Define the encrypt input
var encryptInput = new EncryptInput
{
Plaintext = plaintext,
Keyring = keyring,
EncryptionContext = encryptionContext
};
```
ステップ 6: プレーンテキストを暗号化します。
の `Encrypt()`メソッド AWS Encryption SDK を使用して、定義したキーリングを使用してプレーンテキストを暗号化します。
この `Encrypt() ` メソッドが返す `EncryptOutput` には、暗号化されたメッセージ (`Ciphertext`)、暗号化コンテキスト、アルゴリズムスイートを取得するメソッドがあります。
```
var encryptOutput = encryptionSdk.Encrypt(encryptInput);
```
ステップ 7: 暗号化されたメッセージを取得します。
for .NET AWS Encryption SDK の `Decrypt()`メソッドは、`EncryptOutput`インスタンス`Ciphertext`のメンバーを取得します。
`EncryptOutput` オブジェクトの `Ciphertext` メンバーは [暗号化されたメッセージ](concepts.md#message) であり、暗号化されたデータ、暗号化されたデータキー、メタデータ (暗号化コンテキストを含む) を含むポータブルオブジェクトです。暗号化されたメッセージを長期間安全に保管したり、`Decrypt()` メソッドに送信してプレーンテキストを復元することもできます。
```
var encryptedMessage = encryptOutput.Ciphertext;
```
## for .NET での厳密なモードで AWS Encryption SDK の復号化
ベストプラクティスでは、データを復号する際に使用するキーを指定することを推奨していますが、これは Strict モードと呼ばれるオプションです。 AWS Encryption SDK は、キーリングで指定した KMS キーのみを使用して暗号文を復号します。復号化キーリング内のキーには、データを暗号化したキーが少なくとも 1 つ含まれている必要があります。
この例は、.NET 用 AWS Encryption SDK による Strict モードでの復号化の基本パターンを示しています。
ステップ 1: AWS Encryption SDK および マテリアルプロバイダーライブラリをインスタンス化します。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。 AWS Encryption SDK for .NET の各キーリングメソッドには、対応する入力オブジェクトがあります。この例では、`CreateAwsKmsKeyring()` メソッドを使用してキーリングを作成しているため、入力用の `CreateAwsKmsKeyringInput` クラスをインスタンス化しています。
復号キーリングでは、キー ARN を使用して KMS キー を指定する必要があります。
```
string keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
// Instantiate the keyring input object
var kmsKeyringInput = new CreateAwsKmsKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
KmsKeyId = keyArn
};
```
ステップ 3: キーリングを作成します。
復号化キーリングを作成するために、この例では `CreateAwsKmsKeyring()` メソッドとキーリング入力オブジェクトを使用します。
```
var keyring = materialProviders.CreateAwsKmsKeyring(kmsKeyringInput);
```
ステップ 4: 復号化用の入力オブジェクトを作成します。
`Decrypt()` メソッドの入力オブジェクトを作成するには、`DecryptInput` クラスをインスタンス化します。
`DecryptInput()` コンストラクタの `Ciphertext` パラメータは、`Encrypt()` メソッドが返した `EncryptOutput` オブジェクトの `Ciphertext` メンバーを受け取ります。`Ciphertext` プロパティは [暗号化されたメッセージ](concepts.md#message) を表します。これには、 AWS Encryption SDK がメッセージの復号化に必要な暗号化されたデータ、暗号化されたデータキー、メタデータが含まれます。
.NET AWS Encryption SDK 用 のバージョン 4.*x* では、オプションの `EncryptionContext`パラメータを使用して、 `Decrypt()`メソッドで暗号化コンテキストを指定できます。
この `EncryptionContext` パラメータを使用して、暗号化時に使用された暗号化コンテキストが、暗号文の復号化に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名付きアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
var encryptedMessage = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = encryptedMessage,
Keyring = keyring,
EncryptionContext = encryptionContext // OPTIONAL
};
```
ステップ 5: 暗号文を復号化します。
```
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
ステップ 6: 暗号化コンテキストを確認します — バージョン 3.x
for .NET のバージョン 3.*x* AWS Encryption SDK の `Decrypt()`メソッドは、暗号化コンテキストを使用しません。暗号化されたメッセージのメタデータから暗号化コンテキストの値を取得します。ただし、プレーンテキストを返したり使用したりする前に、暗号文の復号に使用した暗号化コンテキストに、暗号化時に指定した暗号化コンテキストが含まれていることを確認することがベストプラクティスです。
暗号化に使用した暗号化コンテキストが、暗号文の復号に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名でアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
## AWS Encryption SDK for .NET の検出キーリングを使用した復号
復号化に KMS キーを指定するのではなく、KMS キーを指定しないキーリングである AWS KMS ディスカバリーキーリングを提供できます。検出キーリングを使用すると、発信者がキーに対する復号アクセス許可を持っている限り、 AWS Encryption SDK は暗号化された KMS キーを使用してデータを復号できます。ベストプラクティスとして、 AWS アカウント 特定のパーティションで使用できる KMS キーを制限する検出フィルターを追加します。
AWS Encryption SDK for .NET には、 AWS KMS クライアントを必要とする基本的な検出キーリングと、1 つ以上の を指定する必要がある検出マルチキーリングが用意されています AWS リージョン。クライアントとリージョンはどちらも、暗号化されたメッセージの復号化に使用できる KMS キーを制限します。 どちらのキーリングの入力オブジェクトにも、推奨ディスカバリーフィルターが適用されます。
次の例は、 AWS KMS ディスカバリーキーリングとディスカバリーフィルターを使用してデータを復号化するパターンを示しています。
ステップ 1: AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。
```
// Instantiate the AWS Encryption SDK and material providers
var esdk = new ESDK(new AwsEncryptionSdkConfig());
var mpl = new MaterialProviders(new MaterialProvidersConfig());
```
ステップ 2: キーリング用の入力オブジェクトを作成します。
キーリングメソッドのパラメータを指定するには、入力オブジェクトを作成します。 AWS Encryption SDK for .NET の各キーリングメソッドには、対応する入力オブジェクトがあります。この例では、`CreateAwsKmsDiscoveryKeyring()` メソッドを使用してキーリングを作成しているため、入力用の `CreateAwsKmsDiscoveryKeyringInput` クラスをインスタンス化しています。
```
List accounts = new List { "111122223333" };
var discoveryKeyringInput = new CreateAwsKmsDiscoveryKeyringInput
{
KmsClient = new AmazonKeyManagementServiceClient(),
DiscoveryFilter = new DiscoveryFilter()
{
AccountIds = accounts,
Partition = "aws"
}
};
```
ステップ 3: キーリングを作成します。
復号化キーリングを作成するために、この例では `CreateAwsKmsDiscoveryKeyring()` メソッドとキーリング入力オブジェクトを使用します。
```
var discoveryKeyring = materialProviders.CreateAwsKmsDiscoveryKeyring(discoveryKeyringInput);
```
ステップ 4: 復号化用の入力オブジェクトを作成します。
`Decrypt()` メソッドの入力オブジェクトを作成するには、`DecryptInput` クラスをインスタンス化します。`Ciphertext` パラメータの値は、`Encrypt()` メソッドが返す `EncryptOutput` オブジェクトの `Ciphertext` メンバーです。
for .NET のバージョン 4.*x* AWS Encryption SDK では、オプションの `EncryptionContext`パラメータを使用して、 `Decrypt()`メソッドで暗号化コンテキストを指定できます。
この `EncryptionContext` パラメータを使用して、暗号化時に使用された暗号化コンテキストが、暗号文の復号化に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名付きアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
var ciphertext = encryptOutput.Ciphertext;
var decryptInput = new DecryptInput
{
Ciphertext = ciphertext,
Keyring = discoveryKeyring,
EncryptionContext = encryptionContext // OPTIONAL
};
var decryptOutput = encryptionSdk.Decrypt(decryptInput);
```
ステップ 5: 暗号化コンテキストを確認します — バージョン 3.x
for .NET のバージョン 3.*x* AWS Encryption SDK の `Decrypt()`メソッドは、 で暗号化コンテキストを使用しません`Decrypt()`。暗号化されたメッセージのメタデータから暗号化コンテキストの値を取得します。ただし、プレーンテキストを返したり使用したりする前に、暗号文の復号に使用した暗号化コンテキストに、暗号化時に指定した暗号化コンテキストが含まれていることを確認することがベストプラクティスです。
暗号化で使用された暗号化コンテキストが、暗号文の復号に使用された暗号化コンテキストに含まれていることを確認します。は、デフォルトのアルゴリズムスイートなどの署名でアルゴリズムスイートを使用している場合、デジタル署名を含むペアを暗号化コンテキスト AWS Encryption SDK に追加します。
```
// Verify the encryption context
string contextKey = "purpose";
string contextValue = "test";
if (!decryptOutput.EncryptionContext.TryGetValue(contextKey, out var decryptContextValue)
|| !decryptContextValue.Equals(contextValue))
{
throw new Exception("Encryption context does not match expected values");
}
```
# AWS Encryption SDK Go 用
このトピックでは、 AWS Encryption SDK for Go をインストールして使用する方法について説明します。 AWS Encryption SDK for Go を使用したプログラミングの詳細については、GitHub の aws-encryption-sdk リポジトリの [go](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/) ディレクトリを参照してください。
AWS Encryption SDK for Go は、以下の点 AWS Encryption SDK で の他のプログラミング言語実装とは異なります。
+ [データキーキャッシュ](data-key-caching.md)はサポートされていません。ただし、 AWS Encryption SDK for Go は、代替の暗号化マテリアルキャッシュソリューションである[AWS KMS 階層キーリング](use-hierarchical-keyring.md)をサポートしています。
+ ストリーミングデータはサポートしていません
AWS Encryption SDK for Go には、 の他の言語実装のバージョン 2.0.*x* 以降で導入されたすべてのセキュリティ機能が含まれています AWS Encryption SDK。ただし、 AWS Encryption SDK for Go を使用して、 の 2.0.*x* より前のバージョンの別の言語実装で暗号化されたデータを復号する場合は AWS Encryption SDK、[コミットメントポリシー](concepts.md#commitment-policy)を調整する必要がある場合があります。詳細については、「[コミットメントポリシーの設定方法](migrate-commitment-policy.md#migrate-commitment-step1)」を参照してください。
AWS Encryption SDK for Go は、[Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) の の製品 AWS Encryption SDK であり、仕様を記述する正式な検証言語、実装するコード、およびテストするための証明です。その結果、機能の正確性を保証するフレームワークに、 AWS Encryption SDK の機能を実装するライブラリができあがりました。
**詳細はこちら**
+ 代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
+ AWS Encryption SDK for Go を設定して使用する方法の例については、GitHub の aws-encryption-sdk リポジトリの [Go の例](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/examples)を参照してください。
**Topics**
+ [前提条件](#prerequisites-go)
+ [インストール](#go-installation)
## 前提条件
AWS Encryption SDK for Go をインストールする前に、次の前提条件があることを確認してください。
**Go のサポートされているバージョン**
Go には Go 1.23 AWS Encryption SDK 以降が必要です。
Go のダウンロードとインストールの詳細については、「Go [のインストール](https://go.dev/doc/install)」を参照してください。
## インストール
AWS Encryption SDK for Go の最新バージョンをインストールします。 AWS Encryption SDK for Go のインストールと構築の詳細については、GitHub の aws-encryption-sdk リポジトリの go ディレクトリにある [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline/releases/go/encryption-sdk/README.md) を参照してください。
**最新バージョンをインストールするには**
+ AWS Encryption SDK for Go のインストール
```
go get github.com/aws/aws-encryption-sdk/releases/go/encryption-sdk@latest
```
+ [暗号化マテリアルプロバイダーライブラリ](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) をインストールする
```
go get github.com/aws/aws-cryptographic-material-providers-library/releases/go/mpl
```
# AWS Encryption SDK for Java
このトピックでは、 AWS Encryption SDK for Javaをインストールして使用する方法について説明します。を使用したプログラミングの詳細については AWS Encryption SDK for Java、GitHub の [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) リポジトリを参照してください。API のドキュメントについては、 AWS Encryption SDK for Javaの [Javadoc](https://aws.github.io/aws-encryption-sdk-java/) を参照してください。
**Topics**
+ [前提条件](#java-prerequisites)
+ [インストール](#java-installation)
+ [例](java-example-code.md)
## 前提条件
をインストールする前に AWS Encryption SDK for Java、次の前提条件があることを確認してください。
**Java 開発環境**
Java 8 以降が必要になります。Oracle のウェブサイトで [Java SE のダウンロード](https://www.oracle.com/java/technologies/downloads/)に移動し、Java SE Development Kit (JDK) をダウンロードして、インストールします。
Oracle JDK を使用する場合は、[Java Cryptography Extension (JCE) 無制限強度の管轄ポリシーファイル](http://www.oracle.com/java/technologies/javase-jce8-downloads.html)をダウンロードして、インストールする必要があります。
**Bouncy Castle**
には [Bouncy Castle](https://www.bouncycastle.org/download/bouncy-castle-java/) AWS Encryption SDK for Java が必要です。
+ AWS Encryption SDK for Java バージョン 1.6.1 以降では、Bouncy Castle を使用して暗号化オブジェクトをシリアル化および逆シリアル化します。この要件を満たすには、Bouncy Castle または [Bouncy Castle FIPS](https://www.bouncycastle.org/about/bouncy-castle-fips-faq/) を使用できます。Bouncy Castle FIPS のインストールおよび設定については、[Bouncy Castle FIPS のドキュメント](https://www.bouncycastle.org/documentation/)の特に**ユーザーガイド**と**セキュリティポリシー**の PDF を参照してください。
+ 以前のバージョンの では、Bouncy Castle の cryptography API for Java AWS Encryption SDK for Java を使用しています。この要件は、FIPS 非対応の Bouncy Castle によってのみ満たされます。
Bouncy Castle がない場合は、[Java 用 Bouncy Castle のダウンロード](https://bouncycastle.org/download/bouncy-castle-java/)に移動して、JDK に対応するプロバイダーファイルをダウンロードします。また、[Apache Maven](https://maven.apache.org/) を使用して、標準の Bouncy Castle プロバイダー ([bcprov-ext-jdk15on](https://mvnrepository.com/artifact/org.bouncycastle/bcprov-ext-jdk15on)) のアーティファクトや Bouncy Castle FIPS ([bc-fips](https://mvnrepository.com/artifact/org.bouncycastle/bc-fips)) のアーティファクトを取得することもできます。
**AWS SDK for Java**
のバージョン 3.*x* では、 AWS KMS キーリングを使用していない場合でも AWS SDK for Java 2.x、 AWS Encryption SDK for Java が必要です。
バージョン 2.*x* 以前の AWS Encryption SDK for Java では、 は必要ありません AWS SDK for Java。ただし、マスターキープロバイダーとして [AWS Key Management Service](https://aws.amazon.com/kms/) (AWS KMS) を使用するには、 AWS SDK for Java が必要です。 AWS Encryption SDK for Java バージョン 2.4.0 以降、 AWS Encryption SDK for Java は、1.x および 2.x 用の AWS SDK for Java. AWS Encryption SDK code のバージョン AWS SDK for Java 1.x と 2.x の両方を相互運用できます。たとえば、 AWS SDK for Java 1.x をサポートする AWS Encryption SDK コードでデータを暗号化し、 をサポートするコードを使用して復号化できます AWS SDK for Java 2.x (またはその逆）。2.4.0 より AWS Encryption SDK for Java 前のバージョンの は、 AWS SDK for Java 1.x のみをサポートしています。のバージョンの更新については AWS Encryption SDK、「」を参照してください[の移行 AWS Encryption SDK](migration.md)。
AWS Encryption SDK for Java コードを AWS SDK for Java 1.x から に更新するときは AWS SDK for Java 2.x、 AWS SDK for Java 1.x の[`AWSKMS`インターフェイス](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/kms/package-summary.html)への参照を の[`KmsClient`インターフェイス](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/package-summary.html)への参照に置き換えます AWS SDK for Java 2.x。 AWS Encryption SDK for Java は [`KmsAsyncClient`インターフェイス](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kms/KmsAsyncClient.html)をサポートしていません。また、`kms` 名前空間の代わりに、`kmssdkv2` 名前空間の AWS KMS関連オブジェクトを使用するようにコードを更新してください。
をインストールするには AWS SDK for Java、Apache Maven を使用します。
+ 依存関係として [AWS SDK for Java全体をインポートする](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project)には、`pom.xml` ファイルでそれを宣言します。
+ モジュール AWS KMS in AWS SDK for Java 1.x にのみ依存関係を作成するには、[特定のモジュールを指定する](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/setup-project-maven.html#modules-dependencies)手順に従い、 `artifactId`を に設定します`aws-java-sdk-kms`。
+ AWS KMS モジュール in AWS SDK for Java 2.x にのみ依存関係を作成するには、特定の[モジュールを指定する手順に従います](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies)。`groupId` を `software.amazon.awssdk` に、`artifactId` を `kms` に設定します。
その他の変更点については、[「 デベロッパーガイド」の AWS SDK for Java 「1.x と 2.x の違い](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-whats-different.html)」を参照してください。 AWS SDK for Java 2.x
AWS Encryption SDK デベロッパーガイドの Java の例は、 を使用します AWS SDK for Java 2.x。
## インストール
AWS Encryption SDK for Javaの最新バージョンをインストールします。
**注記**
2.0.0 より AWS Encryption SDK for Java 前の のすべてのバージョンは[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.0.x 以降から AWS Encryption SDK for Java の最新バージョンにコードやデータを変更せずに安全に更新できます。ただし、バージョン 2.0.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。1.7.x より前のバージョンから 2.0.x 以降のバージョンに更新するには、まず AWS Encryption SDKの最新の 1.x バージョンに更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
は、次の AWS Encryption SDK for Java 方法でインストールできます。
**手動**
をインストールするには AWS Encryption SDK for Java、[aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) GitHub リポジトリのクローンを作成するか、ダウンロードします。
**Apache Maven の使用**
AWS Encryption SDK for Java は、次の依存関係定義を使用して [Apache Maven](https://maven.apache.org/) を通じて使用できます。
```
com.amazonawsaws-encryption-sdk-java3.0.0
```
SDK をインストールしたら、このガイドの [Java コード例](java-example-code.md)と [GitHub の Javadoc](https://aws.github.io/aws-encryption-sdk-java/) を見て開始します。
# AWS Encryption SDK for Java 例
次の例は、 を使用してデータを AWS Encryption SDK for Java 暗号化および復号する方法を示しています。これらの例は、 のバージョン 3.*x* 以降を使用する方法を示しています AWS Encryption SDK for Java。のバージョン 3.*x* には AWS Encryption SDK for Java が必要です AWS SDK for Java 2.x。のバージョン 3.*x* は AWS Encryption SDK for Java 、[マスターキープロバイダー](concepts.md#master-key-provider)を[キーリングに置き換えます](concepts.md#keyring)。前バージョンを使用する例については、GitHub の [aws-encryption-sdk-java](https://github.com/aws/aws-encryption-sdk-java/) リポジトリの[リリース](https://github.com/aws/aws-encryption-sdk-java/releases)リストで使用中のリリースを検索してください。
**Topics**
+ [文字列](#java-example-strings)
+ [バイトストリーム](#java-example-streams)
+ [複数のマスターキープロバイダーでのバイトストリーム](#java-example-multiple-providers)
## 文字列の暗号化と復号
次の例は、 のバージョン 3.*x* を使用して文字列 AWS Encryption SDK for Java を暗号化および復号する方法を示しています。文字列を使用する前にバイト配列に変換します。
この例では、 [AWS KMS キーリング](use-kms-keyring.md)を使用します。 AWS KMS キーリングで暗号化する場合、キー ID、キー ARN、エイリアス名、またはエイリアス ARN を使用して KMS キーを識別できます。復号するときは、キー ARN を使用して KMS キーを識別する必要があります。
`encryptData()` メソッドを呼び出すと、暗号化テキスト、暗号化されたデータキー、暗号化コンテキストを含む[暗号化されたメッセージ](concepts.md#message) (`CryptoResult`) が返されます。`CryptoResult` オブジェクトで `getResult` を呼び出すと、[暗号化されたメッセージ](message-format.md)の Base-64 でエンコードされた文字列バージョンが返され、`decryptData()` メソッドに渡すことができるようになります。
同様に、 を呼び出すと`decryptData()`、返される`CryptoResult`オブジェクトにはプレーンテキストメッセージと AWS KMS key ID が含まれます。アプリケーションがプレーンテキストを返す前に、暗号化されたメッセージの AWS KMS key ID と暗号化コンテキストが想定どおりであることを確認します。
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoResult;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
/**
* Encrypts and then decrypts data using an AWS KMS Keyring.
*
*
Arguments:
*
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS customer master
* key (CMK), see 'Viewing Keys' at
* http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*/
public class BasicEncryptionKeyringExample {
private static final byte[] EXAMPLE_DATA = "Hello World".getBytes(StandardCharsets.UTF_8);
public static void main(final String[] args) {
final String keyArn = args[0];
encryptAndDecryptWithKeyring(keyArn);
}
public static void encryptAndDecryptWithKeyring(final String keyArn) {
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto =
AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders materialProviders =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput =
CreateAwsKmsMultiKeyringInput.builder().generator(keyArn).build();
final IKeyring kmsKeyring = materialProviders.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create an encryption context
// We recommend using an encryption context whenever possible
// to protect integrity. This sample uses placeholder values.
// For more information see:
// blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management
final Map encryptionContext =
Collections.singletonMap("ExampleContextKey", "ExampleContextValue");
// 4. Encrypt the data
final CryptoResult encryptResult =
crypto.encryptData(kmsKeyring, EXAMPLE_DATA, encryptionContext);
final byte[] ciphertext = encryptResult.getResult();
// 5. Decrypt the data
final CryptoResult decryptResult =
crypto.decryptData(
kmsKeyring,
ciphertext,
// Verify that the encryption context in the result contains the
// encryption context supplied to the encryptData method
encryptionContext);
// 6. Verify that the decrypted plaintext matches the original plaintext
assert Arrays.equals(decryptResult.getResult(), EXAMPLE_DATA);
}
}
```
## バイトストリームの暗号化と復号
次の例は、 を使用してバイトストリーム AWS Encryption SDK を暗号化および復号する方法を示しています。
この例では、[Raw AES キーリング](use-raw-aes-keyring.md)を使用します。
暗号化するときには、`AwsCrypto.builder() .withEncryptionAlgorithm()` メソッドを使用して、[デジタル署名](concepts.md#digital-sigs)のないアルゴリズムスイートを指定します。復号化時に、暗号化テキストが署名なしであることを確認するために、この例では `createUnsignedMessageDecryptingStream()` メソッドを使用します。`createUnsignedMessageDecryptingStream()` メソッドは、デジタル署名を持つ暗号文を検出すると失敗します。
デジタル署名を含むデフォルトのアルゴリズムスイートで暗号化する場合は、次の例に示すように、代わりに `createDecryptingStream()` メソッドを使用します。
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoAlgorithm;
import com.amazonaws.encryptionsdk.CryptoInputStream;
import com.amazonaws.encryptionsdk.jce.JceMasterKey;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.AesWrappingAlg;
import software.amazon.cryptography.materialproviders.model.CreateRawAesKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Collections;
import java.util.Map;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
/**
*
* Encrypts and then decrypts a file under a random key.
*
*
* Arguments:
*
*
Name of file containing plaintext data to encrypt
*
*
*
* This program demonstrates using a standard Java {@link SecretKey} object as a {@link IKeyring} to
* encrypt and decrypt streaming data.
*/
public class FileStreamingKeyringExample {
private static String srcFile;
public static void main(String[] args) throws IOException {
srcFile = args[0];
// In this example, we generate a random key. In practice,
// you would get a key from an existing store
SecretKey cryptoKey = retrieveEncryptionKey();
// Create a Raw Aes Keyring using the random key and an AES-GCM encryption algorithm
final MaterialProviders materialProviders = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawAesKeyringInput keyringInput = CreateRawAesKeyringInput.builder()
.wrappingKey(ByteBuffer.wrap(cryptoKey.getEncoded()))
.keyNamespace("Example")
.keyName("RandomKey")
.wrappingAlg(AesWrappingAlg.ALG_AES128_GCM_IV12_TAG16)
.build();
IKeyring keyring = materialProviders.CreateRawAesKeyring(keyringInput);
// Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
// This example encrypts with an algorithm suite that doesn't include signing for faster decryption,
// since this use case assumes that the contexts that encrypt and decrypt are equally trusted.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.withEncryptionAlgorithm(CryptoAlgorithm.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY)
.build();
// Create an encryption context to identify the ciphertext
Map context = Collections.singletonMap("Example", "FileStreaming");
// Because the file might be too large to load into memory, we stream the data, instead of
//loading it all at once.
FileInputStream in = new FileInputStream(srcFile);
CryptoInputStream encryptingStream = crypto.createEncryptingStream(keyring, in, context);
FileOutputStream out = new FileOutputStream(srcFile + ".encrypted");
IOUtils.copy(encryptingStream, out);
encryptingStream.close();
out.close();
// Decrypt the file. Verify the encryption context before returning the plaintext.
// Since the data was encrypted using an unsigned algorithm suite, use the recommended
// createUnsignedMessageDecryptingStream method, which only accepts unsigned messages.
in = new FileInputStream(srcFile + ".encrypted");
CryptoInputStream decryptingStream = crypto.createUnsignedMessageDecryptingStream(keyring, in);
// Does it contain the expected encryption context?
if (!"FileStreaming".equals(decryptingStream.getCryptoResult().getEncryptionContext().get("Example"))) {
throw new IllegalStateException("Bad encryption context");
}
// Write the plaintext data to disk.
out = new FileOutputStream(srcFile + ".decrypted");
IOUtils.copy(decryptingStream, out);
decryptingStream.close();
out.close();
}
/**
* In practice, this key would be saved in a secure location.
* For this demo, we generate a new random key for each operation.
*/
private static SecretKey retrieveEncryptionKey() {
SecureRandom rnd = new SecureRandom();
byte[] rawKey = new byte[16]; // 128 bits
rnd.nextBytes(rawKey);
return new SecretKeySpec(rawKey, "AES");
}
}
```
## マルチキーリングを使用したバイトストリームの暗号化と復号
次の例は、[マルチキーリング](use-multi-keyring.md) AWS Encryption SDK で を使用する方法を示しています。マルチキーリングを使用してデータを暗号化する場合は、そのキーリングに含まれる任意のラッピングキーを使用してそのデータを復号できます。この例では、 [AWS KMS キーリング](use-kms-keyring.md)と [Raw RSA キーリング](use-raw-rsa-keyring.md)を子キーリングとして使用します。
この例では、[デジタル署名](concepts.md#digital-sigs)を含む[デフォルトのアルゴリズムスイート](supported-algorithms.md)で暗号化します。ストリーミング時、 は整合性チェックの後、デジタル署名を検証する前にプレーンテキストを AWS Encryption SDK リリースします。署名が検証されるまでプレーンテキストを使用しないようにするため、この例ではプレーンテキストをバッファリングし、復号化および検証が完了したときにのみディスクに書き込みます。
```
// Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
// SPDX-License-Identifier: Apache-2.0
package com.amazonaws.crypto.keyrings;
import com.amazonaws.encryptionsdk.AwsCrypto;
import com.amazonaws.encryptionsdk.CommitmentPolicy;
import com.amazonaws.encryptionsdk.CryptoOutputStream;
import com.amazonaws.util.IOUtils;
import software.amazon.cryptography.materialproviders.IKeyring;
import software.amazon.cryptography.materialproviders.MaterialProviders;
import software.amazon.cryptography.materialproviders.model.CreateAwsKmsMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateMultiKeyringInput;
import software.amazon.cryptography.materialproviders.model.CreateRawRsaKeyringInput;
import software.amazon.cryptography.materialproviders.model.MaterialProvidersConfig;
import software.amazon.cryptography.materialproviders.model.PaddingScheme;
import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.util.Collections;
/**
*
* Encrypts a file using both AWS KMS Key and an asymmetric key pair.
*
*
* Arguments:
*
*
Key ARN: For help finding the Amazon Resource Name (ARN) of your AWS KMS key,
* see 'Viewing Keys' at http://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html
*
*
Name of file containing plaintext data to encrypt
*
*
* You might use AWS Key Management Service (AWS KMS) for most encryption and decryption operations, but
* still want the option of decrypting your data offline independently of AWS KMS. This sample
* demonstrates one way to do this.
*
* The sample encrypts data under both an AWS KMS key and an "escrowed" RSA key pair
* so that either key alone can decrypt it. You might commonly use the AWS KMS key for decryption. However,
* at any time, you can use the private RSA key to decrypt the ciphertext independent of AWS KMS.
*
* This sample uses the RawRsaKeyring to generate a RSA public-private key pair
* and saves the key pair in memory. In practice, you would store the private key in a secure offline
* location, such as an offline HSM, and distribute the public key to your development team.
*/
public class EscrowedEncryptKeyringExample {
private static ByteBuffer publicEscrowKey;
private static ByteBuffer privateEscrowKey;
public static void main(final String[] args) throws Exception {
// This sample generates a new random key for each operation.
// In practice, you would distribute the public key and save the private key in secure
// storage.
generateEscrowKeyPair();
final String kmsArn = args[0];
final String fileName = args[1];
standardEncrypt(kmsArn, fileName);
standardDecrypt(kmsArn, fileName);
escrowDecrypt(fileName);
}
private static void standardEncrypt(final String kmsArn, final String fileName) throws Exception {
// Encrypt with the KMS key and the escrowed public key
// 1. Instantiate the SDK
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Encrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName);
final FileOutputStream out = new FileOutputStream(fileName + ".encrypted");
final CryptoOutputStream encryptingStream = crypto.createEncryptingStream(multiKeyring, out);
IOUtils.copy(in, encryptingStream);
in.close();
encryptingStream.close();
}
private static void standardDecrypt(final String kmsArn, final String fileName) throws Exception {
// Decrypt with the AWS KMS key and the escrow public key.
// 1. Instantiate the SDK.
// This builds the AwsCrypto client with the RequireEncryptRequireDecrypt commitment policy,
// which means this client only encrypts using committing algorithm suites and enforces
// that the client will only decrypt encrypted messages that were created with a committing
// algorithm suite.
// This is the default commitment policy if you build the client with
// `AwsCrypto.builder().build()`
// or `AwsCrypto.standard()`.
final AwsCrypto crypto = AwsCrypto.builder()
.withCommitmentPolicy(CommitmentPolicy.RequireEncryptRequireDecrypt)
.build();
// 2. Create the AWS KMS keyring.
// This example creates a multi keyring, which automatically creates the KMS client.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsMultiKeyringInput keyringInput = CreateAwsKmsMultiKeyringInput.builder()
.generator(kmsArn)
.build();
IKeyring kmsKeyring = matProv.CreateAwsKmsMultiKeyring(keyringInput);
// 3. Create the Raw Rsa Keyring with Public Key.
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.build();
IKeyring rsaPublicKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 4. Create the multi-keyring.
final CreateMultiKeyringInput createMultiKeyringInput = CreateMultiKeyringInput.builder()
.generator(kmsKeyring)
.childKeyrings(Collections.singletonList(rsaPublicKeyring))
.build();
IKeyring multiKeyring = matProv.CreateMultiKeyring(createMultiKeyringInput);
// 5. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".decrypted");
// Since we are using a signing algorithm suite, we avoid streaming decryption directly to the output file,
// to ensure that the trailing signature is verified before writing any untrusted plaintext to disk.
final ByteArrayOutputStream plaintextBuffer = new ByteArrayOutputStream();
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(multiKeyring, plaintextBuffer);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
final ByteArrayInputStream plaintextReader = new ByteArrayInputStream(plaintextBuffer.toByteArray());
IOUtils.copy(plaintextReader, out);
out.close();
}
private static void escrowDecrypt(final String fileName) throws Exception {
// You can decrypt the stream using only the private key.
// This method does not call AWS KMS.
// 1. Instantiate the SDK
final AwsCrypto crypto = AwsCrypto.standard();
// 2. Create the Raw Rsa Keyring with Private Key.
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateRawRsaKeyringInput encryptingKeyringInput = CreateRawRsaKeyringInput.builder()
.keyName("Escrow")
.keyNamespace("Escrow")
.paddingScheme(PaddingScheme.OAEP_SHA512_MGF1)
.publicKey(publicEscrowKey)
.privateKey(privateEscrowKey)
.build();
IKeyring escrowPrivateKeyring = matProv.CreateRawRsaKeyring(encryptingKeyringInput);
// 3. Decrypt the file
// To simplify this code example, we omit the encryption context. Production code should always
// use an encryption context.
final FileInputStream in = new FileInputStream(fileName + ".encrypted");
final FileOutputStream out = new FileOutputStream(fileName + ".deescrowed");
final CryptoOutputStream decryptingStream = crypto.createDecryptingStream(escrowPrivateKeyring, out);
IOUtils.copy(in, decryptingStream);
in.close();
decryptingStream.close();
}
private static void generateEscrowKeyPair() throws GeneralSecurityException {
final KeyPairGenerator kg = KeyPairGenerator.getInstance("RSA");
kg.initialize(4096); // Escrow keys should be very strong
final KeyPair keyPair = kg.generateKeyPair();
publicEscrowKey = RawRsaKeyringExample.getPEMPublicKey(keyPair.getPublic());
privateEscrowKey = RawRsaKeyringExample.getPEMPrivateKey(keyPair.getPrivate());
}
}
```
# AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript は、JavaScript でウェブブラウザアプリケーションを記述しているデベロッパーや Node.js でウェブサーバーアプリケーションを記述しているデベロッパー向けに、クライアント側の暗号化ライブラリを提供するように設計されています。
のすべての実装と同様に AWS Encryption SDK、 は高度なデータ保護機能 AWS Encryption SDK for JavaScript を提供します。これには[エンベロープ暗号化](concepts.md#envelope-encryption)、追加の認証データ (AAD)、キー取得および署名で使用する 256 ビット AES-GCM などのセキュアで認証済みの対称キー[アルゴリズムスイート](concepts.md#crypto-algorithm)などが含まれます。
のすべての言語固有の実装 AWS Encryption SDK は、言語の制約に従って相互運用できるように設計されています。JavaScript の言語による制約の詳細については、「[の互換性 AWS Encryption SDK for JavaScript](javascript-compatibility.md)」を参照してください。
**詳細はこちら**
+ を使用したプログラミングの詳細については AWS Encryption SDK for JavaScript、GitHub の [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) リポジトリを参照してください。
+ プログラミング例については、[aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) リポジトリの「[AWS Encryption SDK for JavaScript 例](js-examples.md)」および [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) と [example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) モジュールを参照してください。
+ を使用してウェブアプリケーションのデータを暗号化 AWS Encryption SDK for JavaScript する実際の例については、 AWS セキュリティブログの「 [AWS Encryption SDK for JavaScript と Node.js を使用してブラウザで暗号化を有効にする方法](https://aws.amazon.com/blogs/security/how-to-enable-encryption-browser-aws-encryption-sdk-javascript-node-js/)」を参照してください。
**Topics**
+ [互換性](javascript-compatibility.md)
+ [インストール](javascript-installation.md)
+ [モジュール](javascript-modules.md)
+ [例](js-examples.md)
# の互換性 AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript は、 の他の言語実装と相互運用できるように設計されています AWS Encryption SDK。ほとんどの場合、 でデータを暗号化 AWS Encryption SDK for JavaScript し、 [AWS Encryption SDK コマンドラインインターフェイス](crypto-cli.md)を含む他の言語実装で復号できます。また、 を使用して AWS Encryption SDK for JavaScript 、 の他の言語実装によって生成された[暗号化されたメッセージを](concepts.md#message)復号できます AWS Encryption SDK。
ただし、 を使用する場合は AWS Encryption SDK for JavaScript、JavaScript 言語の実装とウェブブラウザにおけるいくつかの互換性の問題に注意する必要があります。
また、他の言語の実装を使用する場合は、必ず互換性のあるマスターキープロバイダー、マスターキー、キーリングを設定してください。詳細については、「[キーリングの互換性](choose-keyring.md#keyring-compatibility)」を参照してください。
## AWS Encryption SDK for JavaScript 互換性
の JavaScript 実装は、次の点で他の言語実装 AWS Encryption SDK とは異なります。
+ の暗号化オペレーション AWS Encryption SDK for JavaScript は、フレーム化されていない暗号文を返しません。ただし、 AWS Encryption SDK for JavaScript は、 の他の言語実装によって返されるフレーム暗号文と非フレーム暗号文を復号します AWS Encryption SDK。
+ Node.js のバージョン 12.9.0 以降で、以下の RSA キーのラッピングオプションをサポートしています。
+ OAEP と SHA1、SHA256、SHA384、SHA512
+ OAEP と SHA1 および MGF1 と SHA1
+ PKCS1v15
+ バージョン 12.9.0 より前の Node.js では、以下の RSA キーのラッピングオプションのみをサポートしています。
+ OAEP と SHA1 および MGF1 と SHA1
+ PKCS1v15
## ブラウザの互換性
ウェブブラウザによっては、 AWS Encryption SDK for JavaScript が必要とする基本的な暗号化オペレーションがサポートされていません。ブラウザが実装している WebCrypto API のフォールバックを設定することで、不足しているオペレーションの一部を補うことができます。
**ウェブブラウザの制限事項**
以下の制限は、すべてのウェブブラウザに共通です。
+ WebCrypto API では、PKCS1v15 のキーのラッピングはサポートされていません。
+ ブラウザでは、192 ビットキーはサポートされていません。
**必要な暗号化オペレーション**
では、ウェブブラウザで以下のオペレーション AWS Encryption SDK for JavaScript が必要です。ブラウザでこれらのオペレーションがサポートされていない場合は、 AWS Encryption SDK for JavaScriptとの互換性がありません。
+ ブラウザには、暗号化の乱数を生成するメソッドである `crypto.getRandomValues()` が含まれている必要があります。`crypto.getRandomValues()` をサポートしているウェブブラウザのバージョンについては、「[Can I Use crypto.getRandomValues()?](https://caniuse.com/#feat=getrandomvalues)」を参照してください。
**必要なフォールバック**
には、ウェブブラウザで次のライブラリとオペレーション AWS Encryption SDK for JavaScript が必要です。これらの要件を満たしていないウェブブラウザをサポートする場合は、フォールバックを設定する必要があります。そうしないと、ブラウザ AWS Encryption SDK for JavaScript で を使用しようとすると失敗します。
+ ウェブアプリケーションで基本的な暗号化オペレーションを行う WebCrypto API は、すべてのブラウザで使用できるわけではありません。ウェブでの暗号化をサポートしているウェブブラウザのバージョンについては、「[Can I Use Web Cryptography?](https://caniuse.com/#feat=cryptography)」を参照してください。
+ Safari ウェブブラウザの最新バージョンは、 が AWS Encryption SDK 必要とする 0 バイトの AES-GCM 暗号化をサポートしていません。ブラウザが WebCrypto API を実装しているが、AES-GCM を使用してゼロバイトを暗号化できない場合、 はゼロバイト暗号化にのみフォールバックライブラリ AWS Encryption SDK for JavaScript を使用します。他のすべてのオペレーションには、WebCrypto API を使用します。
いずれかの制限のフォールバックを設定するには、コードに次のステートメントを追加します。[configureFallback](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/web-crypto-backend/src/backend-factory.ts#L78) 関数に不足している機能をサポートするライブラリを指定します。この例では、マイクロソフトリサーチの JavaScript 暗号化ライブラリ (`msrcrypto`) を使用していますが、互換性のあるライブラリに置き換えることができます。詳しい例については、[fallback.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/fallback.ts) を参照してください。
```
import { configureFallback } from '@aws-crypto/client-browser'
configureFallback(msrCrypto)
```
# のインストール AWS Encryption SDK for JavaScript
AWS Encryption SDK for JavaScript は、相互依存モジュールのコレクションで構成されています。このモジュールのいくつかは、一緒に動作するように設計されたモジュールの集まりです。一部のモジュールは、単独で動作するように設計されています。すべての実装に必要なモジュールはほんの少しです。また、特殊な場合にのみ必要なモジュールもほんの少しです。for AWS Encryption SDK JavaScript のモジュールの詳細については、 [のモジュール AWS Encryption SDK for JavaScript](javascript-modules.md)および GitHub の [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules) リポジトリの各モジュールの `README.md` ファイルを参照してください。
**注記**
2.0.0 より AWS Encryption SDK for JavaScript 前の のすべてのバージョンは[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.0.x 以降から AWS Encryption SDK for JavaScript の最新バージョンにコードやデータを変更せずに安全に更新できます。ただし、バージョン 2.0.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。1.7.x より前のバージョンから 2.0.x 以降のバージョンに更新するには、まず AWS Encryption SDK for JavaScriptの最新の 1.x バージョンに更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
モジュールをインストールするには、[npm パッケージマネージャー](https://www.npmjs.com/get-npm)を使用します。
例えば、 AWS Encryption SDK for JavaScript Node.js の でプログラムするために必要なすべてのモジュールを含む `client-node`モジュールをインストールするには、次のコマンドを使用します。
```
npm install @aws-crypto/client-node
```
AWS Encryption SDK for JavaScript ブラウザで を使用してプログラムするために必要なすべてのモジュールを含む `client-browser` モジュールをインストールするには、次のコマンドを使用します。
```
npm install @aws-crypto/client-browser
```
の使用方法の実例については AWS Encryption SDK for JavaScript、GitHub の [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/) リポジトリの `example-node`および `example-browser`モジュールの例を参照してください。
# のモジュール AWS Encryption SDK for JavaScript
のモジュール AWS Encryption SDK for JavaScript を使用すると、プロジェクトに必要なコードを簡単にインストールできます。
## JavaScript Node.js 用のモジュール
[client-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-node)
AWS Encryption SDK for JavaScript Node.js の でプログラムするために必要なすべてのモジュールが含まれています。
[caching-materials-manager-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-node)
Node.js の [でデータキーキャッシュ](data-key-caching.md)機能をサポートする関数 AWS Encryption SDK for JavaScript をエクスポートします。
[decrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-node)
データとデータストリームを表す暗号化されたメッセージを復号および検証する関数をエクスポートします。これは、`client-node` モジュールに含まれています。
[encrypt-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-node)
さまざまなタイプのデータを暗号化して署名する関数をエクスポートします。これは、`client-node` モジュールに含まれています。
[example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node)
Node.js の を使用したプログラミングの実例 AWS Encryption SDK for JavaScript をエクスポートします。さまざまなタイプのキーリングやさまざまなタイプのデータの例が含まれています。
[hkdf-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/hkdf-node)
AWS Encryption SDK for JavaScript Node.js の [が特定のアルゴリズムスイートで使用する HMAC ベースのキー導出関数](https://en.wikipedia.org/wiki/HKDF) (HKDF) をエクスポートします。ブラウザ AWS Encryption SDK for JavaScript の は、WebCrypto API のネイティブ HKDF 関数を使用します。
[integration-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-node)
Node.js AWS Encryption SDK for JavaScript の が の他の言語実装と互換性があることを確認するテストを定義します AWS Encryption SDK。
[kms-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-node)
Node.js の AWS KMS キーリングをサポートする関数をエクスポートします。
[raw-aes-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-node)
Node.js で [Raw AES キーリング](use-raw-aes-keyring.md)をサポートする関数をエクスポートします。
[raw-rsa-keyring-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-node)
Node.js で [Raw RSA キーリング](use-raw-rsa-keyring.md)をサポートする関数をエクスポートします。
## JavaScript ブラウザ用のモジュール
[client-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/client-browser)
ブラウザで を使用してプログラムするために必要なすべてのモジュール AWS Encryption SDK for JavaScript が含まれています。
[caching-materials-manager-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/caching-materials-manager-browser)
ブラウザで JavaScript の[データキーキャッシュ](data-key-caching.md)機能をサポートする関数をエクスポートします。
[decrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/decrypt-browser)
データとデータストリームを表す暗号化されたメッセージを復号および検証する関数をエクスポートします。
[encrypt-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/encrypt-browser)
さまざまなタイプのデータを暗号化して署名する関数をエクスポートします。
[example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser)
ブラウザ AWS Encryption SDK for JavaScript での を使用したプログラミングの実例。さまざまなタイプのキーリングやさまざまなタイプのデータの例が含まれています。
[integration-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/integration-browser)
ブラウザのスクリプトが AWS Encryption SDK for Javaの他の言語実装と互換性があることを確認するテストを定義します AWS Encryption SDK。
[kms-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring-browser)
ブラウザで [AWS KMS キーリング](use-kms-keyring.md)をサポートする関数をエクスポートします。
[raw-aes-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-aes-keyring-browser)
ブラウザで [Raw AES キーリング](use-raw-aes-keyring.md)をサポートする関数をエクスポートします。
[raw-rsa-keyring-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-rsa-keyring-browser)
ブラウザで [Raw RSA キーリング](use-raw-rsa-keyring.md)をサポートする関数をエクスポートします。
## すべての実装用のモジュール
[cache-material](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/cache-material)
[データキーキャッシュ](data-key-caching.md)機能をサポートします。各データキーでキャッシュされる暗号化マテリアルを収集するためのコードを提供します。
[kms-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/kms-keyring)
[KMS キーリング](use-kms-keyring.md)をサポートする関数をエクスポートします。
[material-management](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/material-management)
[暗号化マテリアルマネージャー](concepts.md#crypt-materials-manager) (CMM) を実装します。
[raw-keyring](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/raw-keyring)
Raw AES キーリングと Raw RSA キーリングに必要な関数をエクスポートします。
[serialize](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/serialize)
SDK が出力をシリアル化するために使用する関数をエクスポートします。
[web-crypto-backend](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/web-crypto-backend)
ブラウザの で WebCrypto API を使用する関数をエクスポート AWS Encryption SDK for JavaScript します。
# AWS Encryption SDK for JavaScript 例
以下の例では、 AWS Encryption SDK for JavaScript を使用してデータの暗号化と復号を行う方法を示します。
を使用するその他の例については、GitHub AWS Encryption SDK for JavaScript の [aws-encryption-sdk-javascript](https://github.com/aws/aws-encryption-sdk-javascript/)[-encryption-sdk-javascript リポジトリの example-node](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-node) モジュールと [example-browser](https://github.com/aws/aws-encryption-sdk-javascript/tree/master/modules/example-browser) モジュールを参照してください。これらのサンプルモジュールは、`client-browser` モジュールや `client-node` モジュールのインストール時にはインストールされません。
**詳しいサンプルコードについては**、ノードの場合は [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-node/src/kms_simple.ts)、ブラウザの場合は [kms\$1simple.ts](https://github.com/aws/aws-encryption-sdk-javascript/blob/master/modules/example-browser/src/kms_simple.ts) を参照してください。
**Topics**
+ [AWS KMS キーリングによるデータの暗号化](#javascript-example-encrypt)
+ [AWS KMS キーリングを使用したデータの復号化](#javascript-example-decrypt)
## AWS KMS キーリングによるデータの暗号化
次の例は、 を使用して短い文字列またはバイト配列を AWS Encryption SDK for JavaScript 暗号化および復号する方法を示しています。
この例では、 [AWS KMS キーリング](use-kms-keyring.md)を使用しています。これは、 AWS KMS key を使用してデータキーを生成および暗号化するキーリングの一種です。の作成については AWS KMS key、「 *AWS Key Management Service デベロッパーガイド*」の[「キーの作成](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)」を参照してください。 AWS KMS キーリング AWS KMS keys で を識別する方法については、「」を参照してください。 [AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)
ステップ 1: コミットメントポリシーを設定します。
のバージョン 1.7.*x* 以降では AWS Encryption SDK for JavaScript、 AWS Encryption SDK クライアントをインスタンス化する新しい`buildClient`関数を呼び出すときにコミットメントポリシーを設定できます。`buildClient` 関数は、コミットメントポリシーを表す列挙値を取ります。更新された `encrypt` 関数と `decrypt` 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。
次の例では、 `buildClient`関数を使用してデフォルトの[コミットメントポリシー](migrate-commitment-policy.md) を指定します`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。を使用して`buildClient`、暗号化されたメッセージ内の暗号化されたデータキーの数を制限することもできます。詳細については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
ステップ 2: キーリングを作成します。
暗号化用の AWS KMS キーリングを作成します。
AWS KMS キーリングで暗号化する場合は、*ジェネレーターキー*、つまりプレーンテキストのデータキーを生成して暗号化する AWS KMS key ために使用される を指定する必要があります。また、同じプレーンテキストのデータキーを暗号化する*追加のキー*を必要な数だけ指定することもできます。キーリングは、プレーンテキストのデータキーと、ジェネレーターキーを含むキーリング AWS KMS key 内の各 の暗号化されたデータキーの 1 つのコピーを返します。データを復号するには、この暗号化されたデータキーのいずれかを復号する必要があります。
で暗号化キーリング AWS KMS keys の を指定するには AWS Encryption SDK for JavaScript、[サポートされている任意の AWS KMS キー識別子](use-kms-keyring.md#kms-keyring-id)を使用できます。この例では、[エイリアス ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-alias-ARN) で指定するジェネレーターキーと[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) で指定する 1 つの追加のキーを使用します。
キー AWS KMS リングを復号化に再利用する場合は、キー ARNs を使用してキーリング AWS KMS keys 内の を識別する必要があります。
このコードを実行する前に、サンプル AWS KMS key 識別子を有効な識別子に置き換えます。キーリングの [AWS KMS keysを使用するために必要なアクセス許可](use-kms-keyring.md#kms-keyring-permissions)を持っている必要があります。
まず、ブラウザの認証情報を指定します。この AWS Encryption SDK for JavaScript の例では、認証情報の定数を実際の認証情報に置き換える [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/) を使用しています。ただし、認証情報の指定には任意の方法を使用することができます。次に、認証情報を使用して AWS KMS クライアントを作成します。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
次に、ジェネレーターキーと追加キー AWS KMS keys の を指定します。次に、 クライアントと を使用して AWS KMS AWS KMS キーリングを作成します AWS KMS keys。
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, generatorKeyId, keyIds })
```
```
const generatorKeyId = 'arn:aws:kms:us-west-2:111122223333:alias/EncryptDecrypt'
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ generatorKeyId, keyIds })
```
ステップ 3: 暗号化コンテキストを設定します。
[暗号化コンテキスト](concepts.md#encryption-context)は、任意の、シークレットではない追加認証データです。暗号化時に暗号化コンテキストを指定すると、 は暗号化コンテキストを暗号化テキストに AWS Encryption SDK 暗号化バインドし、データの復号に同じ暗号化コンテキストが必要になります。暗号化コンテキストの使用はオプションですが、ベストプラクティスとして推奨します。
暗号化コンテキストのペアを含むシンプルなオブジェクトを作成します。各ペアのキーと値は、文字列である必要があります。
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
```
const context = {
stage: 'demo',
purpose: 'simple demonstration app',
origin: 'us-west-2'
}
```
ステップ 4: データを暗号化します。
プレーンテキストのデータを暗号化するには、`encrypt` 関数を呼び出します。 AWS KMS キーリング、プレーンテキストデータ、および暗号化コンテキストを渡します。
`encrypt` 関数は、暗号化されたデータ、暗号化されたデータキー、重要なメタデータ (暗号化コンテキストや署名など) を含む[暗号化されたメッセージ](concepts.md#message) (`result`) を返します。
[この暗号化されたメッセージは、サポートされているプログラミング言語の を使用して復号](#javascript-example-decrypt)できます。 AWS Encryption SDK
```
const plaintext = new Uint8Array([1, 2, 3, 4, 5])
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
```
const plaintext = 'asdf'
const { result } = await encrypt(keyring, plaintext, { encryptionContext: context })
```
## AWS KMS キーリングを使用したデータの復号化
を使用して AWS Encryption SDK for JavaScript 暗号化されたメッセージを復号し、元のデータを復元できます。
この例では、「[AWS KMS キーリングによるデータの暗号化](#javascript-example-encrypt)」の例で暗号化したデータを復号します。
ステップ 1: コミットメントポリシーを設定します。
のバージョン 1.7.*x* 以降では AWS Encryption SDK for JavaScript、 AWS Encryption SDK クライアントをインスタンス化する新しい`buildClient`関数を呼び出すときにコミットメントポリシーを設定できます。`buildClient` 関数は、コミットメントポリシーを表す列挙値を取ります。更新された `encrypt` 関数と `decrypt` 関数が返されて、暗号化および復号化時にコミットメントポリシーが適用されます。
次の例では、 `buildClient`関数を使用してデフォルトの[コミットメントポリシー](migrate-commitment-policy.md) を指定します`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。を使用して`buildClient`、暗号化されたメッセージ内の暗号化されたデータキーの数を制限することもできます。詳細については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
```
import {
KmsKeyringBrowser,
KMS,
getClient,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-browser'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
```
import {
KmsKeyringNode,
buildClient,
CommitmentPolicy,
} from '@aws-crypto/client-node'
const { encrypt, decrypt } = buildClient(
CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
```
ステップ 2: キーリングを作成します。
データを復号するには、`encrypt` 関数が返す[暗号化されたメッセージ](concepts.md#message) (`result`) を渡します。暗号化されたメッセージには、暗号化されたデータ、暗号化されたデータキー、重要なメタデータ (暗号化コンテキストや署名など) が含まれています。
[AWS KMS キーリング](use-kms-keyring.md)は、復号時にも指定する必要があります。データの暗号化に使用したものと同じキーリングを使用することも、別のキーリングを使用することもできます。成功するには、復号キーリングの少なくとも AWS KMS key 1 つが、暗号化されたメッセージ内の暗号化されたデータキーの 1 つを復号できる必要があります。データキーは生成されないため、復号キーリングでジェネレーターキーを指定する必要はありません。指定しても、ジェネレーターキーと追加のキーは同じように扱われます。
で復号キーリング AWS KMS key の を指定するには AWS Encryption SDK for JavaScript、[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) を使用する必要があります。それ以外の場合、 AWS KMS key は認識されません。 AWS KMS キーリング AWS KMS keys で を識別する方法については、「」を参照してください。 [AWS KMS キーリング AWS KMS keys での の識別](use-kms-keyring.md#kms-keyring-id)
暗号化と復号に同じキーリングを使用する場合は、キー ARNs を使用してキーリング AWS KMS keys 内の を識別します。
この例では、暗号化キーリング AWS KMS keys に の 1 つだけを含むキーリングを作成します。このコードを実行する前に、キー ARN を有効なキー ARN に置き換えます。 AWS KMS keyに対する `kms:Decrypt` アクセス許可が必要です。
まず、ブラウザの認証情報を指定します。この AWS Encryption SDK for JavaScript の例では、認証情報の定数を実際の認証情報に置き換える [webpack.DefinePlugin](https://webpack.js.org/plugins/define-plugin/) を使用しています。ただし、認証情報の指定には任意の方法を使用することができます。次に、認証情報を使用して AWS KMS クライアントを作成します。
```
declare const credentials: {accessKeyId: string, secretAccessKey:string, sessionToken:string }
const clientProvider = getClient(KMS, {
credentials: {
accessKeyId,
secretAccessKey,
sessionToken
}
})
```
次に、 AWS KMS クライアントを使用して AWS KMS キーリングを作成します。この例では、暗号化キーリング AWS KMS keys から 1 つの のみを使用します。
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringBrowser({ clientProvider, keyIds })
```
```
const keyIds = ['arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab']
const keyring = new KmsKeyringNode({ keyIds })
```
ステップ 3: データを復号します。
次に、`decrypt` 関数を呼び出します。先ほど作成した復号化キーリング (`keyring`) および `encrypt` 関数が返す[暗号化されたメッセージ](concepts.md#message) (`result`) を渡します。 AWS Encryption SDK はキーリングを使用して、暗号化されたデータキーの 1 つを復号します。次に、そのプレーンテキストのデータキーを使用してデータを復号します。
呼び出しが成功すると、`plaintext` フィールドにはプレーンテキストの (復号された) データが含まれます。`messageHeader` フィールドには、データの復号に使用した暗号化コンテキストなどの復号プロセスに関するメタデータが含まれます。
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
```
const { plaintext, messageHeader } = await decrypt(keyring, result)
```
ステップ 4: 暗号化コンテキストを確認します。
データの復号に使用した[暗号化コンテキスト](concepts.md#encryption-context)は、`decrypt` 関数から返されるメッセージヘッダー (`messageHeader`) に含まれます。アプリケーションでプレーンテキストのデータを返す前に、暗号化時に指定した暗号化コンテキストが復号時に使用した暗号化コンテキストに含まれていることを確認します。一致しない場合は、データが改ざんされたか、復号する暗号化テキストを間違ったことを示している可能性があります。
暗号化コンテキストを確認する際は、完全に一致している必要ありません。署名付きの暗号化アルゴリズムを使用する場合、[暗号化マテリアルマネージャー](concepts.md#crypt-materials-manager) (CMM) は、メッセージを暗号化する前にパブリック署名キーを暗号化コンテキストに追加します。ただし、送信したすべての暗号化コンテキストのペアが返された暗号化コンテキストに含まれている必要があります。
まず、メッセージヘッダーから暗号化コンテキストを取得します。次に、元の暗号化コンテキスト (`context`) のキーと値の各ペアが、返された暗号化コンテキスト (`encryptionContext`) のキーと値のペアと一致することを確認します。
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
```
const { encryptionContext } = messageHeader
Object
.entries(context)
.forEach(([key, value]) => {
if (encryptionContext[key] !== value) throw new Error('Encryption Context does not match expected values')
})
```
暗号化コンテキストを確認して問題がなければ、プレーンテキストのデータを返すことができます。
# AWS Encryption SDK for Python
このトピックでは、 AWS Encryption SDK for Pythonをインストールして使用する方法について説明します。を使用したプログラミングの詳細については AWS Encryption SDK for Python、GitHub の [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) リポジトリを参照してください。API のドキュメントについては、[Read the Docs](https://aws-encryption-sdk-python.readthedocs.io/en/latest/) を参照してください。
**Topics**
+ [前提条件](#python-prerequisites)
+ [インストール](#python-installation)
+ [例](python-example-code.md)
## 前提条件
をインストールする前に AWS Encryption SDK for Python、次の前提条件を満たしていることを確認してください。
**Python のサポートされているバージョン**
AWS Encryption SDK for Python バージョン 3.2.0 以降では、Python 3.8 以降が必要です。
[AWS 暗号化マテリアルプロバイダーライブラリ](https://github.com/aws/aws-cryptographic-material-providers-library) (MPL) は、バージョン 4.*x* で AWS Encryption SDK for Python 導入された のオプション依存関係です。MPL をインストールする場合は、Python 3.11 以降を使用する必要があります。
以前のバージョンの は Python 2.7 および Python 3.4 以降 AWS Encryption SDK をサポートしていますが、最新バージョンの を使用することをお勧めします AWS Encryption SDK。
Python をダウンロードするには、「[Python のダウンロード](https://www.python.org/downloads/)」を参照してください。
**Python 用 pip インストールツール**
`pip` は、Python 3.6 以降のバージョンには含まれていますが、アップグレードすることをお勧めします。`pip` のアップグレードまたはインストールの詳細については、「`pip` ドキュメント」の「[インストール](https://pip.pypa.io/en/latest/installation/)」を参照してください。
## インストール
AWS Encryption SDK for Pythonの最新バージョンをインストールします。
**注記**
3.0.0 より AWS Encryption SDK for Python 前の のすべてのバージョンは[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.0.x 以降から AWS Encryption SDK の最新バージョンにコードやデータを変更せずに安全に更新できます。ただし、バージョン 2.0.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。1.7.x より前のバージョンから 2.0.x 以降のバージョンに更新するには、まず AWS Encryption SDKの最新の 1.x バージョンに更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
次の例に示すように AWS Encryption SDK for Python、 `pip`を使用して をインストールします。
**最新バージョンをインストールするには**
```
pip install "aws-encryption-sdk[MPL]"
```
`[MPL]` サフィックスは、[AWS 暗号化マテリアルプロバイダーライブラリ (MPL) をインストールします](https://github.com/aws/aws-cryptographic-material-providers-library)。MPL には、データを暗号化および復号するためのコンストラクトが含まれています。MPL は、バージョン 4.*x* で AWS Encryption SDK for Python 導入された のオプション依存関係です。MPL のインストールを強くお勧めします。ただし、MPL を使用する予定がない場合は、`[MPL]`サフィックスを省略できます。
pip を使用してパッケージをインストールおよびアップグレードする方法の詳細については、「[パッケージのインストール](https://packaging.python.org/tutorials/installing-packages/)」を参照してください。
では、すべてのプラットフォームで[暗号化ライブラリ](https://cryptography.io/en/latest/) (pyca/cryptography) AWS Encryption SDK for Python が必要です。`pip` のすべてのバージョンでは、Windows に `cryptography` ライブラリがインストールされて構築されます。`pip` 8.1 以降では、Linux に `cryptography` が自動的にインストールされて構築されます。以前のバージョンの `pip` を使用していて、Linux 環境に、`cryptography` ライブラリを構築するために必要なツールがない場合は、それらをインストールする必要があります。詳細については、「[Building cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)」を参照してください。
バージョン 1.10.0 と 2.5.0 は、2.5.0 と 3.3.2 の間の[暗号化](https://cryptography.io/en/latest/)依存関係 AWS Encryption SDK for Python を固定します。の他のバージョンでは、最新バージョンの暗号化 AWS Encryption SDK for Python がインストールされます。3.3.2 以降の暗号化のバージョンが必要な場合は、 AWS Encryption SDK for Pythonの最新のメジャーバージョンを使用することを推奨します。
の最新バージョンについては AWS Encryption SDK for Python、GitHub の [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) リポジトリを参照してください。
をインストールしたら AWS Encryption SDK for Python、このガイドの [Python サンプルコード](python-example-code.md)を参照して開始します。
# AWS Encryption SDK for Python サンプルコード
次の例は、 AWS Encryption SDK for Python を使用してデータを暗号化および復号する方法を示しています。
このセクションの例では、オプションの[暗号化マテリアルプロバイダーライブラリ](https://github.com/aws/aws-cryptographic-material-providers-library)の依存関係 () AWS Encryption SDK for Python で のバージョン 4.*x* を使用する方法を示します`aws-cryptographic-material-providers`。以前のバージョンを使用する例、またはマテリアルプロバイダーライブラリ (MPL) を使用しないインストールを表示するには、GitHub の [aws-encryption-sdk-python](https://github.com/aws/aws-encryption-sdk-python/) リポジトリの[リリース](https://github.com/aws/aws-encryption-sdk-python/releases)リストでリリースを検索します。
MPL AWS Encryption SDK for Python で のバージョン 4.*x* を使用する場合、[キーリング](choose-keyring.md)を使用して[エンベロープ暗号化](concepts.md#envelope-encryption)を実行します。 AWS Encryption SDK には、以前のバージョンで使用していたマスターキープロバイダーと互換性のあるキーリングが用意されています。詳細については、「[キーリングの互換性](choose-keyring.md#keyring-compatibility)」を参照してください。マスターキープロバイダーからキーリングへの移行の例については、GitHub の `aws-encryption-sdk-python`リポジトリの[「移行の例](https://github.com/aws/aws-encryption-sdk-python/tree/master/examples/src/migration)」を参照してください。
**Topics**
+ [文字列](#python-example-strings)
+ [バイトストリーム](#python-example-streams)
## 文字列の暗号化と復号
次の例は、 を使用して文字列 AWS Encryption SDK を暗号化および復号する方法を示しています。この例では、対称暗号化 KMS キーを持つ キー[AWS KMS リング](use-kms-keyring.md)を使用します。
この例では、[デフォルトのコミットメントポリシー](migrate-commitment-policy.md) を使用して AWS Encryption SDK クライアントをインスタンス化します`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。詳細については、「[コミットメントポリシーの設定](migrate-commitment-policy.md)」を参照してください。
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example sets up the KMS Keyring
The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and
decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA
with an encryption context. This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings
of the same or a different type.
"""
import boto3
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import CreateAwsKmsKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
EXAMPLE_DATA: bytes = b"Hello World"
def encrypt_and_decrypt_with_keyring(
kms_key_id: str
):
"""Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring.
Usage: encrypt_and_decrypt_with_keyring(kms_key_id)
:param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and
decryption of your data keys.
:type kms_key_id: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. Create a boto3 client for KMS.
kms_client = boto3.client('kms', region_name="us-west-2")
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"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",
}
# 4. Create your keyring
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput(
kms_key_id=kms_key_id,
kms_client=kms_client
)
kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring(
input=keyring_input
)
# 5. Encrypt the data with the encryptionContext.
ciphertext, _ = client.encrypt(
source=EXAMPLE_DATA,
keyring=kms_keyring,
encryption_context=encryption_context
)
# 6. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert ciphertext != EXAMPLE_DATA, \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 7. Decrypt your encrypted data using the same keyring you used on encrypt.
plaintext_bytes, _ = client.decrypt(
source=ciphertext,
keyring=kms_keyring,
# Provide the encryption context that was supplied to the encrypt method
encryption_context=encryption_context,
)
# 8. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert plaintext_bytes == EXAMPLE_DATA, \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
## バイトストリームの暗号化と復号
次の例は、 を使用してバイトストリーム AWS Encryption SDK を暗号化および復号する方法を示しています。この例では、[Raw AES キーリング](use-raw-aes-keyring.md)を使用します。
この例では、[デフォルトのコミットメントポリシー](migrate-commitment-policy.md) を使用して AWS Encryption SDK クライアントをインスタンス化します`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`。詳細については、「[コミットメントポリシーの設定](migrate-commitment-policy.md)」を参照してください。
```
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
This example demonstrates file streaming for encryption and decryption.
File streaming is useful when the plaintext or ciphertext file/data is too large to load into
memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it
all at once in memory. In this example, we demonstrate file streaming for encryption and decryption
using a Raw AES keyring. However, you can use any keyring with streaming.
This example creates a Raw AES Keyring and then encrypts an input stream from the file
`plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`.
It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`.
This example also includes some sanity checks for demonstration:
1. Ciphertext and plaintext data are not the same
2. Encryption context is correct in the decrypted message header
3. Decrypted plaintext value matches EXAMPLE_DATA
These sanity checks are for demonstration in the example only. You do not need these in your code.
See raw_aes_keyring_example.py in the same directory for another raw AES keyring example
in the AWS Encryption SDK for Python.
"""
import filecmp
import secrets
from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders
from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig
from aws_cryptographic_material_providers.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput
from aws_cryptographic_material_providers.mpl.references import IKeyring
from typing import Dict # noqa pylint: disable=wrong-import-order
import aws_encryption_sdk
from aws_encryption_sdk import CommitmentPolicy
def encrypt_and_decrypt_with_keyring(
plaintext_filename: str,
ciphertext_filename: str,
decrypted_filename: str
):
"""Demonstrate a streaming encrypt/decrypt cycle.
Usage: encrypt_and_decrypt_with_keyring(plaintext_filename
ciphertext_filename
decrypted_filename)
:param plaintext_filename: filename of the plaintext data
:type plaintext_filename: string
:param ciphertext_filename: filename of the ciphertext data
:type ciphertext_filename: string
:param decrypted_filename: filename of the decrypted data
:type decrypted_filename: string
"""
# 1. Instantiate the encryption SDK client.
# This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy,
# which enforces that this client only encrypts using committing algorithm suites and enforces
# that this client will only decrypt encrypted messages that were created with a committing
# algorithm suite.
# This is the default commitment policy if you were to build the client as
# `client = aws_encryption_sdk.EncryptionSDKClient()`.
client = aws_encryption_sdk.EncryptionSDKClient(
commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT
)
# 2. The key namespace and key name are defined by you.
# and are used by the Raw AES keyring to determine
# whether it should attempt to decrypt an encrypted data key.
key_name_space = "Some managed raw keys"
key_name = "My 256-bit AES wrapping key"
# 3. Optional: create encryption context.
# Remember that your encryption context is NOT SECRET.
encryption_context: Dict[str, str] = {
"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",
}
# 4. Generate a 256-bit AES key to use with your keyring.
# In practice, you should get this key from a secure key management system such as an HSM.
# Here, the input to secrets.token_bytes() = 32 bytes = 256 bits
static_key = secrets.token_bytes(32)
# 5. Create a Raw AES keyring
# We choose to use a raw AES keyring, but any keyring can be used with streaming.
mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(
config=MaterialProvidersConfig()
)
keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput(
key_namespace=key_name_space,
key_name=key_name,
wrapping_key=static_key,
wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16
)
raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring(
input=keyring_input
)
# 6. Encrypt the data stream with the encryptionContext
with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file:
with client.stream(
mode='e',
source=pt_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as encryptor:
for chunk in encryptor:
ct_file.write(chunk)
# 7. Demonstrate that the ciphertext and plaintext are different.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \
"Ciphertext and plaintext data are the same. Invalid encryption"
# 8. Decrypt your encrypted data stream using the same keyring you used on encrypt.
with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file:
with client.stream(
mode='d',
source=ct_file,
keyring=raw_aes_keyring,
encryption_context=encryption_context
) as decryptor:
for chunk in decryptor:
pt_file.write(chunk)
# 10. Demonstrate that the decrypted plaintext is identical to the original plaintext.
# (This is an example for demonstration; you do not need to do this in your own code.)
assert filecmp.cmp(plaintext_filename, decrypted_filename), \
"Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
```
# AWS Encryption SDK Rust 用
このトピックでは、 AWS Encryption SDK for Rust をインストールして使用する方法について説明します。 AWS Encryption SDK for Rust を使用したプログラミングの詳細については、GitHub の aws-encryption-sdk リポジトリの [Rust](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/) ディレクトリを参照してください。
AWS Encryption SDK for Rust は、以下の点 AWS Encryption SDK で の他のプログラミング言語実装とは異なります。
+ [データキーキャッシュ](data-key-caching.md)はサポートされていません。ただし、 AWS Encryption SDK for Rust は、代替の暗号化マテリアルキャッシュソリューションである[AWS KMS 階層キーリング](use-hierarchical-keyring.md)をサポートしています。
+ ストリーミングデータはサポートしていません
AWS Encryption SDK for Rust には、 の他の言語実装のバージョン 2.0.*x* 以降で導入されたすべてのセキュリティ機能が含まれています AWS Encryption SDK。ただし、 AWS Encryption SDK for Rust を使用して、 の 2.0.*x* より前のバージョンの別の言語実装で暗号化されたデータを復号する場合は AWS Encryption SDK、[コミットメントポリシー](concepts.md#commitment-policy)を調整する必要がある場合があります。詳細については、「[コミットメントポリシーの設定方法](migrate-commitment-policy.md#migrate-commitment-step1)」を参照してください。
AWS Encryption SDK for Rust は、仕様を記述する正式な検証言語である [Dafny](https://github.com/dafny-lang/dafny/blob/master/README.md) AWS Encryption SDK の の製品であり、実装するコード、およびテストするための証明です。その結果、機能の正確性を保証するフレームワークに、 AWS Encryption SDK の機能を実装するライブラリができあがりました。
**詳細はこちら**
+ 代替アルゴリズムスイートの指定 AWS Encryption SDK、暗号化されたデータキーの制限、 AWS KMS マルチリージョンキーの使用など、 でオプションを設定する方法の例については、「」を参照してください[の設定 AWS Encryption SDK](configure.md)。
+ Rust AWS Encryption SDK の を設定して使用する方法の例については、GitHub の aws-encryption-sdk リポジトリの [Rust の例](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples)を参照してください。
**Topics**
+ [前提条件](#prerequisites-rust)
+ [インストール](#rust-installation)
+ [例](rust-examples.md)
## 前提条件
AWS Encryption SDK for Rust をインストールする前に、次の前提条件があることを確認してください。
**Rust と Cargo をインストールする**
[rustup](https://rustup.rs/) を使用して [Rust](https://www.rust-lang.org/) の現在の安定リリースをインストールします。
rustup のダウンロードとインストールの詳細については、「Cargo Book」の[「インストール手順](https://doc.rust-lang.org/cargo/getting-started/installation.html)」を参照してください。
## インストール
AWS Encryption SDK for Rust は[https://crates.io/crates/aws-esdk](https://crates.io/crates/aws-esdk)、Crates.io で木箱として利用できます。 AWS Encryption SDK for Rust のインストールと構築の詳細については、GitHub の aws-encryption-sdk リポジトリの [README.md](https://github.com/aws/aws-encryption-sdk/tree/mainline) を参照してください。
AWS Encryption SDK for Rust は、次の方法でインストールできます。
**手動**
AWS Encryption SDK for Rust をインストールするには、[aws-encryption-sdk](https://github.com/aws/aws-encryption-sdk/tree/mainline) GitHub リポジトリのクローンを作成するか、ダウンロードします。
**Crates.io の使用**
プロジェクトディレクトリで次の Cargo コマンドを実行します。
```
cargo add aws-esdk
```
または、Cargo.toml に次の行を追加します。
```
aws-esdk = ""
```
# AWS Encryption SDK Rust のサンプルコード
次の例は、 AWS Encryption SDK for Rust でプログラミングするときに使用する基本的なコーディングパターンを示しています。具体的には、 AWS Encryption SDK とマテリアルプロバイダーライブラリをインスタンス化します。次に、各メソッドを呼び出す前に、メソッドの入力を定義する オブジェクトをインスタンス化します。
代替アルゴリズムスイートの指定や暗号化されたデータキーの制限など AWS Encryption SDK、 でオプションを設定する方法の例については、GitHub の aws-encryption-sdk リポジトリの [Rust の例](https://github.com/aws/aws-encryption-sdk-dafny/tree/mainline/AwsEncryptionSDK/runtimes/rust/examples/)を参照してください。
## AWS Encryption SDK for Rust でのデータの暗号化と復号
この例では、データを暗号化および復号するための基本的なパターンを示しています。1 つのラ AWS KMS ッピングキーで保護されたデータキーを使用して小さなファイルを暗号化します。
**ステップ 1: をインスタンス化します AWS Encryption SDK。**
のメソッドを使用して、データを AWS Encryption SDK 暗号化および復号します。
```
let esdk_config = AwsEncryptionSdkConfig::builder().build()?;
let esdk_client = esdk_client::Client::from_conf(esdk_config)?;
```
**ステップ 2: AWS KMS クライアントを作成する。**
```
let sdk_config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
let kms_client = aws_sdk_kms::Client::new(&sdk_config);
```
**オプション: 暗号化コンテキストを作成します。**
```
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()),
]);
```
**ステップ 3: マテリアルプロバイダーライブラリをインスタンス化します。**
マテリアルプロバイダライブラリのメソッドを使用して、データを保護するキーを指定するキーリングを作成します。
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
```
**ステップ 4: AWS KMS キーリングを作成します。**
キーリングを作成するには、キーリング入力オブジェクトを使用してキーリングメソッドを呼び出します。この例では、 `create_aws_kms_keyring()`メソッドを使用し、1 つの KMS キーを指定します。
```
let kms_keyring = mpl
.create_aws_kms_keyring()
.kms_key_id(kms_key_id)
.kms_client(kms_client)
.send()
.await?;
```
**ステップ 5: プレーンテキストを暗号化します。**
```
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?;
let ciphertext = encryption_response
.ciphertext
.expect("Unable to unwrap ciphertext from encryption response");
```
**ステップ 6: 暗号化に使用したのと同じキーリングを使用して、暗号化されたデータを復号します。**
```
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?;
let decrypted_plaintext = decryption_response
.plaintext
.expect("Unable to unwrap plaintext from decryption response");
```
# AWS Encryption SDK コマンドラインインターフェイス
AWS Encryption SDK コマンドラインインターフェイス (AWS Encryption CLI) を使用すると、 を使用して AWS Encryption SDK 、コマンドラインとスクリプトでデータをインタラクティブに暗号化および復号化できます。暗号化やプログラミングの専門知識は必要ありません。
**注記**
4.0.0 より前のバージョンの AWS Encryption CLI は[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.1.x 以降から、コードやデータを変更せずに最新バージョンの AWS Encryption CLI に安全に更新できます。ただし、バージョン 2.1.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。バージョン 1.7.*x* 以前から更新するには、まず Encryption AWS CLI の最新バージョンの 1.*x* に更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.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、Encryption AWS CLI には高度なデータ保護機能が用意されています。これには[エンベロープ暗号化](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/how-it-works.html#envelope-encryption)、追加の認証データ (AAD)、キー取得、[キーコミットメント](concepts.md#key-commitment)、署名で使用する 256 ビット AES-GCM などのセキュアで認証済みの対称キー[アルゴリズムスイート](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/supported-algorithms.html)などが含まれます。
AWS Encryption CLI は 上に構築[AWS Encryption SDK for Python](python.md)されており、Linux、macOS、および Windows でサポートされています。コマンドやスクリプトを実行して、Linux や macOS の任意のシェル、Windows のコマンドプロンプトウィンドウ (cmd.exe)、任意のシステムの PowerShell コンソールでデータを暗号化および復号することができます。
Encryption AWS CLI AWS Encryption SDKを含む の言語固有の実装はすべて相互運用可能です。たとえば、 でデータを暗号化[AWS Encryption SDK for Java](java.md)し、Encryption CLI AWS で復号できます。
このトピックでは、Encryption AWS CLI を紹介し、インストールして使用する方法と、使用開始に役立ついくつかの例を示します。クイックスタートについては、 AWS セキュリティブログ[の「暗号化 CLI を使用してデータを AWS 暗号化および復号する方法](https://aws.amazon.com/blogs/security/how-to-encrypt-and-decrypt-your-data-with-the-aws-encryption-cli/)」を参照してください。詳細については、[「 ドキュメントを読み](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)、GitHub の aws-encryption-sdk-cli AWS リポジトリで Encryption CLI の開発に参加してください。」を参照してください。 [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/)
**パフォーマンス**
Encryption AWS CLI は 上に構築されています AWS Encryption SDK for Python。CLI を実行するたびに、Python ランタイムの新しいインスタンスが起動されます。パフォーマンスを向上させるには、個別のコマンドを何回も使用するのではなく、できるだけ 1 つのコマンドを使用します。例えば、ファイルごとに個別のコマンドを実行するのではなく、ディレクトリ内のファイルを再帰的に処理する 1 つのコマンドを実行します。
**Topics**
+ [CLI のインストール](crypto-cli-install.md)
+ [CLI の使用方法](crypto-cli-how-to.md)
+ [例](crypto-cli-examples.md)
+ [構文およびパラメータのリファレンス](crypto-cli-reference.md)
+ [バージョン](crypto-cli-versions.md)
# AWS Encryption SDK コマンドラインインターフェイスのインストール
このトピックでは、Encryption AWS CLI をインストールする方法について説明します。詳細については、GitHub の [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) リポジトリおよび「[ドキュメントを読む](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)」を参照してください。
**Topics**
+ [前提条件のインストール](#crypto-cli-prerequisites)
+ [CLI のインストール](#install-sdk-cli)
## 前提条件のインストール
Encryption AWS CLI は 上に構築されています AWS Encryption SDK for Python。 AWS Encryption CLI をインストールするには、Python と `pip`Python パッケージ管理ツールである が必要です。Python と `pip` は、サポートされているすべてのプラットフォームで使用できます。
Encryption CLI AWS をインストールする前に、次の前提条件をインストールします。
**Python**
Encryption CLI バージョン 4.2.0 AWS 以降では、Python 3.8 以降が必要です。
以前のバージョンの AWS Encryption CLI は Python 2.7 および 3.4 以降をサポートしていますが、最新バージョンの AWS Encryption CLI を使用することをお勧めします。
Python は、ほとんどの Linux と macOS のインストールに含まれていますが、Python 3.6 以降にアップグレードする必要があります。最新バージョンの Python の使用をお勧めします。Windows では Python をインストールする必要があります。デフォルトではインストールされていません。Python をダウンロードしてインストールするには、「[Python のダウンロード](https://www.python.org/downloads/)」を参照してください。
Python がインストールされているかどうかを確認するには、コマンドラインで次のように入力します。
```
python
```
Python のバージョンを確認するには `-V` (大文字 V) パラメータを使用します。
```
python -V
```
Windows では、Python をインストールしたら、`Python.exe` ファイルのパスを **Path** 環境変数の値に追加します。
デフォルトでは、`$home` サブディレクトリの Python がインストールされているすべてのユーザーまたはユーザープロファイルディレクトリ内 (`%userprofile%` または `AppData\Local\Programs\Python`) にあります。システム内の `Python.exe` ファイルの場所を確認するには、次のいずれかのレジストリキーを確認します。PowerShell を使用してレジストリを検索できます。
```
PS C:\> dir HKLM:\Software\Python\PythonCore\version\InstallPath
# -or-
PS C:\> dir HKCU:\Software\Python\PythonCore\version\InstallPath
```
**pip**
`pip` は Python パッケージマネージャーです。 AWS Encryption CLI とその依存関係をインストールするには、8.1 `pip` 以降が必要です。`pip` のインストールまたはアップグレードのヘルプについては、`pip` ドキュメントの「[インストール](https://pip.pypa.io/en/latest/installing/)」を参照してください。
Linux インストールでは、 8.1 より`pip`前のバージョンの では、Encryption CLI AWS が必要とする**暗号化**ライブラリを構築できません。`pip` バージョンを更新しないことを選択した場合は、ビルドツールを個別にインストールできます。詳細については、「[Building cryptography on Linux](https://cryptography.io/en/latest/installation.html#building-cryptography-on-linux)」を参照してください。
**AWS Command Line Interface**
AWS Command Line Interface (AWS CLI) は、Encryption CLI で (AWS KMS) AWS KMS keys で AWS Key Management Service AWS を使用している場合にのみ必要です。別の[マスターキープロバイダー](concepts.md#master-key-provider)を使用している場合、 AWS CLI は必要ありません。
Encryption AWS CLI AWS KMS keys で を使用するには、 [をインストール](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)して[設定](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-quick-configuration)する必要があります AWS CLI。この設定により、認証に使用する認証情報が AWS Encryption CLI AWS KMS で使用できるようになります。
## Encryption AWS CLI のインストールと更新
最新バージョンの AWS Encryption CLI をインストールします。`pip` を使用して Encryption CLI AWS をインストールすると、 、Python 暗号化ライブラリ[AWS Encryption SDK for Python](python.md)、 など、CLI に必要な[ライブラリ](https://cryptography.io/en/latest/)が自動的にインストールされます[AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)。
**注記**
4.0.0 より前のバージョンの AWS Encryption CLI は[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.1.x 以降から、コードやデータを変更せずに最新バージョンの AWS Encryption CLI に安全に更新できます。ただし、バージョン 2.1.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。バージョン 1.7.*x* 以前から更新するには、まず Encryption AWS CLI の最新バージョンの 1.*x* に更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.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)を参照してください。
**Encryption CLI AWS の最新バージョンをインストールするには**
```
pip install aws-encryption-sdk-cli
```
**Encryption CLI AWS の最新バージョンにアップグレードするには**
```
pip install --upgrade aws-encryption-sdk-cli
```
**Encryption CLI と AWS のバージョン番号を確認するには AWS Encryption SDK**
```
aws-encryption-cli --version
```
出力には、両方のライブラリのバージョン番号が表示されます。
```
aws-encryption-sdk-cli/2.1.0 aws-encryption-sdk/2.0.0
```
**Encryption CLI AWS の最新バージョンにアップグレードするには**
```
pip install --upgrade aws-encryption-sdk-cli
```
Encryption AWS CLI をインストールすると AWS SDK for Python (Boto3)、最新バージョンの もインストールされます。Boto3 がインストールされている場合、インストーラは Boto3 のバージョンを確認し、必要に応じて更新します。
**インストールされている Boto3 のバージョンを確認するには**
```
pip show boto3
```
**Boto3 の最新バージョンに更新するには**
```
pip install --upgrade boto3
```
現在開発中の Encryption CLI AWS のバージョンをインストールするには、GitHub の [aws-encryption-sdk-cli](https://github.com/aws/aws-encryption-sdk-cli/) リポジトリを参照してください。
`pip` を使用した Python パッケージのインストールおよびアップグレードの詳細については、[pip のドキュメント](https://pip.pypa.io/en/stable/quickstart/)を参照してください。
# Encryption AWS CLI の使用方法
このトピックでは、Encryption CLI AWS でパラメータを使用する方法について説明します。例については「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。完全なドキュメントについては、「[ドキュメントを読む](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)」を参照してください。これらの例に示す構文は、Encryption CLI AWS バージョン 2.1.*x* 以降用です。
**注記**
4.0.0 より前のバージョンの AWS Encryption CLI は[end-of-supportフェーズ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle)にあります。
バージョン 2.1.x 以降から、コードやデータを変更せずに最新バージョンの AWS Encryption CLI に安全に更新できます。ただし、バージョン 2.1.x で導入された[新しいセキュリティ機能](about-versions.md#version-2)には下位互換性がありません。バージョン 1.7.*x* 以前から更新するには、まず Encryption AWS CLI の最新バージョンの 1.*x* に更新する必要があります。詳細については、「[の移行 AWS Encryption SDK](migration.md)」を参照してください。
新しいセキュリティ機能は、もともと AWS Encryption CLI バージョン 1.7.*x* および 2.0.*x* でリリースされました。ただし、 AWS Encryption CLI バージョン 1.8.*x* はバージョン 1.7.*x* に置き換わり、Encryption AWS 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)を参照してください。
暗号化されたデータキーを制限するセキュリティ機能の使用方法の例については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
AWS KMS マルチリージョンキーの使用方法を示す例については、「」を参照してください[マルチリージョンの使用 AWS KMS keys](configure.md#config-mrks)。
**Topics**
+ [データを暗号化および復号する方法](#crypto-cli-e-d-intro)
+ [ラッピングキーの指定方法](#crypto-cli-master-key)
+ [入力を指定する方法](#crypto-cli-input)
+ [出力の場所を指定する方法](#crypto-cli-output)
+ [暗号化コンテキストを使用する方法](#crypto-cli-encryption-context)
+ [コミットメントポリシーの指定方法](#crypto-cli-commitment-policy)
+ [設定ファイルにパラメータを保存する方法](#crypto-cli-config-file)
## データを暗号化および復号する方法
AWS Encryption CLI は の機能を使用して AWS Encryption SDK 、データを安全に暗号化および復号化することを容易にします。
**注記**
`--master-keys` パラメータは AWS Encryption CLI のバージョン 1.8.*x* で非推奨となり、バージョン 2.1.*x* で削除されます。代わりに、`--wrapping-keys` パラメータを使用します。バージョン 2.1.*x* 以降は、`--wrapping-keys` パラメータが暗号化および復号化時に必要となります。詳細については、「[AWS Encryption SDK CLI 構文とパラメータリファレンス](crypto-cli-reference.md)」を参照してください。
+ Encryption CLI AWS でデータを暗号化するときは、プレーンテキストデータと in AWS Key Management Service () などの[ラッピングキー](concepts.md#master-key) (または*マスターキー*) AWS KMS key を指定しますAWS KMS。カスタムのマスターキープロバイダーを使用する場合は、プロバイダーを指定する必要もあります。また、[暗号化されたメッセージ](concepts.md#message)および暗号化オペレーションに関するメタデータの出力場所を指定します。[暗号化コンテキスト](concepts.md#encryption-context)はオプションですが、推奨されています。
バージョン 1.8.*x* では、`--wrapping-keys` パラメータを使用するときに `--commitment-policy` パラメータが必要です。これがない場合は無効です。バージョン 2.1.*x* 以降では、`--commitment-policy` パラメータはオプションですが推奨されます。
```
aws-encryption-cli --encrypt --input myPlaintextData \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myEncryptedMessage \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
AWS Encryption CLI は、一意のデータキーでデータを暗号化します。その後、指定したラッピングキーでデータキーを暗号化します。[暗号化されたメッセージ](concepts.md#message)とオペレーションに関するメタデータが返されます。暗号化されたメッセージには、暗号化されたデータ (*暗号化テキスト*) およびデータキーの暗号化されたコピーが含まれます。データキーの保存、管理、または紛失について心配する必要はありません。
+ データを復号する際、暗号化されたメッセージ、オプションの暗号化コンテキスト、プレーンテキスト出力およびメタデータの場所を渡します。また、Encryption CLI AWS がメッセージの復号に使用できるラッピングキーを指定するか、メッセージを暗号化したラッピングキーを使用できることを AWS Encryption CLI に伝えます。
バージョン 1.8.*x* 以降では、復号時の `--wrapping-keys` パラメータはオプションですが推奨されます。バージョン 2.1.*x* 以降は、`--wrapping-keys` パラメータが暗号化および復号化時に必要となります。
復号するときには、`--wrapping-keys` パラメータの **key** 属性を使用して、データを復号化するラッピングキーを指定します。復号時に AWS KMS ラッピングキーを指定することはオプションですが、使用する予定のないキーを使用できないようにする[ベストプラクティス](best-practices.md)です。カスタムのマスターキープロバイダーを使用する場合は、プロバイダーおよびラッピングキーを指定する必要があります。
key **** 属性を使用しない場合は、 `--wrapping-keys`パラメータの検出[****属性](#discovery-cli-attribute)を に設定する必要があります。これにより`true`、Encryption AWS CLI はメッセージを暗号化したラッピングキーを使用して復号化できます。
ベストプラクティスとして、`--max-encrypted-data-keys` パラメータを使用して、暗号化されたデータキーの数が多すぎる不正な形式のメッセージの復号化を回避してください。暗号化されたデータキーの予想数 (暗号化で使用されるラッピングキーごとに 1 つ)、または適切な最大値 (5 など) を指定します。詳細については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
`--buffer` パラメータでは、デジタル署名が存在する場合の検証も含めて、すべての入力が処理された後にのみプレーンテキストが返されます。
`--decrypt-unsigned` パラメータでは、暗号化テキストを復号し、復号化前にメッセージが署名なしであることを確認します。このパラメータは、`--algorithm` パラメータを使用し、データを暗号化するためのデジタル署名なしのアルゴリズムスイートを選択した場合に使用します。暗号化テキストが署名されている場合、復号化は失敗します。
`--decrypt` または `--decrypt-unsigned` を復号化に使用できますが、両方とも使用することはできません。
```
aws-encryption-cli --decrypt --input myEncryptedMessage \
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab \
--output myPlaintextData \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt
```
AWS Encryption CLI はラッピングキーを使用して、暗号化されたメッセージのデータキーを復号します。次に、データキーを使ってデータを復号します。プレーンテキストのデータとオペレーションに関するメタデータが返されます。
## ラッピングキーの指定方法
Encryption CLI でデータを暗号化する場合は、少なくとも 1 AWS つの[ラッピングキー](concepts.md#master-key) (または*マスターキー*) を指定する必要があります。 AWS KMS keys in AWS Key Management Service (AWS KMS)、カスタム[マスターキープロバイダーからのラッピングキー](concepts.md#master-key-provider)、またはその両方を使用できます。カスタムのマスターキープロバイダは、互換性がある Python マスターキープロバイダのいずれかです。
バージョン 1.8.*x* 以降でラッピングキーを指定するには、`--wrapping-keys` パラメータ (`-w`) を使用します。このパラメータの値は、`attribute=value` 形式を使用する[属性](#cli-master-key-attributes)の集合です。使用する属性は、マスターキープロバイダやコマンドによって異なります。
+ **AWS KMS**。暗号化コマンドでは、**key** 属性を使用して `--wrapping-keys` パラメータを指定する必要があります。バージョン 2.1.*x* 以降は、`--wrapping-keys` パラメータが復号化コマンドにも必要となります。復号化するとき、`--wrapping-keys` パラメータでは、**key** 属性を指定するか、**discovery** 属性を `true` にする必要があります (両方ではない)。その他の属性はオプションです。
+ **カスタムマスターキープロバイダー**。どのコマンドでも `--wrapping-keys` パラメータを指定する必要があります。パラメータ値に **key** および **provider** 属性を含める必要があります。
同じコマンドで[複数の `--wrapping-keys` パラメータ](#cli-many-cmks)および複数の **key** 属性を含めることができます。
### ラッピングキーパラメータの属性
`--wrapping-keys` パラメータの値は、次の属性と値で構成されます。`--wrapping-keys` パラメータ (または `--master-keys` パラメータ) は、すべての暗号化コマンドで必要です。バージョン 2.1.*x* 以降は、`--wrapping-keys` パラメータが復号化時にも必要となります。
属性名や値にスペースや特殊文字が含まれている場合、名前と値の両方を引用符で囲みます。例えば、`--wrapping-keys key=12345 "provider=my cool provider"`。
**Key: ラッピングキーを指定します。**
**key** 属性を使用してラッピングキーを識別します。暗号化時に、この値は、マスターキープロバイダーが認識する任意のキー識別子を使用できます。
```
--wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab
```
暗号化コマンドでは、少なくとも 1 つの **key** 属性と値が含まれている必要があります。複数のラッピングキーでデータキーを暗号化するには、[複数の **key** 属性](#cli-many-cmks)を使用します。
```
aws-encryption-cli --encrypt --wrapping-keys key=1234abcd-12ab-34cd-56ef-1234567890ab key=1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
```
が使用する暗号化コマンドでは AWS KMS keys、**キー**の値はキー ID、キー ARN、エイリアス名、またはエイリアス ARN です。たとえば、この暗号化コマンドでは、**key** 属性の値のエイリアス ARN を使用しています。のキー識別子の詳細については AWS KMS key、「 *AWS Key Management Service デベロッパーガイド*」の[「キー識別子](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)」を参照してください。
```
aws-encryption-cli --encrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:alias/ExampleAlias
```
カスタムのマスターキープロバイダーを使用する復号コマンドでは、**key** および **provider** 属性が必須です。
```
\\ Custom master key provider
aws-encryption-cli --decrypt --wrapping-keys provider='myProvider' key='100101'
```
が使用する復号コマンドでは AWS KMS、**key** 属性を使用して復号 AWS KMS keys に使用する を指定するか、 の値を持つ [**discovery** 属性](#discovery-cli-attribute)を指定できます。これにより`true`、Encryption AWS CLI AWS KMS key はメッセージの暗号化に使用された任意の を使用できます。を指定する場合 AWS KMS key、メッセージの暗号化に使用されるラッピングキーの 1 つである必要があります。
ラッピングキーの指定は、[AWS Encryption SDK のベストプラクティス](best-practices.md)です。これにより、使用する AWS KMS key 予定の を使用することが保証されます。
復号コマンドでは、**key** 属性の値は[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) にする必要があります。
```
\\ AWS KMS key
aws-encryption-cli --decrypt --wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
**検出: 復号 AWS KMS key 時に任意の を使用する**
復号時に AWS KMS keys 使用する を制限する必要がない場合は、**discovery** 属性を の値で使用できます`true`。の値`true`を指定すると、Encryption AWS CLI はメッセージを暗号化 AWS KMS key した を使用して復号できます。**discovery** 属性は、指定しない場合、`false` です (デフォルト)。**discovery** 属性は、復号コマンドで、メッセージが暗号化された場合にのみ有効です AWS KMS keys。
**discovery** 属性を `true` にするのは、**key** 属性を使用して AWS KMS keysを指定することに代わる方法です。で暗号化されたメッセージを復号する場合 AWS KMS keys、各`--wrapping-keys`パラメータには**キー**属性または の値を持つ**検出**属性が必要ですが`true`、両方を持つことはできません。
discovery が true の場合、**discovery-partition** 属性と **discovery-account** 属性を使用して、 AWS KMS keys 使用する を AWS アカウント 指定した 内のものに制限するのがベストプラクティスです。次の例では、**検出**属性により、Encryption AWS CLI は指定された AWS KMS key で を使用できます AWS アカウント。
```
aws-encryption-cli --decrypt --wrapping-keys \
discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
**Provider: マスターキープロバイダーを指定します。**
**provider** 属性は、[マスターキープロバイダー](concepts.md#master-key-provider)を識別します。デフォルト値は `aws-kms` であり、 AWS KMSを表します。別のマスターキープロバイダーを使用している場合、**provider** 属性が必要です。
```
--wrapping-keys key=12345 provider=my_custom_provider
```
カスタム (AWS KMSではない) マスターキープロバイダーを使用する方法の詳細については、[AWS Encryption CLI](https://github.com/aws/aws-encryption-sdk-cli/) レポジトリの [README](https://github.com/aws/aws-encryption-sdk-cli/blob/master/README.rst) ファイルにあるトピック「**高度な設定**」を参照してください。
**リージョン: を指定する AWS リージョン**
region **** 属性を使用して、 AWS リージョン の を指定します AWS KMS key。この属性は、暗号化コマンドで、マスターキープロバイダが AWS KMSのときにのみ有効です。
```
--encrypt --wrapping-keys key=alias/primary-key region=us-east-2
```
AWS 暗号化 CLI コマンド AWS リージョン は、ARN などのリージョンが含まれている場合、**キー**属性値で指定された を使用します。**キー**値が を指定すると AWS リージョン、**リージョン**属性は無視されます。
**region** 属性は、他のリージョンの仕様よりも優先されます。region 属性を使用しない場合、 AWS Encryption CLI コマンドは、 AWS CLI [名前付きプロファイル](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)で AWS リージョン 指定された 、存在する場合は 、またはデフォルトのプロファイルを使用します。
**profile: 名前付きプロファイルを指定**
**profile** 属性を使用して AWS CLI の[名前付きプロファイル](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles)を指定します。名前付きプロファイルには、認証情報と AWS リージョンを含めることができます。この属性は、マスターキープロバイダが AWS KMSでない場合にのみ有効です。
```
--wrapping-keys key=alias/primary-key profile=admin-1
```
**profile** 属性を使用して、暗号化と復号コマンドで別の認証情報を指定できます。Encryption コマンドでは、 AWS Encryption CLI は、**キー**値にリージョンが含まれておらず、**リージョン**属性がない場合にのみ、名前付きプロファイル AWS リージョン で を使用します。復号コマンドでは、名前プロファイル AWS リージョン の は無視されます。
### 複数のラッピングキーを指定する方法
複数のラッピングキー (*マスターキー*) を各コマンドで指定できます。
複数のラッピングキーを指定した場合、最初のラッピングキーはデータの暗号化に使用するデータキーを生成および暗号化します。その他のラッピングキーは、同じデータキーを暗号化します。結果として得られる[暗号化されたメッセージ](concepts.md#message)には、暗号化されたデータ (暗号化テキスト) と各ラッピングキーで 1 つずつ暗号化された一組のデータキーが含まれます。どのラッピングも、1 つの暗号化されたデータキーを復号してデータを復号することができます。
複数のラッピングキーを指定するには、2 つの方法があります。
+ `--wrapping-keys` パラメータの値に複数の **key** 属性を含めます。
```
$key_oregon=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$key_ohio=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
--wrapping-keys key=$key_oregon key=$key_ohio
```
+ 同じコマンドに複数の `--wrapping-keys` パラメータを含めます。この構文は、指定する属性値をコマンドのラッピングキーに一括で適用しない場合に使用します。
```
--wrapping-keys region=us-east-2 key=alias/test_key \
--wrapping-keys region=us-west-1 key=alias/test_key
```
の値を持つ **discovery** 属性`true`を使用すると、Encryption AWS CLI はメッセージを暗号化 AWS KMS key した を使用できます。複数の `--wrapping-keys` パラメータを同じコマンドで使用する場合、`--wrapping-keys` パラメータで `discovery=true` を使用すると、その他の `--wrapping-keys` パラメータで **key** 属性の制限が事実上無効になります。
たとえば、次のコマンドでは、最初の`--wrapping-keys`パラメータの **key** 属性は AWS Encryption CLI を指定された に制限します AWS KMS key。ただし、2 番目の`--wrapping-keys`パラメータの **discovery** 属性を使用すると、Encryption AWS CLI AWS KMS key は指定されたアカウントの のいずれかを使用してメッセージを復号できます。
```
aws-encryption-cli --decrypt \
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
--wrapping-keys discovery=true \
discovery-partition=aws \
discovery-account=111122223333 \
discovery-account=444455556666
```
## 入力を指定する方法
Encryption CLI AWS の暗号化オペレーションは、プレーンテキストデータを入力として受け取り、[暗号化されたメッセージ](concepts.md#message)を返します。復号オペレーションは、暗号化されたメッセージを入力として受け取り、プレーンテキストのデータを返します。
すべての Encryption AWS CLI コマンドでは、入力の場所を Encryption CLI AWS に指示する `--input`パラメータ (`-i`) が必要です。
次のいずれかの方法で入力を指定できます。
+ ファイルを使用します。
```
--input myData.txt
```
+ ファイル名のパターンを使用します。
```
--input testdir/*.xml
```
+ ディレクトリまたはディレクトリ名のパターンを使用します。入力がディレクトリの場合、`--recursive` パラメータ (`-r`、`-R`) が必要です。
```
--input testdir --recursive
```
+ 入力をコマンド (stdin) へパイプします。`-` パラメータに `--input` の値を使用します。(`--input` パラメータは常に必須です。)
```
echo 'Hello World' | aws-encryption-cli --encrypt --input -
```
## 出力の場所を指定する方法
`--output` パラメータは AWS 、暗号化または復号オペレーションの結果を書き込む場所を Encryption CLI に指示します。これは、すべての AWS Encryption CLI コマンドで必要です。 AWS Encryption CLI は、オペレーションの入力ファイルごとに新しい出力ファイルを作成します。
出力ファイルがすでに存在する場合、デフォルトで Encryption AWS CLI は警告を出力し、ファイルを上書きします。上書きされないようにするには、上書きする前に確認のメッセージが表示する `--interactive` パラメータを使用するか、または、出力が上書きしようとすると入力をスキップする `--no-overwrite` を使用します。上書きの警告を表示しないようにするには、`--quiet` を使用します。Encryption CLI AWS からエラーと警告をキャプチャするには、`2>&1`リダイレクト演算子を使用して出力ストリームに書き込みます。
**注記**
出力ファイルを上書きするコマンドは、出力ファイルを削除することで開始します。コマンドが失敗した場合は、出力ファイルが既に削除されている場合があります。
さまざまな方法で出力場所を変更できます。
+ ファイル名を指定します。ファイルにパスを指定する場合、コマンドの実行前にパス内のすべてのディレクトリが存在している必要があります。
```
--output myEncryptedData.txt
```
+ ディレクトリを指定します。コマンドの実行前に出力ディレクトリが存在している必要があります。
入力にサブディレクトリが含まれている場合、コマンドは指定されたディレクトリの下にサブディレクトリを再現します。
```
--output Test
```
出力場所がディレクトリ (ファイル名なし) AWS の場合、Encryption CLI は入力ファイル名とサフィックスに基づいて出力ファイル名を作成します。暗号化オペレーションは、入力ファイル名に `.encrypted` を追加します。復号オペレーションは `.decrypted` を追加します。サフィックスを変更するには、`--suffix` パラメータを使用します。
たとえば、`file.txt` を暗号化する場合、暗号化コマンドは `file.txt.encrypted` を作成します。`file.txt.encrypted` を復号する場合、復号コマンドは `file.txt.encrypted.decrypted` を作成します。
+ コマンドライン (stdout) に書き込みます。`-` パラメータに `--output` の値を入力します。`--output -` を使用して、出力を他のコマンドやプログラムにパイプできます。
```
--output -
```
## 暗号化コンテキストを使用する方法
AWS Encryption CLI では、暗号化コマンドと復号コマンドで暗号化コンテキストを指定できます。これは必須ではありませんが、推奨される暗号化のベストプラクティスです。
*暗号化コンテキスト*は、任意の、シークレットではない*追加認証データ*です。 AWS Encryption CLI では、暗号化コンテキストは `name=value` のペアの集合で構成されます。ペアの内容はどれでも使用できます。これには、権限やポリシーに必要とされるログ、またはデータ内の暗号化オペレーションを探すのに役立つファイルやデータに関する情報が含まれます。
**暗号化コマンドの場合**
暗号化コンポーネントによって追加された追加の暗号化コンテキストと共に、[CMM](concepts.md#crypt-materials-manager) によって追加されたペアは、暗号化されたデータに暗号化されてバインドされます。これは、コマンドが返す[暗号化されたメッセージ](concepts.md#encryption-context)にも含まれています (プレーンテキスト)。を使用している場合 AWS KMS key、暗号化コンテキストは、 などの監査レコードやログにもプレーンテキストで表示されることがあります AWS CloudTrail。
次の例は、`name=value` の 3 つのペアを持つ暗号化コンテキストを示しています。
```
--encryption-context purpose=test dept=IT class=confidential
```
**復号コマンドの場合**
復号コマンドにおいて、暗号化コンテキストは、暗号化された適切なメッセージを復号しているかどうか確認するのに役立ちます。
暗号化コンテキストが暗号化で使用されていないとしても、復号コマンドで暗号化コンテキストを指定する必要はありません。ただし、その場合、Encryption AWS CLI は、復号コマンドの暗号化コンテキストのすべての要素が、暗号化されたメッセージの暗号化コンテキストの要素と一致することを確認します。いずれかの要素が一致しない場合、復号コマンドは失敗します。
たとえば、次のコマンドは、暗号化コンテキストに `dept=IT` が含まれている場合にのみ暗号化メッセージを復号します。
```
aws-encryption-cli --decrypt --encryption-context dept=IT ...
```
暗号化コンテキストは、セキュリティ戦略の重要な部分です。ただし、暗号化コンテキストを選択する際、その値がシークレットではないことに注意してください。暗号化コンテキストに機密データを含めないでください。
**暗号化コンテキストを指定するには**
+ **暗号化**コマンドでは、`--encryption-context` パラメータを 1 つ以上の `name=value` ペアで使用します。各ペアを区切るためにスペースを使用します。
```
--encryption-context name=value [name=value] ...
```
+ **復号**コマンドでは、`--encryption-context` パラメータ値に `name=value` ペア、`name` 要素 (値なし)、または両方の組み合わせを含めることができます。
```
--encryption-context name[=value] [name] [name=value] ...
```
`name` ペアの `value` や `name=value` にスペースや特殊文字が含まれている場合、ペア全体を引用符で囲みます。
```
--encryption-context "department=software engineering" "AWS リージョン=us-west-2"
```
たとえば、この暗号化コマンドには、`purpose=test` と `dept=23` という 2 つのペアを持つ暗号化コンテキストが含まれています。
```
aws-encryption-cli --encrypt --encryption-context purpose=test dept=23 ...
```
これらの復号コマンドは成功します。各コマンドの暗号化コンテキストは、元の暗号化コンテキストのサブセットです。
```
\\ Any one or both of the encryption context pairs
aws-encryption-cli --decrypt --encryption-context dept=23 ...
\\ Any one or both of the encryption context names
aws-encryption-cli --decrypt --encryption-context purpose ...
\\ Any combination of names and pairs
aws-encryption-cli --decrypt --encryption-context dept purpose=test ...
```
ただし、これらの復号コマンドは失敗します。暗号化されたメッセージの暗号化コンテキストには、指定された要素は含まれていません。
```
aws-encryption-cli --decrypt --encryption-context dept=Finance ...
aws-encryption-cli --decrypt --encryption-context scope ...
```
## コミットメントポリシーの指定方法
コマンドに[コミットメントポリシー](concepts.md#commitment-policy)を設定するには、[`--commitment-policy` パラメータ](crypto-cli-reference.md#syntax-commitment-policy)を使用します。このパラメータはバージョン 1.8.*x* で導入されました。暗号化コマンドと復号コマンドで有効です。設定するコミットメントポリシーは、表示されるコマンドに対してのみ有効です。コマンドのコミットメントポリシーを設定しない場合、Encryption AWS CLI はデフォルト値を使用します。
例えば、次のパラメータ値ではコミットメントポリシーが `require-encrypt-allow-decrypt` に設定され、常にキーコミットメントで暗号化されますが、暗号化された暗号化テキストはキーコミットメントの有無にかかわらず復号化されます。
```
--commitment-policy require-encrypt-allow-decrypt
```
## 設定ファイルにパラメータを保存する方法
頻繁に使用する Encryption CLI AWS パラメータと値を設定ファイルに保存することで、時間を節約し、入力エラーを回避できます。
*設定ファイルは*、Encryption AWS CLI コマンドのパラメータと値を含むテキストファイルです。 AWS Encryption CLI コマンドで設定ファイルを参照すると、リファレンスは設定ファイルのパラメータと値で置き換えられます。ファイルの内容をコマンドラインで入力した場合にも同じ効果が得られます。設定ファイルは任意の名前を使用でき、現在のユーザーがアクセス可能な任意のディレクトリに配置できます。
次の設定ファイル (`key.conf`) の例では、2 つの AWS KMS keys を異なるリージョンで指定しています。
```
--wrapping-keys key=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
--wrapping-keys key=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
```
コマンドで設定ファイルを使用するには、ファイル名の先頭にアットマーク (`@`) を使用します。PowerShell コンソールでは、バックティック文字を使用してアットマーク (``@`) をエスケープする必要があります。
このコマンド例では、暗号化コマンドで `key.conf` ファイルを使用します。
------
#### [ Bash ]
```
$ aws-encryption-cli -e @key.conf -i hello.txt -o testdir
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -e `@key.conf -i .\Hello.txt -o .\TestDir
```
------
**設定ファイルのルール**
設定ファイルを使用するためのルールは次のとおりです。
+ 各設定ファイルで複数のパラメータを含めることができ、任意の順序で表示できます。各パラメータとその値 (あれば) を個別の行で表示します。
+ `#` を使用して行の全体または一部にコメントを追加します。
+ 他の設定ファイルへの参照を含めることができます。PowerShell コンソールでも、バックティック文字を使用して `@` 文字をエスケープすることはしないでください。
+ 設定ファイルで引用符を使用する場合、引用されたテキストが複数の行にまたがることはできません。
たとえば、これはサンプル `encrypt.conf` ファイルの内容です。
```
# Archive Files
--encrypt
--output /archive/logs
--recursive
--interactive
--encryption-context class=unclassified dept=IT
--suffix # No suffix
--metadata-output ~/metadata
@caching.conf # Use limited caching
```
コマンドには複数の設定ファイルを含めることもできます。このコマンド例では、`encrypt.conf` との両方の `master-keys.conf` 設定ファイルが使用されます。
------
#### [ Bash ]
```
$ aws-encryption-cli -i /usr/logs @encrypt.conf @master-keys.conf
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli -i $home\Test\*.log `@encrypt.conf `@master-keys.conf
```
------
**Next: **[AWS Encryption CLI の例を試します。](crypto-cli-examples.md)
# Encryption AWS CLI の例
次の例を使用して、希望するプラットフォームで AWS Encryption CLI を試します。マスターキーおよびその他のパラメータのヘルプについては、「[Encryption AWS CLI の使用方法](crypto-cli-how-to.md)」を参照してください。クイックリファレンスについては、「[AWS Encryption SDK CLI 構文とパラメータリファレンス](crypto-cli-reference.md)」を参照してください。
**注記**
次の例では、Encryption CLI AWS バージョン 2.1.*x* の構文を使用します。
新しいセキュリティ機能は、もともと 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)を参照してください。
暗号化されたデータキーを制限するセキュリティ機能の使用方法の例については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
AWS KMS マルチリージョンキーの使用方法を示す例については、「」を参照してください[マルチリージョンの使用 AWS KMS keys](configure.md#config-mrks)。
**Topics**
+ [ファイルの暗号化](#cli-example-encrypt-file)
+ [ファイルの復号](#cli-example-decrypt-file)
+ [ディレクトリ内のすべてのファイルの暗号化](#cli-example-encrypt-directory)
+ [ディレクトリ内のすべてのファイルの復号](#cli-example-decrypt-directory)
+ [コマンドラインでの暗号化と復号](#cli-example-stdin)
+ [複数のマスターキーの使用](#cli-example-multimaster)
+ [スクリプトでの暗号化と復号](#cli-example-script)
+ [データキーキャッシュの使用](#cli-example-caching)
## ファイルの暗号化
この例では AWS 、Encryption CLI を使用して、「Hello World」文字列を含む`hello.txt`ファイルの内容を暗号化します。
ファイルで暗号化コマンドを実行すると、 AWS Encryption CLI はファイルの内容を取得し、一意の[データキー](concepts.md#DEK)を生成し、データキーの下のファイル内容を暗号化してから、[暗号化されたメッセージを](concepts.md#message)新しいファイルに書き込みます。
最初のコマンドは、 のキー ARN を `$keyArn`変数 AWS KMS key に保存します。で暗号化する場合 AWS KMS key、キー ID、キー ARN、エイリアス名、またはエイリアス ARN を使用して識別できます。のキー識別子の詳細については AWS KMS key、「 *AWS Key Management Service デベロッパーガイド*」の[「キー識別子](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id)」を参照してください。
2 番目のコマンドは、ファイルの内容を暗号化します。コマンドは `--encrypt` パラメータを使用してオペレーションを指定し、`--input` パラメータを使用して暗号化するファイルを指定します。[`--wrapping-keys` パラメータ](crypto-cli-how-to.md#crypto-cli-master-key)とその必須の **key** 属性は、キー ARN で AWS KMS key 表される を使用するように コマンドに指示します。
このコマンドは `--metadata-output` パラメータを使用して、暗号化オペレーションに関するメタデータのテキストファイルを指定します。ベストプラクティスとして、このコマンドは `--encryption-context` パラメータを使用して[暗号化コンテキスト](crypto-cli-how-to.md#crypto-cli-encryption-context)を指定します。
このコマンドでは、[`--commitment-policy` パラメータ](crypto-cli-reference.md#syntax-commitment-policy)も使用してコミットメントポリシーを明示的に設定します。バージョン 1.8.*x* では、`--wrapping-keys` パラメータを使用するときにこのパラメータが必要です。バージョン 2.1.*x* 以降では、`--commitment-policy` パラメータはオプションですが推奨されます。
`--output` パラメータの値のドット (.) は、出力ファイルを現在のディレクトリに書き込むようコマンドに指示します。
------
#### [ Bash ]
```
\\ 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 \
--metadata-output ~/metadata \
--encryption-context purpose=test \
--commitment-policy require-encrypt-require-decrypt \
--output .
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input Hello.txt `
--wrapping-keys key=$keyArn `
--metadata-output $home\Metadata.txt `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--output .
```
------
暗号化コマンドが成功した場合、出力を返しません。コマンドが成功したかどうかを確認するには、`$?` 変数のブール値をチェックします。コマンドが成功した場合、`$?` の値は `0` (Bash) または `True` (PowerShell) です。コマンドが失敗した場合、`$?` の値は 0 以外 (Bash) または `False` (PowerShell) です。
------
#### [ Bash ]
```
$ echo $?
0
```
------
#### [ PowerShell ]
```
PS C:\> $?
True
```
------
また、ディレクトリ一覧コマンドを使用して、暗号化コマンドが新しいファイル `hello.txt.encrypted` を作成したかどうかを確認することもできます。encrypt コマンドは出力のファイル名を指定しなかったため、Encryption CLI AWS は入力ファイルと同じ名前と`.encrypted`サフィックスを持つファイルに出力を書き込みました。別のサフィックスを使用するか、サフィックスを抑制するには、`--suffix` パラメータを使用します。
`hello.txt.encrypted` ファイルには、[暗号化メッセージ](concepts.md#message)が含まれています。それには、`hello.txt` ファイルの暗号テキスト、データキーの暗号化コピー、および暗号化コンテキストを含む追加のメタデータが含まれています。
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
```
------
## ファイルの復号
この例では、Encryption AWS CLI を使用して、前の例で暗号化された`Hello.txt.encrypted`ファイルの内容を復号します。
復号コマンドは `--decrypt` パラメータを使用してオペレーションを指定し、`--input` パラメータを使用して復号するファイルを指定します。`--output` パラメータの値は、現在のディレクトリを表すドットです。
**key** 属性を含む `--wrapping-keys` パラメータでは、暗号化されたメッセージの復号に使用するラッピングキーを指定します。を使用した復号コマンドでは AWS KMS keys、key 属性の値は[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) である必要があります。復号コマンドには `--wrapping-keys` パラメータが必要です。 AWS KMS keysを使用している場合は、**key** 属性を使用して復号用の AWS KMS keys を指定するか、**discovery** 属性を `true` にします (両方ではない)。カスタムマスターキープロバイダーを使用している場合、**key** 属性と **provider** 属性は必須です。
バージョン 2.1.x 以降では、[`--commitment-policy` パラメータ](crypto-cli-reference.md#syntax-commitment-policy)はオプションですが推奨されます。明示的に使用すると、デフォルト値 `require-encrypt-require-decrypt` を指定した場合でも、意図が明確になります。
`--encryption-context` パラメータは、暗号化コマンドで[暗号化コンテキスト](crypto-cli-how-to.md#crypto-cli-encryption-context)が指定されている場合でも、復号コマンドではオプションです。この場合、復号コマンドは暗号化コマンドで提供されたものと同じ暗号化コンテキストを使用します。暗号化 CLI AWS は、復号する前に、暗号化されたメッセージの暗号化コンテキストに`purpose=test`ペアが含まれていることを確認します。そうでない場合、復号コマンドは失敗します。
`--metadata-output` パラメータは、復号オペレーションに関するメタデータのファイルを指定します。`--output` パラメータの値のドット (.) は、出力ファイルを現在のディレクトリに書き込みます。
ベストプラクティスとして、`--max-encrypted-data-keys` パラメータを使用して、暗号化されたデータキーの数が多すぎる不正な形式のメッセージの復号化を回避してください。暗号化されたデータキーの予想数 (暗号化で使用されるラッピングキーごとに 1 つ)、または適切な最大値 (5 など) を指定します。詳細については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
`--buffer` では、デジタル署名が存在する場合の検証も含めて、すべての入力が処理された後にのみプレーンテキストが返されます。
------
#### [ Bash ]
```
\\ 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 \
--input hello.txt.encrypted \
--wrapping-keys key=$keyArn \
--commitment-policy require-encrypt-require-decrypt \
--encryption-context purpose=test \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output .
```
------
#### [ PowerShell ]
```
\\ To run this example, replace the fictitious key ARN with a valid value.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input Hello.txt.encrypted `
--wrapping-keys key=$keyArn `
--commitment-policy require-encrypt-require-decrypt `
--encryption-context purpose=test `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output .
```
------
復号コマンドが成功した場合、出力を返しません。コマンドが成功したかどうかを確認するには、`$?` 変数の値を取得します。また、ディレクトリ一覧コマンドを使用して、コマンドが `.decrypted` サフィックスが付加された新しいファイルを作成したかどうかを確認することもできます。プレーンテキストコンテンツを表示するには、ファイルコンテンツを取得するコマンドの `cat` や [Get-Content](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-content) などを使用します。
------
#### [ Bash ]
```
$ ls
hello.txt hello.txt.encrypted hello.txt.encrypted.decrypted
$ cat hello.txt.encrypted.decrypted
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> dir
Directory: C:\TestCLI
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 1:01 PM 11 Hello.txt
-a---- 9/17/2017 1:06 PM 585 Hello.txt.encrypted
-a---- 9/17/2017 1:08 PM 11 Hello.txt.encrypted.decrypted
PS C:\> Get-Content Hello.txt.encrypted.decrypted
Hello World
```
------
## ディレクトリ内のすべてのファイルの暗号化
この例では、Encryption AWS CLI を使用して、ディレクトリ内のすべてのファイルの内容を暗号化します。
コマンドが複数のファイルに影響を与えると、Encryption AWS CLI は各ファイルを個別に処理します。コマンドはファイルの内容を取得し、マスターキーからファイルの一意の[データキー](concepts.md#DEK)を取得し、データキーでファイルの内容を暗号化して、結果を出力ディレクトリの新しいファイルに書き込みます。その結果、出力ファイルを個別に復号することができます。
`TestDir` ディレクトリのこのリストには、暗号化するプレーンテキストファイルが表示されています。
------
#### [ Bash ]
```
$ ls testdir
cool-new-thing.py hello.txt employees.csv
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestDir
Directory: C:\TestDir
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/12/2017 3:11 PM 2139 cool-new-thing.py
-a---- 9/15/2017 5:57 PM 11 Hello.txt
-a---- 9/17/2017 1:44 PM 46 Employees.csv
```
------
最初のコマンドは、 の [Amazon リソースネーム (ARN)](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn) を `$keyArn`変数 AWS KMS key に保存します。
2 番目のコマンドは、`TestDir` ディレクトリ内のファイルのコンテンツを暗号化し、暗号化されたコンテンツのファイルを `TestEnc` ディレクトリに書き込みます。`TestEnc` ディレクトリが存在しない場合、コマンドは失敗します。入力場所はディレクトリのため、`--recursive` パラメータが必要です。
[`--wrapping-keys` パラメータ](crypto-cli-how-to.md#crypto-cli-master-key)とその必須の **key** 属性は、使用するラッピングキーを指定します。暗号化コマンドには[暗号化コンテキスト](crypto-cli-how-to.md#crypto-cli-encryption-context)、`dept=IT` が含まれています。複数のファイルを暗号化するコマンドに暗号化コンテキストを指定すると、すべてのファイルで同じ暗号化コンテキストが使用されます。
コマンドには、暗号化オペレーションに関するメタデータを書き込む場所を Encryption AWS CLI に指示する`--metadata-output`パラメータもあります。 AWS Encryption CLI は、暗号化されたファイルごとに 1 つのメタデータレコードを書き込みます。
バージョン 2.1.x.以降では、[`--commitment-policy parameter`](crypto-cli-how-to.md#crypto-cli-commitment-policy) はオプションですが推奨されます。コマンドまたはスクリプトが暗号化テキストを復号化できないために失敗した場合は、明示的なコミットメントポリシー設定により、問題を迅速に検出できます。
コマンドが完了すると、Encryption AWS CLI は暗号化されたファイルを `TestEnc` ディレクトリに書き込みますが、出力は返しません。
最後のコマンドは `TestEnc` ディレクトリ内のファイルを一覧表示します。プレーンテキストの入力ファイルごとに、暗号化されたコンテンツの出力ファイルが 1 つあります。コマンドは代替サフィックスを指定していないため、暗号化コマンドは各入力ファイル名に `.encrypted` を付加しました。
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input testdir --recursive\
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--output testenc
$ ls testenc
cool-new-thing.py.encrypted employees.csv.encrypted hello.txt.encrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
PS C:\> aws-encryption-cli --encrypt `
--input .\TestDir --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output .\Metadata\Metadata.txt `
--output .\TestEnc
PS C:\> dir .\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
## ディレクトリ内のすべてのファイルの復号
この例では、ディレクトリ内のすべてのファイルを復号します。これは、前の例で暗号化された `TestEnc` ディレクトリ内のファイルから始まります。
------
#### [ Bash ]
```
$ ls testenc
cool-new-thing.py.encrypted hello.txt.encrypted employees.csv.encrypted
```
------
#### [ PowerShell ]
```
PS C:\> dir C:\TestEnc
Directory: C:\TestEnc
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 9/17/2017 2:32 PM 2713 cool-new-thing.py.encrypted
-a---- 9/17/2017 2:32 PM 620 Hello.txt.encrypted
-a---- 9/17/2017 2:32 PM 585 Employees.csv.encrypted
```
------
この復号コマンドは、TestEnc ディレクトリ内のすべてのファイルを復号し、プレーンテキストファイルを TestDec ディレクトリに書き込みます。**キー**属性と[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) AWS 値を持つ `--wrapping-keys`パラメータは、ファイルの復号 AWS KMS keys に使用する Encryption CLI に指示します。コマンドは `--interactive`パラメータを使用して、同じ名前のファイルを上書きする前に Encryption AWS CLI にプロンプトを表示します。
このコマンドは、ファイルが暗号化されたときに指定された暗号化コンテキストも使用します。複数のファイルを復号する場合、Encryption AWS CLI はすべてのファイルの暗号化コンテキストをチェックします。ファイルの暗号化コンテキストチェックが失敗した場合、Encryption AWS CLI はファイルを拒否し、警告を書き込み、失敗をメタデータに記録し、残りのファイルのチェックを続行します。 AWS Encryption CLI が他の理由でファイルの復号に失敗した場合、復号コマンド全体がすぐに失敗します。
この例では、すべての入力ファイルで暗号化されたメッセージに `dept=IT` 暗号化コンテキスト要素が含まれています。ただし、異なる暗号化コンテキストを使用してメッセージを復号している場合でも、暗号化コンテキストの一部を確認できる可能性があります。たとえば、あるメッセージの暗号化コンテキストが `dept=finance` で、他のメッセージが `dept=IT` だった場合、その値を指定しないことで暗号化コンテキストに常に `dept` 名が含まれていることを確認できます。より具体的にするには、別々のコマンドでファイルを復号します。
復号コマンドから返される出力はありませんが、ディレクトリ一覧コマンドを使用して `.decrypted` サフィックスが付いた新しいファイルを作成したことを確認できます。プレーンテキストコンテンツを表示するには、ファイルコンテンツを取得するコマンドを使用します。
------
#### [ Bash ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --decrypt \
--input testenc --recursive \
--wrapping-keys key=$keyArn \
--encryption-context dept=IT \
--commitment-policy require-encrypt-require-decrypt \
--metadata-output ~/metadata \
--max-encrypted-data-keys 1 \
--buffer \
--output testdec --interactive
$ ls testdec
cool-new-thing.py.encrypted.decrypted hello.txt.encrypted.decrypted employees.csv.encrypted.decrypted
```
------
#### [ PowerShell ]
```
# To run this example, replace the fictitious key ARN with a valid master key identifier.
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --decrypt `
--input C:\TestEnc --recursive `
--wrapping-keys key=$keyArn `
--encryption-context dept=IT `
--commitment-policy require-encrypt-require-decrypt `
--metadata-output $home\Metadata.txt `
--max-encrypted-data-keys 1 `
--buffer `
--output C:\TestDec --interactive
PS C:\> dir .\TestDec
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/8/2017 4:57 PM 2139 cool-new-thing.py.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 46 Employees.csv.encrypted.decrypted
-a---- 10/8/2017 4:57 PM 11 Hello.txt.encrypted.decrypted
```
------
## コマンドラインでの暗号化と復号
これらの例は、入力をコマンドにパイプし (stdin)、出力をコマンドライン (stdout) に書き込む方法を示しています。これらは、コマンドで stdin と stdout を表す方法と、組み込みの Base64 エンコードツールを使用してシェルが ASCII 以外の文字を誤って解釈するのを防ぐ方法について説明します。
この例では、パイププレーンテキストの文字列を暗号化コマンドにパイプし、暗号化されたメッセージを変数に保存します。次に、変数に格納された暗号化されたメッセージを復号コマンドにパイプし、その出力をパイプライン (stdout) に書き込みます。
この例では、3 つのコマンドで構成されています。
+ 最初のコマンドは、 の[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) を `$keyArn`変数 AWS KMS key に保存します。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
```
------
+ 2 番目のコマンドは、`Hello World` 文字列を暗号化コマンドにパイプし、その結果を `$encrypted` 変数に保存します。
`--input` および `--output` パラメータは、すべての AWS Encryption CLI コマンドで必須です。入力がコマンドにパイプされている (stdin) ことを示すには、(`-`) を `--input` パラメータの値に使用します。出力をコマンドラインに送信する (stdout) には、`--output` パラメータの値にハイフンを使用します。
`--encode` パラメータは、出力を返す前に Base64 エンコードします。これにより、暗号化されたメッセージの ASCII 以外の文字をシェルが誤って解釈することを防止します。
このコマンドは PoC (概念実証) に過ぎないため、暗号化コンテキストを省略し、メタデータを抑制します (`-S`)。
------
#### [ Bash ]
```
$ encrypted=$(echo 'Hello World' | aws-encryption-cli --encrypt -S \
--input - --output - --encode \
--wrapping-keys key=$keyArn )
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted = 'Hello World' | aws-encryption-cli --encrypt -S `
--input - --output - --encode `
--wrapping-keys key=$keyArn
```
------
+ 3 番目のコマンドは、`$encrypted` 変数に格納された暗号化されたメッセージを復号コマンドにパイプします。
この復号コマンドでは、入力がパイプラインから来ている (stdin) ことを示すために `--input -` を使い、出力をパイプラインに送る (stdout) ために `--output -` を使います。(入力パラメータは実際の入力バイトではなく、入力の場所を取るため、`$encrypted` 変数を `--input` パラメータの値として使用することはできません。)
この例では、 `--wrapping-keys`パラメータの検出****属性を使用して、Encryption AWS CLI が任意の AWS KMS key を使用してデータを復号できるようにします。[コミットメントポリシー](concepts.md#commitment-policy)は指定しないため、バージョン 2.1.*x* 以降のデフォルト値 `require-encrypt-require-decrypt` が使用されます。
出力が暗号化されてエンコードされたため、復号コマンドは `--decode` パラメータを使用して Base64 でエンコードされた入力を復号する前にデコードします。また、`--decode` パラメータを使用して、Base64 でエンコードされた入力を暗号化する前にデコードすることもできます。
ここでも、コマンドは暗号化コンテキストを省略し、メタデータを抑制します (-`S`)。
------
#### [ Bash ]
```
$ echo $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode --buffer -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $encrypted | aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode --buffer -S
Hello World
```
------
暗号化および復号オペレーションは、介在する変数なしで 1 つのコマンドで実行することもできます。
前の例と同様に、`--input` および `--output` パラメータには `-` 値があり、このコマンドは `--encode` パラメータを使用して出力をエンコードし、`--decode` パラメータを使用して入力をデコードします。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ echo 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=true --input - --output - --decode -S
Hello World
```
------
#### [ PowerShell ]
```
PS C:\> $keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> 'Hello World' |
aws-encryption-cli --encrypt --wrapping-keys key=$keyArn --input - --output - --encode -S |
aws-encryption-cli --decrypt --wrapping-keys discovery=$true --input - --output - --decode -S
Hello World
```
------
## 複数のマスターキーの使用
この例では、 AWS Encryption CLI でデータを暗号化および復号するときに複数のマスターキーを使用する方法を示します。
複数のマスターキーを使用してデータを暗号化すると、いずれかのマスターキーを使用してデータを復号できます。この戦略では、マスターキーの 1 つが使用できなくてもデータを復号できます。暗号化されたデータを複数の に保存する場合 AWS リージョン、この戦略では、同じリージョンのマスターキーを使用してデータを復号化できます。
複数のマスターキーで暗号化する場合、最初のマスターキーが特別な役割を果たします。それは、データの暗号化に使用されるデータキーを生成します。残りのマスターキーは、プレーンテキストのデータキーを暗号化します。結果として得られる[暗号化されたメッセージ](concepts.md#message)には、暗号化されたデータと、各マスターキーに対して 1 つずつの暗号化されたデータキーの集合が含まれます。最初のマスターキーがデータキーを生成したにもかかわらず、いずれのマスターキーもデータキーの 1 つを復号でき、それをデータキーの復号に使用することができます。
**3 つのマスターキーによる暗号化**
このコマンド例では、3 つの AWS リージョンの 3 つのラッピングキーを使用して `Finance.log` ファイルを暗号化しています。
これは、暗号化されたメッセージを `Archive` ディレクトリに書き込みます。このコマンドでは、サフィックスを抑制する値を指定せずに `--suffix` パラメータを使用しているため、入力ファイル名と出力ファイル名は変わりません。
このコマンドは、`--wrapping-keys` パラメータとその 3 つの **key** 属性を使用します。同じコマンドで複数の `--wrapping-keys` パラメータを使用することもできます。
ログファイルを暗号化するために、Encryption AWS CLI はリストの最初のラッピングキー に`$key1`、データの暗号化に使用するデータキーの生成を求めます。次に、他の各ラッピングキーを使用して同じデータキーのプレーンテキストコピーを暗号化します。出力ファイルの暗号化されたメッセージには、暗号化された 3 つのデータキーがすべて含まれています。
------
#### [ Bash ]
```
$ key1=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ key2=arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef
$ key3=arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d
$ aws-encryption-cli --encrypt --input /logs/finance.log \
--output /archive --suffix \
--encryption-context class=log \
--metadata-output ~/metadata \
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
#### [ PowerShell ]
```
PS C:\> $key1 = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> $key2 = 'arn:aws:kms:us-east-2:111122223333:key/0987ab65-43cd-21ef-09ab-87654321cdef'
PS C:\> $key3 = 'arn:aws:kms:ap-southeast-1:111122223333:key/1a2b3c4d-5e6f-1a2b-3c4d-5e6f1a2b3c4d'
PS C:\> aws-encryption-cli --encrypt --input D:\Logs\Finance.log `
--output D:\Archive --suffix `
--encryption-context class=log `
--metadata-output $home\Metadata.txt `
--wrapping-keys key=$key1 key=$key2 key=$key3
```
------
このコマンドは、`Finance.log` ファイルの暗号化されたコピーを復号し、それを `Finance.log.clear` ディレクトリの `Finance` ファイルに書き込みます。3 で暗号化されたデータを復号するには AWS KMS keys、同じ 3 AWS KMS keys つ、またはそのサブセットを指定できます。この例では AWS KMS keysを 1 つだけ指定します。
データの復号 AWS KMS keys に使用する AWS Encryption CLI に指示するには、 `--wrapping-keys`パラメータの **key** 属性を使用します。で復号する場合 AWS KMS keys、**キー**属性の値は[キー ARN](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id-key-ARN) である必要があります。
AWS KMS keys 指定した で [Decrypt API](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) を呼び出すアクセス許可が必要です。詳細については、「[AWS KMSに対する認証とアクセスコントロール](https://docs.aws.amazon.com/kms/latest/developerguide/control-access.html)」を参照してください。
ベストプラクティスとして、この例では `--max-encrypted-data-keys` パラメータを使用して、暗号化されたデータキーの数が多すぎる不正なメッセージの復号化を回避します。この例では、復号化にラッピングキーを 1 つだけ使用しますが、暗号化されたメッセージには、暗号化時に使用される 3 つのラッピングキーごとに 1 つずつ、合計 3 つの暗号化されたデータキーがあります。暗号化されたデータキーの予想数または適切な最大値 (5 など) を指定します。3 より小さい最大値を指定すると、コマンドは失敗します。詳細については、「[暗号化されたデータキーの制限](configure.md#config-limit-keys)」を参照してください。
------
#### [ Bash ]
```
$ aws-encryption-cli --decrypt --input /archive/finance.log \
--wrapping-keys key=$key1 \
--output /finance --suffix '.clear' \
--metadata-output ~/metadata \
--max-encrypted-data-keys 3 \
--buffer \
--encryption-context class=log
```
------
#### [ PowerShell ]
```
PS C:\> aws-encryption-cli --decrypt `
--input D:\Archive\Finance.log `
--wrapping-keys key=$key1 `
--output D:\Finance --suffix '.clear' `
--metadata-output .\Metadata\Metadata.txt `
--max-encrypted-data-keys 3 `
--buffer `
--encryption-context class=log
```
------
## スクリプトでの暗号化と復号
この例では、スクリプトで AWS Encryption CLI を使用する方法を示します。データを暗号化または復号するだけのスクリプト、またはデータ管理プロセスの一部として暗号化または復号するスクリプトを作成できます。
この例では、スクリプトはログファイルのコレクションを取得、圧縮してから暗号化し、暗号化されたファイルを Amazon S3 バケットにコピーします。このスクリプトは各ファイルを別々に処理するため、それらを個別に復号して展開できます。
ファイルを圧縮して暗号化するときは、暗号化する前に圧縮する必要があります。適切に暗号化されたデータは圧縮できません。
**警告**
シークレットデータと悪意のあるユーザーによって制御される可能性のあるデータの両方を含むデータを圧縮するときは注意が必要です。圧縮されたデータの最終サイズは、誤ってそのコンテンツに関する機密情報を明らかにする可能性があります。
------
#### [ Bash ]
```
# Continue running even if an operation fails.
set +e
dir=$1
encryptionContext=$2
s3bucket=$3
s3folder=$4
masterKeyProvider="aws-kms"
metadataOutput="/tmp/metadata-$(date +%s)"
compress(){
gzip -qf $1
}
encrypt(){
# -e encrypt
# -i input
# -o output
# --metadata-output unique file for metadata
# -m masterKey read from environment variable
# -c encryption context read from the second argument.
# -v be verbose
aws-encryption-cli -e -i ${1} -o $(dirname ${1}) --metadata-output ${metadataOutput} -m key="${masterKey}" provider="${masterKeyProvider}" -c "${encryptionContext}" -v
}
s3put (){
# copy file argument 1 to s3 location passed into the script.
aws s3 cp ${1} ${s3bucket}/${s3folder}
}
# Validate all required arguments are present.
if [ "${dir}" ] && [ "${encryptionContext}" ] && [ "${s3bucket}" ] && [ "${s3folder}" ] && [ "${masterKey}" ]; then
# Is $dir a valid directory?
test -d "${dir}"
if [ $? -ne 0 ]; then
echo "Input is not a directory; exiting"
exit 1
fi
# Iterate over all the files in the directory, except *gz and *encrypted (in case of a re-run).
for f in $(find ${dir} -type f \( -name "*" ! -name \*.gz ! -name \*encrypted \) ); do
echo "Working on $f"
compress ${f}
encrypt ${f}.gz
rm -f ${f}.gz
s3put ${f}.gz.encrypted
done;
else
echo "Arguments: "
echo " and ENV var \$masterKey must be set"
exit 255
fi
```
------
#### [ PowerShell ]
```
#Requires -Modules AWSPowerShell, Microsoft.PowerShell.Archive
Param
(
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String[]]
$FilePath,
[Parameter()]
[Switch]
$Recurse,
[Parameter(Mandatory=$true)]
[String]
$wrappingKeyID,
[Parameter()]
[String]
$masterKeyProvider = 'aws-kms',
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$ZipDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$EncryptDirectory,
[Parameter()]
[String]
$EncryptionContext,
[Parameter(Mandatory)]
[ValidateScript({Test-Path $_})]
[String]
$MetadataDirectory,
[Parameter(Mandatory)]
[ValidateScript({Test-S3Bucket -BucketName $_})]
[String]
$S3Bucket,
[Parameter()]
[String]
$S3BucketFolder
)
BEGIN {}
PROCESS {
if ($files = dir $FilePath -Recurse:$Recurse)
{
# Step 1: Compress
foreach ($file in $files)
{
$fileName = $file.Name
try
{
Microsoft.PowerShell.Archive\Compress-Archive -Path $file.FullName -DestinationPath $ZipDirectory\$filename.zip
}
catch
{
Write-Error "Zip failed on $file.FullName"
}
# Step 2: Encrypt
if (-not (Test-Path "$ZipDirectory\$filename.zip"))
{
Write-Error "Cannot find zipped file: $ZipDirectory\$filename.zip"
}
else
{
# 2>&1 captures command output
$err = (aws-encryption-cli -e -i "$ZipDirectory\$filename.zip" `
-o $EncryptDirectory `
-m key=$wrappingKeyID provider=$masterKeyProvider `
-c $EncryptionContext `
--metadata-output $MetadataDirectory `
-v) 2>&1
# Check error status
if ($? -eq $false)
{
# Write the error
$err
}
elseif (Test-Path "$EncryptDirectory\$fileName.zip.encrypted")
{
# Step 3: Write to S3 bucket
if ($S3BucketFolder)
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted" -Key "$S3BucketFolder/$fileName.zip.encrypted"
}
else
{
Write-S3Object -BucketName $S3Bucket -File "$EncryptDirectory\$fileName.zip.encrypted"
}
}
}
}
}
}
```
------
## データキーキャッシュの使用
この例では、多数のファイルを暗号化するコマンドで[データキーキャッシュ](data-key-caching.md)を使用します。
デフォルトでは、Encryption AWS CLI (および の他のバージョン AWS Encryption SDK) は、暗号化するファイルごとに一意のデータキーを生成します。各オペレーションに一意のデータキーを使用するのは暗号化のベストプラクティスですが、一部の状況では限定的なデータキーの再利用が許容されます。データキーキャッシュを検討している場合は、セキュリティエンジニアに相談して、アプリケーションのセキュリティ要件を理解し、適切なセキュリティしきい値を判断してください。
この例では、マスターキープロバイダへのリクエストの頻度を減らすことによって、データキーキャッシュは暗号化オペレーションを高速化します。
この例のコマンドは、合計約 800 の小さなログファイルを含む複数のサブディレクトリを持つ大きなディレクトリを暗号化します。最初のコマンドは、 AWS KMS key の ARN を `keyARN` 変数に保存します。2 番目のコマンドは、入力ディレクトリ内のすべてのファイルを (再帰的に) 暗号化し、アーカイブディレクトリに書き込みます。このコマンドでは、`--suffix` パラメータを使用して `.archive` サフィックスを指定します。
`--caching` パラメータはデータキーキャッシュを有効にします。シリアルのファイル処理では一度に複数のデータキーを使用することはないため、キャッシュ内のデータキーの数を制限する **capacity** 属性は 1 に設定されます。キャッシュされたデータキーの使用可能時間を決定する **max\$1age** 属性は 10 秒に設定します。
オプションの **max\$1messages\$1encrypted** 属性は 10 個のメッセージに設定されているため、1 つのデータキーが 10 個以上のファイルを暗号化するために使用されることはありません。各データキーで暗号化するファイル数を制限することで、万一データキーが侵害された場合に影響を受けるファイルの数を減らすことができます。
オペレーティングシステムが生成するログファイルに対してこのコマンドを実行するには、管理者アクセス許可 (Linux では `sudo`、Windows では [**管理者として実行**]) が必要な場合があります。
------
#### [ Bash ]
```
$ keyArn=arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
$ aws-encryption-cli --encrypt \
--input /var/log/httpd --recursive \
--output ~/archive --suffix .archive \
--wrapping-keys key=$keyArn \
--encryption-context class=log \
--suppress-metadata \
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
#### [ PowerShell ]
```
PS C:\> $keyARN = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
PS C:\> aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10
```
------
データキーキャッシュの効果をテストするために、この例では PowerShell の [Measure-Command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/measure-command) コマンドレットを使用します。データキーキャッシュなしでこの例を実行すると、完了に約 25 秒かかります。このプロセスは、ディレクトリ内のファイルごとに新しいデータキーを生成します。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata }
Days : 0
Hours : 0
Minutes : 0
Seconds : 25
Milliseconds : 453
Ticks : 254531202
TotalDays : 0.000294596298611111
TotalHours : 0.00707031116666667
TotalMinutes : 0.42421867
TotalSeconds : 25.4531202
TotalMilliseconds : 25453.1202
```
データキーキャッシュを使用すると、各データキーを最大 10 個のファイルに制限しても、処理が迅速になります。このコマンドは完了するまでに 12 秒もかからず、マスターキープロバイダへの呼び出し回数を元の値の 1/10 に減らしました。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10 max_messages_encrypted=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 11
Milliseconds : 813
Ticks : 118132640
TotalDays : 0.000136727592592593
TotalHours : 0.00328146222222222
TotalMinutes : 0.196887733333333
TotalSeconds : 11.813264
TotalMilliseconds : 11813.264
```
`max_messages_encrypted` の制限を解除すると、すべてのファイルが同じデータキーで暗号化されます。この変更では、プロセスは大幅に高速化されず、データキーの再利用に伴うリスクが高まります。ただし、マスターキープロバイダの呼び出し数は 1 回に減ります。
```
PS C:\> Measure-Command {aws-encryption-cli --encrypt `
--input C:\Windows\Logs --recursive `
--output $home\Archive --suffix '.archive' `
--wrapping-keys key=$keyARN `
--encryption-context class=log `
--suppress-metadata `
--caching capacity=1 max_age=10}
Days : 0
Hours : 0
Minutes : 0
Seconds : 10
Milliseconds : 252
Ticks : 102523367
TotalDays : 0.000118661304398148
TotalHours : 0.00284787130555556
TotalMinutes : 0.170872278333333
TotalSeconds : 10.2523367
TotalMilliseconds : 10252.3367
```
# AWS Encryption SDK CLI 構文とパラメータリファレンス
このトピックでは、 AWS Encryption SDK コマンドラインインターフェイス (CLI) の使用に役立つ構文の例を示し、パラメータについて簡単に説明します。ラッピングキーおよびその他のパラメータのヘルプについては、「[Encryption AWS CLI の使用方法](crypto-cli-how-to.md)」を参照してください。例については「[Encryption AWS CLI の例](crypto-cli-examples.md)」を参照してください。完全なドキュメントについては、「[ドキュメントを読む](https://aws-encryption-sdk-cli.readthedocs.io/en/latest/)」を参照してください。
**Topics**
+ [AWS 暗号化 CLI 構文](#crypto-cli-syntax)
+ [AWS Encryption CLI コマンドラインパラメータ](#crypto-cli-parameters)
+ [高度なパラメータ](#cli-advanced-parameters)
## AWS 暗号化 CLI 構文
これらの AWS Encryption CLI 構文図は、 AWS Encryption CLI で実行する各タスクの構文を示しています。Encryption CLI AWS バージョン 2.1.*x* 以降の推奨構文を表します。
新しいセキュリティ機能は、もともと 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)を参照してください。
**注記**
パラメータの説明に記載されている場合を除き、各パラメータまたは属性は、各コマンドで 1 回のみ使用できます。
パラメータがサポートしていない属性を使用する場合、Encryption AWS CLI はそのサポートされていない属性を警告やエラーなしで無視します。
**ヘルプの表示**
パラメータの説明を含む完全な AWS Encryption CLI 構文を取得するには、 `--help`または を使用します`-h`。
```
aws-encryption-cli (--help | -h)
```
**バージョンの取得**
Encryption CLI AWS インストールのバージョン番号を取得するには、 を使用します`--version`。Encryption CLI AWS の使用に関する質問、問題の報告、ヒントの共有を行う場合は、必ず バージョンを含めてください。
```
aws-encryption-cli --version
```
**データを暗号化する**
次の構文の例は、**encrypt** コマンドで使用するパラメータを示しています。
```
aws-encryption-cli --encrypt
--input [--recursive] [--decode]
--output