As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Configurar beacons
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
Há dois tipos de beacons que oferecem suporte à criptografia pesquisável. Os beacons padrão realizam pesquisas de igualdade. Eles são a maneira mais simples de implementar criptografia pesquisável em seu banco de dados. Os beacons compostos combinam cadeias de texto simples literais e beacons padrão para realizar consultas mais complexas.
Os beacons são projetados para serem implementados em bancos de dados novos e vazios. Qualquer beacon configurado em um banco de dados existente mapeará somente novos registros gravados no banco de dados. Os beacons são calculados a partir do valor de texto simples de um campo, uma vez que o campo é criptografado, não há como o beacon mapear os dados existentes. Depois de gravar novos registros com o beacon, não será possível atualizar a configuração do beacon. No entanto, é possível adicionar novos beacons aos novos campos que você adiciona ao seu registro.
Depois de determinar seus padrões de acesso, a configuração dos beacons deve ser a segunda etapa na implementação do banco de dados. Depois de configurar todos os seus beacons, você precisa criar um [chaveiro AWS KMS hierárquico](use-hierarchical-keyring.md), definir a versão do beacon, configurar um [índice secundário para cada beacon, definir suas [ações criptográficas](concepts.md#crypt-actions) e configurar](ddb-searchable-encryption.md#ddb-beacon-indexes) seu banco de dados e o cliente Database Encryption SDK. AWS Para ter mais informações, consulte [Usar beacons](using-beacons.md).
Para facilitar a definição da versão do beacon, recomendamos criar listas para beacons padrão e compostos. Adicione cada beacon que você criar à respectiva lista de beacons padrão ou compostos à medida que você os configura.
**Topics**
+ [Configurando beacons padrão](#config-standard-beacons)
+ [Configuração de beacons compostos](#config-compound-beacons)
+ [Exemplos de configuração](beacon-config-examples.md)
## Configurando beacons padrão
Os [beacons padrão](beacons.md#standard-beacon-overview) são a maneira mais simples de implementar criptografia pesquisável em seu banco de dados. Eles só podem realizar pesquisas de igualdade para um único campo criptografado ou virtual.
### Sintaxe de exemplo de configuração
------
#### [ 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 a partir do qual seu beacon padrão é construído sempre que possível. Dois beacons diferentes não podem ter o mesmo nome de beacon. Para obter ajuda para determinar o melhor nome de beacon para sua implementação, consulte [Escolher um nome de beacon](choosing-beacon-name.md).
**Comprimento do beacon**
O número de bits do valor de hash do beacon que são mantidos após o truncamento.
O comprimento do beacon determina o número médio de falsos positivos produzidos por um determinado beacon. Para obter mais informações e ajudar a determinar o comprimento adequado do beacon para sua implementação, consulte [Determinar o comprimento do beacon](choosing-beacon-length.md).
**Fonte do beacon (opcional)**
O campo a partir do qual um beacon padrão é construído.
A fonte do beacon deve ser um nome de campo ou um índice referente ao valor de um campo aninhado. Quando o nome do beacon é o mesmo da fonte do beacon, você pode omitir a fonte do beacon da sua configuração e o SDK do AWS Database Encryption usará automaticamente o nome do beacon como fonte do beacon.
### Criação de um campo virtual
Para criar um [campo virtual](beacons.md#virtual-field), você deve fornecer um nome para o campo virtual e uma lista dos campos de origem. A ordem em que você adiciona campos de origem à lista de partes virtuais determina a ordem em que eles são concatenados para criar o campo virtual. O exemplo a seguir concatena dois campos de origem em sua totalidade para criar um campo virtual.
**nota**
Recomendamos verificar se seus campos virtuais produzem o resultado esperado antes de preencher seu banco de dados. Para obter mais informações, consulte [Teste de saídas de beacon](ddb-searchable-encryption.md#ddb-beacon-testing).
------
#### [ Java ]
**Veja o exemplo de código completo**: [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 ]
**Veja o exemplo de código completo**: [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 ]
**Veja o exemplo de código completo**: [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];
```
------
Para criar um campo virtual com um segmento específico de um campo de origem, você deve definir essa transformação antes de adicionar o campo de origem à sua lista de partes virtuais.
#### Considerações de segurança para campos virtuais
Os beacons não alteram o estado criptografado do campo. No entanto, quando você usa beacons, há uma compensação inerente entre a eficiência de suas consultas e a quantidade de informações reveladas sobre a distribuição dos dados. A forma como você configura seu beacon determina o nível de segurança que é preservado por esse beacon.
Evite criar um campo virtual com campos de origem que se sobreponham aos beacons padrão existentes. A criação de campos virtuais que incluam um campo de origem que já tenha sido usado para criar um beacon padrão pode reduzir o nível de segurança de ambos os beacons. A extensão da redução da segurança depende do nível de entropia adicionado pelos campos de origem adicionais. O nível de entropia é determinado pela distribuição de valores exclusivos no campo de origem adicional e pelo número de bits que o campo de origem adicional contribui para o tamanho geral do campo virtual.
É possível usar a população e o [comprimento do beacon](choosing-beacon-length.md) para determinar se os campos de origem de um campo virtual preservam a segurança do seu conjunto de dados. A população é o número esperado de valores exclusivos em um campo. A sua população não precisa ser precisa. Para obter ajuda para estimar a população de um campo, consulte [Estimar a população](choosing-beacon-length.md#estimate-population).
Considere o exemplo a seguir ao analisar a segurança de seus campos virtuais.
+ Beacon1 é construído a partir de `FieldA`. `FieldA` tem uma população maior que **2 (comprimento do Beacon1)**.
+ Beacon2 é construído a partir de `VirtualField`, que é construído a partir de `FieldA`, `FieldB`, `FieldC` e `FieldD`. Juntos, `FieldB`, `FieldC` e `FieldD` têm uma população maior que **2N**
O Beacon2 preserva a segurança do Beacon1 e do Beacon2 se as seguintes afirmações forem verdadeiras:
```
N ≥ (Beacon1 length)/2
```
and
```
N ≥ (Beacon2 length)/2
```
### Definindo estilos de farol
Os beacons padrão podem ser usados para realizar pesquisas de igualdade para um campo criptografado ou virtual. Ou, eles podem ser usados para construir beacons compostos para realizar operações de banco de dados mais complexas. Para ajudá-lo a organizar e gerenciar beacons padrão, o SDK de criptografia de AWS banco de dados fornece os seguintes *estilos de beacon* opcionais que definem o uso pretendido de um beacon padrão.
**nota**
Para definir estilos de beacon, você deve usar a versão 3.2 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão em todos os leitores antes de adicionar estilos de beacon às suas configurações de beacon.
------
#### [ PartOnly ]
Um farol padrão definido como só `PartOnly` pode ser usado para definir uma [parte criptografada](#encrypted-parts) de um farol composto. Você não pode consultar diretamente um `PartOnly` farol padrão.
**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 ]
Por padrão, cada farol padrão gera uma chave HMAC exclusiva para o cálculo do farol. Como resultado, você não pode realizar uma pesquisa de igualdade nos campos criptografados a partir de dois beacons padrão separados. Um farol padrão definido como `Shared` usa a chave HMAC de outro farol padrão para seus cálculos.
Por exemplo, se você precisar comparar `beacon1` campos com `beacon2` campos, defina `beacon2` como um `Shared` farol que usa a chave HMAC de `beacon1` para seus cálculos.
**nota**
Considere suas necessidades de segurança e desempenho antes de configurar qualquer `Shared` beacon. `Shared`os beacons podem aumentar a quantidade de informações estatísticas que podem ser identificadas sobre a distribuição do seu conjunto de dados. Por exemplo, eles podem revelar quais campos compartilhados contêm o mesmo valor em texto simples.
**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 ]
Por padrão, se o valor de um campo for um conjunto, o SDK do AWS Database Encryption calcula um único beacon padrão para o conjunto. Como resultado, você não pode realizar a consulta `CONTAINS(a, :value)` onde `a` está um campo criptografado. Um farol padrão definido como `AsSet` calcula valores individuais de farol padrão para cada elemento individual do conjunto e armazena o valor do farol no item como um conjunto. Isso permite que o SDK AWS de criptografia de banco de dados realize a consulta`CONTAINS(a, :value)`.
Para definir um farol `AsSet` padrão, os elementos no conjunto devem ser da mesma população para que todos possam usar o mesmo comprimento de [farol](choosing-beacon-length.md). O conjunto de faróis pode ter menos elementos do que o conjunto de texto simples se houver colisões ao calcular os valores dos faróis.
**nota**
Considere suas necessidades de segurança e desempenho antes de configurar qualquer `AsSet` beacon. `AsSet`os beacons podem aumentar a quantidade de informações estatísticas que podem ser identificadas sobre a distribuição do seu conjunto de dados. Por exemplo, eles podem revelar o tamanho do conjunto de texto simples.
**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 ]
Um farol padrão definido como `SharedSet` combina as `AsSet` funções `Shared` e para que você possa realizar pesquisas de igualdade nos valores criptografados de um conjunto e campo. Isso permite que o SDK AWS de criptografia de banco de dados realize a consulta `CONTAINS(a, b)` onde `a` está um conjunto criptografado e `b` um campo criptografado.
**nota**
Considere suas necessidades de segurança e desempenho antes de configurar qualquer `Shared` beacon. `SharedSet`os beacons podem aumentar a quantidade de informações estatísticas que podem ser identificadas sobre a distribuição do seu conjunto de dados. Por exemplo, eles podem revelar o tamanho do conjunto de texto sem formatação ou quais campos compartilhados contêm o mesmo valor em texto sem formatação.
**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()?
```
------
## Configuração de beacons compostos
Os beacons compostos para combinar cadeias de texto simples literais e beacons padrão para realizar operações de banco de dados complexas, como consultar dois tipos de registro diferentes de um único índice ou consultar uma combinação de campos com uma chave de classificação. Faróis compostos podem ser construídos a partir de`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, e `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campos. Você deve criar um beacon padrão para cada campo criptografado incluído no beacon composto.
**nota**
Recomendamos verificar se seus beacons compostos produzem o resultado esperado antes de preencher seu banco de dados. Para obter mais informações, consulte [Teste de saídas de beacon](ddb-searchable-encryption.md#ddb-beacon-testing).
### Sintaxe de exemplo de configuração
------
#### [ Java ]
**Configuração de farol composto**
O exemplo a seguir define listas de peças criptografadas e assinadas localmente na configuração do beacon composto.
```
List compoundBeaconList = new ArrayList<>();
CompoundBeacon exampleCompoundBeacon = CompoundBeacon.builder()
.name("compoundBeaconName")
.split(".")
.encrypted(encryptedPartList)
.signed(signedPartList)
.constructors(constructorList)
.build();
compoundBeaconList.add(exampleCompoundBeacon);
```
**Definição da versão do Beacon**
O exemplo a seguir define listas de peças criptografadas e assinadas globalmente na versão beacon. Para obter mais informações sobre como definir a versão do beacon, consulte [Usando](using-beacons.md) beacons.
```
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 ]
**Veja o exemplo de código completo**: [BeaconConfig.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/complexexample/BeaconConfig.cs)
**Configuração de farol composto**
O exemplo a seguir define listas de peças criptografadas e assinadas localmente na configuração do beacon composto.
```
var compoundBeaconList = new List();
var exampleCompoundBeacon = new CompoundBeacon
{
Name = "compoundBeaconName",
Split = ".",
Encrypted = encryptedPartList,
Signed = signedPartList,
Constructors = constructorList
};
compoundBeaconList.Add(exampleCompoundBeacon);
```
**Definição da versão do Beacon**
O exemplo a seguir define listas de peças criptografadas e assinadas globalmente na versão beacon. Para obter mais informações sobre como definir a versão do beacon, consulte [Usando](using-beacons.md) beacons.
```
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 ]
**Veja o exemplo de código completo**: [beacon\$1config.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/complexexample/beacon_config.rs)
**Configuração de farol composto**
O exemplo a seguir define listas de peças criptografadas e assinadas localmente na configuração do beacon composto.
```
let compound_beacon_list = vec beacons.
```
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];
```
------
Você pode definir suas [partes criptografadas](#encrypted-parts) e [assinadas](#signed-parts) em listas definidas local ou globalmente. Recomendamos definir suas partes criptografadas e assinadas em uma lista global na [versão do beacon](using-beacons.md#beacon-version) sempre que possível. Ao definir peças criptografadas e assinadas globalmente, você pode definir cada peça uma vez e depois reutilizá-las em várias configurações de faróis compostos. Se você pretende usar uma peça criptografada ou assinada apenas uma vez, você pode defini-la em uma lista local na configuração do beacon composto. Você pode referenciar partes locais e globais na sua [lista de construtores](#constructor-parts).
Se você definir suas listas de peças criptografadas e assinadas globalmente, deverá fornecer uma lista de peças do construtor que identifique todas as formas possíveis pelas quais o farol composto pode montar os campos em sua configuração de farol composto.
**nota**
Para definir listas de peças criptografadas e assinadas globalmente, você deve usar a versão 3.2 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de definir qualquer nova parte globalmente.
Você não pode atualizar as configurações de beacon existentes para definir listas de peças criptografadas e assinadas globalmente.
Para configurar um beacon composto, forneça os valores a seguir.
**Nome do beacon**
O nome que você usa ao consultar um campo criptografado.
O nome de um beacon pode ter o mesmo nome de um campo criptografado ou campo virtual, mas não pode ser igual ao nome de um campo não criptografado. Beacons diferentes não podem ter o mesmo nome. Para obter ajuda para determinar o melhor nome de beacon para sua implementação, consulte [Escolher um nome de beacon](choosing-beacon-name.md).
**Dividir caractere**
O personagem usado para separar as partes que compõem seu beacon composto.
O caractere dividido não pode aparecer nos valores de texto simples de nenhum dos campos a partir dos quais o beacon composto foi construído.
**Lista de peças criptografadas**
Identifica os campos `ENCRYPT_AND_SIGN` incluídos no beacon composto.
Cada parte deve incluir um nome e um prefixo. O nome da parte deve ser o nome do beacon padrão construído a partir do campo criptografado. O prefixo pode ser qualquer string, mas deve ser exclusivo. Uma parte criptografada não pode ter o mesmo prefixo de uma parte assinada. Recomendamos usar um valor curto que diferencie a parte de outras partes atendidas pelo beacon composto.
Recomendamos definir suas partes criptografadas globalmente sempre que possível. Você pode considerar definir uma parte criptografada localmente se pretende usá-la apenas em um farol composto. Uma peça criptografada definida localmente não pode ter o mesmo prefixo ou nome de uma peça criptografada definida globalmente.
```
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()?
];
```
**Lista de peças assinadas**
Identifica os campos assinados incluídos no farol composto.
As peças assinadas são opcionais. Você pode configurar um farol composto que não faça referência a nenhuma peça assinada.
Cada parte deve incluir um nome, uma fonte e um prefixo. A fonte é o `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campo `SIGN_ONLY` ou que a peça identifica. A fonte deve ser um nome de campo ou um índice referente ao valor de um campo aninhado. Se o nome da peça identificar a fonte, você poderá omitir a fonte e o SDK do AWS Database Encryption usará automaticamente o nome como fonte. Recomendamos especificar a fonte como nome da parte sempre que possível. O prefixo pode ser qualquer string, mas deve ser exclusivo. Uma parte criptografada assinada não pode ter o mesmo prefixo de uma parte criptografada. Recomendamos usar um valor curto que diferencie a parte de outras partes atendidas pelo beacon composto.
Recomendamos definir suas peças assinadas globalmente sempre que possível. Você pode considerar definir uma peça assinada localmente se pretende usá-la apenas em um farol composto. Uma peça assinada definida localmente não pode ter o mesmo prefixo ou nome de uma peça assinada definida globalmente.
```
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()?,
];
```
**Lista de construtores**
Identifica os *construtores* que definem as diferentes maneiras pelas quais as partes criptografadas e assinadas podem ser montadas pelo beacon composto. Você pode referenciar partes locais e globais na sua lista de construtores.
Se você construir seu farol composto a partir de partes criptografadas e assinadas globalmente definidas, deverá fornecer uma lista de construtores.
Se você não usar nenhuma peça criptografada ou assinada globalmente definida para construir seu farol composto, a lista de construtores é opcional. Se você não especificar uma lista de construtores, o SDK do AWS Database Encryption monta o beacon composto com o construtor padrão a seguir.
+ Todas as partes assinadas na ordem em que foram adicionadas à lista de partes assinadas
+ Todas as partes criptografadas na ordem em que foram adicionadas à lista de partes criptografadas
+ Todas as partes são obrigatórias
**Construtores**
Cada construtor é uma lista ordenada de *partes do construtor* que define uma maneira pela qual o beacon composto pode ser montado. As partes do construtor são unidas na ordem em que são adicionadas à lista, com cada parte separada pelo caractere de divisão especificado.
Cada parte do construtor nomeia uma parte criptografada ou assinada e define se essa parte é obrigatória ou opcional dentro do construtor. Por exemplo, se você quiser consultar um beacon composto em `Field1`, `Field1.Field2` e `Field1.Field2.Field3`, marque `Field2` e `Field3` como opcional e crie um construtor.
Cada construtor deve ter pelo menos uma parte obrigatória. Recomendamos tornar obrigatória a primeira parte de cada construtor para que você possa usar o operador `BEGINS_WITH` nas consultas.
Um construtor será bem-sucedido se todas as partes obrigatórias estiverem presentes no registro. Quando você grava um novo registro, o beacon composto usa a lista de construtores para determinar se o beacon pode ser montado a partir dos valores fornecidos. Ele tenta montar o beacon na ordem em que os construtores foram adicionados à lista de construtores e usa o primeiro construtor bem-sucedido. Se nenhum construtor for bem-sucedido, o beacon não será gravado no registro.
Todos os leitores e gravadores devem especificar a mesma ordem de construtores para garantir que os resultados da consulta estejam corretos.
Use o procedimento a seguir para especificar sua própria lista de construtores.
1. Crie uma parte construtora para cada parte criptografada e assinada para definir se essa parte é necessária ou não.
O nome da parte do construtor deve ser o nome do beacon padrão ou do campo assinado que ele representa.
------
#### [ 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. Crie um construtor para cada forma possível de montar o beacon composto usando as partes do construtor que você criou na **Etapa 1**.
Por exemplo, se quiser consultar `Field1.Field2.Field3` e`Field4.Field2.Field3`, você deverá criar dois construtores. `Field1` e `Field4` podem ser obrigatórios porque foram definidos em dois construtores separados.
------
#### [ 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. Crie uma lista de construtores que inclua todos os construtores que você criou na **Etapa 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. Especifique `constructorList` quando você cria seu farol composto.
# Exemplos de configuração
****
| |
| --- |
| Nossa biblioteca de criptografia do lado do cliente foi renomeada para SDK de criptografia de AWS banco de dados. Este guia do desenvolvedor ainda fornece informações sobre o [DynamoDB Encryption Client](legacy-dynamodb-encryption-client.md). |
Os exemplos a seguir demonstram como configurar beacons padrão e compostos. As configurações a seguir não fornecem comprimentos de beacon. Para obter ajuda na determinação do comprimento adequado do beacon para sua configuração, consulte [Escolher um comprimento do beacon](choosing-beacon-length.md).
Para ver exemplos completos de código que demonstram como configurar e usar beacons, consulte os exemplos de criptografia pesquisável em [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/) e [Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/) no repositório -dynamodb em. aws-database-encryption-sdk GitHub
**Topics**
+ [Beacons padrão](#standard-config-examples)
+ [Beacons compostos](#compound-config-examples)
## Beacons padrão
Se você quiser consultar o campo `inspector_id_last4` para obter correspondências exatas, crie um beacon padrão usando a configuração a seguir.
------
#### [ 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];
```
------
## Beacons compostos
Se você quiser consultar o banco de dados `UnitInspection` em `inspector_id_last4` e `inspector_id_last4.unit`, crie um beacon composto com a configuração a seguir. Este beacon composto requer apenas [partes criptografadas](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()?];
```
------