AWS KMS 階層キーリング - AWS データベース暗号化 SDK
仕組み前提条件階層キーリングを作成するアクティブなブランチキーをローテーションするマルチテナンシーデータベースでの階層キーリングの使用検索可能な暗号化のための階層キーリングの使用

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

AWS KMS 階層キーリング

クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き DynamoDB Encryption Client に関する情報を提供します。
注記

2023 年 7 月 24 日の時点では、デベロッパープレビュー中に作成されたブランチキーはサポートされていません。デベロッパープレビュー中に作成したブランチキーストアを引き続き使用するには、新しいブランチキーを作成します。

AWS KMS 階層キーリングを使用すると、レコードを暗号化または復号する AWS KMS たびに を呼び出すことなく、対称暗号化 KMS キーで暗号化マテリアルを保護できます。これは、 への呼び出しを最小限に抑える必要があるアプリケーションや AWS KMS、セキュリティ要件に違反することなく一部の暗号化マテリアルを再利用できるアプリケーションに適しています。

階層キーリングは、Amazon DynamoDB テーブルに保持されている AWS KMS 保護されたブランチキーを使用して AWS KMS 呼び出しの数を減らし、暗号化および復号オペレーションで使用されるブランチキーマテリアルをローカルにキャッシュする暗号化マテリアルキャッシュソリューションです。DynamoDB テーブルは、ブランチキーを管理および保護するブランチキーストアとして機能します。アクティブなブランチキーと、ブランチキーの以前のすべてのバージョンが格納されます。アクティブなブランチキーは、ブランチキーの最新バージョンです。階層キーリングは、一意のデータキーを使用して各フィールドを暗号化し、アクティブなブランチキーから導出した一意のラッピングキーを使用して各データキーを暗号化します。階層キーリングは、アクティブなブランチキーと、その導出ラッピングキーの間に確立された階層に依拠します。

階層キーリングは通常、複数のリクエストを満たすために各ブランチキーバージョンを使用します。ただし、ユーザーがアクティブなブランチキーを再利用する範囲を制御し、アクティブなブランチキーをローテーションする頻度を決定します。ブランチキーのアクティブなバージョンは、ローテーションされるまでアクティブなままとなります。アクティブなブランチキーの以前のバージョンは暗号化オペレーションの実行には使用されませんが、引き続きクエリを実行して復号オペレーションに使用できます。

階層キーリングをインスタンス化すると、ローカルキャッシュが作成されます。ブランチキーマテリアルがローカルキャッシュ内に格納される最大時間 (ブランチキーマテリアルが期限切れになってキャッシュから削除されるまでの時間) を定義するキャッシュ制限を指定します。階層キーリングは 1 回の AWS KMS 呼び出しでブランチキーを復号し、 オペレーションで が初めてbranch-key-id指定されたときにブランチキーマテリアルをアセンブルします。その後、ブランチキーマテリアルはローカルキャッシュに格納され、キャッシュ制限が期限切れになるまで、その branch-key-id を指定するすべての暗号化および復号オペレーションのために再利用されます。ブランチキーマテリアルをローカルキャッシュに保存すると、 AWS KMS 呼び出しが減ります。例えば、キャッシュ制限が 15 分である場合を考えてみましょう。そのキャッシュ制限内で 10,000 回の暗号化オペレーションを実行する場合、従来の AWS KMS キーリングは 10,000 回の暗号化オペレーションを満たすために 10,000 回の AWS KMS 呼び出しを行う必要があります。アクティブな が 1 つある場合branch-key-id、階層キーリングは 10,000 回の暗号化オペレーションを満たすために 1 回の AWS KMS 呼び出しを行うだけで済みます。

ローカルキャッシュは 2 つのパーティションで構成され、1 つは暗号化オペレーション用、もう 1 つは復号オペレーション用です。暗号化パーティションは、アクティブなブランチキーからアセンブルされたブランチキーマテリアルを格納し、キャッシュ制限が期限切れになるまですべての暗号化オペレーションのためにそれらのマテリアルを再利用します。復号パーティションは、復号オペレーションで識別された他のブランチキーバージョン用にアセンブルされたブランチキーマテリアルを格納します。復号パーティションは、一度に複数のアクティブなブランチキーマテリアルのバージョンを格納できます。マルチテナンシーデータベースのためにブランチキー ID サプライヤーを使用するように設定されている場合、暗号化パーティションも、一度に複数のブランチキーマテリアルのバージョンを格納できます。詳細については、「マルチテナンシーデータベースでの階層キーリングの使用」を参照してください。

注記

AWS Database Encryption SDK の階層キーリングに関するすべての言及は、 AWS KMS 階層キーリングを参照しています。

