本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用信标
****
| |
| --- |
| 我们的客户端加密库已重命名为 AWS 数据库加密 SDK。本开发人员指南仍提供有关 [DynamoDB 加密客户端](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 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
{
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 数据库加密 SDK 客户端**
要配置保护您的 DynamoDB 表中的表项目的 AWS 数据库加密 SDK 客户端，[请参阅 DynamoDB 的 Java 客户端加密](ddb-java.md)库。
## 查询信标
您配置的信标类型决定了您能够执行的查询类型。标准信标使用筛选条件表达式来执行相等搜索。复合信标则组合文字明文字符串和标准信标来执行复杂的查询。查询加密的数据时，您可以搜索信标名称。
您无法比较两个标准信标的值，即使其中包含相同的底层明文。两个标准信标将为相同的明文值生成两个不同的 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)的前缀附加到一个或多个签名部分中，但不能在任何查询中包括加密字段的值。
例如，您可以比较已签名的部分并对 `signedField1 = signedField2` 或 `value IN (signedField1, signedField2, ...)` 进行查询。
您还可以通过查询 `signedField1.A_ = signedField2.B_` 来比较已签名部分和加密部分的前缀。
+ `field BETWEEN a AND b`，其中 `a` 和 `b` 是签名部分。您可以选择将加密部分的前缀附加到一个或多个签名部分中，但不能在任何查询中包括加密字段的值。
您必须为对复合信标的查询中包含的每个部分添加前缀。例如，如果您从两个字段 `encryptedField` 和 `signedField` 构造了一个复合信标 `compoundBeacon`，则在查询信标时必须包含为这两个部分配置的前缀。
```
compoundBeacon = E_encryptedFieldValue.S_signedFieldValue
```