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á. # Criptografia pesquisável **** | | | --- | | 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). | A criptografia pesquisável permite pesquisar registros criptografados sem descriptografar todo o banco de dados. Isso é feito usando *beacons*, que criam um mapa entre o valor de texto simples gravado em um campo e o valor criptografado que está realmente armazenado em seu banco de dados. O SDK AWS de criptografia de banco de dados armazena o beacon em um novo campo que ele adiciona ao registro. Dependendo do tipo de beacon que você usa, você pode realizar pesquisas de correspondência exata ou consultas complexas mais personalizadas em seus dados criptografados. **nota** [A criptografia pesquisável no SDK AWS de criptografia de banco de dados difere da criptografia simétrica pesquisável definida em pesquisas acadêmicas, como a criptografia simétrica pesquisável.](https://dl.acm.org/doi/10.1145/1180405.1180417) Um beacon é uma tag truncada do código de autenticação de mensagens por hash (HMAC) que cria um mapa entre o texto simples e os valores criptografados de um campo. Quando você grava um novo valor em um campo criptografado configurado para criptografia pesquisável, o SDK de criptografia de AWS banco de dados calcula um HMAC sobre o valor de texto sem formatação. Essa saída de HMAC é uma correspondência de um para um (1:1) para o valor de texto sem formatação desse campo. A saída de HMAC é truncada para que vários valores de texto simples distintos sejam mapeados para a mesma etiqueta de HMAC truncada. Esses falsos positivos limitam a capacidade de um usuário não autorizado de identificar informações diferenciadas sobre o valor do texto sem formatação. Quando você consulta um beacon, o SDK de criptografia de banco de dados da AWS filtra automaticamente esses falsos positivos e retorna o resultado da sua consulta em texto simples. O número médio de falsos positivos gerados para cada beacon é determinado pelo comprimento do beacon restante após o truncamento. Para obter ajuda na determinação do comprimento adequado do beacon para sua implementação, consulte [Determinação do comprimento do beacon](choosing-beacon-length.md). **nota** A criptografia pesquisável foi projetada para ser implementada em bancos de dados novos e não preenchidos. Qualquer beacon configurado em um banco de dados existente mapeará somente os novos registros enviados para o banco de dados, não há como um beacon mapear os dados existentes. **Tópicos** + [Os beacons são adequados para meu conjunto de dados?](#are-beacons-right-for-me) + [Cenário de criptografia pesquisável](#beacon-overview-example) ## Os beacons são adequados para meu conjunto de dados? Usar beacons para realizar consultas de dados criptografados reduz o desempenho de custos associados aos banco de dados de criptografia do lado do cliente. 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. O beacon não altera o estado criptografado do campo. Quando você criptografa e assina um campo com o SDK AWS de criptografia de banco de dados, o valor em texto simples do campo nunca é exposto ao banco de dados. O banco de dados armazena o valor aleatório e criptografado do campo. Os beacons são armazenados junto com os campos criptografados a partir dos quais são calculados. Isso significa que, mesmo que um usuário não autorizado não consiga visualizar os valores de texto simples de um campo criptografado, ele poderá realizar análises estatísticas nos beacons para saber mais sobre a distribuição do seu conjunto de dados e, em casos extremos, identificar os valores de texto simples para os quais um beacon mapeia. A maneira como você configura seus beacons pode mitigar esses riscos. Em particular, [escolher o comprimento correto do beacon](choosing-beacon-length.md) pode ajudá-lo a preservar a confidencialidade do seu conjunto de dados. **Segurança versus desempenho** + Quanto menor o comprimento do beacon, mais segurança é preservada. + Quanto maior o comprimento do beacon, mais desempenho é preservado. A criptografia pesquisável pode não ser capaz de fornecer os níveis desejados de desempenho e segurança para todos os conjuntos de dados. Analise seu modelo de ameaça, requisitos de segurança e necessidades de desempenho antes de configurar qualquer beacon. Considere os seguintes requisitos de exclusividade do conjunto de dados ao determinar se a criptografia pesquisável é adequada para seu conjunto de dados. **Distribuição** A quantidade de segurança preservada por um beacon depende da distribuição do seu conjunto de dados. Quando você configura um campo criptografado para criptografia pesquisável, o SDK AWS de criptografia de banco de dados calcula um HMAC sobre os valores de texto simples gravados nesse campo. Todos os beacons calculados para um determinado campo são calculados usando a mesma chave, com exceção dos bancos de dados multilocatários que usam uma chave distinta para cada locatário. Isso significa que, se o mesmo valor de texto simples for gravado no campo várias vezes, a mesma tag HMAC será criada para cada instância desse valor de texto sem formatação. Você deve evitar construir beacons a partir de campos que contenham valores muito comuns. Por exemplo, considere um banco de dados que armazena o endereço de cada residente do estado de Illinois. Se você construir um beacon a partir do `City` campo criptografado, o beacon calculado sobre "Chicago" estará sobre-representado devido à grande porcentagem da população de Illinois que vive em Chicago. Mesmo que um usuário não autorizado possa ler apenas os valores criptografados e os valores do beacon, ele poderá identificar quais registros contêm dados para residentes de Chicago se o beacon preservar essa distribuição. Para minimizar a quantidade de informações distintivas reveladas sobre sua distribuição, você deve truncar suficientemente o beacon. O comprimento do beacon necessário para ocultar essa distribuição desigual tem custos de desempenho significativos que podem não atender às necessidades do seu aplicativo. Você deve analisar cuidadosamente a distribuição do seu conjunto de dados para determinar o quanto seus beacons precisam ser truncados. O comprimento do beacon restante após o truncamento se correlaciona diretamente com a quantidade de informações estatísticas que podem ser identificadas sobre sua distribuição. Talvez seja necessário escolher comprimentos de beacon mais curtos para minimizar suficientemente a quantidade de informações distintivas reveladas sobre seu conjunto de dados. Em casos extremos, você não pode calcular o comprimento do beacon para um conjunto de dados distribuído de forma desigual que equilibre efetivamente o desempenho e a segurança. Por exemplo, você não deve construir um beacon a partir de um campo que armazena o resultado de um exame médico para uma doença rara. Como se espera que os resultados de `NEGATIVE` sejam significativamente mais prevalentes no conjunto de dados, os resultados de `POSITIVE` podem ser facilmente identificados pela raridade. É muito difícil ocultar a distribuição quando o campo tem apenas dois valores possíveis. Se você usar um comprimento de beacon curto o suficiente para ocultar a distribuição, todos os valores de texto simples serão mapeados para a mesma tag HMAC. Se você usar um comprimento de beacon maior, é óbvio quais beacons são mapeados para valores `POSITIVE` de texto simples. **Correlação** É altamente recomendável que você evite construir beacons distintos a partir de campos com valores correlacionados. Os beacons construídos a partir de campos correlacionados exigem comprimentos de beacon mais curtos para minimizar suficientemente a quantidade de informações reveladas sobre a distribuição de cada conjunto de dados a um usuário não autorizado. Você deve analisar cuidadosamente o seu conjunto de dados, incluindo a sua entropia e distribuição conjunta de valores correlacionados, para determinar o quanto seus beacons precisam ser truncados. Se o comprimento do beacon resultante não atender às suas necessidades de desempenho, os beacons podem não ser adequados para seu conjunto de dados. Por exemplo, você não deve construir dois beacons separados de campos `City` e `ZIPCode` porque o CEP provavelmente estará associado a apenas uma cidade. Normalmente, os falsos positivos gerados por um beacon limitam a capacidade de um usuário não autorizado de identificar informações diferenciadas sobre seu conjunto de dados. Mas a correlação entre os campos `City` e `ZIPCode` significa que um usuário não autorizado pode identificar facilmente quais resultados são falsos positivos e distinguir os diferentes CEPs. Você deve evitar construir beacons a partir de campos que contenham os mesmos valores de texto simples. Por exemplo, você não deve construir um beacon a partir dos campos `mobilePhone` e `preferredPhone`, pois eles provavelmente têm os mesmos valores. Se você criar beacons distintos dos dois campos, o SDK de criptografia AWS de banco de dados criará os beacons para cada campo em chaves diferentes. Isso resulta em duas tags HMAC diferentes para o mesmo valor de texto simples. É improvável que os dois beacons distintos tenham os mesmos falsos positivos e um usuário não autorizado poderá distinguir números de telefone diferentes. Mesmo que seu conjunto de dados contenha campos correlacionados ou tenha uma distribuição desigual, você poderá construir beacons que preservem a confidencialidade do seu conjunto de dados usando beacons menores. No entanto, o comprimento do beacon não garante que cada valor exclusivo em seu conjunto de dados produza vários falsos positivos que minimizem efetivamente a quantidade de informações distintivas reveladas sobre seu conjunto de dados. O comprimento do beacon estima apenas o número médio de falsos positivos produzidos. Quanto mais desigualmente distribuído seu conjunto de dados, menos efetivo é o comprimento do beacon na determinação do número médio de falsos positivos produzidos. Considere cuidadosamente a distribuição dos campos a partir dos quais você constrói os beacons e considere o quanto você precisará truncar o comprimento do beacon para atender aos seus requisitos de segurança. Os tópicos a seguir neste capítulo pressupõem que seus beacons estejam distribuídos uniformemente e não contenham dados correlacionados. ## Cenário de criptografia pesquisável O exemplo a seguir demonstra uma solução de criptografia simples que pode ser pesquisada. No aplicativo, os campos de exemplo usados neste exemplo podem não atender às recomendações de exclusividade de distribuição e correlação para beacons. É possível usar esse exemplo para referência ao ler sobre os conceitos de criptografia pesquisável neste capítulo. Considere um banco de dados chamado `Employees` que monitora os dados dos funcionários de uma empresa. *Cada registro no banco de dados contém campos chamados *EmployeeID *LastName**,, *FirstName*, e Address.* Cada campo no banco de dados `Employees` é identificado pela chave primária `EmployeeID`. Veja a seguir um exemplo de um registro de texto sem formatação no banco de dados. ``` { "EmployeeID": 101, "LastName": "Jones", "FirstName": "Mary", "Address": { "Street": "123 Main", "City": "Anytown", "State": "OH", "ZIPCode": 12345 } } ``` Se você marcou os campos `LastName` e `FirstName` como `ENCRYPT_AND_SIGN` em suas [ações criptográficas](concepts.md#crypt-actions), os valores nesses campos são criptografados localmente antes de serem carregados no banco de dados. Os dados criptografados enviados são totalmente aleatórios, o banco de dados não reconhece esses dados como protegidos. Ele apenas detecta entradas de dados típicas. Isso significa que o registro que está realmente armazenado no banco de dados pode ter a seguinte aparência. ``` { "PersonID": 101, "LastName": "1d76e94a2063578637d51371b363c9682bad926cbd", "FirstName": "21d6d54b0aaabc411e9f9b34b6d53aa4ef3b0a35", "Address": { "Street": "123 Main", "City": "Anytown", "State": "OH", "ZIPCode": 12345 } } ``` Se você precisar consultar o banco de dados para obter correspondências exatas no `LastName` campo, [configure um farol padrão](configure-beacons.md#config-standard-beacons) chamado *LastName*para mapear os valores de texto simples gravados no `LastName` campo para os valores criptografados armazenados no banco de dados. Esse farol calcula a HMACs partir dos valores de texto simples no campo. `LastName` Cada saída HMAC é truncada para que não seja mais uma correspondência exata para o valor do texto sem formatação. Por exemplo, o hash completo e o hash truncado para `Jones` podem ter a seguinte aparência. **Hash completo** `2aa4e9b404c68182562b6ec761fcca5306de527826a69468885e59dc36d0c3f824bdd44cab45526f70a2a18322000264f5451acf75f9f817e2b35099d408c833` **Hash truncado** `b35099d408c833` Depois que o beacon padrão for configurado, você poderá realizar pesquisas de igualdade no campo `LastName`. Por exemplo, se você quiser pesquisar`Jones`, use o *LastName*beacon para realizar a consulta a seguir. ``` LastName = Jones ``` O SDK AWS de criptografia de banco de dados filtra automaticamente os falsos positivos e retorna o resultado em texto simples da sua consulta. # 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). | Um beacon é uma tag truncada do código de autenticação de mensagens por hash (HMAC) que cria um mapa entre o valor de texto simples e os valores criptografados que estão realmente armazenados no banco de dados. O beacon não altera o estado criptografado do campo. O beacon calcula um HMAC sobre o valor de texto simples do campo e o armazena junto com o valor criptografado. Essa saída de HMAC é uma correspondência de um para um (1:1) para o valor de texto sem formatação desse campo. A saída de HMAC é truncada para que vários valores de texto simples distintos sejam mapeados para a mesma etiqueta de HMAC truncada. Esses falsos positivos limitam a capacidade de um usuário não autorizado de identificar informações diferenciadas sobre o valor do texto sem formatação. Os beacons só podem ser construídos a partir de campos `ENCRYPT_AND_SIGN` marcados ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` em suas ações [criptográficas](concepts.md#crypt-actions). `SIGN_ONLY` O beacon em si não está assinado nem criptografado. Você não pode construir um beacon com campos marcados com `DO_NOTHING`. O tipo de beacon que você configura determina o tipo de consultas que você é capaz de realizar. Há dois tipos de beacons que oferecem suporte à criptografia pesquisável. Os *beacons padrão* realizam pesquisas de igualdade. Os *beacons compostos* combinam cadeias de texto simples literais e beacons padrão para realizar operações complexas de banco de dados. Depois de [configurar os beacons](configure-beacons.md), você deve configurar um índice secundário para cada beacon antes de poder pesquisar nos campos criptografados. Para obter mais informações, consulte [Configuração de índices secundários com beacons](ddb-searchable-encryption.md#ddb-beacon-indexes). **Topics** + [ ## Beacons padrão ](#standard-beacon-overview) + [ ## Beacons compostos ](#compound-beacon-overview) ## Beacons padrão Os beacons padrão 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. Para saber mais sobre a configuração de beacons padrão, consulte [Configuração de beacons padrão](configure-beacons.md#config-standard-beacons). O campo a partir do qual um beacon padrão é construído é chamado de *fonte do beacon*. Ele identifica a localização dos dados que o beacon precisa mapear. A fonte do beacon pode ser um campo criptografado ou um *campo virtual*. A fonte do beacon em cada beacon padrão deve ser exclusiva. Você não pode configurar dois beacons com a mesma fonte de beacon. 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. Para obter mais informações, consulte [Definindo estilos de beacon](configure-beacons.md#define-beacon-styles). Você pode criar um farol padrão que realiza pesquisas de igualdade para um único campo criptografado ou pode criar um farol padrão que realiza pesquisas de igualdade na concatenação de vários campos`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, e `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criando um campo virtual. **Campos virtuais** Um campo virtual é um campo conceitual construído a partir de um ou mais campos de origem. A criação de um campo virtual não grava um novo campo em seu registro. O campo virtual não é armazenado explicitamente em seu banco de dados. Ele é usado na configuração de beacon padrão para fornecer instruções ao beacon sobre como identificar um segmento específico de um campo ou concatenar vários campos em um registro para realizar uma consulta específica. Um campo virtual exige pelo menos um campo criptografado. O exemplo a seguir demonstra os tipos de transformações e consultas que você pode realizar com um campo virtual. No aplicativo, os campos de exemplo usados neste exemplo podem não atender às recomendações de exclusividade de [distribuição](searchable-encryption.md#searchable-encryption-distribution) e [correlação](searchable-encryption.md#searchable-encryption-correlated-values) para beacons. Por exemplo, se você quiser realizar pesquisas de igualdade na concatenação dos campos `FirstName` e `LastName`, você pode criar um dos campos virtuais a seguir. + Um campo `NameTag` virtual, construído a partir da primeira letra do campo `FirstName`, seguida pelo campo `LastName`, tudo em minúsculas. Esse campo virtual permite que você consulte `NameTag=mjones`. + Um campo `LastFirst` virtual, que é construído a partir do campo `LastName`, seguido pelo campo `FirstName`. Esse campo virtual permite que você consulte `LastFirst=JonesMary`. Ou, se você quiser realizar pesquisas de igualdade em um segmento específico de um campo criptografado, crie um campo virtual que identifique o segmento que você deseja consultar. Por exemplo, se você quiser consultar um campo `IPAddress` criptografado usando os três primeiros segmentos do endereço IP, crie o seguinte campo virtual. + Um campo `IPSegment` virtual, construído a partir de `Segments(‘.’, 0, 3)`. Esse campo virtual permite que você consulte `IPSegment=192.0.2`. A consulta retorna todos os registros com um valor `IPAddress` que começa com "192.0.2". Os campos virtuais devem ser exclusivos. Dois campos virtuais não podem ser construídos exatamente a partir dos mesmos campos de origem. Para obter ajuda na configuração de campos virtuais e os beacons que os usam, consulte [Criar um campo virtual](configure-beacons.md#create-virtual-field). ## Beacons compostos Os beacons compostos criam índices que melhoram o desempenho das consultas e permitem que você execute operações de banco de dados mais complexas. É possível usar beacons compostos para combinar cadeias de texto simples literais e beacons padrão para realizar consultas complexas em registros criptografados, como consultar dois tipos de registro diferentes de um único índice ou consultar uma combinação de campos com uma chave de classificação. Para obter mais exemplos de soluções de beacon composto, consulte [Escolher um tipo de beacon](choosing-beacon-type.md). Os faróis compostos podem ser construídos a partir de faróis padrão ou uma combinação de faróis padrão e campos assinados. Eles são construídos a partir de uma lista de partes. Todos os beacons compostos devem incluir uma lista de [partes criptografadas](configure-beacons.md#encrypted-parts) que identifique os campos `ENCRYPT_AND_SIGN` incluídos no beacon. Cada campo `ENCRYPT_AND_SIGN` deve ser identificado por um beacon padrão. Os faróis compostos mais complexos também podem incluir uma lista de [partes assinadas](configure-beacons.md#signed-parts) que identificam o texto simples `SIGN_ONLY` ou os `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campos incluídos no farol e uma lista de [partes do construtor](configure-beacons.md#constructor-parts) que identificam todas as maneiras possíveis pelas quais o farol composto pode montar os campos. **nota** O SDK AWS de criptografia de banco de dados também oferece suporte a *beacons assinados* que podem ser configurados inteiramente a partir de texto simples `SIGN_ONLY` e campos. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Os beacons assinados são um tipo de farol composto que indexa e executa consultas complexas em campos assinados, mas não criptografados. Para obter mais informações, consulte [Criação de beacons assinados](configure.md#signed-beacons). Para obter ajuda com a configuração de beacons compostos, consulte [Configurar beacons compostos](configure-beacons.md#config-compound-beacons). O tipo de beacon que você configura determina o beacon composto determina os tipos de consultas que você pode realizar. Por exemplo, você pode tornar algumas partes criptografadas e assinadas opcionais para permitir mais flexibilidade em suas consultas. Para obter mais informações sobre os tipos de consultas que os beacons compostos podem realizar, consulte [Consultar beacons](using-beacons.md#querying-beacons). # Planejar 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). | 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. Para implementar a criptografia pesquisável, você deve usar o [token de autenticação hierárquico do AWS KMS](use-hierarchical-keyring.md) para gerar, criptografar e descriptografar as chaves de dados usadas para proteger seus registros. Para obter mais informações, consulte [Uso do token de autenticação hierárquico para criptografia pesquisável](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings). Antes de configurar [beacons](searchable-encryption.md#beacon-definition) para criptografia pesquisável, você precisa analisar seus requisitos de criptografia, padrões de acesso ao banco de dados e modelo de ameaça para determinar a melhor solução para seu banco de dados. O [tipo de beacon](beacons.md) que você configura determina o tipo de consultas que é possível realizar. O [comprimento do beacon](choosing-beacon-length.md) que você especifica na configuração padrão do beacon determina o número esperado de falsos positivos produzidos para um determinado beacon. É altamente recomendável identificar e planejar os tipos de consultas que você precisa realizar antes de configurar os beacons. Depois de usar um beacon, a configuração não poderá ser atualizada. É altamente recomendável que você revise e conclua as tarefas a seguir antes de configurar qualquer beacon. + [Determine se os beacons são adequados para seu conjunto de dados](searchable-encryption.md#are-beacons-right-for-me) + [Escolha um tipo de beacon](choosing-beacon-type.md) + [Escolher um comprimento de beacon](choosing-beacon-length.md) + [Escolha um nome de beacon](choosing-beacon-name.md) Lembre-se dos requisitos de exclusividade de beacon a seguir ao planejar a solução de criptografia pesquisável para seu banco de dados. + **Cada beacon padrão deve ter uma [fonte de beacon](beacons.md#beacon-source) exclusiva** Vários beacons padrão não podem ser construídos a partir do mesmo campo criptografado ou virtual. No entanto, um único beacon padrão pode ser usado para construir vários beacons compostos. + **Evite criar um campo virtual com campos de origem que se sobreponham aos beacons padrão existentes** Construir um beacon padrão a partir de um campo virtual que contém um campo de origem usado para criar outro beacon padrão pode reduzir a segurança de ambos os beacons. Para obter mais informações, consulte [Considerações de segurança para campos virtuais](configure-beacons.md#virtual-field-considerations). ## Considerações para bancos de dados multilocatários Para consultar beacons configurados em um banco de dados multilocatário, você deve incluir o campo que armazena o `branch-key-id` associado ao locatário que criptografou o registro em sua consulta. Você define esse campo ao [definir a fonte da chave do beacon](use-hierarchical-keyring.md#beacon-key-source). Para que a consulta seja bem-sucedida, o valor nesse campo deve identificar os materiais de chave de beacon apropriados necessários para recalcular o beacon. Antes de configurar seus beacons, você deve decidir como planeja incluir `branch-key-id` em suas consultas. Para obter mais informações sobre as diferentes maneiras de incluir `branch-key-id` em suas consultas, consulte [Consultar beacons em um banco de dados multilocatário](searchable-encryption-multitenant.md#query-multitenant-beacons). # Escolha de um tipo de beacon **** | | | --- | | 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). | Com a criptografia pesquisável, você pode pesquisar registros criptografados mapeando os valores de texto simples em um campo criptografado com *um beacon*. O tipo de beacon que você configura determina o tipo de consultas que você pode realizar. É altamente recomendável identificar e planejar os tipos de consultas que você precisa realizar antes de configurar os beacons. Depois de [configurar os beacons](configure-beacons.md), você deve configurar um índice secundário para cada beacon antes de poder pesquisar nos campos criptografados. Para obter mais informações, consulte [Configuração de índices secundários com beacons](ddb-searchable-encryption.md#ddb-beacon-indexes). Os beacons criam um mapa entre o valor de texto simples gravado em um campo e o valor criptografado que está realmente armazenado em seu banco de dados. Não é possível comparar os valores de dois beacons padrão, mesmo que eles contenham o mesmo texto simples subjacente. Os dois beacons padrão produzirão duas etiquetas de HMAC diferentes para os mesmos valores de texto simples. Como resultado, os beacons padrão não podem realizar as consultas a seguir. + `beacon1 = beacon2` + `beacon1 IN (beacon2)` + `value IN (beacon1, beacon2, ...)` + `CONTAINS(beacon1, beacon2)` Você só pode realizar as consultas acima se comparar as [partes assinadas](configure-beacons.md#signed-parts) dos beacons compostos, com exceção do `CONTAINS` operador, que pode ser usado com beacons compostos para identificar o valor total de um campo criptografado ou assinado que o beacon montado contém. Ao comparar partes assinadas, você pode, opcionalmente, incluir o prefixo de uma [parte criptografada](configure-beacons.md#encrypted-parts), mas não pode incluir o valor criptografado de um campo. Para obter mais informações sobre os tipos de consultas que os beacons padrão e compostos podem realizar, consulte [Consultar beacons](using-beacons.md#querying-beacons). Considere as seguintes soluções de criptografia pesquisáveis ao analisar seus padrões de acesso ao banco de dados. Os exemplos a seguir definem qual beacon configurar para atender aos diferentes requisitos de criptografia e consulta. ## Beacons padrão Os [beacons padrão](beacons.md#standard-beacon-overview) só podem realizar pesquisas de igualdade. É possível usar beacons padrão para realizar as consultas a seguir. ### Consultar um único campo criptografado Se você quiser identificar registros que contenham um valor específico para um campo criptografado, crie um beacon padrão. #### Exemplos Para o exemplo a seguir, considere um banco de dados chamado `UnitInspection` que monitora os dados de inspeção de uma instalação de produção. Cada registro no banco de dados contém campos chamados `work_id`, `inspection_date`, `inspector_id_last4` e `unit`. O ID completo do inspetor é um número entre 0 e 99.999.999. No entanto, para garantir que o conjunto de dados seja distribuído uniformemente, ele armazena apenas os últimos quatro dígitos `inspector_id_last4` da ID do inspetor. Cada campo no banco de dados é identificado pela chave primária `work_id`. Os campos `inspector_id_last4` e `unit` são marcados `ENCRYPT_AND_SIGN` nas [ações criptográficas](concepts.md#crypt-actions). Veja a seguir um exemplo de uma entrada de texto sem formatação no banco de dados `UnitInspection`. ``` { "work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b", "inspection_date": 2023-06-07, "inspector_id_last4": 8744, "unit": 229304973450 } ``` **Consultar um único campo criptografado em um registro** Se o campo `inspector_id_last4` precisar ser criptografado, mas você ainda precisar consultá-lo para obter correspondências exatas, construa um beacon padrão a partir do campo `inspector_id_last4`. Em seguida, use o beacon padrão para criar um índice secundário. É possível usar esse índice secundário para consultar o campo `inspector_id_last4` criptografado. Para obter ajuda sobre a configuração de beacons padrão, consulte [Configuração de beacons padrão](configure-beacons.md#config-standard-beacons). ### Consultar um campo virtual Um [campo virtual](beacons.md#virtual-field) é um campo conceitual construído a partir de um ou mais campos de origem. Se você quiser realizar pesquisas de igualdade para um segmento específico de um campo criptografado ou realizar pesquisas de igualdade na concatenação de vários campos, construa um beacon padrão a partir de um campo virtual. Todos os campos virtuais devem incluir pelo menos um campo de origem criptografado. #### Exemplos Os exemplos a seguir criam campos virtuais para o banco de dados `Employees`. Veja a seguir um exemplo de um registro de texto sem formatação no banco de dados `Employees`. ``` { "EmployeeID": 101, "SSN": 000-00-0000, "LastName": "Jones", "FirstName": "Mary", "Address": { "Street": "123 Main", "City": "Anytown", "State": "OH", "ZIPCode": 12345 } } ``` **Consultar um segmento de um campo criptografado** Neste exemplo, o campo `SSN` é criptografado. Se você quiser consultar o campo `SSN` usando os últimos quatro dígitos de um número de previdência social, crie um campo virtual que identifique o segmento que você planeja consultar. Um campo `Last4SSN` virtual, construído a partir de `Suffix(4)` permite que você faça consultas `Last4SSN=0000`. Use esse campo virtual para construir um beacon padrão. Em seguida, use o beacon padrão para criar um índice secundário. É possível usar esse índice secundário para fazer consultas no campo virtual. Essa consulta retorna todos os registros com um valor `SSN` que termina com os últimos quatro dígitos que você especificou. **Consultar a concatenação de vários campos** O exemplo a seguir demonstra os tipos de transformações e consultas que você pode realizar com um campo virtual. No aplicativo, os campos de exemplo usados neste exemplo podem não atender às recomendações de exclusividade de [distribuição](searchable-encryption.md#searchable-encryption-distribution) e [correlação](searchable-encryption.md#searchable-encryption-correlated-values) para beacons. Se você quiser realizar pesquisas de igualdade em uma concatenação dos campos `FirstName` e `LastName`, é possível criar um campo virtual `NameTag`, construído a partir da primeira letra do campo `FirstName`, seguida pelo campo `LastName`, tudo em minúsculas. Use esse campo virtual para construir um beacon padrão. Em seguida, use o beacon padrão para criar um índice secundário. É possível usar esse índice secundário para fazer consultas `NameTag=mjones` no campo virtual. Pelo menos um dos campos de origem deve ser criptografado. `FirstName` ou `LastName` podem ser criptografados, ou ambos podem ser criptografados. Todos os campos de origem de texto simples devem ser marcados como `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` em suas ações [criptográficas](concepts.md#crypt-actions). Para obter ajuda na configuração de campos virtuais e os beacons que os usam, consulte [Criar um campo virtual](configure-beacons.md#create-virtual-field). ## Beacons compostos Os [beacons compostos](beacons.md#compound-beacon-overview) criam um índice a partir de cadeias de texto simples literais e beacons padrão para realizar operações complexas de banco de dados. É possível usar beacons compostos para realizar as consultas a seguir. ### Consulte uma combinação de campos criptografados em um único índice Se você precisar consultar uma combinação de campos criptografados em um único índice, crie um beacon composto que combine os beacons padrão individuais construídos para cada campo criptografado para formar um único índice. Depois de configurar o beacon composto, é possível criar um índice secundário que especifica o beacon composto como a chave de partição para realizar consultas de correspondência exata ou usar uma chave de classificação para realizar consultas mais complexas. Os índices secundários que especificam o beacon composto como chave de classificação podem realizar consultas de correspondência exata e consultas complexas mais personalizadas. #### Exemplos Para os exemplos a seguir, considere um banco de dados chamado `UnitInspection` que monitora os dados de inspeção de uma instalação de produção. Cada registro no banco de dados contém campos chamados `work_id`, `inspection_date`, `inspector_id_last4` e `unit`. O ID completo do inspetor é um número entre 0 e 99.999.999. No entanto, para garantir que o conjunto de dados seja distribuído uniformemente, ele armazena apenas os últimos quatro dígitos `inspector_id_last4` da ID do inspetor. Cada campo no banco de dados é identificado pela chave primária `work_id`. Os campos `inspector_id_last4` e `unit` são marcados `ENCRYPT_AND_SIGN` nas [ações criptográficas](concepts.md#crypt-actions). Veja a seguir um exemplo de uma entrada de texto sem formatação no banco de dados `UnitInspection`. ``` { "work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b", "inspection_date": 2023-06-07, "inspector_id_last4": 8744, "unit": 229304973450 } ``` **Realizar pesquisas de igualdade em uma combinação de campos criptografados** Se você quiser consultar o banco de dados `UnitInspection` para obter correspondências exatas em `inspector_id_last4.unit`, primeiro crie beacons padrão distintos para os campos `inspector_id_last4` e `unit`. Em seguida, crie um beacon composto a partir dos dois beacons padrão. Depois de configurar o beacon composto, crie um índice secundário que especifica o beacon composto como a chave de partição. Use esse índice secundário para consultar as correspondências exatas em `inspector_id_last4.unit`. Por exemplo, você pode consultar esse beacon para encontrar uma lista das inspeções que um inspetor realizou para uma determinada unidade. **Execute consultas complexas em uma combinação de campos criptografados** Se você quiser consultar o banco de dados `UnitInspection` em `inspector_id_last4` e `inspector_id_last4.unit`, primeiro crie beacons padrão distintos para os campos `inspector_id_last4` e `unit`. Em seguida, crie um beacon composto a partir dos dois beacons padrão. Depois de configurar o beacon composto, crie um índice secundário que especifica o beacon composto como a chave de classificação. Use esse índice secundário para consultar o banco de dados `UnitInspection` em busca de entradas que começam com um determinado inspetor ou consultar o banco de dados para obter uma lista de todas as unidades dentro de um intervalo de ID de unidade específico que foram inspecionadas por um determinado inspetor. Também é possível realizar pesquisas de correspondência exata em `inspector_id_last4.unit`. Para obter ajuda com a configuração de beacons compostos, consulte [Configurar beacons compostos](configure-beacons.md#config-compound-beacons). ### Consulte uma combinação de campos de texto simples criptografados em um único índice Se você precisar consultar uma combinação de campos criptografados de texto simples em um único índice, crie um beacon composto que combine os beacons padrão individuais e campos de texto simples para formar um único índice. [Os campos de texto simples usados para construir o farol composto devem estar marcados `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` em suas ações criptográficas.](concepts.md#crypt-actions) Depois de configurar o beacon composto, é possível criar um índice secundário que especifica o beacon composto como a chave de partição para realizar consultas de correspondência exata ou usar uma chave de classificação para realizar consultas mais complexas. Os índices secundários que especificam o beacon composto como chave de classificação podem realizar consultas de correspondência exata e consultas complexas mais personalizadas. #### Exemplos Para os exemplos a seguir, considere um banco de dados chamado `UnitInspection` que monitora os dados de inspeção de uma instalação de produção. Cada registro no banco de dados contém campos chamados `work_id`, `inspection_date`, `inspector_id_last4` e `unit`. O ID completo do inspetor é um número entre 0 e 99.999.999. No entanto, para garantir que o conjunto de dados seja distribuído uniformemente, ele armazena apenas os últimos quatro dígitos `inspector_id_last4` da ID do inspetor. Cada campo no banco de dados é identificado pela chave primária `work_id`. Os campos `inspector_id_last4` e `unit` são marcados `ENCRYPT_AND_SIGN` nas [ações criptográficas](concepts.md#crypt-actions). Veja a seguir um exemplo de uma entrada de texto sem formatação no banco de dados `UnitInspection`. ``` { "work_id": "1c7fcff3-6e74-41a8-b7f7-925dc039830b", "inspection_date": 2023-06-07, "inspector_id_last4": 8744, "unit": 229304973450 } ``` **Realizar pesquisas de igualdade em uma combinação de campos** Se você quiser consultar o banco de dados `UnitInspection` para inspeções conduzidas por um inspetor específico em uma data específica, primeiro crie um beacon padrão para o campo `inspector_id_last4`. O campo `inspector_id_last4` é marcado como `ENCRYPT_AND_SIGN` nas [ações criptográficas](concepts.md#crypt-actions). Todas as partes criptografadas exigem seu próprio beacon padrão. O campo `inspection_date` está marcado `SIGN_ONLY` e não requer um beacon padrão. Em seguida, crie um beacon composto a partir do campo `inspection_date` e do beacon `inspector_id_last4` padrão. Depois de configurar o beacon composto, crie um índice secundário que especifica o beacon composto como a chave de partição. Use esse índice secundário para consultar os bancos de dados em busca de registros com correspondências exatas com um determinado inspetor e data de inspeção. Por exemplo, você pode consultar o banco de dados para obter uma lista de todas as inspeções realizadas pelo inspetor cujo ID termina em `8744` em uma data específica. **Execute consultas complexas em uma combinação de campos** Se você quiser consultar o banco de dados para inspeções conduzidas dentro de um intervalo `inspection_date`, ou consultar o banco de dados para inspeções conduzidas em uma determinada `inspection_date` restringida por `inspector_id_last4` ou `inspector_id_last4.unit`, primeiro crie beacons padrão distintos para os campos `inspector_id_last4` e `unit`. Em seguida, crie um beacon composto a partir do campo `inspection_date` de texto simples e dos dois beacons padrão. Depois de configurar o beacon composto, crie um índice secundário que especifica o beacon composto como a chave de classificação. Use esse índice secundário para realizar consultas para inspeções realizadas em datas específicas por um inspetor específico. Por exemplo, você pode consultar o banco de dados para obter uma lista de todas as unidades inspecionadas na mesma data. Ou você pode consultar o banco de dados para obter uma lista de todas as inspeções realizadas em uma unidade específica entre um determinado intervalo de datas de inspeção. Para obter ajuda com a configuração de beacons compostos, consulte [Configurar beacons compostos](configure-beacons.md#config-compound-beacons). # Escolher um comprimento de beacon **** | | | --- | | 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). | Quando você grava um novo valor em um campo criptografado configurado para criptografia pesquisável, o SDK de criptografia de AWS banco de dados calcula um HMAC sobre o valor de texto sem formatação. Essa saída de HMAC é uma correspondência de um para um (1:1) para o valor de texto sem formatação desse campo. A saída de HMAC é truncada para que vários valores de texto simples distintos sejam mapeados para a mesma etiqueta de HMAC truncada. Essas colisões, ou *falsos positivos*, limitam a capacidade de um usuário não autorizado de identificar informações diferenciadas sobre o valor do texto sem formatação. O número médio de falsos positivos gerados para cada beacon é determinado pelo comprimento do beacon restante após o truncamento. Você só precisa definir o comprimento do beacon ao configurar os beacons padrão. Os beacons compostos usam os comprimentos dos beacons padrão a partir dos quais são construídos. O beacon não altera 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. O objetivo da criptografia pesquisável é reduzir os custos de desempenho associados aos bancos de dados criptografados do lado do cliente usando beacons para realizar consultas em dados criptografados. Os beacons são armazenados junto com os campos criptografados a partir dos quais são calculados. Isso significa que eles podem revelar informações diferenciadas sobre a distribuição do seu conjunto de dados. Em casos extremos, um usuário não autorizado pode analisar as informações reveladas sobre sua distribuição e usá-las para identificar o valor em texto simples de um campo. Escolher o comprimento certo do beacon pode ajudar a mitigar esses riscos e preservar a confidencialidade de sua distribuição. Analise seu modelo de ameaça para determinar o nível de segurança de que você precisa. Por exemplo, quanto mais pessoas tiverem acesso ao seu banco de dados, mas não devem ter acesso aos dados em texto simples, mais você pode querer proteger a confidencialidade da distribuição do conjunto de dados. Para aumentar a confidencialidade, um beacon precisa gerar mais falsos positivos. O aumento da confidencialidade resulta na redução do desempenho das consultas. **Segurança versus desempenho** + Um comprimento de beacon **muito longo** produz poucos falsos positivos e pode revelar informações diferenciadas sobre a distribuição do seu conjunto de dados. + Um comprimento de beacon **muito curto** produz muitos falsos positivos e aumenta o custo de desempenho das consultas porque exige uma varredura mais ampla do banco de dados. Ao determinar o comprimento adequado do beacon para sua solução, você deve encontrar um comprimento que preserve adequadamente a segurança de seus dados sem afetar o desempenho de suas consultas mais do que o absolutamente necessário. A quantidade de segurança preservada por um beacon depende da [distribuição](searchable-encryption.md#searchable-encryption-distribution) do seu conjunto de dados e da [correlação dos campos a partir](searchable-encryption.md#searchable-encryption-correlated-values) dos quais seus beacons são construídos. Os tópicos a seguir pressupõem que seus beacons estejam distribuídos uniformemente e não contenham dados correlacionados. **Topics** + [ ## Cálculo do tamanho do beacon ](#calculate-beacon-length) + [ ## Exemplo ](#beacon-length-example) ## Cálculo do tamanho do beacon O comprimento do beacon é definido em *bits* e se refere ao número de bits da tag HMAC que são mantidos após o truncamento. O comprimento recomendado do beacon varia de acordo com a distribuição do conjunto de dados, a presença de valores correlacionados e seus requisitos específicos de segurança e desempenho. Se seu conjunto de dados estiver distribuído uniformemente, você poderá usar as equações e procedimentos a seguir para ajudar a identificar o melhor comprimento de beacon para sua implementação. Essas equações estimam apenas o número médio de falsos positivos que o beacon produzirá, mas não garantem que cada valor exclusivo em seu conjunto de dados produza um número específico de falsos positivos. **nota** A eficácia dessas equações depende da distribuição do seu conjunto de dados. Se seu conjunto de dados não estiver distribuído uniformemente, consulte. [Os beacons são adequados para meu conjunto de dados?](searchable-encryption.md#are-beacons-right-for-me) Em geral, quanto mais longe seu conjunto de dados estiver de uma distribuição uniforme, mais você precisará reduzir o comprimento do beacon. 1. **Estimar a população** A população é o número esperado de valores exclusivos no campo a partir do qual seu beacon padrão é construído, não é o número total esperado de valores armazenados no campo. Por exemplo, considere um `Room` campo criptografado que identifica o local das reuniões dos funcionários. Espera-se que o `Room` campo armazene 100.000 valores totais, mas existem apenas 50 salas diferentes que os funcionários podem reservar para reuniões. Isso significa que a população é 50 porque há apenas 50 valores exclusivos possíveis que podem ser armazenados no `Room` campo. **nota** Se seu beacon padrão for construído a partir de um [campo virtual](beacons.md#virtual-field), a população usada para calcular o comprimento do beacon é o número de combinações exclusivas criadas pelo campo virtual. Ao estimar sua população, não se esqueça de considerar o crescimento projetado do conjunto de dados. Depois de gravar novos registros com o beacon, não será possível atualizar o comprimento do beacon. Analise seu modelo de ameaças e todas as soluções de banco de dados existentes para criar uma estimativa do número de valores exclusivos que você espera que esse campo armazene nos próximos cinco anos. A sua população não precisa ser precisa. Primeiro, identifique o número de valores exclusivos em seu banco de dados atual ou estime o número de valores exclusivos que você espera armazenar no primeiro ano. Em seguida, use as perguntas a seguir para ajudá-lo a determinar o crescimento projetado de valores exclusivos nos próximos cinco anos. + Você espera que os valores exclusivos se multipliquem por 10? + Você espera que os valores exclusivos se multipliquem por 100? + Você espera que os valores exclusivos se multipliquem por 1000? A diferença entre 50.000 e 60.000 valores exclusivos não é significativa e ambos resultarão no mesmo comprimento de beacon recomendado. No entanto, a diferença entre 50.000 e 500.000 valores exclusivos afetará significativamente o comprimento recomendado do beacon. Considere analisar os dados públicos com base na frequência de tipos de dados comuns, como códigos postais ou sobrenomes. Por exemplo, existem 41.707 CEPs nos Estados Unidos. A população que você usa deve ser proporcional ao seu próprio banco de dados. Se o `ZIPCode` campo em seu banco de dados incluir dados de todos os Estados Unidos, você poderá definir sua população como 41.707, mesmo que o `ZIPCode` campo não tenha *atualmente* 41.707 valores exclusivos. Se o `ZIPCode` campo em seu banco de dados incluir apenas dados de um único estado e sempre incluirá dados de um único estado, você poderá definir sua população como o número total de CEPs nesse estado, em vez de 41.704. 1. **Calcule a faixa recomendada para o número esperado de colisões** Para determinar o comprimento adequado do beacon para um determinado campo, você deve primeiro identificar um intervalo apropriado para o número esperado de colisões. O número esperado de colisões representa o número médio esperado de valores de texto simples exclusivos que são mapeados para uma tag HMAC específica. O número esperado de falsos positivos para um valor de texto simples exclusivo é um a menos do que o número esperado de colisões. Recomendamos que o número esperado de colisões seja maior ou igual a dois e menor que a raiz quadrada da sua população. As equações a seguir só funcionam se sua população tiver 16 ou mais valores exclusivos. ``` 2 ≤ number of collisions < √(Population) ``` Se o número de colisões for menor que dois, o beacon produzirá poucos falsos positivos. Recomendamos dois como o número mínimo de colisões esperadas, pois isso significa que, em média, cada valor exclusivo no campo gerará pelo menos um falso positivo ao ser mapeado para outro valor exclusivo. 1. **Calcule o intervalo recomendado para comprimentos de beacon** Depois de identificar o número mínimo e máximo de colisões esperadas, use a equação a seguir para identificar uma faixa de comprimentos de beacon apropriados. ``` number of collisions = Population * 2-(beacon length) ``` Primeiro, resolva o **comprimento do beacon** em que o número de colisões esperadas é igual a dois (o número mínimo recomendado de colisões esperadas). ``` 2 = Population * 2-(beacon length) ``` Em seguida, calcule o **comprimento do beacon** em que o número esperado de colisões é igual à raiz quadrada da sua população (o número máximo recomendado de colisões esperadas). ``` √(Population) = Population * 2-(beacon length) ``` Recomendamos arredondar a saída produzida por essa equação para o menor comprimento do beacon. Por exemplo, se a equação produzir um comprimento de beacon de 15,6, recomendamos arredondar esse valor para 15 bits em vez de arredondar para 16 bits. 1. **Escolher um comprimento de beacon** Essas equações identificam apenas uma faixa recomendada de comprimentos de beacon para seu campo. Recomendamos usar um comprimento de beacon menor para preservar a segurança do seu conjunto de dados sempre que possível. No entanto, o comprimento do beacon que você realmente usa é determinado pelo seu modelo de ameaça. Considere seus requisitos de desempenho ao analisar seu modelo de ameaça para determinar o melhor comprimento do beacon para seu campo. Usar um comprimento de beacon menor reduz o desempenho da consulta, enquanto usar um comprimento de beacon maior diminui a segurança. Em geral, se seu conjunto de dados estiver [distribuído](searchable-encryption.md#searchable-encryption-distribution) de forma desigual ou se você construir beacons distintos a partir de campos [correlacionados](searchable-encryption.md#searchable-encryption-correlated-values), precisará usar beacons menores para minimizar a quantidade de informações reveladas sobre a distribuição de seus conjuntos de dados. Se você analisar seu modelo de ameaça e decidir que qualquer informação distintiva revelada sobre a distribuição de um campo não representa uma ameaça à sua segurança geral, você pode optar por usar um comprimento de beacon maior do que o intervalo recomendado calculado. Por exemplo, se você calculou o intervalo recomendado de comprimentos de beacon para um campo como 9 a 16 bits, você pode optar por usar um comprimento de beacon de 24 bits para evitar qualquer perda de desempenho. Escolha o comprimento do beacon com cuidado. Depois de gravar novos registros com o beacon, não será possível atualizar o comprimento do beacon. ## Exemplo Considere um banco de dados que marcou o `unit` campo como `ENCRYPT_AND_SIGN` nas [ações criptográficas](concepts.md#crypt-actions). Para configurar um beacon padrão para o campo `unit`, precisamos determinar o número esperado de falsos positivos e o comprimento do beacon para o campo `unit`. 1. Estimar a população Depois de analisar nosso modelo de ameaças e a solução atual de banco de dados, esperamos que o campo `unit` eventualmente tenha 100.000 valores exclusivos. Isso significa que **População = 100.000**. 1. Calcule a faixa recomendada para o número esperado de colisões. Neste exemplo, o número esperado de colisões deve estar entre 2 e 316. ``` 2 ≤ number of collisions < √(Population) ``` 1. ``` 2 ≤ number of collisions < √(100,000) ``` 1. ``` 2 ≤ number of collisions < 316 ``` 1. Calcule o intervalo recomendado para o comprimento do beacon. Neste exemplo, o comprimento do beacon deve estar entre 9 e 16 bits. ``` number of collisions = Population * 2-(beacon length) ``` 1. Calcule o comprimento do beacon em que o número esperado de colisões é igual ao mínimo identificado na **Etapa 2**. ``` 2 = 100,000 * 2-(beacon length) ``` Comprimento do beacon = 15,6 ou 15 bits 1. Calcule o comprimento do beacon em que o número esperado de colisões é igual ao máximo identificado na **Etapa 2**. ``` 316 = 100,000 * 2-(beacon length) ``` Comprimento do beacon = 8,3 ou 8 bits 1. Determine o comprimento do beacon adequado aos seus requisitos de segurança e desempenho. Para cada bit abaixo de 15, o custo de desempenho e a segurança dobram. + 16 bits + Em média, cada valor exclusivo será mapeado para 1,5 outras unidades. + Segurança: dois registros com a mesma tag HMAC truncada têm 66% de probabilidade de ter o mesmo valor em texto simples. + Desempenho: uma consulta recuperará 15 registros para cada 10 registros que você realmente solicitou. + 14 bits + Em média, cada valor exclusivo será mapeado para 6,1 outras unidades. + Segurança: dois registros com a mesma tag HMAC truncada têm 33% de probabilidade de ter o mesmo valor em texto simples. + Desempenho: uma consulta recuperará 30 registros para cada 10 registros que você realmente solicitou. # Escolher um nome de beacon **** | | | --- | | 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). | Cada beacon é identificado por um *nome de beacon* exclusivo. Depois que um beacon é configurado, o 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](beacons.md#virtual-field), mas não pode ser igual ao nome de um campo não criptografado. Dois beacons diferentes não podem ter o mesmo nome de beacon. Para obter exemplos que demonstram como nomear e configurar beacons, consulte [Configurar beacons](configure-beacons.md). **Nomear o beacon padrão** Ao nomear beacons padrão, é altamente recomendável que o nome do seu beacon seja resolvido para a [*fonte do beacon*](beacons.md#beacon-source) sempre que possível. Isso significa que o nome do beacon e o nome do campo criptografado ou [virtual](beacons.md#virtual-field) a partir do qual seu beacon padrão é construído são os mesmos. Por exemplo, se você estiver criando um beacon padrão para um campo criptografado chamado `LastName`, o nome do seu beacon também deve ser `LastName`. 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. # 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![ StandardBeacon::builder().name("beacon_name").length(beacon_length_in_bits).build()?, ``` ------ Para configurar um beacon padrão, 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. É altamente recomendável usar o nome do campo criptografado ou do [campo virtual](beacons.md#virtual-field) 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![ CompoundBeacon::builder() .name("compound_beacon_name") .split(".") .encrypted(encrypted_parts_list) .signed(signed_parts_list) .constructors(constructor_list) .build()? ``` **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. ``` 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()?]; ``` ------ # Uso de 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). | Os beacons permitem pesquisar registros criptografados sem descriptografar todo o banco de dados que está sendo consultado. 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 configurar seus beacons, você deve concluir as etapas a seguir antes de começar a preencher seu banco de dados e realizar consultas em seus beacons. 1. **Crie um AWS KMS chaveiro hierárquico** [Para usar a criptografia pesquisável, você deve usar o [token de autenticação hierárquico do AWS KMS](use-hierarchical-keyring.md) para gerar, criptografar e descriptografar as chaves de dados](concepts.md#data-key) usadas para proteger seus registros. [Depois de configurar seus beacons, reúna os [pré-requisitos do token de autenticação hierárquico](use-hierarchical-keyring.md#hierarchical-keyring-prereqs) e crie seu token de autenticação hierárquico](use-hierarchical-keyring.md#initialize-hierarchical-keyring). Para obter mais detalhes sobre por que o token de autenticação hierárquico é necessário, consulte [Uso do token de autenticação hierárquico para criptografia pesquisável](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings). 1. **Definir a versão do beacon ** Especifique sua`keyStore`,`keySource`, uma lista de todos os beacons padrão que você configurou, uma lista de todos os beacons compostos que você configurou, uma lista de peças criptografadas, uma lista de peças assinadas e uma versão do beacon. Você deve especificar `1` para a versão do beacon. Para obter orientação sobre como definir `keySource`, consulte [Definição da fonte de chave de beacon](use-hierarchical-keyring.md#beacon-key-source). O exemplo de Java a seguir define a versão do beacon para um único banco de dados de locatário. Para obter ajuda na definição da versão do beacon para um banco de dados multilocatário, consulte [Criptografia pesquisável para bancos de dados multilocatários](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. **Configurar índices secundários** Depois de [configurar os beacons](configure-beacons.md), você deve configurar um índice secundário que reflete cada beacon antes de poder pesquisar nos campos criptografados. Para obter mais informações, consulte [Configuração de índices secundários com beacons](ddb-searchable-encryption.md#ddb-beacon-indexes). 1. **Definir [ações criptográficas](concepts.md#crypt-actions)** Todos os campos usados para construir um beacon padrão devem ser marcados com `ENCRYPT_AND_SIGN`. Todos os outros campos usados para construir beacons devem ser marcados `SIGN_ONLY` com ou. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` 1. **Configurar um cliente SDK AWS de criptografia de banco de dados** Para configurar um cliente SDK AWS de criptografia de banco de dados que proteja os itens da tabela em sua tabela do DynamoDB, [consulte Biblioteca de criptografia Java do lado do cliente](ddb-java.md) para o DynamoDB. ## Consultar beacons O tipo de beacon que você configura determina o tipo de consultas que você é capaz de realizar. Os beacons padrão usam expressões de filtro para realizar pesquisas de igualdade. Os beacons compostos combinam cadeias de texto simples literais e beacons padrão para realizar consultas complexas. Ao consultar dados criptografados, você pesquisa pelo nome do beacon. Não é possível comparar os valores de dois beacons padrão, mesmo que eles contenham o mesmo texto simples subjacente. Os dois beacons padrão produzirão duas etiquetas de HMAC diferentes para os mesmos valores de texto simples. Como resultado, os beacons padrão não podem realizar as consultas a seguir. + `beacon1 = beacon2` + `beacon1 IN (beacon2)` + `value IN (beacon1, beacon2, ...)` + `CONTAINS(beacon1, beacon2)` Os beacons compostos podem realizar as consultas a seguir. + `BEGINS_WITH(a)`, onde `a` reflete o valor total do campo com o qual o beacon composto montado começa. Não é possível usar o operador `BEGINS_WITH` para identificar um valor que comece com uma substring específica. No entanto, é possível usar `BEGINS_WITH(S_)`, em que `S_` reflete o prefixo de uma parte com a qual o beacon composto montado começa. + `CONTAINS(a)`, em que `a` reflete o valor total de um campo que o beacon composto montado contém. Não é possível usar o operador `CONTAINS` para identificar um registro que contenha uma substring específica ou um valor dentro de um conjunto. Por exemplo, não é possível realizar uma consulta `CONTAINS(path, "a"` em que `a` reflita o valor em um conjunto. + É possível comparar [partes assinadas](configure-beacons.md#signed-parts) de beacons compostos. Ao comparar partes assinadas, é possível, opcionalmente, acrescentar o prefixo de uma [parte criptografada](configure-beacons.md#encrypted-parts) a uma ou mais partes assinadas, mas não é possível incluir o valor de um campo criptografado em nenhuma consulta. Por exemplo, é possível comparar partes assinadas e consultar em `signedField1 = signedField2` ou`value IN (signedField1, signedField2, ...)`. Também é possível comparar partes assinadas e o prefixo de uma parte criptografada por meio de consulta em `signedField1.A_ = signedField2.B_`. + `field BETWEEN a AND b`, em que `a` e `b` são partes assinadas. Opcionalmente, é possível acrescentar o prefixo de uma parte criptografada a uma ou mais partes assinadas, mas não é possível incluir o valor de um campo criptografado em nenhuma consulta. Você deve incluir o prefixo de cada parte incluída em uma consulta em um beacon composto. Por exemplo, se você construiu um beacon composto, `compoundBeacon`, a partir de dois campos `encryptedField` e `signedField`, deverá incluir os prefixos configurados para essas duas partes ao consultar o beacon. ``` compoundBeacon = E_encryptedFieldValue.S_signedFieldValue ``` # Criptografia pesquisável para bancos de dados multilocatários **** | | | --- | | 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). | Para implementar a criptografia pesquisável em seu banco de dados, você deve usar um [token de autenticação hierárquico do AWS KMS](use-hierarchical-keyring.md). O AWS KMS chaveiro hierárquico gera, criptografa e descriptografa as chaves de dados usadas para proteger seus registros. Ele também cria a chave do beacon usada para gerar beacons. Ao usar o AWS KMS chaveiro hierárquico com bancos de dados multilocatários, há uma chave de ramificação e uma chave de beacon distintas para cada inquilino. Para consultar dados criptografados em um banco de dados multilocatário, você deve identificar os materiais de chave do beacon usados para gerar o beacon que você está consultando. Para obter mais informações, consulte [Uso do token de autenticação hierárquico para criptografia pesquisável](use-hierarchical-keyring.md#searchable-encryption-hierarchical-keyrings). Ao definir a [versão do beacon](using-beacons.md#beacon-version) para um banco de dados multilocatário, especifique uma lista de todos os beacons padrão que você configurou, uma lista de todos os beacons compostos que você configurou, uma versão do beacon e uma `keySource`. Você deve [definir sua fonte de chave de beacon](use-hierarchical-keyring.md#beacon-key-source) como `MultiKeyStore` e incluir um `keyFieldName` de tempo de vida útil para o cache de chave de beacon local e tamanho máximo de cache para o cache de chave de beacon local. Se você configurou algum [beacon assinado](configure.md#signed-beacons), ele deve ser incluído no seu `compoundBeaconList`. Os beacons assinados são um tipo de farol composto que indexa e executa consultas complexas em campos e. `SIGN_ONLY` `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` ------ #### [ Java ] ``` List beaconVersions = new ArrayList<>(); beaconVersions.add( BeaconVersion.builder() .standardBeacons(standardBeaconList) .compoundBeacons(compoundBeaconList) .version(1) // MUST be 1 .keyStore(branchKeyStoreName) .keySource(BeaconKeySource.builder() .multi(MultiKeyStore.builder() .keyFieldName(keyField) .cacheTTL(6000) .maxCacheSize(10) .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 { Multi = new MultiKeyStore { KeyId = branch-key-id, CacheTTL = 6000, MaxCacheSize = 10 } } } }; ``` ------ #### [ 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::Multi( MultiKeyStore::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) .max_cache_size(10) .build()?, )) .build()?; let beacon_versions = vec![beacon_version]; ``` ------ **keyFieldName** O [`keyFieldName`](use-hierarchical-keyring.md#keyFieldName) define o nome do campo que armazena o `branch-key-id` associado à chave de beacon usada para gerar beacons para um determinado locatário. Quando você grava novos registros em seu banco de dados, a chave `branch-key-id` que identifica a chave de beacon usada para gerar quaisquer beacons para esse registro é armazenada nesse campo. Por padrão, `keyField` é um campo conceitual que não está explicitamente armazenado em seu banco de dados. [O SDK AWS de criptografia de banco de dados identifica a [chave `branch-key-id` de dados](concepts.md#data-key) criptografada na [descrição do material](concepts.md#material-description) e armazena o valor no conceito `keyField` para você referenciar em seus beacons compostos e beacons assinados.](configure.md#signed-beacons) Como a descrição do material é assinada, o `keyField` conceitual é considerado uma parte assinada. Você também pode incluir o `keyField` em suas ações criptográficas como um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` campo `SIGN_ONLY` ou para armazenar explicitamente o campo em seu banco de dados. Se você fizer isso, deverá incluir manualmente o `branch-key-id` no `keyField` sempre que gravar um registro no seu banco de dados. ## Consultar beacons em um banco de dados multilocatário Para consultar um beacon, você deve incluir o `keyField` em sua consulta para identificar os materiais de chave de beacon apropriados necessários para recalcular o beacon. Você deve especificar o `branch-key-id` associado à chave de beacon usada para gerar os beacons para um registro. Você não pode especificar o [nome amigável](use-hierarchical-keyring.md#branch-key-id-supplier) que identifica o nome de um locatário `branch-key-id` no fornecedor da ID da chave da ramificação. É possível incluir o `keyField` em suas consultas das maneiras a seguir. **Beacons compostos** Quer você armazene explicitamente o `keyField` em seus registros ou não, você poderá inclur `keyField` diretamente em seus beacons compostos como uma parte assinada. A parte `keyField` assinada deve ser necessária. Por exemplo, se você quiser construir um beacon composto, `compoundBeacon`, a partir de dois campos, `encryptedField` e`signedField`, você também deverá incluir `keyField` como uma parte assinada. Isso permite executar a consulta a seguir em `compoundBeacon`. ``` compoundBeacon = E_encryptedFieldValue.S_signedFieldValue.K_branch-key-id ``` **Beacons assinados** O SDK AWS de criptografia de banco de dados usa beacons padrão e compostos para fornecer soluções de criptografia pesquisáveis. Esses beacons devem incluir pelo menos um campo criptografado. No entanto, o SDK AWS de criptografia de banco de dados também oferece suporte a [beacons assinados](configure.md#signed-beacons) que podem ser configurados inteiramente a partir de texto simples `SIGN_ONLY` e campos. `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` Os beacons assinados podem ser construídos a partir de uma única parte. Independentemente de você armazenar explicitamente `keyField` em seus registros ou não, você pode construir um beacon assinado a partir do `keyField` e usá-lo para criar consultas compostas que combinam uma consulta no beacon `keyField` assinado com uma consulta em um de seus outros beacons. Por exemplo, você poderia realizar a consulta a seguir. ``` keyField = K_branch-key-id AND compoundBeacon = E_encryptedFieldValue.S_signedFieldValue ``` Para obter ajuda sobre a configuração de beacons assinados, consulte [Criação de beacons assinados](configure.md#signed-beacons) **Consulte diretamente no `keyField`** Se você especificou o `keyField` em suas ações criptográficas e armazenou explicitamente o campo em seu registro, você pode criar uma consulta composta que combina uma consulta no seu beacon com uma consulta no `keyField`. É possível optar por consultar diretamente no `keyField` se desejar consultar um beacon padrão. Por exemplo, você poderia realizar a consulta a seguir. ``` keyField = branch-key-id AND standardBeacon = S_standardBeaconValue ```