仕組み

次のチュートリアルでは、階層キーリングが暗号化および復号マテリアルをアセンブルする方法と、暗号化および復号オペレーションのためにキーリングが実行するさまざまな呼び出しについて説明します。ラッピングキーの導出とプレーンテキストデータキーの暗号化プロセスの技術的な詳細については、「AWS KMS 階層キーリングの技術的な詳細」を参照してください。

暗号化および署名

次のチュートリアルでは、階層キーリングが暗号化マテリアルをアセンブルし、一意のラッピングキーを導出する方法について説明します。

  1. 暗号化メソッドは、階層キーリングに暗号化マテリアルを要求します。キーリングはプレーンテキストデータキーを生成し、ラッピングキーを生成するために、ローカルキャッシュに有効なブランチマテリアルがあるかどうかを確認します。有効なブランチキーマテリアルがある場合、キーリングはステップ 5 に進みます。

  2. 有効なブランチキーマテリアルがない場合、階層キーリングは、ブランチキーストアをクエリして、アクティブなブランチキーがあるかどうかを確認します。

    1. ブランチキーストアは AWS KMS を呼び出してアクティブなブランチキーを復号し、プレーンテキストのアクティブなブランチキーを返します。アクティブなブランチキーを識別するデータは、 AWS KMSに対する復号呼び出しで追加認証データ (AAD) を提供するためにシリアル化されます。

    2. ブランチキーストアは、プレーンテキストのブランチキーと、それを識別するデータ (ブランチキーのバージョンなど) を返します。

  3. 階層キーリングはブランチキーマテリアル (プレーンテキストブランチキーとブランチキーバージョン) をアセンブルし、それらのコピーをローカルキャッシュに格納します。

  4. 階層キーリングは、プレーンテキストブランチキーと 16 バイトのランダムソルトから一意のラッピングキーを導出します。プレーンテキストデータキーのコピーを暗号化するために、導出されたラッピングキーを使用します。

暗号化メソッドは、暗号化マテリアルを使用してレコードを暗号化して署名します。 AWS Database Encryption SDK でレコードがどのように暗号化および署名されるのかに関する詳細については、「暗号化して署名」を参照してください。

表示を増やす表示を減らす
復号および検証

次のチュートリアルでは、階層キーリングが復号マテリアルをアセンブルし、暗号化されたデータキーを復号する方法について説明します。

  1. 復号メソッドは、暗号化されたレコードのマテリアルの説明フィールドから暗号化されたデータキーを識別し、それを階層キーリングに渡します。

  2. 階層キーリングは、ブランチキーのバージョン、16 バイトのソルト、およびデータキーの暗号化方法を説明する他の情報を含む、暗号化されたデータキーを識別するデータを逆シリアル化します。

    詳細については、「AWS KMS 階層キーリングの技術的な詳細」を参照してください。

  3. 階層キーリングは、ステップ 2 で特定されたブランチキーのバージョンと一致する有効なブランチキーマテリアルがローカルキャッシュ内に存在するかどうかをチェックします。有効なブランチキーマテリアルがある場合、キーリングはステップ 6 に進みます。

  4. 有効なブランチキーマテリアルがない場合、階層キーリングは、ブランチキーストアをクエリして、ステップ 2 で特定されたブランチキーバージョンと一致するブランチキーがあるかどうかを確認します。

    1. ブランチキーストアは AWS KMS を呼び出してブランチキーを復号し、プレーンテキストのアクティブなブランチキーを返します。アクティブなブランチキーを識別するデータは、 AWS KMSに対する復号呼び出しで追加認証データ (AAD) を提供するためにシリアル化されます。

    2. ブランチキーストアは、プレーンテキストのブランチキーと、それを識別するデータ (ブランチキーのバージョンなど) を返します。

  5. 階層キーリングはブランチキーマテリアル (プレーンテキストブランチキーとブランチキーバージョン) をアセンブルし、それらのコピーをローカルキャッシュに格納します。

  6. 階層キーリングは、アセンブルされたブランチキーマテリアルと、ステップ 2 で識別された 16 バイトのソルトを使用して、データキーを暗号化した一意のラッピングキーを複製します。

  7. 階層キーリングは、複製されたラッピングキーを使用してデータキーを復号し、プレーンテキストのデータキーを返します。

復号メソッドは、復号マテリアルとプレーンテキストデータキーを使用し、レコードを復号して検証します。 AWS Database Encryption SDK でレコードを復号化して検証する方法の詳細については、「復号化して検証する」を参照してください。

表示を増やす表示を減らす

前提条件

