Criptografia pesquisável no DynamoDB

Para configurar suas tabelas do Amazon DynamoDB para criptografia pesquisável, você deve usar o token de autenticação hierárquico do AWS KMS para gerar, criptografar e descriptografar as chaves de dados usadas para proteger seus itens. Você também deve incluir o SearchConfig na configuração de criptografia da tabela.

nota

Se você estiver usando a biblioteca de criptografia Java do lado do cliente para o DynamoDB, deverá usar o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB para criptografar, assinar, verificar e descriptografar os itens da tabela. O DynamoDB Enhanced Client e o DynamoDBItemEncryptor de nível inferior não oferecem suporte à criptografia pesquisável.

Configuração de índices secundários com beacons

Depois de configurar os beacons, você deve configurar um índice secundário que reflete cada beacon antes de poder pesquisar nos atributos criptografados.

Quando você configura um beacon padrão ou composto, o SDK de criptografia AWS de banco de dados adiciona o aws_dbe_b_ prefixo ao nome do beacon para que o servidor possa identificar facilmente os beacons. Por exemplo, se você nomear um beacon composto, compoundBeacon, o nome completo do beacon será aws_dbe_b_compoundBeacon. Se você quiser configurar índices secundários que incluam um beacon padrão ou composto, deverá incluir o prefixo aws_dbe_b_ ao identificar o nome do beacon.

Partição e chaves de classificação

Não é possível criptografar valores de chave primária. Suas chaves de partição e classificação devem ser assinadas. Os valores de chave primária não podem ser um beacon padrão ou composto.

Seus valores de chave primária devem serSIGN_ONLY, a menos que você especifique algum SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT atributo, os atributos de partição e classificação também devem serSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT.

Os valores de chave primária podem ser beacons assinados. Se você configurou beacons assinados distintos para cada um dos seus valores de chave primária, deverá o nome do atributo que identifica o valor da chave primária como o nome do beacon assinado. No entanto, o SDK AWS de criptografia de banco de dados não adiciona o aws_dbe_b_ prefixo aos beacons assinados. Mesmo que você tenha configurado beacons assinados distintos para os valores de chave primária, você só precisará especificar os nomes dos atributos para os valores de chave primária ao configurar um índice secundário.

Índices secundários locais

A chave de classificação para um índice secundário local pode ser um beacon.

Se você especificar um beacon para a chave de classificação, o tipo deverá ser String. Se você especificar um beacon padrão ou composto para a chave de classificação, ele deverá incluir o prefixo aws_dbe_b_ ao especificar o nome do beacon. Se você especificar um beacon assinado, especifique o nome do beacon sem nenhum prefixo.

Índices secundários globais

As chaves de classificação e de partição de um índice secundário global podem ser beacons.

Se você especificar um beacon para a partição ou chave de classificação, o tipo deverá ser String. Se você especificar um beacon padrão ou composto para a chave de classificação, ele deverá incluir o prefixo aws_dbe_b_ ao especificar o nome do beacon. Se você especificar um beacon assinado, especifique o nome do beacon sem nenhum prefixo.

Projeções de atributo

Uma projeção é o conjunto de atributos que é copiado de uma tabela para um índice secundário. A chave de partição e a chave de classificação da tabela são sempre projetadas no índice; é possível projetar outros atributos para suportar os requisitos de consulta da sua aplicação. O DynamoDB fornece três opções diferentes para projeções de atributo: KEYS_ONLY, INCLUDE e ALL.

Se você usar a projeção do atributo INCLUDE para pesquisar em um beacon, deverá especificar os nomes de todos os atributos a partir dos quais o beacon é construído e o nome do beacon com o prefixo aws_dbe_b_. Por exemplo, se você configurou um beacon composto, compoundBeacon, defield1, field2 efield3, deverá especificar aws_dbe_b_compoundBeacon, field1, field2 e field3 na projeção.

Um índice secundário global só pode usar os atributos explicitamente especificados na projeção, mas um índice secundário local pode usar qualquer atributo.

Testando saídas de farol

Se você configurou beacons compostos ou construiu seus beacons usando campos virtuais, recomendamos verificar se esses beacons produzem a saída esperada antes de preencher sua tabela do DynamoDB.

O SDK AWS de criptografia de banco de dados fornece o DynamoDbEncryptionTransforms serviço para ajudá-lo a solucionar problemas de campo virtual e saídas de beacon composto.

Testando campos virtuais

O snippet a seguir cria itens de teste, define o DynamoDbEncryptionTransforms serviço com a configuração de criptografia de tabela do DynamoDB e demonstra como usá-lo para verificar se o campo virtual produz ResolveAttributes a saída esperada.

Java

Veja a amostra de código completa: VirtualBeaconSearchableEncryptionExample.java

// Create test items
final PutItemRequest itemWithHasTestResultPutRequest = PutItemRequest.builder()
    .tableName(ddbTableName)
    .item(itemWithHasTestResult)
    .build();

final PutItemResponse itemWithHasTestResultPutResponse = ddb.putItem(itemWithHasTestResultPutRequest);

