翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# ビーコンの設定
****
| |
| --- |
| クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md) に関する情報を提供します。 |
検索可能な暗号化をサポートするビーコンには 2 つのタイプがあります。標準ビーコンは、一致検索を実行します。これらは、データベースで検索可能な暗号化を実装する最も簡単な方法です。複合ビーコンは、リテラルプレーンテキスト文字列と標準ビーコンを組み合わせて、より複雑なクエリを実行します。
ビーコンは、データが入力されていない新しいデータベースに実装されるように設計されています。既存のデータベースで設定されたビーコンは、データベースに書き込まれる新しいレコードのみをマッピングします。ビーコンはフィールドのプレーンテキストの値から計算されます。フィールドが暗号化されると、ビーコンは既存のデータをマッピングできなくなります。ビーコンを持つ新しいレコードを書き込んだ後に、そのビーコンの設定を更新することはできません。ただし、レコードに追加する新しいフィールドに新しいビーコンを追加できます。
アクセスパターンを決定したら、データベース実装の 2 番目のステップとしてビーコンを設定する必要があります。次に、すべてのビーコンを設定したら、[AWS KMS 階層キーリング](use-hierarchical-keyring.md)の作成、ビーコンバージョンの定義、[各ビーコンのセカンダリインデックスの設定](ddb-searchable-encryption.md#ddb-beacon-indexes)、[暗号化アクション](concepts.md#crypt-actions)の定義、データベースと AWS Database Encryption SDK クライアントの設定を行う必要があります。詳細については、「[ビーコンの使用](using-beacons.md)」を参照してください。
ビーコンのバージョンをより簡単に定義できるように、標準ビーコンと複合ビーコンのリストを作成することをお勧めします。作成した各ビーコンを、設定時にそれぞれの標準ビーコンリストまたは複合ビーコンリストに追加します。
**Topics**
+ [標準ビーコンの設定](#config-standard-beacons)
+ [複合ビーコンの設定](#config-compound-beacons)
+ [設定例](beacon-config-examples.md)
## 標準ビーコンの設定
[標準ビーコン](beacons.md#standard-beacon-overview)は、データベースで検索可能な暗号化を実装する最も簡単な方法です。単一の暗号化されたフィールドまたは仮想フィールドについてのみ一致検索を実行できます。
### 設定構文の例
------
#### [ Java ]
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
------
#### [ C\$1 / .NET ]
```
var standardBeaconList = new List();
StandardBeacon exampleStandardBeacon = new StandardBeacon
{
Name = "beaconName",
Length = 10
};
standardBeaconList.Add(exampleStandardBeacon);
```
------
#### [ Rust ]
```
let standard_beacon_list = vecの名前を使用することを強くお勧めします。2 つの異なるビーコンに同じビーコン名を付けることはできません。実装に最適なビーコン名を決定する方法については、「[ビーコン名の選択](choosing-beacon-name.md)」を参照してください。
**ビーコンの長さ**
切り詰めた後に保持されるビーコンのハッシュ値のビット数。
ビーコンの長さによって、特定のビーコンによって生成される誤検知の平均数が決まります。実装に適切なビーコンの長さを決定する方法の詳細とヘルプについては、「[ビーコンの長さの決定](choosing-beacon-length.md)」を参照してください。
**ビーコンソース (オプション)**
標準ビーコンの構築元となるフィールド。
ビーコンソースは、フィールド名、またはネストされたフィールドの値を参照するインデックスである必要があります。ビーコン名がビーコンソースと同じ場合、設定からビーコンソースを省略でき、 AWS Database Encryption SDK は自動的にビーコン名をビーコンソースとして使用します。
### 仮想フィールドの作成
[仮想フィールド](beacons.md#virtual-field)を作成するには、仮想フィールドの名前とソースフィールドのリストを指定する必要があります。ソースフィールドを仮想部分のリストに追加する順序によって、仮想フィールドを構築するためにこれらのソースフィールドが連結される順序が決まります。次の例では、2 つのソースフィールド全体を連結して、仮想フィールドを作成します。
**注記**
データベースに入力する前に、仮想フィールドが期待される結果を生成することを確認することをお勧めします。詳細については、[「ビーコン出力のテスト](ddb-searchable-encryption.md#ddb-beacon-testing)」を参照してください。
------
#### [ Java ]
**完全なコード例を参照**: [VirtualBeaconSearchableEncryptionExample.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption/VirtualBeaconSearchableEncryptionExample.java)
```
List virtualPartList = new ArrayList<>();
virtualPartList.add(sourceField1);
virtualPartList.add(sourceField2);
VirtualField virtualFieldName = VirtualField.builder()
.name("virtualFieldName")
.parts(virtualPartList)
.build();
List virtualFieldList = new ArrayList<>();
virtualFieldList.add(virtualFieldName);
```
------
#### [ C\$1 / .NET ]
**完全なコード例を参照**: [VirtualBeaconSearchableEncryptionExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/VirtualBeaconSearchableEncryptionExample.cs)
```
var virtualPartList = new List { sourceField1, sourceField2 };
var virtualFieldName = new VirtualField
{
Name = "virtualFieldName",
Parts = virtualPartList
};
var virtualFieldList = new List { virtualFieldName };
```
------
#### [ Rust ]
**完全なコード例を参照**: [virtual\$1beacon\$1searchable\$1encryption.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/virtual_beacon_searchable_encryption.rs)
```
let virtual_part_list = vec![source_field_one, source_field_two];
let state_and_has_test_result_field = VirtualField::builder()
.name("virtual_field_name")
.parts(virtual_part_list)
.build()?;
let virtual_field_list = vec![virtual_field_name];
```
------
ソースフィールドの特定のセグメントを使用して仮想フィールドを作成するには、ソースフィールドを仮想部分のリストに追加する前に、その変換を定義する必要があります。
#### 仮想フィールドのセキュリティに関する考慮事項
ビーコンはフィールドの暗号化状態を変更しません。ただし、ビーコンを使用する場合、クエリの効率性と、データの分布に関して明らかになる情報の量との間には、固有のトレードオフが存在します。ビーコンを設定する方法によって、そのビーコンによって維持されるセキュリティのレベルが決まります。
既存の標準ビーコンと重複するソースフィールドを含む仮想フィールドを作成しないようにしてください。標準ビーコンを作成するために既に使用されているソースフィールドを含む仮想フィールドを作成すると、両方のビーコンのセキュリティレベルが低下する可能性があります。セキュリティが低下する程度は、追加のソースフィールドによって追加されるエントロピーのレベルによって異なります。エントロピーのレベルは、追加のソースフィールド内の固有の値の分布と、追加のソースフィールドが仮想フィールドの全体的なサイズに寄与するビット数によって決まります。
母集団と[ビーコンの長さ](choosing-beacon-length.md)を使用して、仮想フィールドのソースフィールドがデータセットのセキュリティを維持するかどうかを判断できます。母集団は、フィールド内の一意の値の想定数です。母集団は正確である必要はありません。フィールドの母集団の推定については、「[母集団の推定](choosing-beacon-length.md#estimate-population)」を参照してください。
仮想フィールドのセキュリティを確認する際には、次の例を考慮してください。
+ Beacon1 は `FieldA` から構築されます。`FieldA` の母集団は、**2 (Beacon1 の長さ)** よりも大きいです。
+ Beacon2 は `VirtualField` から構築されます。これは、`FieldA`、`FieldB`、`FieldC`、および `FieldD` から構築されます。`FieldB`、`FieldC`、および `FieldD` を合わせると、母集団は **2N** よりも大きくなります
次のステートメントが真の場合、Beacon2 は Beacon1 と Beacon2 の両方のセキュリティを維持します。
```
N ≥ (Beacon1 length)/2
```
と
```
N ≥ (Beacon2 length)/2
```
### ビーコンスタイルの定義
標準ビーコンを使用して、暗号化されたフィールドまたは仮想フィールドの等価検索を実行できます。または、複合ビーコンを構築して、より複雑なデータベースオペレーションを実行することもできます。標準ビーコンの整理と管理に役立つように、 AWS Database Encryption SDK には、標準ビーコンの用途を定義する以下のオプション*ビーコンスタイル*が用意されています。
**注記**
ビーコンスタイルを定義するには、 AWS Database Encryption SDK のバージョン 3.2 以降を使用する必要があります。ビーコン設定にビーコンスタイルを追加する前に、すべてのリーダーに新しいバージョンをデプロイします。
------
#### [ PartOnly ]
として定義された標準ビーコンは、複合ビーコンの[暗号化された部分](#encrypted-parts)を定義するために`PartOnly`のみ使用できます。`PartOnly` 標準ビーコンを直接クエリすることはできません。
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.partOnly(PartOnly.builder().build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1 / .NET**
```
new StandardBeacon
{
Name = "beaconName",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
PartOnly = new PartOnly()
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon_name")
.length(beacon_length_in_bits)
.style(BeaconStyle::PartOnly(PartOnly::builder().build()?))
.build()?
```
------
#### [ Shared ]
デフォルトでは、すべての標準ビーコンはビーコン計算用の一意の HMAC キーを生成します。そのため、2 つの異なる標準ビーコンから暗号化されたフィールドに対して等価検索を実行することはできません。として定義された標準ビーコン`Shared`は、別の標準ビーコンの HMAC キーを計算に使用します。
たとえば、`beacon1`フィールドと`beacon2`フィールドを比較する必要がある場合は、 を、 の計算に の HMAC キーを使用する`Shared`ビーコン`beacon2`として定義`beacon1`します。
**注記**
`Shared` ビーコンを設定する前に、セキュリティとパフォーマンスのニーズを考慮してください。 `Shared` ビーコンは、データセットの分布に関して識別できる統計情報の量を増やす可能性があります。たとえば、どの共有フィールドに同じプレーンテキスト値が含まれているかを明らかにすることができます。
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beacon2")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.shared(Shared.builder().other("beacon1").build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1 / .NET**
```
new StandardBeacon
{
Name = "beacon2",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
Shared = new Shared { Other = "beacon1" }
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon2")
.length(beacon_length_in_bits)
.style(BeaconStyle::Shared(
Shared::builder().other("beacon1").build()?,
))
.build()?
```
------
#### [ AsSet ]
デフォルトでは、フィールド値がセットの場合、 AWS Database Encryption SDK はセットの単一の標準ビーコンを計算します。そのため、 が暗号化されたフィールド`CONTAINS(a, :value)``a`であるクエリを実行することはできません。として定義された標準ビーコンは、セットの各要素の個々の標準ビーコン値を`AsSet`計算し、ビーコン値をセットとして項目に保存します。これにより、 AWS Database Encryption SDK はクエリ を実行できます`CONTAINS(a, :value)`。
`AsSet` 標準ビーコンを定義するには、セット内の要素が同じビーコン[の長さ](choosing-beacon-length.md)を使用できるように、同じ母集団の要素である必要があります。ビーコン値の計算時に衝突が発生した場合、ビーコンセットの要素数がプレーンテキストセットよりも少なくなる可能性があります。
**注記**
`AsSet` ビーコンを設定する前に、セキュリティとパフォーマンスのニーズを考慮してください。 `AsSet` ビーコンは、データセットの分布に関して識別できる統計情報の量を増やす可能性があります。たとえば、プレーンテキストセットのサイズが明らかになる場合があります。
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beaconName")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.asSet(AsSet.builder().build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1 / .NET**
```
new StandardBeacon
{
Name = "beaconName",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
AsSet = new AsSet()
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon_name")
.length(beacon_length_in_bits)
.style(BeaconStyle::AsSet(AsSet::builder().build()?))
.build()?
```
------
#### [ SharedSet ]
として定義された標準ビーコンは、 関数`Shared`と `AsSet`関数`SharedSet`を組み合わせて、セットとフィールドの暗号化された値に対して等価検索を実行できるようにします。これにより、 AWS Database Encryption SDK は、 `CONTAINS(a, b)` `a`が暗号化されたセットであり、 が暗号化されたフィールド`b`であるクエリを実行できます。
**注記**
`Shared` ビーコンを設定する前に、セキュリティとパフォーマンスのニーズを考慮してください。 `SharedSet` ビーコンは、データセットの分布に関して識別できる統計情報の量を増やす可能性があります。たとえば、プレーンテキストセットのサイズや、同じプレーンテキスト値を含む共有フィールドが明らかになる場合があります。
**Java**
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("beacon2")
.length(beaconLengthInBits)
.style(
BeaconStyle.builder()
.sharedSet(SharedSet.builder().other("beacon1").build())
.build()
)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
**C\$1 / .NET**
```
new StandardBeacon
{
Name = "beacon2",
Length = beaconLengthInBits,
Style = new BeaconStyle
{
SharedSet = new SharedSet { Other = "beacon1" }
}
}
```
**Rust**
```
StandardBeacon::builder()
.name("beacon2")
.length(beacon_length_in_bits)
.style(BeaconStyle::SharedSet(
SharedSet::builder().other("beacon1").build()?,
))
.build()?
```
------
## 複合ビーコンの設定
複合ビーコンは、リテラルプレーンテキスト文字列と標準ビーコンを組み合わせて、単一のインデックスから 2 つの異なるレコードタイプをクエリしたり、ソートキーを使用してフィールドの組み合わせをクエリしたりするなど、複雑なデータベースオペレーションを実行します。複合ビーコンは、`ENCRYPT_AND_SIGN`、、`SIGN_ONLY`および `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`フィールドから構築できます。複合ビーコンに含まれる暗号化されたフィールドごとに標準ビーコンを作成する必要があります。
**注記**
データベースに入力する前に、複合ビーコンが期待される結果を生成することを確認することをお勧めします。詳細については、[「ビーコン出力のテスト](ddb-searchable-encryption.md#ddb-beacon-testing)」を参照してください。
### 設定構文の例
------
#### [ Java ]
**複合ビーコン設定**
次の例では、複合ビーコン設定内で暗号化および署名されたパートリストをローカルに定義します。
```
List compoundBeaconList = new ArrayList<>();
CompoundBeacon exampleCompoundBeacon = CompoundBeacon.builder()
.name("compoundBeaconName")
.split(".")
.encrypted(encryptedPartList)
.signed(signedPartList)
.constructors(constructorList)
.build();
compoundBeaconList.add(exampleCompoundBeacon);
```
**ビーコンバージョン定義**
次の例では、ビーコンバージョンで暗号化および署名されたパートリストをグローバルに定義します。ビーコンバージョンの定義の詳細については、[「ビーコンの使用](using-beacons.md)」を参照してください。
```
List beaconVersions = new ArrayList<>();
beaconVersions.add(
BeaconVersion.builder()
.standardBeacons(standardBeaconList)
.compoundBeacons(compoundBeaconList)
.encryptedParts(encryptedPartList)
.signedParts(signedPartList)
.version(1) // MUST be 1
.keyStore(keyStore)
.keySource(BeaconKeySource.builder()
.single(SingleKeyStore.builder()
.keyId(branchKeyId)
.cacheTTL(6000)
.build())
.build())
.build()
);
```
------
#### [ C\$1 / .NET ]
**完全なコードサンプルを参照**: [BeaconConfig.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/complexexample/BeaconConfig.cs)
**複合ビーコン設定**
次の例では、複合ビーコン設定内で暗号化および署名されたパートリストをローカルに定義します。
```
var compoundBeaconList = new List();
var exampleCompoundBeacon = new CompoundBeacon
{
Name = "compoundBeaconName",
Split = ".",
Encrypted = encryptedPartList,
Signed = signedPartList,
Constructors = constructorList
};
compoundBeaconList.Add(exampleCompoundBeacon);
```
**ビーコンバージョン定義**
次の例では、ビーコンバージョンで暗号化および署名されたパートリストをグローバルに定義します。ビーコンバージョンの定義の詳細については、[「ビーコンの使用](using-beacons.md)」を参照してください。
```
var beaconVersions = new List
{
new BeaconVersion
{
StandardBeacons = standardBeaconList,
CompoundBeacons = compoundBeaconList,
EncryptedParts = encryptedPartsList,
SignedParts = signedPartsList,
Version = 1, // MUST be 1
KeyStore = keyStore,
KeySource = new BeaconKeySource
{
Single = new SingleKeyStore
{
KeyId = branchKeyId,
CacheTTL = 6000
}
}
}
};
```
------
#### [ Rust ]
**完全なコードサンプル**[「beacon\$1config.rs」を参照してください。](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/complexexample/beacon_config.rs)
**複合ビーコン設定**
次の例では、複合ビーコン設定内で暗号化および署名されたパートリストをローカルに定義します。
```
let compound_beacon_list = vec」を参照してください。
```
let beacon_versions = BeaconVersion::builder()
.standard_beacons(standard_beacon_list)
.compound_beacons(compound_beacon_list)
.encrypted_parts(encrypted_parts_list)
.signed_parts(signed_parts_list)
.version(1) // MUST be 1
.key_store(key_store.clone())
.key_source(BeaconKeySource::Single(
SingleKeyStore::builder()
.key_id(branch_key_id)
.cache_ttl(6000)
.build()?,
))
.build()?;
let beacon_versions = vec![beacon_versions];
```
------
[暗号化されたパート](#encrypted-parts)と[署名されたパート](#signed-parts)は、ローカルまたはグローバルに定義されたリストで定義できます。可能な限り[、ビーコンバージョンの](using-beacons.md#beacon-version)グローバルリストで暗号化および署名されたパートを定義することをお勧めします。暗号化されたパートと署名されたパートをグローバルに定義することで、各パートを 1 回定義し、そのパートを複数の複合ビーコン設定で再利用できます。暗号化または署名されたパートを 1 回だけ使用する場合は、複合ビーコン設定のローカルリストで定義できます。[コンストラクタリスト](#constructor-parts)では、ローカルパートとグローバルパートの両方を参照できます。
暗号化および署名されたパートリストをグローバルに定義する場合は、複合ビーコンが複合ビーコン設定のフィールドをアセンブルできるすべての方法を識別するコンストラクタパートのリストを指定する必要があります。
**注記**
暗号化および署名されたパートリストをグローバルに定義するには、バージョン 3.2 以降の AWS Database Encryption SDK を使用する必要があります。新しいパートをグローバルに定義する前に、すべてのリーダーに新しいバージョンをデプロイします。
既存のビーコン設定を更新して、暗号化および署名されたパートリストをグローバルに定義することはできません。
複合ビーコンを設定するには、次の値を指定します。
**ビーコン名**
暗号化されたフィールドをクエリする際に使用する名前。
ビーコン名は、暗号化されたフィールドまたは仮想フィールドと同じ名前にすることができますが、暗号化されていないフィールドと同じ名前にすることはできません。2 つのビーコンを同じ名前にすることはできません。実装に最適なビーコン名を決定する方法については、「[ビーコン名の選択](choosing-beacon-name.md)」を参照してください。
**分割文字**
複合ビーコンを設定する部分を分離するために使用される文字。
分割文字は、複合ビーコンの構築元となるフィールドのプレーンテキストの値に出現することはできません。
**暗号化されたパートリスト**
複合ビーコンに含まれる `ENCRYPT_AND_SIGN` フィールドを識別します。
各部分には、名前とプレフィックスが含まれている必要があります。部分の名前は、暗号化されたフィールドから構築された標準ビーコンの名前である必要があります。プレフィックスには任意の文字列を指定できますが、一意である必要があります。暗号化された部分は、署名付きの部分と同じプレフィックスを持つことはできません。複合ビーコンによって提供される部分と他の部分を区別する短い値を使用することをお勧めします。
可能な限り、暗号化されたパートをグローバルに定義することをお勧めします。1 つの複合ビーコンでのみ使用する場合は、暗号化された部分をローカルで定義することを検討してください。ローカルに定義された暗号化されたパートは、グローバルに定義された暗号化されたパートと同じプレフィックスまたは名前を持つことはできません。
```
List encryptedPartList = new ArrayList<>();
EncryptedPart encryptedPartExample = EncryptedPart.builder()
.name("standardBeaconName")
.prefix("E-")
.build();
encryptedPartList.add(encryptedPartExample);
```
```
var encryptedPartList = new List();
var encryptedPartExample = new EncryptedPart
{
Name = "compoundBeaconName",
Prefix = "E-"
};
encryptedPartList.Add(encryptedPartExample);
```
```
let encrypted_parts_list = vec![
EncryptedPart::builder()
.name("standard_beacon_name")
.prefix("E-")
.build()?
];
```
**署名付きパートリスト**
複合ビーコンに含まれる署名付きフィールドを識別します。
署名付きパートはオプションです。署名付きパートを参照しない複合ビーコンを設定できます。
各部分には、名前、ソース、プレフィックスが含まれている必要があります。ソースは、パートが識別する `SIGN_ONLY`または `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`フィールドです。ソースは、フィールド名、またはネストされたフィールドの値を参照するインデックスである必要があります。パーツ名がソースを識別する場合、ソースを省略すると、 AWS Database Encryption SDK は自動的にその名前をソースとして使用します。可能な場合は常に、部分名としてソースを指定することをお勧めします。プレフィックスには任意の文字列を指定できますが、一意である必要があります。署名付きの部分は、暗号化された部分と同じプレフィックスを持つことはできません。複合ビーコンによって提供される部分と他の部分を区別する短い値を使用することをお勧めします。
可能な限り、署名付きパートをグローバルに定義することをお勧めします。署名付きパートを 1 つの複合ビーコンでのみ使用する場合は、ローカルで定義することを検討してください。ローカルに定義された署名付きパートは、グローバルに定義された署名付きパートと同じプレフィックスまたは名前を持つことはできません。
```
List signedPartList = new ArrayList<>();
SignedPart signedPartExample = SignedPart.builder()
.name("signedFieldName")
.prefix("S-")
.build();
signedPartList.add(signedPartExample);
```
```
var signedPartsList = new List
{
new SignedPart { Name = "signedFieldName1", Prefix = "S-" },
new SignedPart { Name = "signedFieldName2", Prefix = "SF-" }
};
```
```
let signed_parts_list = vec![
SignedPart::builder()
.name("signed_field_name_1")
.prefix("S-")
.build()?,
SignedPart::builder()
.name("signed_field_name_2")
.prefix("SF-")
.build()?,
];
```
**コンストラクタリスト**
暗号化および署名付きの部分を複合ビーコンによってアセンブルするさまざまな方法を定義するコンストラクターを識別します。コンストラクタリストでは、ローカルパートとグローバルパートの両方を参照できます。
グローバルに定義された暗号化および署名された部分から複合ビーコンを構築する場合は、コンストラクタリストを指定する必要があります。
グローバルに定義された暗号化または署名されたパートを使用して複合ビーコンを構築しない場合、コンストラクタリストはオプションです。コンストラクタリストを指定しない場合、 AWS Database Encryption SDK は次のデフォルトのコンストラクタを使用して複合ビーコンをアセンブルします。
+ すべての署名付きの部分 (署名付きの部分のリストに追加された順)
+ 暗号化されたすべての部分 (暗号化された部分のリストに追加された順)
+ すべての部分は必須です
**コンストラクタ**
各コンストラクターは、複合ビーコンをアセンブルする 1 つの方法を定義するコンストラクター部分の順序付きリストです。コンストラクター部分はリストに追加された順序で結合され、各部分は指定された分割文字で区切られます。
各コンストラクター部分は、暗号化された部分または署名付きの部分に名前を付け、その部分がコンストラクター内で必須であるか、またはオプションであるかを定義します。例えば、`Field1`、`Field1.Field2`、および `Field1.Field2.Field3` で複合ビーコンをクエリする場合は、`Field2` および `Field3` をオプションとしてマークし、コンストラクターを 1 つ作成します。
各コンストラクターには、少なくとも 1 つの必須部分が必要です。クエリで `BEGINS_WITH` 演算子を使用できるように、各コンストラクターの最初の部分を必須にすることをお勧めします。
コンストラクターは、必要な部分がすべてレコード内に存在する場合に成功します。新しいレコードを書き込む際に、複合ビーコンはコンストラクターのリストを使用して、指定された値からビーコンをアセンブルできるかどうかを判断します。コンストラクターがコンストラクターのリストに追加された順序でビーコンのアセンブルを試み、成功した最初のコンストラクターを使用します。コンストラクターが成功しない場合、ビーコンはレコードに書き込まれません。
すべてのリーダーとライターは、クエリの結果が確実に正しくなるようにコンストラクターの同じ順序を指定する必要があります。
独自のコンストラクターのリストを指定するには、次の手順を使用します。
1. 暗号化部分と署名付きの部分ごとにコンストラクター部分を作成し、その部分が必須かどうかを定義します。
コンストラクター部分の名前は、標準ビーコンの名前、またはそれが表す署名されたフィールドの名前である必要があります。
------
#### [ Java ]
```
ConstructorPart field1ConstructorPart = ConstructorPart.builder()
.name("Field1")
.required(true)
.build();
```
------
#### [ C\$1 / .NET ]
```
var field1ConstructorPart = new ConstructorPart { Name = "Field1", Required = true };
```
------
#### [ Rust ]
```
let field_1_constructor_part = ConstructorPart::builder()
.name("field_1")
.required(true)
.build()?;
```
------
1. **ステップ 1** で作成したコンストラクター部分を使用して、複合ビーコンをアセンブルする可能な方法ごとにコンストラクターを作成します。
例えば、`Field1.Field2.Field3` と `Field4.Field2.Field3` をクエリする場合は、2 つのコンストラクターを作成する必要があります。`Field1` と `Field4` は、2 つの別個のコンストラクターで定義されているため、両方とも必須にすることができます。
------
#### [ Java ]
```
// Create a list for Field1.Field2.Field3 queries
List field123ConstructorPartList = new ArrayList<>();
field123ConstructorPartList.add(field1ConstructorPart);
field123ConstructorPartList.add(field2ConstructorPart);
field123ConstructorPartList.add(field3ConstructorPart);
Constructor field123Constructor = Constructor.builder()
.parts(field123ConstructorPartList)
.build();
// Create a list for Field4.Field2.Field1 queries
List field421ConstructorPartList = new ArrayList<>();
field421ConstructorPartList.add(field4ConstructorPart);
field421ConstructorPartList.add(field2ConstructorPart);
field421ConstructorPartList.add(field1ConstructorPart);
Constructor field421Constructor = Constructor.builder()
.parts(field421ConstructorPartList)
.build();
```
------
#### [ C\$1 / .NET ]
```
// Create a list for Field1.Field2.Field3 queries
var field123ConstructorPartList = new Constructor
{
Parts = new List { field1ConstructorPart, field2ConstructorPart, field3ConstructorPart }
};
// Create a list for Field4.Field2.Field1 queries
var field421ConstructorPartList = new Constructor
{
Parts = new List { field4ConstructorPart, field2ConstructorPart, field1ConstructorPart }
};
```
------
#### [ Rust ]
```
// Create a list for field1.field2.field3 queries
let field1_field2_field3_constructor = Constructor::builder()
.parts(vec![
field1_constructor_part,
field2_constroctor_part.clone(),
field3_constructor_part,
])
.build()?;
// Create a list for field4.field2.field1 queries
let field4_field2_field1_constructor = Constructor::builder()
.parts(vec![
field4_constructor_part,
field2_constroctor_part.clone(),
field1_constructor_part,
])
.build()?;
```
------
1. **ステップ 2** で作成したすべてのコンストラクターを含むコンストラクターのリストを作成します。
------
#### [ Java ]
```
List constructorList = new ArrayList<>();
constructorList.add(field123Constructor);
constructorList.add(field421Constructor);
```
------
#### [ C\$1 / .NET ]
```
var constructorList = new List
{
field123Constructor,
field421Constructor
};
```
------
#### [ Rust ]
```
let constructor_list = vec![
field1_field2_field3_constructor,
field4_field2_field1_constructor,
];
```
------
1. 複合ビーコンを作成する`constructorList`ときに を指定します。
# 設定例
****
| |
| --- |
| クライアント側の暗号化ライブラリの名前が AWS Database Encryption SDK に変更されました。このデベロッパーガイドでは、引き続き [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md) に関する情報を提供します。 |
次の例は、標準ビーコンと複合ビーコンを設定する方法を示しています。次の設定は、ビーコンの長さを指定しません。設定用に適切なビーコンの長さを決定する方法については、「[ビーコンの長さを選択する](choosing-beacon-length.md)」を参照してください。
ビーコンの設定方法と使用方法を示す完全なコード例については、GitHub の aws-database-encryption-sdk-dynamodb リポジトリにある [Java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption)、[.NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/)、および [Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/) の検索可能な暗号化の例を参照してください。
**Topics**
+ [標準ビーコン](#standard-config-examples)
+ [複合ビーコン](#compound-config-examples)
## 標準ビーコン
完全一致を検索するために `inspector_id_last4` フィールドをクエリする場合は、次の設定を使用して標準ビーコンを作成します。
------
#### [ Java ]
```
List standardBeaconList = new ArrayList<>();
StandardBeacon exampleStandardBeacon = StandardBeacon.builder()
.name("inspector_id_last4")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(exampleStandardBeacon);
```
------
#### [ C\$1 / .NET ]
```
var standardBeaconList = new List>);
StandardBeacon exampleStandardBeacon = new StandardBeacon
{
Name = "inspector_id_last4",
Length = 10
};
standardBeaconList.Add(exampleStandardBeacon);
```
------
#### [ Rust ]
```
let last4_beacon = StandardBeacon::builder()
.name("inspector_id_last4")
.length(10)
.build()?;
let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;
let standard_beacon_list = vec![last4_beacon, unit_beacon];
```
------
## 複合ビーコン
`inspector_id_last4` および `inspector_id_last4.unit` で `UnitInspection` データベースをクエリする場合は、次の設定で複合ビーコンを作成します。この複合ビーコンには[暗号化された部分](configure-beacons.md#encrypted-parts)のみが必要です。
------
#### [ Java ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
List standardBeaconList = new ArrayList<>();
StandardBeacon inspectorBeacon = StandardBeacon.builder()
.name("inspector_id_last4")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(inspectorBeacon);
StandardBeacon unitBeacon = StandardBeacon.builder()
.name("unit")
.length(beaconLengthInBits)
.build();
standardBeaconList.add(unitBeacon);
// 2. Define the encrypted parts.
List encryptedPartList = new ArrayList<>();
// Each encrypted part needs a name and prefix
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
EncryptedPart encryptedPartInspector = EncryptedPart.builder()
.name("inspector_id_last4")
.prefix("I-")
.build();
encryptedPartList.add(encryptedPartInspector);
EncryptedPart encryptedPartUnit = EncryptedPart.builder()
.name("unit")
.prefix("U-")
.build();
encryptedPartList.add(encryptedPartUnit);
// 3. Create the compound beacon.
// This compound beacon only requires a name, split character,
// and list of encrypted parts
CompoundBeacon inspectorUnitBeacon = CompoundBeacon.builder()
.name("inspectorUnitBeacon")
.split(".")
.sensitive(encryptedPartList)
.build();
```
------
#### [ C\$1 / .NET ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
StandardBeacon inspectorBeacon = new StandardBeacon
{
Name = "inspector_id_last4",
Length = 10
};
standardBeaconList.Add(inspectorBeacon);
StandardBeacon unitBeacon = new StandardBeacon
{
Name = "unit",
Length = 30
};
standardBeaconList.Add(unitBeacon);
// 2. Define the encrypted parts.
var last4EncryptedPart = new EncryptedPart
// Each encrypted part needs a name and prefix
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
var last4EncryptedPart = new EncryptedPart
{
Name = "inspector_id_last4",
Prefix = "I-"
};
encryptedPartList.Add(last4EncryptedPart);
var unitEncryptedPart = new EncryptedPart
{
Name = "unit",
Prefix = "U-"
};
encryptedPartList.Add(unitEncryptedPart);
// 3. Create the compound beacon.
// This compound beacon only requires a name, split character,
// and list of encrypted parts
var compoundBeaconList = new List>);
var inspectorCompoundBeacon = new CompoundBeacon
{
Name = "inspector_id_last4",
Split = ".",
Encrypted = encryptedPartList
};
compoundBeaconList.Add(inspectorCompoundBeacon);
```
------
#### [ Rust ]
```
// 1. Create standard beacons for the inspector_id_last4 and unit fields.
let last4_beacon = StandardBeacon::builder()
.name("inspector_id_last4")
.length(10)
.build()?;
let unit_beacon = StandardBeacon::builder().name("unit").length(30).build()?;
let standard_beacon_list = vec![last4_beacon, unit_beacon];
// 2. Define the encrypted parts.
// The name must be the name of the standard beacon
// The prefix must be unique
// For this example we use the prefix "I-" for "inspector_id_last4"
// and "U-" for "unit"
let encrypted_parts_list = vec![
EncryptedPart::builder()
.name("inspector_id_last4")
.prefix("I-")
.build()?,
EncryptedPart::builder().name("unit").prefix("U-").build()?,
];
// 3. Create the compound beacon
// This compound beacon only requires a name, split character,
// and list of encrypted parts
let compound_beacon_list = vec![CompoundBeacon::builder()
.name("last4UnitCompound")
.split(".")
.encrypted(encrypted_parts_list)
.build()?];
```
------