AWS Database Encryption SDK は を必要とせず AWS アカウント 、 に依存しません AWS のサービス。ただし、階層キーリングは AWS KMS と Amazon DynamoDB によって異なります。

階層キーリングを使用するには、kms:Decrypt アクセス許可 AWS KMS key による対称暗号化が必要です。対称暗号化マルチリージョンキーを使用することもできます。 AWS KMS keysのアクセス許可については、AWS Key Management Service デベロッパーガイドの「認証とアクセスコントロール」を参照してください。

階層キーリングを作成して使用する前に、ブランチキーストアを作成し、最初のアクティブなブランチキーを格納する必要があります。

ステップ 1: 新しいキーストアサービスを設定する

キーストアサービスは、階層キーリングの前提条件をアセンブルし、ブランチキーストアを管理するのに役立つ、CreateKeyStore や CreateKey などのいくつかのオペレーションを提供します。

次の例では、キーストアサービスを作成します。ブランチキーストアの名前として機能する DynamoDB テーブル名、ブランチキーストアの論理名、およびブランチキーを保護する KMS キーを識別する KMS キー ARN を指定する必要があります。

論理キーストア名は、DynamoDB の復元オペレーションを簡素化するために、テーブルに格納されているすべてのデータに暗号的にバインドされます。論理キーストア名は DynamoDB テーブル名と同じにすることができますが、同じである必要はありません。最初にキーストアサービスを設定する際に、DynamoDB テーブル名を論理テーブル名として指定することを強くお勧めします。常に同じ論理テーブル名を指定する必要があります。DynamoDB テーブルをバックアップから復元した後にブランチキーストア名が変更された場合、階層キーリングが引き続きブランチキーストアにアクセスできるように、論理キーストア名は指定した DynamoDB テーブル名にマッピングされます。

Java
final KeyStore keystore = KeyStore.builder().KeyStoreConfig(
                KeyStoreConfig.builder()
                        .ddbClient(DynamoDbClient.create())
                        .ddbTableName(keyStoreName)
                        .logicalKeyStoreName(logicalKeyStoreName)
                        .kmsClient(KmsClient.create())
                        .kmsConfiguration(KMSConfiguration.builder()
                                .kmsKeyArn(kmsKeyArn)
                                .build())
                        .build()).build();
C# / .NET
var kmsConfig = new KMSConfiguration { KmsKeyArn = kmsKeyArn };
var keystoreConfig = new KeyStoreConfig
{
    KmsClient = new AmazonKeyManagementServiceClient(),
    KmsConfiguration = kmsConfig,
    DdbTableName = keyStoreName,
    DdbClient = new AmazonDynamoDBClient(),
    LogicalKeyStoreName = logicalKeyStoreName
};
var keystore = new KeyStore(keystoreConfig);
ステップ 2: ブランチキーストアを作成するために CreateKeyStore を呼び出す

次のオペレーションでは、ブランチキーを保持および保護するブランチキーストアを作成します。

Java
keystore.CreateKeyStore(CreateKeyStoreInput.builder().build());
C# / .NET
var createKeyStoreOutput = keystore.CreateKeyStore(new CreateKeyStoreInput());

CreateKeyStore オペレーションにより、ステップ 1 で指定したテーブル名と次の必要な値を持つ DynamoDB テーブルが作成されます。

パーティションキー ソートキー
ベーステーブル branch-key-id type
注記

CreateKeyStore オペレーションを使用する代わりに、ブランチキーストアとして機能する DynamoDB テーブルを手動で作成できます。ブランチキーストアを手動で作成する場合は、パーティションキーとソートキーに次の文字列値を指定する必要があります。

  • パーティションキー: branch-key-id

  • ソートキー: type

ステップ 3: 新しいアクティブなブランチキーを作成するために CreateKey を呼び出す

次のオペレーションでは、ステップ 1 で指定した KMS キーを使用して新しいアクティブなブランチキーを作成し、ステップ 2 で作成した DynamoDB テーブルにアクティブなブランチキーを追加します。

CreateKey を呼び出す際に、次のオプションの値を指定することを選択できます。

  • branchKeyIdentifier: カスタム branch-key-id を定義します。

    カスタム branch-key-id を作成するには、encryptionContext パラメータに追加の暗号化コンテキストを含める必要もあります。

  • encryptionContext: は、kms:GenerateDataKeyWithoutPlaintext call に含まれる暗号化コンテキストで追加の認証データ (AAD) を提供する、シークレット以外のキーと値のペアのオプションセットを定義します。

    この追加の暗号化コンテキストは aws-crypto-ec: プレフィックスとともに表示されます。