final PutItemRequest itemWithNoHasTestResultPutRequest = PutItemRequest.builder()
    .tableName(ddbTableName)
    .item(itemWithNoHasTestResult)
    .build();
    
final PutItemResponse itemWithNoHasTestResultPutResponse = ddb.putItem(itemWithNoHasTestResultPutRequest);    

// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
    .DynamoDbTablesEncryptionConfig(encryptionConfig).build();

// Verify configuration
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
    .TableName(ddbTableName)
    .Item(itemWithHasTestResult)
    .Version(1)
    .build();
final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);

// Verify that VirtualFields has the expected value
Map<String, String> vf = new HashMap<>();
vf.put("stateAndHasTestResult", "CAt");
assert resolveOutput.VirtualFields().equals(vf);

C# / .NET

Veja o exemplo de código completo: VirtualBeaconSearchableEncryptionExample.cs

 // Create item with hasTestResult=true
var itemWithHasTestResult = new Dictionary<String, AttributeValue>
{
    ["customer_id"] = new AttributeValue("ABC-123"),
    ["create_time"] = new AttributeValue { N = "1681495205" },
    ["state"] = new AttributeValue("CA"),
    ["hasTestResult"] = new AttributeValue { BOOL = true }
};

// Create item with hasTestResult=false
var itemWithNoHasTestResult = new Dictionary<String, AttributeValue>
{
    ["customer_id"] = new AttributeValue("DEF-456"),
    ["create_time"] = new AttributeValue { N = "1681495205" },
    ["state"] = new AttributeValue("CA"),
    ["hasTestResult"] = new AttributeValue { BOOL = false }
};

// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);

// Verify configuration
var resolveInput = new ResolveAttributesInput
{
    TableName = ddbTableName,
    Item = itemWithHasTestResult,
    Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);

// Verify that VirtualFields has the expected value
Debug.Assert(resolveOutput.VirtualFields.Count == 1);
Debug.Assert(resolveOutput.VirtualFields["stateAndHasTestResult"] == "CAt");

Testando faróis compostos

O trecho a seguir cria um item de teste, define o DynamoDbEncryptionTransforms serviço com a configuração de criptografia de tabela do DynamoDB e demonstra como usá-lo para verificar se o beacon composto produz ResolveAttributes a saída esperada.

Java

Veja a amostra de código completa: CompoundBeaconSearchableEncryptionExample.java

// Create an item with both attributes used in the compound beacon.
final HashMap<String, AttributeValue> item = new HashMap<>();
item.put("work_id", AttributeValue.builder().s("9ce39272-8068-4efd-a211-cd162ad65d4c").build());
item.put("inspection_date", AttributeValue.builder().s("2023-06-13").build());
item.put("inspector_id_last4", AttributeValue.builder().s("5678").build());
item.put("unit", AttributeValue.builder().s("011899988199").build());
                            
// Define the DynamoDbEncryptionTransforms service
final DynamoDbEncryptionTransforms trans = DynamoDbEncryptionTransforms.builder()
    .DynamoDbTablesEncryptionConfig(encryptionConfig).build();

// Verify configuration 
final ResolveAttributesInput resolveInput = ResolveAttributesInput.builder()
    .TableName(ddbTableName)
    .Item(item)
    .Version(1)
    .build();

final ResolveAttributesOutput resolveOutput = trans.ResolveAttributes(resolveInput);
                            
// Verify that CompoundBeacons has the expected value   
Map<String, String> cbs = new HashMap<>();
cbs.put("last4UnitCompound", "L-5678.U-011899988199");
assert resolveOutput.CompoundBeacons().equals(cbs);
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon

C# / .NET

Veja o exemplo de código completo: CompoundBeaconSearchableEncryptionExample.cs

// Create an item with both attributes used in the compound beacon
var item = new Dictionary<String, AttributeValue>
{
    ["work_id"] = new AttributeValue("9ce39272-8068-4efd-a211-cd162ad65d4c"),
    ["inspection_date"] = new AttributeValue("2023-06-13"),
    ["inspector_id_last4"] = new AttributeValue("5678"),
    ["unit"] = new AttributeValue("011899988199")
};                           
                            
// Define the DynamoDbEncryptionTransforms service
var trans = new DynamoDbEncryptionTransforms(encryptionConfig);

// Verify configuration
var resolveInput = new ResolveAttributesInput
{
    TableName = ddbTableName,
    Item = item,
    Version = 1
};
var resolveOutput = trans.ResolveAttributes(resolveInput);                            
                            
// Verify that CompoundBeacons has the expected value 
Debug.Assert(resolveOutput.CompoundBeacons.Count == 1);
Debug.Assert(resolveOutput.CompoundBeacons["last4UnitCompound"] == "L-5678.U-011899988199");
// Note : the compound beacon actually stored in the table is not "L-5678.U-011899988199"
// but rather something like "L-abc.U-123", as both parts are EncryptedParts
// and therefore the text is replaced by the associated beacon