翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# AWS KMS 階層キーリング
****
| |
| --- |
| クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md) に関する情報を提供します。 |
**注記**
2023 年 7 月 24 日の時点では、デベロッパープレビュー中に作成されたブランチキーはサポートされていません。新しいブランチキーを作成して、デベロッパープレビュー中に作成したキーストアを引き続き使用します。
AWS KMS 階層キーリングを使用すると、レコードを暗号化または復号する AWS KMS たびに を呼び出すことなく、対称暗号化 KMS キーで暗号化マテリアルを保護できます。これは、 への呼び出しを最小限に抑える必要があるアプリケーションや AWS KMS、セキュリティ要件に違反することなく一部の暗号化マテリアルを再利用できるアプリケーションに適しています。
階層キーリングは、Amazon DynamoDB テーブルに保持されている AWS KMS 保護された*ブランチキー*を使用し、暗号化および復号オペレーションで使用されるブランチキーマテリアルをローカルにキャッシュすることで AWS KMS 、呼び出しの数を減らす暗号化マテリアルキャッシュソリューションです。DynamoDB テーブルは、ブランチキーを管理および保護するキーストアとして機能します。アクティブなブランチキーと、ブランチキーの以前のすべてのバージョンが格納されます。アクティブなブランチキーは、ブランチキーの最新バージョンです。階層キーリングは、暗号化リクエストごとに一意のデータ暗号化キーを使用し、アクティブなブランチキーから派生した一意のラッピングキーを使用して各データ暗号化キーを暗号化します。階層キーリングは、アクティブなブランチキーと、その導出ラッピングキーの間に確立された階層に依拠します。
階層キーリングは通常、複数のリクエストを満たすために各ブランチキーバージョンを使用します。ただし、ユーザーがアクティブなブランチキーを再利用する範囲を制御し、アクティブなブランチキーをローテーションする頻度を決定します。ブランチキーのアクティブなバージョンは、ローテーションされるまでアクティブなままとなります。アクティブなブランチキーの以前のバージョンは暗号化オペレーションの実行には使用されませんが、引き続きクエリを実行して復号オペレーションに使用できます。
階層キーリングをインスタンス化すると、ローカルキャッシュが作成されます。ブランチキーマテリアルがローカルキャッシュ内に格納される最大時間 (ブランチキーマテリアルが期限切れになってキャッシュから削除されるまでの時間) を定義する[キャッシュ制限](#cache-limit)を指定します。階層キーリングは 1 回の AWS KMS 呼び出しでブランチキーを復号し、 オペレーションで `branch-key-id`が初めて指定されたときにブランチキーマテリアルをアセンブルします。その後、ブランチキーマテリアルはローカルキャッシュに格納され、キャッシュ制限が期限切れになるまで、その `branch-key-id` を指定するすべての暗号化および復号オペレーションのために再利用されます。ブランチキーマテリアルをローカルキャッシュに保存することで、 AWS KMS 呼び出しが減ります。例えば、キャッシュ制限が 15 分である場合を考えてみましょう。そのキャッシュ制限内で 10,000 回の暗号化オペレーションを実行する場合、[従来の AWS KMS キーリング](use-kms-keyring.md)は 10,000 回の暗号化オペレーションを満たすために 10,000 回の AWS KMS 呼び出しを行う必要があります。アクティブな が 1 つある場合`branch-key-id`、階層キーリングは 10,000 回の暗号化オペレーションを満たすために 1 回の AWS KMS 呼び出しを行うだけで済みます。
ローカルキャッシュは、暗号化マテリアルと復号マテリアルを分離します。暗号化マテリアルはアクティブなブランチキーからアセンブルされ、キャッシュ制限の有効期限が切れるまですべての暗号化オペレーションに再利用されます。復号マテリアルは、暗号化されたフィールドのメタデータで識別されるブランチキー ID とバージョンからアセンブルされ、キャッシュ制限の有効期限が切れるまで、ブランチキー ID とバージョンに関連するすべての復号オペレーションに再利用されます。ローカルキャッシュは、一度に同じブランチキーの複数のバージョンを保存できます。ローカルキャッシュが を使用するように設定されている場合[branch key ID supplier](#branch-key-id-supplier)、一度に複数のアクティブなブランチキーからのブランチキーマテリアルを保存することもできます。
**注記**
AWS Database Encryption SDK の*階層キーリング*に関するすべての言及は、 AWS KMS 階層キーリングを参照しています。
**Topics**
+ [仕組み](#how-hierarchical-keyring-works)
+ [前提条件](#hierarchical-keyring-prereqs)
+ [必要なアクセス許可](#hierarchical-keyring-permissions)
+ [キャッシュを選択する](#hierarchical-keyring-caches)
+ [階層キーリングを作成する](#initialize-hierarchical-keyring)
+ [検索可能な暗号化のための階層キーリングの使用](#searchable-encryption-hierarchical-keyrings)
## 仕組み
次のチュートリアルでは、階層キーリングが暗号化および復号マテリアルをアセンブルする方法と、暗号化および復号オペレーションのためにキーリングが実行するさまざまな呼び出しについて説明します。ラッピングキーの導出とプレーンテキストデータキーの暗号化プロセスの技術的な詳細については、「[AWS KMS 階層キーリングの技術的な詳細](reference.md#hierarchical-keyring-details)」を参照してください。
**暗号化および署名**
次のチュートリアルでは、階層キーリングが暗号化マテリアルをアセンブルし、一意のラッピングキーを導出する方法について説明します。
1. 暗号化メソッドは、階層キーリングに暗号化マテリアルを要求します。キーリングはプレーンテキストのデータキーを生成し、ローカルキャッシュにラッピングキーを生成する有効なブランチキーマテリアルがあるかどうかをチェックします。有効なブランチキーマテリアルがある場合、キーリングは**ステップ 4 **に進みます。
1. 有効なブランチキーマテリアルがない場合、階層キーリングはキーストアにアクティブなブランチキーをクエリします。
1. キーストアは AWS KMS を呼び出してアクティブなブランチキーを復号し、プレーンテキストのアクティブなブランチキーを返します。アクティブなブランチキーを識別するデータは、 AWS KMSに対する復号呼び出しで追加認証データ (AAD) を提供するためにシリアル化されます。
1. キーストアは、プレーンテキストのブランチキーと、ブランチキーのバージョンなど、それを識別するデータを返します。
1. 階層キーリングはブランチキーマテリアル (プレーンテキストブランチキーとブランチキーバージョン) をアセンブルし、それらのコピーをローカルキャッシュに格納します。
1. 階層キーリングは、プレーンテキストブランチキーと 16 バイトのランダムソルトから一意のラッピングキーを導出します。プレーンテキストデータキーのコピーを暗号化するために、導出されたラッピングキーを使用します。
暗号化メソッドは、暗号化マテリアルを使用してレコードを暗号化して署名します。 AWS Database Encryption SDK でレコードがどのように暗号化および署名されるのかに関する詳細については、「[暗号化して署名](how-it-works.md#encrypt-and-sign)」を参照してください。
**復号および検証**
次のチュートリアルでは、階層キーリングが復号マテリアルをアセンブルし、暗号化されたデータキーを復号する方法について説明します。
1. 復号メソッドは、暗号化されたレコードのマテリアルの説明フィールドから暗号化されたデータキーを識別し、それを階層キーリングに渡します。
1. 階層キーリングは、ブランチキーのバージョン、16 バイトのソルト、およびデータキーの暗号化方法を説明する他の情報を含む、暗号化されたデータキーを識別するデータを逆シリアル化します。
詳細については、「[AWS KMS 階層キーリングの技術的な詳細](reference.md#hierarchical-keyring-details)」を参照してください。
1. 階層キーリングは、**ステップ 2** で特定されたブランチキーのバージョンと一致する有効なブランチキーマテリアルがローカルキャッシュ内に存在するかどうかをチェックします。有効なブランチキーマテリアルがある場合、キーリングは**ステップ 6** に進みます。
1. 有効なブランチキーマテリアルがない場合、階層キーリングは、**ステップ 2** で識別されたブランチキーバージョンに一致するブランチキーについてキーストアをクエリします。
1. キーストアは AWS KMS を呼び出してブランチキーを復号し、プレーンテキストのアクティブなブランチキーを返します。アクティブなブランチキーを識別するデータは、 AWS KMSに対する復号呼び出しで追加認証データ (AAD) を提供するためにシリアル化されます。
1. キーストアは、プレーンテキストのブランチキーと、ブランチキーのバージョンなど、それを識別するデータを返します。
1. 階層キーリングはブランチキーマテリアル (プレーンテキストブランチキーとブランチキーバージョン) をアセンブルし、それらのコピーをローカルキャッシュに格納します。
1. 階層キーリングは、アセンブルされたブランチキーマテリアルと、**ステップ 2** で識別された 16 バイトのソルトを使用して、データキーを暗号化した一意のラッピングキーを複製します。
1. 階層キーリングは、複製されたラッピングキーを使用してデータキーを復号し、プレーンテキストのデータキーを返します。
復号メソッドは、復号マテリアルとプレーンテキストデータキーを使用し、レコードを復号して検証します。 AWS Database Encryption SDK でのレコードの復号化と検証の詳細については、[「復号化と検証](how-it-works.md#decrypt-and-verify)」を参照してください。
## 前提条件
階層キーリングを作成して使用する前に、次の前提条件を満たしていることを確認してください。
+ ユーザーまたはキーストア管理者が[キーストアを作成し](create-keystore.md)、[少なくとも 1 つのアクティブなブランチキーを作成](create-branch-keys.md)しました。
+ [キーストアアクションを設定しました](keystore-actions.md#config-keystore-actions)。
**注記**
キーストアアクションの設定方法によって、実行できるオペレーションと、階層キーリングで使用できる KMS キーが決まります。詳細については、[「キーストアアクション](keystore-actions.md)」を参照してください。
+ キーストアキーとブランチキーにアクセスして使用するために必要な AWS KMS アクセス許可があります。詳細については、「[必要なアクセス許可](#hierarchical-keyring-permissions)」を参照してください。
+ サポートされているキャッシュタイプを確認し、ニーズに最適なキャッシュタイプを設定しました。詳細については、[キャッシュを選択する](#hierarchical-keyring-caches)を参照してください。
## 必要なアクセス許可
AWS Database Encryption SDK は を必要とせず AWS アカウント 、 に依存しません AWS のサービス。ただし、階層キーリングを使用するには、 AWS アカウント と、キーストアの対称暗号化 AWS KMS key(複数可) に対する以下の最小限のアクセス許可が必要です。
+ 階層キーリングを使用してデータを暗号化および復号するには、[kms:Decrypt ](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)が必要です。
+ ブランチキー[を作成して](create-branch-keys.md)[ローテーション](rotate-branch-key.md)するには、[kms:GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) と [kms:ReEncrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_ReEncrypt.html) が必要です。
ブランチキーとキーストアへのアクセスの制御の詳細については、「」を参照してください[最小特権のアクセス許可の実装](keystore-least-privilege.md)。
## キャッシュを選択する
階層キーリングは、暗号化および復号オペレーションで使用されるブランチキーマテリアルをローカルにキャッシュ AWS KMS することで、 に対する呼び出しの数を減らします。[階層キーリングを作成する](#initialize-hierarchical-keyring)前に、使用するキャッシュのタイプを決定する必要があります。デフォルトのキャッシュを使用するか、ニーズに合わせてキャッシュをカスタマイズできます。
階層キーリングは、次のキャッシュタイプをサポートしています。
+ [デフォルトキャッシュ](#cache-default)
+ [MultiThreadedキャッシュ](#cache-multithreaded)
+ [StormTracking キャッシュ](#cache-stormtracking)
+ [共有キャッシュ](#cache-shared)
### デフォルトキャッシュ
ほとんどのユーザーにとって、Default キャッシュはスレッド要件を満たします。Default キャッシュは、高度にマルチスレッド化されている環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、デフォルトキャッシュは、ブランチキーマテリアルエントリが 10 秒前に期限切れになることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが呼び出されるのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。
デフォルトキャッシュと StormTracking キャッシュは同じスレッドモデルをサポートしますが、デフォルトキャッシュを使用するにはエントリ容量を指定するだけです。より詳細なキャッシュのカスタマイズを行うには、 を使用します[StormTracking キャッシュ](#cache-stormtracking)。
ローカルキャッシュに保存できるブランチキーマテリアルエントリの数をカスタマイズする場合を除き、階層キーリングを作成するときにキャッシュタイプを指定する必要はありません。キャッシュタイプを指定しない場合、階層キーリングはデフォルトのキャッシュタイプを使用し、エントリ容量を 1000 に設定します。
デフォルトキャッシュをカスタマイズするには、次の値を指定します。
+ **エントリキャパシティ**: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。
------
#### [ Java ]
```
.cache(CacheType.builder()
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType defaultCache = new CacheType
{
Default = new DefaultCache{EntryCapacity = 100}
};
```
------
#### [ Rust ]
```
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
```
------
### MultiThreadedキャッシュ
MultiThreadedキャッシュはマルチスレッド環境で安全に使用できますが、 AWS KMS または Amazon DynamoDB 呼び出しを最小限に抑える機能はありません。その結果、ブランチキーマテリアルのエントリの期限が切れると、すべてのスレッドに同時に通知されます。これにより、キャッシュを更新するための複数の AWS KMS 呼び出しが発生する可能性があります。
MultiThreaded キャッシュを使用するには、次の値を指定します。
+ **エントリキャパシティ**: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。
+ **エントリのプルーニングテールのサイズ**: エントリキャパシティに達した場合にプルーニングするエントリの数を定義します。
------
#### [ Java ]
```
.cache(CacheType.builder()
.MultiThreaded(MultiThreadedCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType multithreadedCache = new CacheType
{
MultiThreaded = new MultiThreadedCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1
}
};
```
------
#### [ Rust ]
```
CacheType::MultiThreaded(
MultiThreadedCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.build()?)
```
------
### StormTracking キャッシュ
StormTracking キャッシュは、高度にマルチスレッド化されている環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、StormTracking キャッシュは、ブランチキーマテリアルエントリの有効期限が切れることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが呼び出されるのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。
StormTracking キャッシュを使用するには、次の値を指定します。
+ **エントリキャパシティ**: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。
デフォルト値: 1000 エントリ
+ **エントリのプルーニングテールのサイズ**: 一度にプルーニングするブランチキーマテリアルのエントリの数を定義します。
デフォルトの値: 1 個のエントリ
+ **猶予期間**: 期限が切れる前にブランチキーマテリアルの更新を試行する秒数を定義します。
デフォルト値: 10 秒
+ **猶予間隔**: ブランチキーマテリアルの更新が試行される間隔の秒数を定義します。
デフォルト値: 1 秒
+ **ファンアウト**: ブランチキーマテリアルの更新の同時試行が可能な回数を定義します。
デフォルトの値: 20 回の試行
+ **処理中の Time To Live (TTL)**: ブランチキーマテリアルの更新の試行がタイムアウトするまでの秒数を定義します。キャッシュが `GetCacheEntry` に応答して `NoSuchEntry` を返すたびに、同じキーが `PutCache` エントリを使用して書き込まれるまで、そのブランチキーは処理中であるとみなされます。
デフォルト値: 10 秒
+ **スリープ**: `fanOut` を超えた場合にスレッドがスリープする秒数を定義します。
デフォルトの値: 20 ミリ秒
------
#### [ Java ]
```
.cache(CacheType.builder()
.StormTracking(StormTrackingCache.builder()
.entryCapacity(100)
.entryPruningTailSize(1)
.gracePeriod(10)
.graceInterval(1)
.fanOut(20)
.inFlightTTL(10)
.sleepMilli(20)
.build())
```
------
#### [ C\$1 / .NET ]
```
CacheType stormTrackingCache = new CacheType
{
StormTracking = new StormTrackingCache
{
EntryCapacity = 100,
EntryPruningTailSize = 1,
FanOut = 20,
GraceInterval = 1,
GracePeriod = 10,
InFlightTTL = 10,
SleepMilli = 20
}
};
```
------
#### [ Rust ]
```
CacheType::StormTracking(
StormTrackingCache::builder()
.entry_capacity(100)
.entry_pruning_tail_size(1)
.grace_period(10)
.grace_interval(1)
.fan_out(20)
.in_flight_ttl(10)
.sleep_milli(20)
.build()?)
```
------
### 共有キャッシュ
デフォルトでは、階層キーリングは、キーリングをインスタンス化するたびに新しいローカルキャッシュを作成します。ただし、共有キャッシュを使用すると、複数の階層キーリング間でキャッシュを共有できるため、メモリを節約できます。インスタンス化する階層キーリングごとに新しい暗号化マテリアルキャッシュを作成するのではなく、共有キャッシュは 1 つのキャッシュのみをメモリに保存します。このキャッシュは、それを参照するすべての階層キーリングで使用できます。共有キャッシュは、キーリング間での暗号化マテリアルの重複を回避することで、メモリ使用量を最適化するのに役立ちます。代わりに、階層キーリングは同じ基盤となるキャッシュにアクセスし、全体的なメモリフットプリントを削減できます。
共有キャッシュを作成する場合でも、キャッシュタイプを定義します。キャッシュタイプ[StormTracking キャッシュ](#cache-stormtracking)として [デフォルトキャッシュ](#cache-default)、[MultiThreadedキャッシュ](#cache-multithreaded)、または を指定することも、互換性のあるカスタムキャッシュを置き換えることもできます。
**パーティション**
複数の階層キーリングで 1 つの共有キャッシュを使用できます。共有キャッシュを使用して階層キーリングを作成する場合、オプションの**パーティション ID** を定義できます。パーティション ID は、キャッシュに書き込む階層キーリングを区別します。2 つの階層キーリングが同じパーティション ID、[logical key store name](create-keystore.md#logical-key-store-name)、ブランチキー ID を参照する場合、2 つのキーリングはキャッシュ内で同じキャッシュエントリを共有します。同じ共有キャッシュで異なるパーティション IDs を持つ 2 つの階層キーリングを作成すると、各キーリングは共有キャッシュ内の独自の指定されたパーティションからのみキャッシュエントリにアクセスします。パーティションは共有キャッシュ内の論理分割として機能し、各階層キーリングは、他のパーティションに保存されているデータを妨害することなく、独自の指定されたパーティションで独立して動作できます。
パーティション内のキャッシュエントリを再利用または共有する場合は、独自のパーティション ID を定義する必要があります。パーティション ID を階層キーリングに渡すと、キーリングは、ブランチキーマテリアルを再度取得して再承認するのではなく、共有キャッシュに既に存在するキャッシュエントリを再利用できます。パーティション ID を指定しない場合、階層キーリングをインスタンス化するたびに、一意のパーティション ID がキーリングに自動的に割り当てられます。
次の手順は、[デフォルトのキャッシュタイプ](#cache-default)で共有キャッシュを作成し、階層キーリングに渡す方法を示しています。
1. マテリアルプロバイダーライブラリ `CryptographicMaterialsCache` (MPL) を使用して (CMC) を作成します。 [https://github.com/aws/aws-cryptographic-material-providers-library](https://github.com/aws/aws-cryptographic-material-providers-library)
------
#### [ Java ]
```
// Instantiate the MPL
final MaterialProviders matProv =
MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
// Create a CacheType object for the Default cache
final CacheType cache =
CacheType.builder()
.Default(DefaultCache.builder().entryCapacity(100).build())
.build();
// Create a CMC using the default cache
final CreateCryptographicMaterialsCacheInput cryptographicMaterialsCacheInput =
CreateCryptographicMaterialsCacheInput.builder()
.cache(cache)
.build();
final ICryptographicMaterialsCache sharedCryptographicMaterialsCache =
matProv.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ C\$1 / .NET ]
```
// Instantiate the MPL
var materialProviders = new MaterialProviders(new MaterialProvidersConfig());
// Create a CacheType object for the Default cache
var cache = new CacheType { Default = new DefaultCache{EntryCapacity = 100} };
// Create a CMC using the default cache
var cryptographicMaterialsCacheInput = new CreateCryptographicMaterialsCacheInput {Cache = cache};
var sharedCryptographicMaterialsCache = materialProviders.CreateCryptographicMaterialsCache(cryptographicMaterialsCacheInput);
```
------
#### [ Rust ]
```
// Instantiate the MPL
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
// Create a CacheType object for the default cache
let cache: CacheType = CacheType::Default(
DefaultCache::builder()
.entry_capacity(100)
.build()?,
);
// Create a CMC using the default cache
let shared_cryptographic_materials_cache: CryptographicMaterialsCacheRef = mpl.
create_cryptographic_materials_cache()
.cache(cache)
.send()
.await?;
```
------
1. 共有キャッシュの`CacheType`オブジェクトを作成します。
**ステップ 1 **で`sharedCryptographicMaterialsCache`作成した を新しい`CacheType`オブジェクトに渡します。
------
#### [ Java ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
final CacheType sharedCache =
CacheType.builder()
.Shared(sharedCryptographicMaterialsCache)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a CacheType object for the sharedCryptographicMaterialsCache
var sharedCache = new CacheType { Shared = sharedCryptographicMaterialsCache };
```
------
#### [ Rust ]
```
// Create a CacheType object for the shared_cryptographic_materials_cache
let shared_cache: CacheType = CacheType::Shared(shared_cryptographic_materials_cache);
```
------
1. **ステップ 2 **の `sharedCache` オブジェクトを階層キーリングに渡します。
共有キャッシュを使用して階層キーリングを作成する場合、オプションで を定義`partitionID`して、複数の階層キーリング間でキャッシュエントリを共有できます。パーティション ID を指定しない場合、階層キーリングはキーリングに一意のパーティション ID を自動的に割り当てます。
**注記**
同じパーティション ID、、[logical key store name](create-keystore.md#logical-key-store-name)ブランチキー ID を参照する 2 つ以上のキーリングを作成すると、階層キーリングは共有キャッシュ内で同じキャッシュエントリを共有します。複数のキーリングで同じキャッシュエントリを共有しない場合は、階層キーリングごとに一意のパーティション ID を使用する必要があります。
次の例では、 で[branch key ID supplier](#branch-key-id-supplier)[キャッシュ制限](#cache-limit)が 600 秒の階層キーリングを作成します。次の階層キーリング設定で定義されている値の詳細については、「」を参照してください[階層キーリングを作成する](#initialize-hierarchical-keyring)。
------
#### [ Java ]
```
// Create the Hierarchical keyring
final CreateAwsKmsHierarchicalKeyringInput keyringInput =
CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(sharedCache)
.partitionID(partitionID)
.build();
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
// Create the Hierarchical keyring
var createKeyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
Cache = sharedCache,
TtlSeconds = 600,
PartitionId = partitionID
};
var keyring = materialProviders.CreateAwsKmsHierarchicalKeyring(createKeyringInput);
```
------
#### [ Rust ]
```
// Create the Hierarchical keyring
let keyring1 = mpl
.create_aws_kms_hierarchical_keyring()
.key_store(key_store1)
.branch_key_id(branch_key_id.clone())
// CryptographicMaterialsCacheRef is an Rc (Reference Counted), so if you clone it to
// pass it to different Hierarchical Keyrings, it will still point to the same
// underlying cache, and increment the reference count accordingly.
.cache(shared_cache.clone())
.ttl_seconds(600)
.partition_id(partition_id.clone())
.send()
.await?;
```
------
## 階層キーリングを作成する
階層キーリングを作成するには、次の値を指定する必要があります。
+ **キーストア名**
キーストアとして機能するために作成した DynamoDB テーブルの名前、またはキーストア管理者。
+
**キャッシュ制限 Time to Live (TTL)**
ローカルキャッシュ内のブランチキーマテリアルエントリを使用できる時間 (期限切れになるまでの時間) (秒)。キャッシュ制限 TTL は、クライアントがブランチキーの使用を許可 AWS KMS するために を呼び出す頻度を指定します。この値はゼロより大きくなければなりません。キャッシュ制限 TTL の有効期限が切れると、エントリは提供されず、ローカルキャッシュから削除されます。
+ **ブランチキーの識別子**
キーストア内の 1 つのアクティブなブランチキー`branch-key-id`を識別する を静的に設定するか、ブランチキー ID サプライヤーを指定できます。
*ブランチキー ID サプライヤ*は、暗号化コンテキストに保存されているフィールドを使用して、レコードの復号に必要なブランチキーを決定します。デフォルトでは、パーティションキーとソートキーのみが暗号化コンテキストに含まれます。ただし、`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`[暗号化アクション](concepts.md#crypt-actions)を使用して、暗号化コンテキストに追加のフィールドを含めることができます。
各テナントに独自のブランチキーがあるマルチテナントデータベースには、ブランチキー ID サプライヤーを使用することを強くお勧めします。ブランチキー ID サプライヤーを使用してブランチキー IDs のわかりやすい名前を作成し、特定のテナントの正しいブランチキー ID を簡単に認識できます。例えば、フレンドリ名を使用すると、ブランチキーを `b3f61619-4d35-48ad-a275-050f87e15122` の代わりに `tenant1` として参照できます。
復号オペレーションの場合、単一の階層キーリングを静的に設定して復号を単一のテナンシーに制限することも、ブランチキー ID サプライヤーを使用してレコードの復号を担当するテナンシーを識別することもできます。
+ **(オプション) キャッシュ**
キャッシュタイプまたはローカルキャッシュに格納できるブランチキーマテリアルエントリの数をカスタマイズする場合は、キーリングを初期化する際にキャッシュタイプとエントリキャパシティを指定します。
階層キーリングは、デフォルト、MultiThreaded、StormTracking、共有のキャッシュタイプをサポートします。各キャッシュタイプを定義する方法の詳細と例については、「」を参照してください[キャッシュを選択する](#hierarchical-keyring-caches)。
キャッシュを指定しない場合、階層キーリングは、自動的に Default キャッシュタイプを使用し、エントリキャパシティを 1,000 に設定します。
+ **(オプション) パーティション ID**
を指定する場合は[共有キャッシュ](#cache-shared)、オプションでパーティション ID を定義できます。パーティション ID は、キャッシュに書き込む階層キーリングを区別します。パーティション内のキャッシュエントリを再利用または共有する場合は、独自のパーティション ID を定義する必要があります。パーティション ID には任意の文字列を指定できます。パーティション ID を指定しない場合、作成時に一意のパーティション ID がキーリングに自動的に割り当てられます。
詳細については、「[Partitions](#shared-cache-partitions)」を参照してください。
**注記**
同じパーティション ID、、ブランチキー ID を参照する 2 つ以上のキーリングを作成する[logical key store name](create-keystore.md#logical-key-store-name)と、階層キーリングは共有キャッシュ内で同じキャッシュエントリを共有します。複数のキーリングで同じキャッシュエントリを共有しない場合は、階層キーリングごとに一意のパーティション ID を使用する必要があります。
+ **(オプション) 許可トークンのリスト**
階層キーリング内の KMS キーへのアクセスを[許可](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html)によって制御する場合は、キーリングを初期化する際に必要なすべての許可トークンを指定する必要があります。
### 静的ブランチキー ID を使用して階層キーリングを作成する
次の例は、静的ブランチキー ID、、[デフォルトキャッシュ](#cache-default)キャッシュ制限 TTL が 600 秒の階層キーリングを作成する方法を示しています。
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyId(branch-key-id)
.ttlSeconds(600)
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(branch_key_store_name)
.ttl_seconds(600)
.send()
.await?;
```
------
### ブランチキー ID サプライヤーを使用して階層キーリングを作成する
次の手順は、ブランチキー ID サプライヤーを使用して階層キーリングを作成する方法を示しています。
1. ブランチキー ID サプライヤーを作成する
次の例では、**ステップ 1 **で作成した 2 つのブランチキーのフレンドリ名を作成し、 `CreateDynamoDbEncryptionBranchKeyIdSupplier`を呼び出して AWS Database Encryption SDK for DynamoDB クライアントを使用してブランチキー ID サプライヤーを作成します。
------
#### [ Java ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier implements IDynamoDbKeyBranchKeyIdSupplier {
private static String branchKeyIdForTenant1;
private static String branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this.branchKeyIdForTenant1 = tenant1Id;
this.branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
final DynamoDbEncryption ddbEnc = DynamoDbEncryption.builder()
.DynamoDbEncryptionConfig(DynamoDbEncryptionConfig.builder().build())
.build();
final BranchKeyIdSupplier branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
CreateDynamoDbEncryptionBranchKeyIdSupplierInput.builder()
.ddbKeyBranchKeyIdSupplier(new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2))
.build()).branchKeyIdSupplier();
```
------
#### [ C\$1 / .NET ]
```
// Create friendly names for each branch-key-id
class ExampleBranchKeyIdSupplier : DynamoDbKeyBranchKeyIdSupplierBase {
private String _branchKeyIdForTenant1;
private String _branchKeyIdForTenant2;
public ExampleBranchKeyIdSupplier(String tenant1Id, String tenant2Id) {
this._branchKeyIdForTenant1 = tenant1Id;
this._branchKeyIdForTenant2 = tenant2Id;
}
// Create the branch key ID supplier
var ddbEnc = new DynamoDbEncryption(new DynamoDbEncryptionConfig());
var branchKeyIdSupplier = ddbEnc.CreateDynamoDbEncryptionBranchKeyIdSupplier(
new CreateDynamoDbEncryptionBranchKeyIdSupplierInput
{
DdbKeyBranchKeyIdSupplier = new ExampleBranchKeyIdSupplier(branch-key-ID-tenant1, branch-key-ID-tenant2)
}).BranchKeyIdSupplier;
```
------
#### [ Rust ]
```
// Create friendly names for each branch_key_id
pub struct ExampleBranchKeyIdSupplier {
branch_key_id_for_tenant1: String,
branch_key_id_for_tenant2: String,
}
impl ExampleBranchKeyIdSupplier {
pub fn new(tenant1_id: &str, tenant2_id: &str) -> Self {
Self {
branch_key_id_for_tenant1: tenant1_id.to_string(),
branch_key_id_for_tenant2: tenant2_id.to_string(),
}
}
}
// Create the branch key ID supplier
let dbesdk_config = DynamoDbEncryptionConfig::builder().build()?;
let dbesdk = dbesdk_client::Client::from_conf(dbesdk_config)?;
let supplier = ExampleBranchKeyIdSupplier::new(tenant1_branch_key_id, tenant2_branch_key_id);
let branch_key_id_supplier = dbesdk
.create_dynamo_db_encryption_branch_key_id_supplier()
.ddb_key_branch_key_id_supplier(supplier)
.send()
.await?
.branch_key_id_supplier
.unwrap();
```
------
1. 階層キーリングを作成する
次の例では、**ステップ 1 **で作成したブランチキー ID サプライヤー、キャッシュ制限 TLL が 600 秒、最大キャッシュサイズが 1000 の階層キーリングを初期化します。
------
#### [ Java ]
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(keystore)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(100)
.build())
.build())
.build();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ C\$1 / .NET ]
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 100 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
------
#### [ Rust ]
```
let mpl_config = MaterialProvidersConfig::builder().build()?;
let mpl = mpl_client::Client::from_conf(mpl_config)?;
let hierarchical_keyring = mpl
.create_aws_kms_hierarchical_keyring()
.branch_key_id_supplier(branch_key_id_supplier)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```
------
## 検索可能な暗号化のための階層キーリングの使用
[検索可能な暗号化](searchable-encryption.md)を使用すると、データベース全体を復号することなく、暗号化されたレコードを検索できます。これは、[ビーコン](beacons.md)を使用して暗号化されたフィールドのプレーンテキストの値にインデックスを付けることで実現されます。検索可能な暗号化を実装するには、階層キーリングを使用する必要があります。
キーストア `CreateKey` オペレーションは、ブランチキーとビーコンキーの両方を生成します。ブランチキーは、レコードの暗号化および復号オペレーションで使用されます。ビーコンキーは、ビーコンを生成するために使用されます。
ブランチキーとビーコンキーは、キーストアサービスの作成時に指定した AWS KMS key ものと同じ によって保護されます。`CreateKey` オペレーションが AWS KMS を呼び出してブランチキーを生成すると、[kms:GenerateDataKeyWithoutPlaintext](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKeyWithoutPlaintext.html) を 2 回呼び出して、次のリクエストを使用してビーコンキーを生成します。
```
{
"EncryptionContext": {
"branch-key-id" : "branch-key-id",
"type" : type,
"create-time" : "timestamp",
"tablename" : "the logical table name for your key store",
"kms-arn" : the KMS key ARN,
"hierarchy-version" : 1
},
"KeyId": "the KMS key ARN",
"NumberOfBytes": "32"
}
```
両方のキーを生成した後、`CreateKey` オペレーションは [ddb:TransactWriteItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html) を呼び出して、ブランチキーとビーコンキーを永続化する 2 つの新しい項目をブランチキーストアに書き込みます。
[標準ビーコンを設定する](configure-beacons.md#config-standard-beacons)と、 AWS Database Encryption SDK はキーストアにビーコンキーをクエリします。その後、HMAC ベースの extract-and-expand 鍵導出関数 ([HKDF](https://en.wikipedia.org/wiki/HKDF)) を使用して、ビーコンキーと[標準ビーコン](beacons.md#standard-beacon-overview)の名前を組み合わせ、特定のビーコンの HMAC キーを作成します。
ブランチキーとは異なり、キーストア`branch-key-id`には ごとに 1 つのビーコンキーバージョンしかありません。ビーコンキーがローテーションされることはありません。
### ビーコンキーソースの定義
標準ビーコンおよび複合ビーコンの[ビーコンバージョン](using-beacons.md#beacon-version)を定義する際には、ビーコンキーを識別し、ビーコンキーマテリアルのキャッシュ制限 Time To Live (TTL) を定義する必要があります。ビーコンキーマテリアルは、ブランチキーとは別のローカルキャッシュに格納されます。次のスニペットは、シングルテナンシーデータベースの `keySource` を定義する方法を示しています。関連付けられている `branch-key-id` によってビーコンキーを識別します。
------
#### [ Java ]
```
keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branch-key-id)
.cacheTTL(6000)
.build())
.build())
```
------
#### [ C\$1 / .NET ]
```
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branch-key-id,
CacheTTL = 6000
}
}
```
------
#### [ Rust ]
```
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
// `keyId` references a beacon key.
// For every branch key we create in the keystore,
// we also create a beacon key.
// This beacon key is not the same as the branch key,
// but is created with the same ID as the branch key.
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
```
------
**マルチテナンシーデータベースでのビーコンソースの定義**
マルチテナンシーデータベースがある場合は、`keySource` を設定する際に次の値を指定する必要があります。
+
**keyFieldName**
特定のテナンシーについて生成されたビーコンに使用されるビーコンキーに関連付けられた `branch-key-id` を格納するフィールドの名前を定義します。`keyFieldName` には任意の文字列を指定できますが、データベース内の他のすべてのフィールドで一意である必要があります。新しいレコードをデータベースに書き込むと、そのレコードについてのビーコンを生成するために使用されるビーコンキーを識別する `branch-key-id` がこのフィールドに格納されます。このフィールドをビーコンクエリに含めて、ビーコンの再計算に必要となる適切なビーコンキーマテリアルを特定する必要があります。詳細については、「[マルチテナンシーデータベース内のビーコンのクエリ](searchable-encryption-multitenant.md#query-multitenant-beacons)」を参照してください。
+ **cacheTTL**
ローカルビーコンキャッシュ内のビーコンキーマテリアルエントリを使用できる時間 (期限切れになるまでの時間) (秒)。この値はゼロより大きくなければなりません。キャッシュ制限 TTL の期限が切れると、エントリはローカルキャッシュから削除されます。
+ **(オプション) キャッシュ**
キャッシュタイプまたはローカルキャッシュに格納できるブランチキーマテリアルエントリの数をカスタマイズする場合は、キーリングを初期化する際にキャッシュタイプとエントリキャパシティを指定します。
階層キーリングは、デフォルト、MultiThreaded、StormTracking、共有のキャッシュタイプをサポートします。各キャッシュタイプを定義する方法の詳細と例については、「」を参照してください[キャッシュを選択する](#hierarchical-keyring-caches)。
キャッシュを指定しない場合、階層キーリングは、自動的に Default キャッシュタイプを使用し、エントリキャパシティを 1,000 に設定します。
次の例では、ブランチキー ID サプライヤー、キャッシュ制限 TLL が 600 秒、エントリ容量が 1000 の階層キーリングを作成します。
```
final MaterialProviders matProv = MaterialProviders.builder()
.MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
.build();
final CreateAwsKmsHierarchicalKeyringInput keyringInput = CreateAwsKmsHierarchicalKeyringInput.builder()
.keyStore(branchKeyStoreName)
.branchKeyIdSupplier(branchKeyIdSupplier)
.ttlSeconds(600)
.cache(CacheType.builder() //OPTIONAL
.Default(DefaultCache.builder()
.entryCapacity(1000)
.build())
.build());
final IKeyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
KeyStore = keystore,
BranchKeyIdSupplier = branchKeyIdSupplier,
TtlSeconds = 600,
Cache = new CacheType
{
Default = new DefaultCache { EntryCapacity = 1000 }
}
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
```
```
let provider_config = MaterialProvidersConfig::builder().build()?;
let mat_prov = client::Client::from_conf(provider_config)?;
let kms_keyring = mat_prov
.create_aws_kms_hierarchical_keyring()
.branch_key_id(branch_key_id)
.key_store(key_store)
.ttl_seconds(600)
.send()
.await?;
```