Java
final Map<String, String> additionalEncryptionContext = Collections.singletonMap("Additional Encryption Context for",
        "custom branch key id");
            
final String BranchKey = keystore.CreateKey(
        CreateKeyInput.builder()
                .branchKeyIdentifier(custom-branch-key-id) //OPTIONAL
                .encryptionContext(additionalEncryptionContext) //OPTIONAL
                .build()).branchKeyIdentifier();
C# / .NET
var additionalEncryptionContext = new Dictionary<string, string>();
additionalEncryptionContext.Add("Additional Encryption Context for", "custom branch key id");
        
var branchKeyId = keystore.CreateKey(new CreateKeyInput
{
    BranchKeyIdentifier = "custom-branch-key-id", // OPTIONAL
    EncryptionContext = additionalEncryptionContext // OPTIONAL
});

まず、CreateKey オペレーションにより次の値が生成されます。

次に、CreateKeyオペレーションは次のリクエストを使用して kms GenerateDataKeyWithoutPlaintextを呼び出します。

{
   "EncryptionContext": { 
      "branch-key-id" : "branch-key-id",
      "type" : "type",
      "create-time" : "timestamp",
      "logical-key-store-name" : "the logical table name for your branch key store",
      "kms-arn" : the KMS key ARN,
      "hierarchy-version" : "1",
      "aws-crypto-ec:contextKey": "contextValue"
   },
   "KeyId": "the KMS key ARN you specified in Step 1",
   "NumberOfBytes": "32"
}
注記

検索可能な暗号化のためにデータベースを設定していない場合でも、CreateKey オペレーションはアクティブなブランチキーとビーコンキーを作成します。どちらのキーもブランチキーストアに格納されます。詳細については、「検索可能な暗号化のための階層キーリングの使用」を参照してください。

次に、CreateKeyオペレーションは kms:ReEncrypt を呼び出し、暗号化コンテキストを更新してブランチキーのアクティブなレコードを作成します。

最後に、 CreateKeyオペレーションは ddb:TransactWriteItems を呼び出して、ステップ 2 で作成したテーブルにブランチキーを保持する新しい項目を書き込みます。項目には次の属性があります。

{
    "branch-key-id" : branch-key-id,
    "type" : "branch:ACTIVE",
    "enc" : the branch key returned by the GenerateDataKeyWithoutPlaintext call,
    "version": "branch:version:the branch key version UUID",
    "create-time" : "timestamp",
    "kms-arn" : "the KMS key ARN you specified in Step 1",
    "hierarchy-version" : "1",
    "aws-crypto-ec:contextKey": "contextValue"
}

階層キーリングを作成する

階層キーリングを初期化するには、次の値を指定する必要があります。

  • ブランチキーストア名

    ブランチキーストアとして機能させるために作成した DynamoDB テーブルの名前。

  • キャッシュ制限 Time to Live (TTL)

    ローカルキャッシュ内のブランチキーマテリアルエントリを使用できる時間 (期限切れになるまでの時間) (秒)。キャッシュ制限 TTL は、クライアントがブランチキーの使用を許可 AWS KMS するために を呼び出す頻度を決定します。この値はゼロより大きくなければなりません。キャッシュ制限 TTL の期限が切れると、エントリはローカルキャッシュから削除されます。

  • ブランチキーの識別子

    ブランチキーストア内のアクティブなブランチキーを識別する branch-key-id。

    注記

    マルチテナンシー用に階層キーリングを初期化するには、branch-key-id の代わりにブランチキー ID サプライヤーを指定する必要があります。詳細については、「マルチテナンシーデータベースでの階層キーリングの使用」を参照してください。

  • (オプション) 許可トークンのリスト

    階層キーリング内の KMS キーへのアクセスを許可によって制御する場合は、キーリングを初期化する際に必要なすべての許可トークンを指定する必要があります。

次の例は、 AWS Database Encryption SDK for DynamoDB クライアントを使用して階層キーリングを初期化する方法を示しています。次の例では、キャッシュ制限 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# / .NET
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsHierarchicalKeyringInput
{
   KeyStore = keystore,
   BranchKeyIdSupplier = branchKeyIdSupplier,
   TtlSeconds = 600
};
var hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);

アクティブなブランチキーをローテーションする

各ブランチキーのために一度に存在できるアクティブなバージョンは 1 つだけです。階層キーリングは通常、複数のリクエストを満たすためにアクティブな各ブランチキーバージョンを使用します。ただし、ユーザーがアクティブなブランチキーを再利用する範囲を制御し、アクティブなブランチキーをローテーションする頻度を決定します。

