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

# ビーコンの使用
<a name="using-beacons"></a>


****  

|  | 
| --- |
| クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md) に関する情報を提供します。 | 

ビーコンを使用すると、クエリ対象のデータベース全体を復号することなく、暗号化されたレコードを検索できます。ビーコンは、データが入力されていない新しいデータベースに実装されるように設計されています。既存のデータベースで設定されたビーコンは、データベースに書き込まれる新しいレコードのみをマッピングします。ビーコンはフィールドのプレーンテキストの値から計算されます。フィールドが暗号化されると、ビーコンは既存のデータをマッピングできなくなります。ビーコンを持つ新しいレコードを書き込んだ後に、そのビーコンの設定を更新することはできません。ただし、レコードに追加する新しいフィールドに新しいビーコンを追加できます。

ビーコンを設定した後、データベースにデータを入力し、ビーコンをクエリする前に、次のステップを完了する必要があります。

1. ** AWS KMS 階層キーリングを作成する**

   検索可能な暗号化を使用するには、[AWS KMS 階層キーリング](use-hierarchical-keyring.md)を使用して、レコードを保護するために使用される[データキー](concepts.md#data-key)を生成、暗号化、および復号する必要があります。

   ビーコンを設定した後、[階層キーリング](use-hierarchical-keyring.md#hierarchical-keyring-prereqs)の前提条件をアセンブルし、[階層キーリングを作成](use-hierarchical-keyring.md#initialize-hierarchical-keyring)します。

   階層キーリングが必要な理由の詳細については、「[検索可能な暗号化のための階層キーリングの使用](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings)」を参照してください。

1. 

   **ビーコンのバージョンを定義する**

   `keyStore`、`keySource`、設定したすべての標準ビーコンのリスト、設定したすべての複合ビーコンのリスト、暗号化されたパートのリスト、署名されたパートのリスト、ビーコンバージョンを指定します。ビーコンのバージョンとして `1` を指定する必要があります。`keySource` の定義に関するガイダンスについては、「[ビーコンキーソースの定義](use-hierarchical-keyring.md#beacon-key-source)」を参照してください。

   次の Java の例では、シングルテナンシーデータベースのビーコンバージョンを定義します。マルチテナンシーデータベースのビーコンバージョンの定義については、「[マルチテナンシーデータベースの検索可能な暗号化](searchable-encryption-multitenant.md)」を参照してください。

------
#### [ Java ]

   ```
    List<BeaconVersion> beaconVersions = new ArrayList<>();
   beaconVersions.add(
       BeaconVersion.builder()
           .standardBeacons(standardBeaconList)
           .compoundBeacons(compoundBeaconList)
           .encryptedParts(encryptedPartsList)
           .signedParts(signedPartsList)
           .version(1) // MUST be 1
           .keyStore(keyStore)
           .keySource(BeaconKeySource.builder()
               .single(SingleKeyStore.builder()
                   .keyId(branchKeyId)
                   .cacheTTL(6000)
                   .build())
               .build())
           .build()
   );
   ```

------
#### [ C\$1 / .NET ]

   ```
   var beaconVersions = new List<BeaconVersion>
   {
       new BeaconVersion
       {
           StandardBeacons = standardBeaconList,
           CompoundBeacons = compoundBeaconList,
           EncryptedParts = encryptedPartsList,
           SignedParts = signedPartsList,
           Version = 1, // MUST be 1
           KeyStore = branchKeyStoreName,
           KeySource = new BeaconKeySource
           {
               Single = new SingleKeyStore
               {
                   KeyId = branch-key-id,
                   CacheTTL = 6000
               }
           }
       }
   };
   ```

------
#### [ Rust ]

   ```
   let beacon_version = BeaconVersion::builder()
       .standard_beacons(standard_beacon_list)
       .compound_beacons(compound_beacon_list)
       .version(1) // MUST be 1
       .key_store(key_store.clone())
       .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()?,
       ))
       .build()?;
   let beacon_versions = vec![beacon_version];
   ```

------

1. **セカンダリインデックスを設定する**

   [ビーコンを設定](configure-beacons.md)した後、暗号化されたフィールドを検索する前に、各ビーコンを反映するセカンダリインデックスを設定する必要があります。詳細については、「[ビーコンを使用したセカンダリインデックスの設定](ddb-searchable-encryption.md#ddb-beacon-indexes)」を参照してください。

1. **[暗号化アクション](concepts.md#crypt-actions)を定義する**

   標準ビーコンの構築に使用されるすべてのフィールドを `ENCRYPT_AND_SIGN` とマークする必要があります。ビーコンの構築に使用される他のすべてのフィールドは、 `SIGN_ONLY`または とマークする必要があります`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`。

1. ** AWS Database Encryption SDK クライアントを設定する**

   DynamoDB テーブルのテーブル項目を保護する AWS Database Encryption SDK クライアントを設定するには、[DynamoDB の Java クライアント側の暗号化ライブラリ](ddb-java.md)」を参照してください。

## ビーコンのクエリ
<a name="querying-beacons"></a>

設定するビーコンのタイプによって、実行できるクエリのタイプが決まります。標準ビーコンは、フィルター式を使用して一致検索を実行します。複合ビーコンは、リテラルプレーンテキスト文字列と標準ビーコンを組み合わせて、複雑なクエリを実行します。暗号化されたデータをクエリする際には、ビーコン名で検索します。

2 つの標準ビーコンの値は、基になる同じプレーンテキストが含まれている場合でも比較できません。2 つの標準ビーコンは、同じプレーンテキストの値について 2 つの異なる HMAC タグを生成します。その結果、標準ビーコンは次のクエリを実行できません。
+ `beacon1 = beacon2`
+ `beacon1 IN (beacon2)`
+ `value IN (beacon1, beacon2, ...)`
+ `CONTAINS(beacon1, beacon2)`

複合ビーコンは次のクエリを実行できます。
+ `BEGINS_WITH(a)`。ここで、`a` は、アセンブルされた複合ビーコンの先頭のフィールドの値全体を反映します。`BEGINS_WITH` 演算子を使用して、特定の部分文字列で始まる値を識別することはできません。ただし、`BEGINS_WITH(S_)` を使用することはできます。ここで、`S_` は、アセンブルされた複合ビーコンの先頭の部分のプレフィックスを反映します。
+ `CONTAINS(a)`。ここで、`a` は、アセンブルされた複合ビーコンが含むフィールドの値全体を反映します。`CONTAINS` 演算子を使用して、セット内の特定の部分文字列または値を含むレコードを識別することはできません。

  例えば、クエリ `CONTAINS(path, "a"` を実行することはできません。ここで、`a` は、セット内の値を反映します。
+ 複合ビーコンの[署名付きの部分](configure-beacons.md#signed-parts)を比較できます。署名付きの部分を比較する場合、必要に応じて、[暗号化部分](configure-beacons.md#encrypted-parts)のプレフィックスを 1 つ以上の署名付きの部分に付加できますが、暗号化されたフィールドの値をクエリに含めることはできません。

  例えば、署名付きの部分を比較し、`signedField1 = signedField2` または `value IN (signedField1, signedField2, ...)` をクエリできます。

  署名付きの部分と暗号化部分のプレフィックスを、`signedField1.A_ = signedField2.B_` に対するクエリによって比較することもできます。
+ `field BETWEEN a AND b`。ここで、`a` と `b` は署名付きの部分です。必要に応じて、暗号化部分のプレフィックスを 1 つ以上の署名付きの部分に付加できますが、暗号化されたフィールドの値をクエリに含めることはできません。

複合ビーコンに対するクエリに含める各部分のプレフィックスを含める必要があります。例えば、`encryptedField` および `signedField` の 2 つのフィールドから複合ビーコン `compoundBeacon` を構築した場合、ビーコンをクエリする際に、これらの 2 つの部分について設定されたプレフィックスを含める必要があります。

```
compoundBeacon = E_encryptedFieldValue.S_signedFieldValue
```