ブランチキーは、プレーンテキストデータキーの暗号化には使用されません。これらは、プレーンテキストデータキーを暗号化する一意のラッピングキーを導出するために使用されます。ラッピングキー導出プロセスでは、28 バイトのランダム性を備えた一意の 32 バイトのラッピングキーが生成されます。これは、暗号の摩耗が発生する前に、ブランチキーが 7 穣 9 秭、つまり 296 を超える一意のラッピングキーを導出できることを意味します。このように枯渇するリスクは極めて低いものの、ビジネスルールや契約、政府の規制により、アクティブなブランチキーのローテーションが必要になる場合があります。

ブランチキーのアクティブなバージョンは、ローテーションされるまでアクティブなままとなります。以前のバージョンのアクティブなブランチキーは、暗号化オペレーションの実行には使用されず、新しいラッピングキーの導出にも使用できません。ただし、引き続きクエリを実行し、アクティブなときに暗号化したデータキーを復号するためのラッピングキーを提供することはできます。

キーストアサービス VersionKey オペレーションを使用して、アクティブなブランチキーをローテーションします。アクティブなブランチキーをローテーションすると、以前のバージョンを置き換えるために新しいブランチキーが作成されます。アクティブなブランチキーをローテーションしても、branch-key-id は変わりません。VersionKey を呼び出す際に、現在アクティブなブランチキーを識別する branch-key-id を指定する必要があります。

Java
keystore.VersionKey(
    VersionKeyInput.builder()
        .branchKeyIdentifier("branch-key-id")
        .build()
);
C# / .NET
 keystore.VersionKey(new VersionKeyInput{BranchKeyIdentifier = branchKeyId});

マルチテナンシーデータベースでの階層キーリングの使用

アクティブなブランチキーと、その導出されたラッピングキーの間に確立されたキー階層を使用して、データベース内のテナンシーごとにブランチキーを作成することでマルチテナンシーデータベースをサポートできます。その後、階層キーリングは、特定のテナンシーについてのすべてのデータを個別のブランチキーで暗号化して署名します。これにより、マルチテナンシーデータを単一のデータベースに格納し、ブランチキーによってテナンシーデータを分離できます。

各テナンシーには、一意の branch-key-id によって定義される独自のブランチキーがあります。各 branch-key-id のアクティブなバージョンは一度に 1 つだけ存在できます。

ブランチキー ID サプライヤー

マルチテナンシー用に階層キーリングを初期化する前に、各テナンシーのブランチキーを作成し、ブランチキー ID サプライヤーを作成する必要があります。ブランチキー ID サプライヤーでは、暗号化コンテキストに保存されているフィールドを使用して、レコードの復号化に必要なテナントのブランチキーを決定します。デフォルトでは、パーティションキーとソートキーのみが暗号化コンテキストに含まれます。ただし、SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT暗号化アクションを使用して、暗号化コンテキストに追加のフィールドを含めることができます。

注記

SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT 暗号化アクションを使用するには、 AWS Database Encryption SDK のバージョン 3.3 以降を使用する必要があります。データモデルを更新して を含める前に、すべてのリーダーに新しいバージョンをデプロイしますSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。

ブランチキー ID サプライヤーを使用して、テナントの正しい branch-key-idsを簡単に認識できるように、 branch-key-id のわかりやすい名前を作成できます。例えば、フレンドリ名を使用すると、ブランチキーを b3f61619-4d35-48ad-a275-050f87e15122 の代わりに tenant1 として参照できます。

復号オペレーションの場合、単一の階層キーリングを静的に設定して復号を単一のテナンシーに制限することも、ブランチキー ID サプライヤーを使用してレコードの復号を担当するテナンシーを識別することもできます。

まず、前提条件の手順のステップ 1 とステップ 2 に従います。その後、次の手順を使用して、各テナンシーのブランチキーを作成し、ブランチキー ID サプライヤーを作成して、マルチテナンシーで使用するために階層キーリングを初期化します。

ステップ 1: データベース内の各テナンシーのブランチキーを作成する

データベース内の各テナンシーの CreateKey を呼び出します。

次のオペレーションでは、キーストアサービスの作成時に指定した KMS キーを使用して 2 つのブランチキーを作成し、ブランチキーストアとして機能するように作成した DynamoDB テーブルにブランチキーを追加します。同じ KMS キーですべてのブランチキーを保護する必要があります。

Java
CreateKeyOutput branchKeyId1 = keystore.CreateKey(CreateKeyInput.builder().build());
CreateKeyOutput branchKeyId2 = keystore.CreateKey(CreateKeyInput.builder().build());
C# / .NET
var branchKeyId1 = keystore.CreateKey(new CreateKeyInput());
var branchKeyId2 = keystore.CreateKey(new CreateKeyInput());
ステップ 2: ブランチキー 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# / .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;
ステップ 3: ブランチキー ID サプライヤーを使用して階層キーリングを初期化する

階層キーリングを初期化するには、次の値を指定する必要があります。

  • ブランチキーストア名

  • キャッシュ制限 Time to Live (TTL)

  • ブランチキー ID サプライヤー

  • (オプション) キャッシュ

    キャッシュタイプまたはローカルキャッシュに格納できるブランチキーマテリアルエントリの数をカスタマイズする場合は、キーリングを初期化する際にキャッシュタイプとエントリキャパシティを指定します。

    キャッシュタイプはスレッドモデルを定義します。階層キーリングには、マルチテナントデータベースをサポートする 3 つのキャッシュタイプとして、デフォルト、 MultiThreaded、 があります StormTracking。

    キャッシュを指定しない場合、階層キーリングは、自動的に Default キャッシュタイプを使用し、エントリキャパシティを 1,000 に設定します。

    Default (Recommended)

    ほとんどのユーザーにとって、Default キャッシュはスレッド要件を満たします。Default キャッシュは、高度にマルチスレッド化されている環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、デフォルトキャッシュは、ブランチキーマテリアルエントリの有効期限が 10 秒前に切れることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが を呼び出すのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。

    階層キーリングを Default キャッシュで初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    Java
    .cache(CacheType.builder()
        .Default(DefaultCache.builder()
        .entryCapacity(100)
        .build())
    C# / .NET
    CacheType defaultCache = new CacheType
{
    Default = new DefaultCache{EntryCapacity = 100}
};

    デフォルト と StormTracking キャッシュは同じスレッドモデルをサポートしますが、デフォルトキャッシュで階層キーリングを初期化するには、エントリ容量を指定するだけで済みます。より詳細なキャッシュのカスタマイズを行うには、 StormTracking キャッシュを使用します。

    MultiThreaded

    MultiThreaded キャッシュはマルチスレッド環境で安全に使用できますが、 AWS KMS または Amazon DynamoDB 呼び出しを最小限に抑える機能は提供されません。その結果、ブランチキーマテリアルのエントリの期限が切れると、すべてのスレッドに同時に通知されます。これにより、キャッシュを更新するための AWS KMS 呼び出しが複数回発生する可能性があります。

    MultiThreaded キャッシュを使用して階層キーリングを初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    • エントリのプルーニングテールのサイズ: エントリキャパシティに達した場合にプルーニングするエントリの数を定義します。

    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    C# / .NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    StormTracking

    StormTracking キャッシュは、多スレッド環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、 StormTracking キャッシュは、ブランチキーマテリアルエントリの有効期限が切れることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが を呼び出すのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。

    StormTracking キャッシュを使用して階層キーリングを初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    • エントリのプルーニングテールのサイズ: 一度にプルーニングするブランチキーマテリアルのエントリの数を定義します。

      デフォルトの値: 1 個のエントリ

    • 猶予期間: 期限が切れる前にブランチキーマテリアルの更新を試行する秒数を定義します。

      デフォルト値: 10 秒

    • 猶予間隔: ブランチキーマテリアルの更新が試行される間隔の秒数を定義します。

      デフォルト値: 1 秒

    • ファンアウト: ブランチキーマテリアルの更新の同時試行が可能な回数を定義します。

      デフォルトの値: 20 回の試行

    • 処理中の Time To Live (TTL): ブランチキーマテリアルの更新の試行がタイムアウトするまでの秒数を定義します。キャッシュが GetCacheEntry に応答して NoSuchEntry を返すたびに、同じキーが PutCache エントリを使用して書き込まれるまで、そのブランチキーは処理中であるとみなされます。

      デフォルト値: 20 秒

    • スリープ: fanOut を超えた場合にスレッドがスリープする秒数を定義します。

      デフォルトの値: 20 ミリ秒

    Java
    .cache(CacheType.builder()
        .StormTracking(StormTrackingCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())
    C# / .NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};

  • (オプション) 許可トークンのリスト

    階層キーリング内の KMS キーへのアクセスを許可によって制御する場合は、キーリングを初期化する際に必要なすべての許可トークンを指定する必要があります。

次の例では、ステップ 2 で作成したブランチキー ID サプライヤー、キャッシュ制限 TLL が 600 秒、最大キャッシュサイズが 1000 の階層キーリングを初期化します。この例では、 AWS Database Encryption SDK for DynamoDB クライアントを使用して階層キーリングを初期化します。

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();
final Keyring hierarchicalKeyring = matProv.CreateAwsKmsHierarchicalKeyring(keyringInput);
C# / .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);
表示を増やす表示を減らす

検索可能な暗号化のための階層キーリングの使用

検索可能な暗号化を使用すると、データベース全体を復号することなく、暗号化されたレコードを検索できます。これは、ビーコンを使用して暗号化されたフィールドのプレーンテキストの値にインデックスを付けることで実現されます。検索可能な暗号化を実装するには、階層キーリングを使用する必要があります。

キーストア CreateKey オペレーションは、ブランチキーとビーコンキーの両方を生成します。ブランチキーは、レコードの暗号化および復号オペレーションで使用されます。ビーコンキーは、ビーコンを生成するために使用されます。

ブランチキーとビーコンキーは、キーストアサービスの作成時に指定した AWS KMS key ものと同じ によって保護されます。CreateKey オペレーションが AWS KMS を呼び出してブランチキーを生成すると、kmsGenerateDataKeyWithoutPlaintext を呼び出します。2 回目は、次のリクエストを使用してビーコンキーを生成します。

{
   "EncryptionContext": { 
      "branch-key-id" : "branch-key-id",
      "type" : type,
      "create-time" : "timestamp",
      "logical-key-store-name" : "the logical table name for your branch key store",
      "kms-arn" : the KMS key ARN,
      "hierarchy-version" : 1
   },
   "KeyId": "the KMS key ARN",
   "NumberOfBytes": "32"
}

両方のキーを生成した後、 CreateKeyオペレーションは ddb:TransactWriteItems を呼び出して、ブランチキーストアにブランチキーとビーコンキーを保持する 2 つの新しい項目を書き込みます。

標準ビーコン を設定すると、 AWS Database Encryption SDK はブランチキーストアにビーコンキーをクエリします。次に、HMAC ベースの extract-and-expand キー取得関数 (HKDF) を使用して、ビーコンキーと標準ビーコンの名前を組み合わせて、特定のビーコンの HMAC キーを作成します。

ブランチキーとは異なり、ブランチキーストアの branch-key-id ごとに存在するビーコンキーのバージョンは 1 つだけです。ビーコンキーがローテーションされることはありません。

ビーコンキーソースの定義

標準ビーコンおよび複合ビーコンのビーコンバージョンを定義する際には、ビーコンキーを識別し、ビーコンキーマテリアルのキャッシュ制限 Time To Live (TTL) を定義する必要があります。ビーコンキーマテリアルは、ブランチキーとは別のローカルキャッシュに格納されます。次のスニペットは、シングルテナンシーデータベースの keySource を定義する方法を示しています。関連付けられている branch-key-id によってビーコンキーを識別します。

Java
keySource(BeaconKeySource.builder()
        .single(SingleKeyStore.builder()
                .keyId(branch-key-id)
                .cacheTTL(6000)
                .build())
        .build())
C# / .NET
KeySource = new BeaconKeySource
{
    Single = new SingleKeyStore
    {
       KeyId = branch-key-id,
       CacheTTL = 6000
    }
}
マルチテナンシーデータベースでのビーコンソースの定義

マルチテナンシーデータベースがある場合は、keySource を設定する際に次の値を指定する必要があります。

  • keyFieldName

    特定のテナンシーについて生成されたビーコンに使用されるビーコンキーに関連付けられた branch-key-id を格納するフィールドの名前を定義します。keyFieldName には任意の文字列を指定できますが、データベース内の他のすべてのフィールドで一意である必要があります。新しいレコードをデータベースに書き込むと、そのレコードについてのビーコンを生成するために使用されるビーコンキーを識別する branch-key-id がこのフィールドに格納されます。このフィールドをビーコンクエリに含めて、ビーコンの再計算に必要となる適切なビーコンキーマテリアルを特定する必要があります。詳細については、「マルチテナンシーデータベース内のビーコンのクエリ」を参照してください。

  • cacheTTL

    ローカルビーコンキャッシュ内のビーコンキーマテリアルエントリを使用できる時間 (期限切れになるまでの時間) (秒)。この値はゼロより大きくなければなりません。キャッシュ制限 TTL の期限が切れると、エントリはローカルキャッシュから削除されます。

  • (オプション) キャッシュ

    キャッシュタイプまたはローカルキャッシュに格納できるブランチキーマテリアルエントリの数をカスタマイズする場合は、キーリングを初期化する際にキャッシュタイプとエントリキャパシティを指定します。

    キャッシュタイプはスレッドモデルを定義します。階層キーリングには、マルチテナントデータベースをサポートする 3 つのキャッシュタイプとして、デフォルト、 MultiThreaded、 があります StormTracking。

    キャッシュを指定しない場合、階層キーリングは、自動的に Default キャッシュタイプを使用し、エントリキャパシティを 1,000 に設定します。

    Default (Recommended)

    ほとんどのユーザーにとって、Default キャッシュはスレッド要件を満たします。Default キャッシュは、高度にマルチスレッド化されている環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、デフォルトキャッシュは、ブランチキーマテリアルエントリの有効期限が 10 秒前に切れることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが を呼び出すのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。

    階層キーリングを Default キャッシュで初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    Java
    .cache(CacheType.builder()
        .Default(DefaultCache.builder()
        .entryCapacity(100)
        .build())
    C# / .NET
    CacheType defaultCache = new CacheType
{
    Default = new DefaultCache{EntryCapacity = 100}
};

    デフォルト と StormTracking キャッシュは同じスレッドモデルをサポートしますが、デフォルトキャッシュで階層キーリングを初期化するには、エントリ容量を指定するだけで済みます。より詳細なキャッシュのカスタマイズを行うには、 StormTracking キャッシュを使用します。

    MultiThreaded

    MultiThreaded キャッシュはマルチスレッド環境で安全に使用できますが、 AWS KMS または Amazon DynamoDB 呼び出しを最小限に抑える機能は提供されません。その結果、ブランチキーマテリアルのエントリの期限が切れると、すべてのスレッドに同時に通知されます。これにより、キャッシュを更新するための AWS KMS 呼び出しが複数回発生する可能性があります。

    MultiThreaded キャッシュを使用して階層キーリングを初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    • エントリのプルーニングテールのサイズ: エントリキャパシティに達した場合にプルーニングするエントリの数を定義します。

    Java
    .cache(CacheType.builder()
        .MultiThreaded(MultiThreadedCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)                                        
        .build())
    C# / .NET
    CacheType multithreadedCache = new CacheType
{
    MultiThreaded = new MultiThreadedCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1
    }
};
    StormTracking

    StormTracking キャッシュは、多スレッド環境をサポートするように設計されています。ブランチキーマテリアルエントリの有効期限が切れると、 StormTracking キャッシュは、ブランチキーマテリアルエントリの有効期限が切れることを 1 つのスレッドに通知 AWS KMS することで、複数のスレッドが を呼び出すのを防ぎます。これにより、1 つのスレッドのみが にリクエストを送信 AWS KMS してキャッシュを更新します。

    StormTracking キャッシュを使用して階層キーリングを初期化するには、次の値を指定します。

    • エントリキャパシティ: ローカルキャッシュに格納できるブランチキーマテリアルのエントリの数を制限します。

    • エントリのプルーニングテールのサイズ: 一度にプルーニングするブランチキーマテリアルのエントリの数を定義します。

      デフォルトの値: 1 個のエントリ

    • 猶予期間: 期限が切れる前にブランチキーマテリアルの更新を試行する秒数を定義します。

      デフォルト値: 10 秒

    • 猶予間隔: ブランチキーマテリアルの更新が試行される間隔の秒数を定義します。

      デフォルト値: 1 秒

    • ファンアウト: ブランチキーマテリアルの更新の同時試行が可能な回数を定義します。

      デフォルトの値: 20 回の試行

    • 処理中の Time To Live (TTL): ブランチキーマテリアルの更新の試行がタイムアウトするまでの秒数を定義します。キャッシュが GetCacheEntry に応答して NoSuchEntry を返すたびに、同じキーが PutCache エントリを使用して書き込まれるまで、そのブランチキーは処理中であるとみなされます。

      デフォルト値: 20 秒

    • スリープ: fanOut を超えた場合にスレッドがスリープする秒数を定義します。

      デフォルトの値: 20 ミリ秒

    Java
    .cache(CacheType.builder()
        .StormTracking(StormTrackingCache.builder()
        .entryCapacity(100)
        .entryPruningTailSize(1)
        .gracePeriod(10)
        .graceInterval(1)
        .fanOut(20) 
        .inFlightTTL(20)
        .sleepMilli(20)                                        
        .build())
    C# / .NET
    CacheType stormTrackingCache = new CacheType
{
    StormTracking = new StormTrackingCache
    {
        EntryCapacity = 100,
        EntryPruningTailSize = 1,
        FanOut = 20,
        GraceInterval = 1,
        GracePeriod = 10,
        InFlightTTL = 20,
        SleepMilli = 20
    }
};

次の例では、ステップ 2 で作成したブランチキー ID サプライヤー、キャッシュ制限 TLL が 600 秒、エントリ容量が 1000 の階層キーリングを初期化します。

Java
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);
C# / .NET
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);