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á.

# AWS SDK de criptografia de banco de dados para DynamoDB
<a name="dynamodb-encryption-client"></a>


****  

|  | 
| --- |
| 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). | 

[O AWS Database Encryption SDK for DynamoDB é uma biblioteca de software que permite incluir criptografia do lado do cliente em seu design do Amazon DynamoDB.](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/) O SDK AWS de criptografia de banco de dados para DynamoDB fornece criptografia em nível de atributo e permite que você especifique quais itens criptografar e quais itens incluir nas assinaturas para garantir a autenticidade de seus dados. Criptografar dados em trânsito e em repouso confidenciais ajuda você a garantir que os dados em texto simples não estejam disponíveis a terceiros, incluindo à AWS.

**nota**  
O SDK AWS de criptografia de banco de dados não é compatível com partiQL.

No DynamoDB, uma [tabela](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.TablesItemsAttributes) é uma coleção de itens. Cada *item* é uma coleção de *atributos*. Cada atributo tem um nome e um valor. O SDK AWS de criptografia de banco de dados para DynamoDB criptografa os valores dos atributos. Em seguida, ele calcula uma assinatura sobre os atributos. É possível especificar quais valores de atributo criptografar e quais incluir na assinatura das [ações criptográficas](concepts.md#crypt-actions).

Os tópicos deste capítulo fornecem uma visão geral do SDK de criptografia de AWS banco de dados para DynamoDB, incluindo quais campos são criptografados, orientações sobre instalação e configuração do cliente e exemplos de Java para ajudar você a começar.

**Topics**
+ [Criptografia do lado do cliente e do lado do servidor](client-server-side.md)
+ [Quais campos são criptografados e assinados?](DDB-encrypted-and-signed.md)
+ [Criptografia pesquisável no DynamoDB](ddb-searchable-encryption.md)
+ [Atualizar seu modelo de dados](ddb-update-data-model.md)
+ [AWS SDK de criptografia de banco de dados para linguagens de programação disponíveis do DynamoDB](ddb-programming-languages.md)
+ [Cliente legado de criptografia do DynamoDB](legacy-dynamodb-encryption-client.md)

# Criptografia do lado do cliente e do lado do servidor
<a name="client-server-side"></a>


****  

|  | 
| --- |
| 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). | 

O SDK AWS de criptografia de banco de dados para DynamoDB *oferece suporte à criptografia do lado do cliente*, na qual você criptografa os dados da tabela antes de enviá-los para o banco de dados. Contudo, o DynamoDB fornece um atributo de *criptografia em repouso* que criptografa a tabela de forma transparente quando ela é mantida no disco e a descriptografa quando você a acessa. 

As ferramentas escolhidas dependem da confidencialidade dos seus dados e dos requisitos de segurança do seu aplicativo. Você pode usar o AWS Database Encryption SDK para DynamoDB e a criptografia em repouso. Quando você envia itens criptografados e assinados ao DynamoDB, o DynamoDB não os reconhece como itens protegidos. Ele apenas detecta itens típicos da tabela com valores de atributo binários. 

**Criptografia do lado do servidor em repouso**

O DynamoDB é compatível com a [criptografia em repouso](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/EncryptionAtRest.html), um atributo de *criptografia do lado do servidor* no qual o DynamoDB criptografa suas tabelas de forma transparente quando elas são mantidas no disco e as descriptografa quando você acessa os dados da tabela.

Quando você usa um AWS SDK para interagir com o DynamoDB, por padrão, seus dados são criptografados em trânsito por uma conexão HTTPS, descriptografados no endpoint do DynamoDB e depois criptografados novamente antes de serem armazenados no DynamoDB.
+ **Criptografia por padrão.** O DynamoDB criptografa e descriptografa de forma transparente todas as tabelas quando elas são gravadas. Não há nenhuma opção para habilitar ou desabilitar a criptografia em repouso. 
+ **O DynamoDB cria e gerencia as chaves de criptografia.**A chave exclusiva de cada tabela é protegida por uma [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) que nunca deixa o [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) descriptografado. Por padrão, o DynamoDB usa uma [Chave pertencente à AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) na conta do serviço do DynamoDB, mas é possível escolher uma [Chave gerenciada pela AWS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-managed-cmk) ou uma [chave gerenciada pelo cliente](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk) na conta para proteger algumas ou todas as suas tabelas.
+ **Todos os dados da tabela são criptografados no disco. **Quando uma tabela criptografada é salva no disco, o DynamoDB criptografa todos os dados da tabela, incluindo a [chave primária](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey) e os [índices secundários](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.SecondaryIndexes) locais e globais. Se sua tabela tem uma chave de classificação, algumas dessas chaves que marcam os limites de intervalo são armazenadas em textos simples nos metadados da tabela.
+ **Os objetos relacionados a tabelas também são criptografados.** A criptografia em repouso protege os [streams do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html), as [tabelas globais](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html) e os [backups](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/BackupRestore.html) sempre que eles estão gravados em mídia durável.
+ **Os itens são descriptografados quando você os acessa. **Quando você acessa a tabela, o DynamoDB descriptografa a parte da tabela que inclui o item de destino e retorna o item em texto sem formatação para você.

**AWS SDK de criptografia de banco de dados para DynamoDB**

A criptografia do lado do cliente fornece end-to-end proteção para seus dados, em trânsito e em repouso, desde a origem até o armazenamento no DynamoDB. Seus dados em texto simples nunca são expostos a terceiros, inclusive. AWS Você pode usar o AWS Database Encryption SDK for DynamoDB com novas tabelas do DynamoDB ou migrar suas tabelas existentes do Amazon DynamoDB para a versão mais recente do Database Encryption SDK for DynamoDB. AWS 
+ **Seus dados são protegidos em trânsito e em repouso.** Nunca é exposto a terceiros, inclusive AWS.
+ **É possível assinar os itens da tabela.** É possível direcionar o SDK de criptografia de banco de dados da AWS para calcular uma assinatura em todo ou em parte de um item da tabela, incluindo os atributos de chave primária e o nome da tabela. Essa assinatura permite que você detecte alterações não autorizadas no item como um todo, incluindo a adição ou a exclusão de atributos ou a troca de valores de atributos.
+ **Você determina como seus dados são protegidos** [selecionando um token de autenticação](keyrings.md). O token de autenticação determina as chaves de empacotamento que protegem as chaves de dados e, em última análise, os dados. Use as chaves de encapsulamento mais seguras e práticas para sua tarefa.
+ **O SDK AWS de criptografia de banco de dados para DynamoDB não criptografa a tabela inteira.** Você escolhe quais atributos são criptografados em seus itens. O SDK AWS de criptografia de banco de dados para DynamoDB não criptografa um item inteiro. Ele não criptografa nomes de atributo ou nomes e valores dos atributos da chave primária (chave de partição e de classificação).

**AWS Encryption SDK**

Se você estiver criptografando dados armazenados no DynamoDB, recomendamos o SDK de criptografia de banco de dados para AWS o DynamoDB. 

O [AWS Encryption SDK](https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/) é uma biblioteca de criptografia do lado do cliente que ajuda você a criptografar e descriptografar dados genéricos. Embora possa proteger qualquer tipo de dado, ele não foi projetado para trabalhar com dados estruturados, como registros de banco de dados. Ao contrário do SDK AWS de criptografia de banco de dados para DynamoDB, AWS Encryption SDK ele não pode fornecer verificação de integridade em nível de item e não tem lógica para reconhecer atributos ou impedir a criptografia de chaves primárias.

Se você usar o AWS Encryption SDK para criptografar qualquer elemento da sua tabela, lembre-se de que ele não é compatível com o SDK de criptografia de AWS banco de dados para DynamoDB. Não é possível criptografar com uma biblioteca e descriptografar com uma diferente.

# Quais campos são criptografados e assinados?
<a name="DDB-encrypted-and-signed"></a>


****  

|  | 
| --- |
| 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). | 

O SDK AWS de criptografia de banco de dados para DynamoDB é uma biblioteca de criptografia do lado do cliente projetada especialmente para aplicativos do Amazon DynamoDB. O Amazon DynamoDB armazena dados em [tabelas](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.TablesItemsAttributes), que são uma coleção de itens. Cada *item* é uma coleção de *atributos*. Cada atributo tem um nome e um valor. O SDK AWS de criptografia de banco de dados para DynamoDB criptografa os valores dos atributos. Em seguida, ele calcula uma assinatura sobre os atributos. Você pode especificar quais valores de atributo criptografar e quais incluir na assinatura.

A criptografia protege a confidencialidade do valor do atributo. A assinatura fornece a integridade de todos os atributos assinados e a relação entre ele, além de fornecer a autenticação. Ele permite que você detecte alterações não autorizadas no item como um todo, incluindo a adição ou a exclusão de atributos, ou a substituição de um valor criptografado por outro.

Em um item criptografado, alguns dados permanecem em texto simples, incluindo o nome da tabela, todos os nomes de atributos, valores de atributos que você não criptografa e os nomes e valores dos atributos de chave primária (chave de partição e chave de classificação). Não armazene dados confidenciais nesses campos.

Para obter mais informações sobre como o SDK AWS de criptografia de banco de dados para DynamoDB funciona, consulte. [Como funciona o SDK AWS de criptografia de banco de dados](how-it-works.md)

**nota**  
[Todas as menções de *ações de atributos nos tópicos* do AWS Database Encryption SDK for DynamoDB se referem a ações criptográficas.](concepts.md#crypt-actions)

**Topics**
+ [Criptografar valores de atributos](#encrypt-attribute-values)
+ [Assinar o item](#sign-the-item)

## Criptografar valores de atributos
<a name="encrypt-attribute-values"></a>

O SDK AWS de criptografia de banco de dados para DynamoDB criptografa os valores (mas não o nome ou o tipo do atributo) dos atributos que você especifica. Para determinar quais valores de atributos são criptografados, use as [ações de atributos](concepts.md#crypt-actions). 

Por exemplo, esse item inclui atributos `example` e `test`.

```
'example': 'data',
'test': 'test-value',
...
```

Se você criptografar o atributo `example`, mas não o `test`, os resultados serão semelhantes aos seguintes. O valor do atributo `example` criptografado são dados binários, em vez de uma string.

```
'example': Binary(b"'b\x933\x9a+s\xf1\xd6a\xc5\xd5\x1aZ\xed\xd6\xce\xe9X\xf0T\xcb\x9fY\x9f\xf3\xc9C\x83\r\xbb\\"),
'test': 'test-value'
...
```

Os atributos de chave primária (chave de partição e chave de classificação) de cada item devem permanecer em texto sem formatação porque o DynamoDB os usa para encontrar o item na tabela. Eles devem ser assinados, mas não criptografados. 

O SDK AWS de criptografia de banco de dados para DynamoDB identifica os atributos da chave primária para você e garante que seus valores sejam assinados, mas não criptografados. E, se você identificar a chave primária e tentar criptografá-la, o cliente gerará uma exceção.

O cliente armazena a [descrição do material](concepts.md#material-description) em um novo atributo (`aws_dbe_head`) que ele adiciona ao item. A descrição do material descreve como o item foi criptografado e assinado. O cliente usa essas informações para verificar e descriptografar o item. O campo que armazena a descrição do material não é criptografado.

## Assinar o item
<a name="sign-the-item"></a>

[Depois de criptografar os valores dos atributos especificados, o SDK de criptografia de AWS banco de dados para DynamoDB calcula códigos de autenticação de mensagens baseados em hash (HMACs) e uma [assinatura digital](concepts.md#digital-sigs) por meio da canonização da descrição do material, do [contexto de criptografia](concepts.md#encryption-context) e de cada campo marcado ou nas ações do atributo. `ENCRYPT_AND_SIGN``SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](concepts.md#crypt-actions) As assinaturas ECDSA são habilitadas por padrão, mas não são obrigatórias. O cliente armazena as assinaturas HMACs e em um novo atributo (`aws_dbe_foot`) que ele adiciona ao item.

# Criptografia pesquisável no DynamoDB
<a name="ddb-searchable-encryption"></a>

Para configurar suas tabelas do Amazon DynamoDB para 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 itens. Você também deve incluir o [`SearchConfig`](ddb-net-using.md#ddb-net-search-config) 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.

**Topics**
+ [Configuração de índices secundários com beacons](#ddb-beacon-indexes)
+ [Testando saídas de farol](#ddb-beacon-testing)

## Configuração de índices secundários com beacons
<a name="ddb-beacon-indexes"></a>

Depois de [configurar os beacons](configure-beacons.md), 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/SecondaryIndexes.html) 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 ser`SIGN_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 ser`SIGN_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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html) 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html) 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](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html#GSI.Projections) é 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`, de`field1`, `field2` e`field3`, 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
<a name="ddb-beacon-testing"></a>

Se você [configurou beacons compostos](configure-beacons.md#config-compound-beacons) ou construiu seus beacons usando [campos virtuais](configure-beacons.md#create-virtual-field), 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
<a name="ddb-beacon-testing-virtual-field"></a>

O snippet a seguir cria itens de teste, define o `DynamoDbEncryptionTransforms` serviço com a [configuração de criptografia de tabela do DynamoDB](ddb-java-using.md#ddb-config-encrypt) 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](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) 

```
// 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\$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)

```
 // 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");
```

------
#### [ 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).

```
// Create item with hasTestResult=true
let item_with_has_test_result = HashMap::from([
    (
        "customer_id".to_string(),
        AttributeValue::S("ABC-123".to_string()),
    ),
    (
        "create_time".to_string(),
        AttributeValue::N("1681495205".to_string()),
    ),
    ("state".to_string(), AttributeValue::S("CA".to_string())),
    ("hasTestResult".to_string(), AttributeValue::Bool(true)),
]);

// Create item with hasTestResult=false
let item_with_no_has_test_result = HashMap::from([
    (
        "customer_id".to_string(),
        AttributeValue::S("DEF-456".to_string()),
    ),
    (
        "create_time".to_string(),
        AttributeValue::N("1681495205".to_string()),
    ),
    ("state".to_string(), AttributeValue::S("CA".to_string())),
    ("hasTestResult".to_string(), AttributeValue::Bool(false)),
]);

// Define the transform service
let trans = transform_client::Client::from_conf(encryption_config.clone())?;

// Verify the configuration 
let resolve_output = trans
    .resolve_attributes()
    .table_name(ddb_table_name)
    .item(item_with_has_test_result.clone())
    .version(1)
    .send()
    .await?;

// Verify that VirtualFields has the expected value
let virtual_fields = resolve_output.virtual_fields.unwrap();
assert_eq!(virtual_fields.len(), 1);
assert_eq!(virtual_fields["stateAndHasTestResult"], "CAt");
```

------

### Testando faróis compostos
<a name="ddb-beacon-testing-compound-beacon"></a>

O trecho a seguir cria um item de teste, define o `DynamoDbEncryptionTransforms` serviço com a [configuração de criptografia de tabela do DynamoDB](ddb-java-using.md#ddb-config-encrypt) 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](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/searchableencryption/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\$1 / .NET ]

**Veja o exemplo de código completo**: [CompoundBeaconSearchableEncryptionExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/searchableencryption/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
```

------
#### [ Rust ]

**Veja o exemplo de código completo**: [compound\$1beacon\$1searchable\$1encryption.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/searchableencryption/compound_beacon_searchable_encryption.rs)

```
// Create an item with both attributes used in the compound beacon
let item = HashMap::from([
    (
        "work_id".to_string(),
        AttributeValue::S("9ce39272-8068-4efd-a211-cd162ad65d4c".to_string()),
    ),
    (
        "inspection_date".to_string(),
        AttributeValue::S("2023-06-13".to_string()),
    ),
    (
        "inspector_id_last4".to_string(),
        AttributeValue::S("5678".to_string()),
    ),
    (
        "unit".to_string(),
        AttributeValue::S("011899988199".to_string()),
    ),
]);                           
                            
// Define the transforms service
let trans = transform_client::Client::from_conf(encryption_config.clone())?;

// Verify configuration
let resolve_output = trans
    .resolve_attributes()
    .table_name(ddb_table_name)
    .item(item.clone())
    .version(1)
    .send()
    .await?;                            
                            
// Verify that CompoundBeacons has the expected value 
let compound_beacons = resolve_output.compound_beacons.unwrap();
assert_eq!(compound_beacons.len(), 1);
assert_eq!(
    compound_beacons["last4UnitCompound"],
    "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
```

------

# Atualizar seu modelo de dados
<a name="ddb-update-data-model"></a>


****  

|  | 
| --- |
| 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). | 

[Ao configurar o SDK AWS de criptografia de banco de dados para o DynamoDB, você fornece ações de atributos.](concepts.md#crypt-actions) Na criptografia, o SDK AWS de criptografia de banco de dados usa as ações de atributos para identificar quais atributos criptografar e assinar, quais atributos assinar (mas não criptografar) e quais ignorar. Os [atributos não assinados permitidos](ddb-java-using.md#allowed-unauth) informam ao cliente quais atributos foram excluídos das assinaturas. Na descriptografia, o SDK de criptografia AWS de banco de dados usa os atributos não assinados permitidos que você definiu para identificar quais atributos não estão incluídos nas assinaturas. As ações de atributo não são salvas no item criptografado e o SDK AWS de criptografia de banco de dados não atualiza suas ações de atributo automaticamente.

Escolha suas ações de atributos com cuidado. Em caso de dúvida, use **Criptografar e assinar**. Depois de usar o SDK AWS de criptografia de banco de dados para proteger seus itens, você não pode alterar um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo ou existente `ENCRYPT_AND_SIGN` para`DO_NOTHING`. `SIGN_ONLY` No entanto, é possível fazer as alterações a seguir.
+ [Adicionar novos `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributos `ENCRYPT_AND_SIGN``SIGN_ONLY`, e](#ddb-add-auth-attribute)
+ [Remover atributos existentes](#ddb-remove-attribute)
+ [Alterar um `ENCRYPT_AND_SIGN` atributo existente para `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](#ddb-encrypt-to-sign)
+ [Alterar um existente `SIGN_ONLY` ou um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo para `ENCRYPT_AND_SIGN`](#ddb-sign-to-encrypt)
+ [Adicionar um novo atributo `DO_NOTHING`](#ddb-add-unauth-attribute)
+ [Alterar um atributo `SIGN_ONLY` existente para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`](#ddb-signOnly-to-signInclude)
+ [Alterar um atributo `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` existente para `SIGN_ONLY`](#ddb-signInclude-to-signOnly)

**Considerações sobre a criptografia pesquisável**  
Antes de atualizar o modelo de dados, considere cuidadosamente como as atualizações podem afetar os [beacons](beacons.md) que você construiu a partir dos atributos. Depois de gravar novos registros com o beacon, não será possível atualizar a configuração do beacon. Não é possível atualizar as ações de atributos associadas aos atributos que você usou para construir beacons. Se você remover um atributo existente e o beacon associado, não poderá consultar registros existentes usando esse beacon. É possível criar novos beacons para novos campos adicionados ao registro, mas não é possível atualizar os beacons existentes para incluir o novo campo.

**Considerações sobre atributos `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`**  
Por padrão, as chaves de partição e classificação são o único atributo incluído no contexto de criptografia. Você pode considerar definir campos adicionais para que o fornecedor da ID da chave de filial do seu [AWS KMS chaveiro hierárquico](use-hierarchical-keyring.md) possa identificar qual chave de ramificação é necessária para a descriptografia a partir `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` do contexto de criptografia. Para obter mais informações, consulte [fornecedor de ID de chave de filial](use-hierarchical-keyring.md#branch-key-id-supplier). Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

**nota**  
Para usar a ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, você deve usar a versão 3.3 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de [atualizar seu modelo de dados](#ddb-update-data-model) para incluí-la`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

## Adicionar novos `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributos `ENCRYPT_AND_SIGN``SIGN_ONLY`, e
<a name="ddb-add-auth-attribute"></a>

Para adicionar um novo`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, defina o novo atributo em suas ações de atributo.

Você não pode remover um `DO_NOTHING` atributo existente e adicioná-lo novamente como um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo `ENCRYPT_AND_SIGN``SIGN_ONLY`, ou.

**Usar uma classe de dados anotada**  
Se você definiu as ações de atributo com um `TableSchema`, adicione o novo atributo à sua classe de dados anotada com a anotação . Se você não especificar uma anotação de ação de atributo para o novo atributo, o cliente criptografará e assinará o novo atributo por padrão (a menos que o atributo faça parte da chave primária). Se quiser assinar apenas o novo atributo, você deve adicionar o novo atributo com a `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotação `@DynamoDBEncryptionSignOnly` ou.

**Usar um objeto de modelo**  
Se você definiu manualmente suas ações de atributo, adicione o novo atributo às ações de atributo em seu modelo de objeto e especifique`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` como a ação do atributo.

## Remover atributos existentes
<a name="ddb-remove-attribute"></a>

Se você decidir que não precisa mais de um atributo, pode parar de gravar dados nesse atributo ou removê-lo formalmente das ações de atributo. Quando você para de gravar novos dados em um atributo, o atributo ainda aparece nas ações de atributo. Isso pode ser útil se você precisar começar a usar o atributo novamente no futuro. A remoção formal do atributo das ações do atributo não o remove do conjunto de dados. O conjunto de dados ainda conterá itens que incluem esse atributo.

Para remover formalmente um `DO_NOTHING` atributo existente`ENCRYPT_AND_SIGN`,`SIGN_ONLY`, ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, atualize suas ações de atributo.

Se você remover um atributo `DO_NOTHING`, não deverá remover esse atributo dos [atributos não assinados permitidos](ddb-java-using.md#allowed-unauth). Mesmo que você não esteja mais gravando novos valores nesse atributo, o cliente ainda precisa saber que o atributo não está assinado para ler os itens existentes que contêm o atributo.

**Usar uma classe de dados anotada**  
Se você definiu as ações de atributo com um `TableSchema`, remova o novo atributo da classe de dados anotada.

**Usar um objeto de modelo**  
Se você definiu manualmente as ações de atributo, remova o atributo das ações de atributo em seu modelo de objeto.

## Alterar um `ENCRYPT_AND_SIGN` atributo existente para `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
<a name="ddb-encrypt-to-sign"></a>

Para alterar um `ENCRYPT_AND_SIGN` atributo existente para `SIGN_ONLY` ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, você deve atualizar suas ações de atributo. Depois de implantar a atualização, o cliente poderá verificar e descriptografar valores existentes gravados no atributo, mas só assinará novos valores gravados no atributo.

**nota**  
Considere cuidadosamente seus requisitos de segurança antes de alterar um `ENCRYPT_AND_SIGN` atributo existente para `SIGN_ONLY` ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Qualquer atributo que possa armazenar dados confidenciais deve ser criptografado.

**Usar uma classe de dados anotada**  
Se você definiu suas ações de atributo com um`TableSchema`, atualize o atributo existente para incluir a `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotação `@DynamoDBEncryptionSignOnly` ou em sua classe de dados anotada.

**Usar um objeto de modelo**  
Se você definiu manualmente suas ações de atributo, atualize a ação de atributo associada ao atributo existente de `ENCRYPT_AND_SIGN` para `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` em seu modelo de objeto.

## Alterar um existente `SIGN_ONLY` ou um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo para `ENCRYPT_AND_SIGN`
<a name="ddb-sign-to-encrypt"></a>

Para alterar um atributo existente `SIGN_ONLY` ou um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo para`ENCRYPT_AND_SIGN`, você deve atualizar suas ações de atributo. Depois de implantar a atualização, o cliente poderá verificar os valores existentes gravados no atributo, mas só criptografará e assinará novos valores gravados no atributo.

**Usar uma classe de dados anotada**  
Se você definiu suas ações de atributo com um`TableSchema`, remova a `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` anotação `@DynamoDBEncryptionSignOnly` ou do atributo existente.

**Usar um objeto de modelo**  
Se você definiu manualmente suas ações de atributo, atualize a ação de atributo associada ao atributo de `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` para `ENCRYPT_AND_SIGN` em seu modelo de objeto.

## Adicionar um novo atributo `DO_NOTHING`
<a name="ddb-add-unauth-attribute"></a>

[Para reduzir o risco de erro ao adicionar um novo atributo `DO_NOTHING`, recomendamos especificar um prefixo distinto ao nomear os atributos `DO_NOTHING` e, em seguida, usar esse prefixo para definir os atributos não assinados permitidos](ddb-java-using.md#allowed-unauth).

Você não pode remover um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo ou existente `ENCRYPT_AND_SIGN` da sua classe de dados anotada e depois adicionar o atributo novamente como um `DO_NOTHING` atributo. `SIGN_ONLY` Só é possível adicionar atributos `DO_NOTHING` totalmente novos.

As etapas que você executa para adicionar um novo atributo `DO_NOTHING` dependem de você ter definido os atributos não assinados permitidos explicitamente em uma lista ou com um prefixo.

**Uso de um prefixo de atributos não assinados permitido**  
Se você definiu suas ações de atributo com um `TableSchema`, adicione o novo atributo `DO_NOTHING` à sua classe de dados anotada com a anotação `@DynamoDBEncryptionDoNothing`. Se você definiu manualmente as ações de atributo, atualize as ações de atributo para incluir o novo atributo. Certifique-se de configurar explicitamente o novo atributo com a ação do atributo `DO_NOTHING`. Você deve incluir o mesmo prefixo distinto no nome do novo atributo.

**Uso de uma lista de atributos não assinados permitido**

1. Adicione o novo atributo `DO_NOTHING` à sua lista de atributos não assinados permitidos e implante a lista atualizada.

1. Implante a alteração da **Etapa 1**.

   Não é possível passar para a **Etapa 3** até que a alteração tenha se propagado para todos os hosts que precisam ler esses dados.

1. Adicione o novo atributo `DO_NOTHING` às ações de atributo.

   1. Se você definiu suas ações de atributo com um `TableSchema`, adicione o novo atributo `DO_NOTHING` à sua classe de dados anotada com a anotação `@DynamoDBEncryptionDoNothing`.

   1. Se você definiu manualmente as ações de atributo, atualize as ações de atributo para incluir o novo atributo. Certifique-se de configurar explicitamente o novo atributo com a ação do atributo `DO_NOTHING`.

1. Implante a alteração da **Etapa 3**.

## Alterar um atributo `SIGN_ONLY` existente para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`
<a name="ddb-signOnly-to-signInclude"></a>

Para alterar um atributo `SIGN_ONLY` existente para `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, você deve atualizar suas ações de atributo. Depois de implantar a atualização, o cliente poderá verificar os valores existentes gravados no atributo e continuará assinando novos valores gravados no atributo. Novos valores gravados no atributo serão incluídos no [contexto de criptografia](concepts.md#encryption-context).

Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

**Usar uma classe de dados anotada**  
Se você definiu suas ações de atributo com um`TableSchema`, atualize a ação de atributo associada ao atributo de `@DynamoDBEncryptionSignOnly` para`@DynamoDBEncryptionSignAndIncludeInEncryptionContext`.

**Usar um objeto de modelo**  
Se você definiu manualmente as ações de atributo, atualize a ação do atributo correspondente ao atributo de `SIGN_ONLY` ou `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` no modelo de objeto.

## Alterar um atributo `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` existente para `SIGN_ONLY`
<a name="ddb-signInclude-to-signOnly"></a>

Para alterar um atributo `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` existente para `SIGN_ONLY`, você deve atualizar suas ações de atributo. Depois de implantar a atualização, o cliente poderá verificar os valores existentes gravados no atributo e continuará assinando novos valores gravados no atributo. Novos valores gravados no atributo não serão incluídos no [contexto de criptografia](concepts.md#encryption-context).

Antes de alterar um `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo existente para`SIGN_ONLY`, considere cuidadosamente como suas atualizações podem afetar a funcionalidade do seu [fornecedor de ID de chave de filial](use-hierarchical-keyring.md#branch-key-id-supplier).

**Usar uma classe de dados anotada**  
Se você definiu suas ações de atributo com um`TableSchema`, atualize a ação de atributo associada ao atributo de `@DynamoDBEncryptionSignAndIncludeInEncryptionContext` para`@DynamoDBEncryptionSignOnly`.

**Usar um objeto de modelo**  
Se você definiu manualmente as ações de atributo, atualize a ação do atributo correspondente ao atributo de `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` ou `SIGN_ONLY` no modelo de objeto.

# AWS SDK de criptografia de banco de dados para linguagens de programação disponíveis do DynamoDB
<a name="ddb-programming-languages"></a>

O SDK AWS de criptografia de banco de dados para DynamoDB está disponível para as seguintes linguagens de programação. As bibliotecas específicas de linguagem variam, mas as implementações resultantes são interoperáveis. É possível criptografar com uma implementação de linguagem e descriptografar com outra. A interoperabilidade pode estar sujeita às restrições de linguagem. Em caso afirmativo, essas restrições estarão descritas no tópico sobre a implementação de linguagem. 

**Topics**
+ [Java](ddb-java.md)
+ [.NET](ddb-net.md)
+ [Rust](ddb-rust.md)

# Java
<a name="ddb-java"></a>


****  

|  | 
| --- |
| 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). | 

Este tópico explica como instalar a versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB. Para obter detalhes sobre a programação com o SDK AWS de criptografia de banco de dados para DynamoDB, consulte os exemplos de [Java no](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) repositório -dynamodb em aws-database-encryption-sdk. GitHub

**nota**  
Os tópicos a seguir se concentram na versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB.  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O SDK do AWS Database Encryption continua oferecendo suporte às versões [antigas do DynamoDB](legacy-dynamodb-encryption-client.md) Encryption Client.

**Topics**
+ [Pré-requisitos](#ddb-java-prerequisites)
+ [Instalação](#ddb-java-installation)
+ [Usar o cliente Java](ddb-java-using.md)
+ [Exemplos de Java](ddb-java-examples.md)
+ [Adicionar versão 3.x a uma tabela existente](ddb-java-config-existing-table.md)
+ [Migrar para a versão 3.x](ddb-java-migrate.md)

## Pré-requisitos
<a name="ddb-java-prerequisites"></a>

Antes de instalar a versão 3.*x* da bibioteca Java de criptografia do lado do cliente, verifique se você tem os pré-requisitos a seguir.

**Um ambiente de desenvolvimento Java**  
Você precisará do Java 8 ou posterior. No site da Oracle, acesse [Java SE Downloads](https://www.oracle.com/java/technologies/downloads/) e faça download e instale o Java SE Development Kit (JDK).  
Se você usa o Oracle JDK, também precisara fazer download e instalar os [arquivos de política de jurisdição de força ilimitada JCE (Java Cryptography Extension)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).

**AWS SDK for Java 2.x**  
O SDK AWS de criptografia de banco de dados para DynamoDB requer [o módulo DynamoDB Enhanced Client do.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) AWS SDK for Java 2.xÉ possível instalar todo o SDK ou apenas esse módulo.  
Para obter informações sobre como atualizar sua versão do AWS SDK para Java, consulte [Migração da versão 1.x para a 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html) do. AWS SDK para Java  
O AWS SDK para Java está disponível por meio do Apache Maven. Você pode declarar uma dependência para todo AWS SDK para Java o módulo ou apenas para o `dynamodb-enhanced` módulo.  

**Instale o AWS SDK para Java usando o Apache Maven**
+ Para [importar todo o AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#build-the-entire-sdk-into-your-project) como uma dependência, declare-o no arquivo `pom.xml`.
+ Para criar uma dependência somente para o módulo Amazon DynamoDB no AWS SDK para Java, siga as instruções para [especificar módulos específicos](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup-project-maven.html#modules-dependencies). Defina o `groupId` como `software.amazon.awssdk` e `artifactID` como `dynamodb-enhanced`.
**nota**  
Se você usar o AWS KMS chaveiro ou o AWS KMS chaveiro hierárquico, também precisará criar uma dependência para o módulo. AWS KMS Defina o `groupId` como `software.amazon.awssdk` e `artifactID` como `kms`.

## Instalação
<a name="ddb-java-installation"></a>

É possível instalar a versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB das formas a seguir.

**Uso do Apache Maven**  
O Amazon DynamoDB Encryption Client para Java está disponível por meio do [Apache Maven](https://maven.apache.org/) com a definição de dependência a seguir.  

```
<dependency>
  <groupId>software.amazon.cryptography</groupId>
  <artifactId>aws-database-encryption-sdk-dynamodb</artifactId>
  <version>version-number</version>
</dependency>
```

**Uso do Gradle Kotlin**  
É possível usar o [Gradle](https://gradle.org/) para declarar uma dependência no Amazon DynamoDB Encryption Client para Java adicionando o que se segue à seção de *dependências* do projeto Gradle.  

```
implementation("software.amazon.cryptography:aws-database-encryption-sdk-dynamodb:version-number")
```

**Manualmente**  
[Para instalar a biblioteca de criptografia Java do lado do cliente para o DynamoDB, clone ou baixe o repositório -dynamodb. aws-database-encryption-sdk](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) GitHub

Depois de instalar o SDK, comece examinando o código de exemplo neste guia e os [exemplos de Java no repositório](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) aws-database-encryption-sdk -dynamodb em. GitHub

# Uso do biblioteca Java de criptografia do lado do cliente para o DynamoDB
<a name="ddb-java-using"></a>


****  

|  | 
| --- |
| 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). | 

Este tópico explica algumas das funções e das classes auxiliares da versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB. 

[Para obter detalhes sobre a programação com a biblioteca de criptografia Java do lado do cliente para o DynamoDB, consulte os exemplos de Java, os [exemplos de Java](java-examples.md) no repositório -dynamodb em.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) aws-database-encryption-sdk GitHub

**Topics**
+ [Criptografadores de itens](#ddb-item-encryptors)
+ [Ações de atributos](#ddb-attribute-actions)
+ [Configuração de criptografia](#ddb-config-encrypt)
+ [Atualização de itens](#ddb-update-items)
+ [Descriptografar conjuntos assinados](#ddb-java-signed-sets)

## Criptografadores de itens
<a name="ddb-item-encryptors"></a>

Basicamente, o SDK AWS de criptografia de banco de dados para DynamoDB é um criptografador de itens. É possível usar a versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB para criptografar, assinar, verificar e descriptografar os itens da tabela do DynamoDB das maneiras a seguir.

**O DynamoDB Enhanced Client**  
É possível configurar o [DynamoDB Enhanced Client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) com `DynamoDbEncryptionInterceptor` o para criptografar e assinar automaticamente itens do lado do cliente com suas solicitações `PutItem` do DynamoDB. Com o DynamoDB Enhanced Client, é possível definir as ações de atributos usando uma [classe de dados anotada](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean). Recomendamos usar o DynamoDB Enhanced Client sempre que possível.  
O DynamoDB Enhanced Client [não oferece suporte à criptografia pesquisável](searchable-encryption.md).  
[O SDK AWS de criptografia de banco de dados não oferece suporte a anotações em atributos aninhados.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html)

**A API de nível inferior do DynamoDB**  
É possível configurar a [API de nível inferior do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html) com `DynamoDbEncryptionInterceptor` para criptografar e assinar automaticamente itens no lado do cliente com suas solicitações `PutItem` do DynamoDB.  
Você deve usar a API de nível inferior do DynamoDB para usar a [criptografia pesquisável](searchable-encryption.md).

**O `DynamoDbItemEncryptor` de nível inferior**  
O `DynamoDbItemEncryptor` de nível inferior criptografa, assina ou descriptografa e verifica diretamente os itens da tabela sem chamar o DynamoDB. Ele não faz solicitações `PutItem` ou `GetItem` para o DynamoDB. Por exemplo, é possível usar o `DynamoDbItemEncryptor` de nível inferior para descriptografar e verificar diretamente um item do DynamoDB que você já recuperou.  
O nível inferior do `DynamoDbItemEncryptor` não oferece suporte à [criptografia pesquisável](searchable-encryption.md).

## Ações de atributos no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-attribute-actions"></a>

[As ações](concepts.md#crypt-actions) de atributo determinam quais valores de atributos são criptografados e assinados, quais são somente assinados, quais são assinados e incluídos no contexto de criptografia e quais são ignorados.

**nota**  
Para usar a ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, você deve usar a versão 3.3 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de [atualizar seu modelo de dados](ddb-update-data-model.md) para incluí-la`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

Se você usar a API do DynamoDB de nível inferior ou a `DynamoDbItemEncryptor` de nível inferior, deverá definir manualmente suas ações de atributos. Se você usar o DynamoDB Enhanced Client, poderá definir manualmente suas ações de atributo ou usar uma classe de dados anotada para [gerar um `TableSchema`](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html). Para simplificar o processo de configuração, recomendamos o uso de uma classe de dados anotada. Ao usar uma classe de dados anotada, você só precisa modelar seu objeto uma vez.

**nota**  
Depois de definir suas ações de atributo, você deverá definir quais atributos serão excluídos das assinaturas. Para facilitar a adição de novos atributos não assinados no futuro, recomendamos escolher um prefixo distinto (como "`:`") para identificar os atributos não assinados. Inclua esse prefixo no nome do atributo para todos os atributos marcados como `DO_NOTHING` ao definir o esquema e as ações de atributos do DynamoDB.

### Uso de uma classe de dados anotada
<a name="ddb-attribute-actions-annotated-data-class"></a>

Use uma [classe de dados anotada](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) para especificar suas ações de atributos com o DynamoDB Enhanced Client e `DynamoDbEncryptionInterceptor`. O SDK de criptografia de banco de dados da AWS usa as [anotações de atributo padrão do DynamoDB](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/package-summary.html) que definem o tipo do atributo para determinar como proteger um atributo. Por padrão, todos os atributos são criptografados e assinados, exceto as chaves primárias, que são assinadas, mas não são criptografadas.

**nota**  
Para usar a ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, você deve usar a versão 3.3 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de [atualizar seu modelo de dados](ddb-update-data-model.md) para incluí-la`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

Consulte [SimpleClass.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) no repositório aws-database-encryption-sdk -dynamodb em GitHub para obter mais orientações sobre as anotações do DynamoDB Enhanced Client.

Por padrão, os atributos da chave primária são assinados, mas não criptografados (`SIGN_ONLY`), e todos os outros atributos são criptografados e assinados (`ENCRYPT_AND_SIGN`). Se você definir qualquer atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Para especificar exceções, use as anotações de criptografia definidas na biblioteca de criptografia do lado do cliente para Java do DynamoDB. Por exemplo, se você quiser que um atributo específico seja somente assinado, use a anotação `@DynamoDbEncryptionSignOnly`. Se você quiser que um atributo específico seja assinado e incluído no contexto de criptografia, use `@DynamoDbEncryptionSignAndIncludeInEncryptionContext` o. Se desejar que um atributo específico não seja assinado nem criptografado (`DO_NOTHING`), use a anotação `@DynamoDbEncryptionDoNothing`.

**nota**  
[O SDK AWS de criptografia de banco de dados não oferece suporte a anotações em atributos aninhados.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html)

O exemplo a seguir mostra as anotações usadas para definir `ENCRYPT_AND_SIGN` e `DO_NOTHING` atribuir ações. `SIGN_ONLY` [Para ver um exemplo que mostra as anotações usadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte SimpleClass 4.java.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java)

```
@DynamoDbBean
public class SimpleClass {

    private String partitionKey;
    private int sortKey;
    private String attribute1;
    private String attribute2;
    private String attribute3;

    @DynamoDbPartitionKey
    @DynamoDbAttribute(value = "partition_key")
    public String getPartitionKey() {
        return this.partitionKey;
    }

    public void setPartitionKey(String partitionKey) {
        this.partitionKey = partitionKey;
    }

    @DynamoDbSortKey
    @DynamoDbAttribute(value = "sort_key")
    public int getSortKey() {
        return this.sortKey;
    }

    public void setSortKey(int sortKey) {
        this.sortKey = sortKey;
    }

    public String getAttribute1() {
        return this.attribute1;
    }

    public void setAttribute1(String attribute1) {
        this.attribute1 = attribute1;
    }

    @DynamoDbEncryptionSignOnly
    public String getAttribute2() {
        return this.attribute2;
    }

    public void setAttribute2(String attribute2) {
        this.attribute2 = attribute2;
    }

    @DynamoDbEncryptionDoNothing
    public String getAttribute3() {
        return this.attribute3;
    }

    @DynamoDbAttribute(value = ":attribute3")
    public void setAttribute3(String attribute3) {
        this.attribute3 = attribute3;
    }
    
}
```

Use a classe de dados anotada para criar o `TableSchema`, conforme mostrado no snippet a seguir.

```
final TableSchema<SimpleClass> tableSchema = TableSchema.fromBean(SimpleClass.class);
```

### Definir as ações de atributos manualmente
<a name="ddb-attribute-actions-manual"></a>

Para especificar manualmente ações de atributos, crie um objeto `Map` em que pares de nome-valor representam os nomes de atributos e as ações especificadas.

Especifique `ENCRYPT_AND_SIGN` para criptografar e assinar um atributo. Especifique `SIGN_ONLY` para assinar, mas não criptografar um atributo. Especifique `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` para assinar um atributo e incluí-lo no contexto de criptografia. Não é possível criptografar um atributo sem também assiná-lo. Especifique `DO_NOTHING` para ignorar um atributo.

Os atributos de partição e classificação devem ser `SIGN_ONLY` ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você definir qualquer atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

**nota**  
Para usar a ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, você deve usar a versão 3.3 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de [atualizar seu modelo de dados](ddb-update-data-model.md) para incluí-la`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be signed
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT); 
// The sort attribute must be signed
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put("attribute3", CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT);
attributeActionsOnEncrypt.put(":attribute4", CryptoAction.DO_NOTHING);
```

## Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-config-encrypt"></a>

Ao usar o AWS Database Encryption SDK, você deve definir explicitamente uma configuração de criptografia para sua tabela do DynamoDB. Os valores necessários em sua configuração de criptografia dependem se você definiu suas ações de atributo manualmente ou com uma classe de dados anotada.

O snippet a seguir define uma configuração de criptografia de tabela do DynamoDB usando o DynamoDB Enhanced Client, [https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html), e permite atributos não assinados definidos por um prefixo distinto.

```
final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
        DynamoDbEnhancedTableEncryptionConfig.builder()
            .logicalTableName(ddbTableName)
            .keyring(kmsKeyring)
            .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
            .schemaOnEncrypt(tableSchema)
            // Optional: only required if you use beacons
            .search(SearchConfig.builder() 
                    .writeVersion(1) // MUST be 1
                    .versions(beaconVersions)
                    .build())         
            .build());
```

**Nome da tabela lógica**  
Um nome de tabela lógica para sua tabela do DynamoDB.  
O nome da tabela lógica é vinculado criptograficamente a todos os dados armazenados na tabela para simplificar as operações de restauração do DynamoDB. É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Você deve sempre especificar o mesmo nome de tabela lógica. Para que a descriptografia seja bem-sucedida, o nome da tabela lógica deve corresponder ao nome especificado na criptografia. Se o nome da tabela do DynamoDB mudar após a [restauração da tabela do DynamoDB a partir de um backup](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html), o nome da tabela lógica garantirá que a operação de descriptografia ainda reconheça a tabela.

**Atributos não assinados permitidos**  
Os atributos marcados `DO_NOTHING` em suas ações de atributos.  
Os atributos não assinados permitidos informam ao cliente quais atributos são excluídos das assinaturas. O cliente presume que todos os outros atributos estão incluídos na assinatura. Em seguida, ao descriptografar um registro, o cliente determina quais atributos ele precisa verificar e quais ignorar dos atributos não assinados permitidos que você especificou. Não é possível remover um atributo dos atributos não assinados permitidos.  
É possível definir explicitamente os atributos não assinados permitidos criando uma matriz que lista todos os atributos `DO_NOTHING`. Também é possível especificar um prefixo distinto ao nomear os atributos `DO_NOTHING` e usar o prefixo para informar ao cliente quais atributos não estão assinados. É altamente recomendável especificar um prefixo distinto, pois isso simplifica o processo de adicionar um novo atributo `DO_NOTHING` no futuro. Para obter mais informações, consulte [Atualizar seu modelo de dados](ddb-update-data-model.md).  
Se você não especificar um prefixo para todos os atributos `DO_NOTHING`, poderá configurar uma matriz `allowedUnsignedAttributes` que liste explicitamente todos os atributos que o cliente deve esperar que não estejam assinados ao encontrá-los na descriptografia. Você só deve definir explicitamente seus atributos não assinados permitidos se for absolutamente necessário.

**Configuração de pesquisa (opcional)**  
O `SearchConfig` define a [versão do beacon](using-beacons.md#beacon-version).  
O `SearchConfig` deve ser especificado para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons).

**Conjunto de algoritmos (opcional)**  
O `algorithmSuiteId` define qual conjunto de algoritmos o SDK de criptografia de banco de dados da AWS usará.  
A menos que você especifique explicitamente um conjunto alternativo de algoritmos, o SDK do AWS Database Encryption usa o conjunto de [algoritmos padrão](supported-algorithms.md#recommended-algorithms). O conjunto de algoritmos padrão usa o algoritmo AES-GCM com derivação de chaves, [assinaturas digitais](concepts.md#digital-sigs) e [comprometimento de chaves](concepts.md#key-commitment). Embora o conjunto de algoritmos padrão provavelmente seja adequado para a maioria dos aplicativos, é possível escolher um conjunto alternativo de algoritmos. Por exemplo, alguns modelos de confiança seriam satisfeitos com um pacote de algoritmos sem assinaturas digitais. Para obter informações sobre os conjuntos de algoritmos compatíveis com o SDK do AWS Database Encryption, consulte[Suítes de algoritmos compatíveis no SDK AWS de criptografia de banco de dados](supported-algorithms.md).  
Para selecionar o [conjunto de algoritmos AES-GCM sem assinaturas digitais ECDSA](supported-algorithms.md#other-algorithms), inclua o seguinte trecho em sua configuração de criptografia de tabela.  

```
.algorithmSuiteId(
    DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384)
```

## Atualização de itens com o SDK AWS de criptografia de banco de dados
<a name="ddb-update-items"></a>

O SDK AWS de criptografia de banco de dados não oferece suporte a [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para itens que foram criptografados ou assinados. Para atualizar um item criptografado ou assinado, você deve usar [ddb: PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html). Se algum item existir em uma tabela específica com a mesma chave primária de um item existente na consulta `PutItem`, o novo item substituirá completamente o item já existente. Também é possível usar o [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) para limpar e substituir todos os atributos ao salvar após atualizar seus itens.

## Descriptografar conjuntos assinados
<a name="ddb-java-signed-sets"></a>

Nas versões 3.0.0 e 3.1.0 do SDK de criptografia de AWS banco de dados, se você definir um atributo de [tipo de conjunto](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes.SetTypes) como`SIGN_ONLY`, os valores do conjunto serão canonizados na ordem em que são fornecidos. O DynamoDB não preserva a ordem dos conjuntos. Como resultado, é possível que a validação da assinatura do item que contém o conjunto falhe. A validação da assinatura falha quando os valores do conjunto são retornados em uma ordem diferente da fornecida ao SDK do AWS Database Encryption, mesmo que os atributos do conjunto contenham os mesmos valores.

**nota**  
As versões 3.1.1 e posteriores do SDK do AWS Database Encryption canonizam os valores de todos os atributos do tipo definido, de forma que os valores sejam lidos na mesma ordem em que foram gravados no DynamoDB.

Se houver falha na validação da assinatura, a operação de descriptografia falhará e retornará a seguinte mensagem de erro:


|  | 
| --- |
| software.amazon.cryptography.dbencryptionsdk.structuredencryption.model. StructuredEncryptionException: Nenhuma etiqueta de destinatário correspondeu. | 

Se você receber a mensagem de erro acima e acreditar que o item que está tentando descriptografar inclui um conjunto que foi assinado usando a versão 3.0.0 ou 3.1.0, consulte o [DecryptWithPermute](https://github.com/aws/aws-database-encryption-sdk-dynamodb-java/tree/v3.1.1/DecryptWithPermute)diretório do repositório aws-database-encryption-sdk -dynamodb-java em para obter detalhes sobre GitHub como validar o conjunto com êxito.

# Exemplos de Java
<a name="ddb-java-examples"></a>


****  

|  | 
| --- |
| 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 mostram como usar a biblioteca de criptografia do lado do cliente para o DynamoDB para proteger os itens da tabela no aplicativo. Você pode encontrar mais exemplos (e contribuir com os seus) nos [exemplos de Java no repositório](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples) aws-database-encryption-sdk -dynamodb em. GitHub

Os exemplos a seguir demonstram como configurar a biblioteca Java de criptografia do lado do cliente para o DynamoDB em uma nova tabela não preenchida do Amazon DynamoDB. Se você quiser configurar suas tabelas existentes do Amazon DynamoDB para criptografia do lado do cliente, consulte [Adicionar versão 3.x a uma tabela existente](ddb-java-config-existing-table.md).

**Topics**
+ [Uso do cliente aprimorado do DynamoDB](#ddb-java-enhanced-client-example)
+ [Uso da API de nível inferior do DynamoDB](#ddb-java-lowlevel-API-example)
+ [Usando o nível inferior DynamoDbItemEncryptor](#ddb-java-itemencryptor)

## Uso do cliente aprimorado do DynamoDB
<a name="ddb-java-enhanced-client-example"></a>

O exemplo a seguir mostra como usar o DynamoDB Enhanced Client e o `DynamoDbEncryptionInterceptor` com um [token de autenticação do AWS KMS](use-kms-keyring.md) para criptografar itens da tabela do DynamoDB como parte de suas chamadas de API do DynamoDB.

Você pode usar qualquer [chaveiro](keyrings.md) compatível com o DynamoDB Enhanced Client, mas recomendamos usar um dos AWS KMS chaveiros sempre que possível.

**nota**  
O DynamoDB Enhanced Client [não oferece suporte à criptografia pesquisável](searchable-encryption.md). Use o `DynamoDbEncryptionInterceptor` com a API de nível inferior do DynamoDB para usar criptografia pesquisável.

**Veja a amostra de código completa**: [EnhancedPutGetExample.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/EnhancedPutGetExample.java)

**Etapa 1: criar o AWS KMS chaveiro**  
O exemplo a seguir é usado `CreateAwsKmsMrkMultiKeyring` para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**Etapa 2: criar um esquema de tabela a partir da classe de dados anotada**  
O exemplo a seguir usa a classe de dados anotada para criar o `TableSchema`.  
[Este exemplo pressupõe que as ações de classe e atributo de dados anotadas foram definidas usando o .java. SimpleClass](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) Para obter mais orientações sobre como anotar suas ações de atributos, consulte [Uso de uma classe de dados anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).  
[O SDK AWS de criptografia de banco de dados não oferece suporte a anotações em atributos aninhados.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-adv-features-nested.html)

```
final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);
```

**Etapa 3: definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presume que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).  

```
final String unsignedAttrPrefix = ":";
```

**Etapa 4: criar a configuração de criptografia**  
O exemplo a seguir define um mapa `tableConfigs` que representa a configuração de criptografia dessa tabela do DynamoDB.   
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-java-using.md#logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-java-using.md#ddb-config-encrypt).  
Para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons), você também deve incluir [`SearchConfig`](ddb-java-using.md#ddb-search-config) na configuração de criptografia.

```
final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
tableConfigs.put(ddbTableName,
    DynamoDbEnhancedTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .schemaOnEncrypt(tableSchema)
        .build());
```

**Etapa 5: cria o `DynamoDbEncryptionInterceptor`**  
O exemplo a seguir cria o `DynamoDbEncryptionInterceptor` usando `tableConfigs` da **Etapa 4**.  

```
final DynamoDbEncryptionInterceptor interceptor =
    DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
        CreateDynamoDbEncryptionInterceptorInput.builder()
            .tableEncryptionConfigs(tableConfigs)
            .build()
    );
```

**Etapa 6: criar um novo cliente AWS SDK do DynamoDB**  
**O exemplo a seguir cria um novo cliente AWS SDK do DynamoDB usando `interceptor` o da Etapa 5.**  

```
final DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(
                ClientOverrideConfiguration.builder()
                       .addExecutionInterceptor(interceptor)
                       .build())
        .build();
```

**Etapa 7: criar o DynamoDB Enhanced Client e criar uma tabela**  
O exemplo a seguir cria o DynamoDB Enhanced Client usando o cliente AWS SDK DynamoDB criado na **Etapa 6** e cria uma tabela usando a classe de dados anotada.  

```
final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
        .dynamoDbClient(ddb)
        .build();
final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
```

**Etapa 8: criptografar e salvar um item da tabela**  
O exemplo a seguir coloca um item na tabela do DynamoDB usando o DynamoDB Enhanced Client. O item é criptografado e assinado no lado do cliente antes de ser enviado ao DynamoDB.  

```
final SimpleClass item = new SimpleClass();
item.setPartitionKey("EnhancedPutGetExample");
item.setSortKey(0);
item.setAttribute1("encrypt and sign me!");
item.setAttribute2("sign me!");
item.setAttribute3("ignore me!");

table.putItem(item);
```

## Uso da API de nível inferior do DynamoDB
<a name="ddb-java-lowlevel-API-example"></a>

O exemplo a seguir mostra como usar a API de nível inferior do DynamoDB com um [token de autenticação do AWS KMS](use-kms-keyring.md) para criptografar e assinar automaticamente itens no lado do cliente com suas solicitações `PutItem` do DynamoDB.

Você pode usar qualquer [chaveiro](keyrings.md) compatível, mas recomendamos usar um dos AWS KMS chaveiros sempre que possível.

**Veja a amostra de código completa**: [BasicPutGetExample.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/BasicPutGetExample.java)

**Etapa 1: criar o AWS KMS chaveiro**  
O exemplo a seguir é usado `CreateAwsKmsMrkMultiKeyring` para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
final MaterialProviders matProv = MaterialProviders.builder()
         .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
         .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**Etapa 2: Configurar ações de atributos**  
O exemplo a seguir define um mapa `attributeActionsOnEncrypt` que representa exemplos de [ações de atributos](concepts.md#crypt-actions) para um item da tabela.  
O exemplo a seguir não define nenhum atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY); 
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);
```

**Etapa 3: definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presume que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).  

```
final String unsignedAttrPrefix = ":";
```

**Etapa 4: definir a configuração de criptografia de tabelas do DynamoDB**  
O exemplo a seguir define um mapa `tableConfigs` que representa a configuração de criptografia dessa tabela do DynamoDB.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-java-using.md#logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-java-using.md#ddb-config-encrypt).  
Para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons), você também deve incluir [`SearchConfig`](ddb-java-using.md#ddb-search-config) na configuração de criptografia.

```
final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .attributeActionsOnEncrypt(attributeActionsOnEncrypt)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .build();
tableConfigs.put(ddbTableName, config);
```

**Etapa 5: criar o perfil do `DynamoDbEncryptionInterceptor`**  
O exemplo a seguir cria o `DynamoDbEncryptionInterceptor` usando `tableConfigs` da **Etapa 4**.  

```
DynamoDbEncryptionInterceptor interceptor = DynamoDbEncryptionInterceptor.builder()
        .config(DynamoDbTablesEncryptionConfig.builder()
                .tableEncryptionConfigs(tableConfigs)
                .build())
        .build();
```

**Etapa 6: criar um novo cliente AWS SDK do DynamoDB**  
**O exemplo a seguir cria um novo cliente AWS SDK do DynamoDB usando `interceptor` o da Etapa 5.**  

```
final DynamoDbClient ddb = DynamoDbClient.builder()
        .overrideConfiguration(
                ClientOverrideConfiguration.builder()
                       .addExecutionInterceptor(interceptor)
                       .build())
        .build();
```

**Etapa 7: criptografar e assinar um item da tabela do DynamoDB**  
O exemplo a seguir define um mapa `item` que representa um item da tabela de exemplo e coloca o item na tabela do DynamoDB. O item é criptografado e assinado no lado do cliente antes de ser enviado ao DynamoDB.  

```
final HashMap<String, AttributeValue> item = new HashMap<>();
item.put("partition_key", AttributeValue.builder().s("BasicPutGetExample").build());
item.put("sort_key", AttributeValue.builder().n("0").build());
item.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
item.put("attribute2", AttributeValue.builder().s("sign me!").build());
item.put(":attribute3", AttributeValue.builder().s("ignore me!").build());

final PutItemRequest putRequest = PutItemRequest.builder()
        .tableName(ddbTableName)
        .item(item)
        .build();

final PutItemResponse putResponse = ddb.putItem(putRequest);
```

## Usando o nível inferior DynamoDbItemEncryptor
<a name="ddb-java-itemencryptor"></a>

O exemplo a seguir mostra como usar o nível inferior de `DynamoDbItemEncryptor` com um [token de autenticação do AWS KMS](use-kms-keyring.md) para criptografar e assinar diretamente os itens da tabela. O `DynamoDbItemEncryptor` não coloca o item na tabela do DynamoDB.

Você pode usar qualquer [chaveiro](keyrings.md) compatível com o DynamoDB Enhanced Client, mas recomendamos usar um dos AWS KMS chaveiros sempre que possível.

**nota**  
O nível inferior do `DynamoDbItemEncryptor` não oferece suporte à [criptografia pesquisável](searchable-encryption.md). Use o `DynamoDbEncryptionInterceptor` com a API de nível inferior do DynamoDB para usar criptografia pesquisável.

**Veja a amostra de código completa**: [ItemEncryptDecryptExample.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/itemencryptor/ItemEncryptDecryptExample.java)

**Etapa 1: criar o AWS KMS chaveiro**  
O exemplo a seguir é usado `CreateAwsKmsMrkMultiKeyring` para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
final MaterialProviders matProv = MaterialProviders.builder()
         .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
         .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**Etapa 2: Configurar ações de atributos**  
O exemplo a seguir define um mapa `attributeActionsOnEncrypt` que representa exemplos de [ações de atributos](concepts.md#crypt-actions) para um item da tabela.  
O exemplo a seguir não define nenhum atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
final Map<String, CryptoAction> attributeActionsOnEncrypt = new HashMap<>();
// The partition attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("partition_key", CryptoAction.SIGN_ONLY); 
// The sort attribute must be SIGN_ONLY
attributeActionsOnEncrypt.put("sort_key", CryptoAction.SIGN_ONLY); 
attributeActionsOnEncrypt.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
attributeActionsOnEncrypt.put("attribute2", CryptoAction.SIGN_ONLY);
attributeActionsOnEncrypt.put(":attribute3", CryptoAction.DO_NOTHING);
```

**Etapa 3: definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presume que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).  

```
final String unsignedAttrPrefix = ":";
```

**Etapa 4: definir a configuração de `DynamoDbItemEncryptor`**  
O exemplo a seguir define a configuração para `DynamoDbItemEncryptor`.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-java-using.md#logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-java-using.md#ddb-config-encrypt).  

```
final DynamoDbItemEncryptorConfig config = DynamoDbItemEncryptorConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .attributeActionsOnEncrypt(attributeActionsOnEncrypt)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .build();
```

**Etapa 5: criar o perfil do `DynamoDbItemEncryptor`**  
O exemplo a seguir cria um novo `DynamoDbItemEncryptor` usando `config` da **Etapa 4**.  

```
final DynamoDbItemEncryptor itemEncryptor = DynamoDbItemEncryptor.builder()
        .DynamoDbItemEncryptorConfig(config)
        .build();
```

**Etapa 6: criptografar e assinar diretamente um item da tabela**  
O exemplo a seguir criptografa e assina diretamente um item usando o `DynamoDbItemEncryptor`. O `DynamoDbItemEncryptor` não coloca o item na tabela do DynamoDB.  

```
final Map<String, AttributeValue> originalItem = new HashMap<>();
originalItem.put("partition_key", AttributeValue.builder().s("ItemEncryptDecryptExample").build());
originalItem.put("sort_key", AttributeValue.builder().n("0").build());
originalItem.put("attribute1", AttributeValue.builder().s("encrypt and sign me!").build());
originalItem.put("attribute2", AttributeValue.builder().s("sign me!").build());
originalItem.put(":attribute3", AttributeValue.builder().s("ignore me!").build());

final Map<String, AttributeValue> encryptedItem = itemEncryptor.EncryptItem(
        EncryptItemInput.builder()
                .plaintextItem(originalItem)
                .build()
).encryptedItem();
```

# Configurar uma tabela existente do DynamoDB para usar o SDK de criptografia de banco de dados para AWS o DynamoDB
<a name="ddb-java-config-existing-table"></a>


****  

|  | 
| --- |
| 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 versão 3.*x* da biblioteca Java de criptografia do lado do cliente para DynamoDB, é possível configurar as tabelas existentes do Amazon DynamoDB para a criptografia do lado do cliente. Este tópico fornece orientação sobre as três etapas que você deve seguir para adicionar a versão 3.*x* para uma tabela existente e preenchida do DynamoDB.

**Pré-requisitos**  
A versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB requer o [DynamoDB Enhanced Client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) fornecido em AWS SDK for Java 2.x . Se você ainda usa o [Dynamo DBMapper](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html), deve migrar AWS SDK for Java 2.x para o DynamoDB Enhanced Client.

 Siga as instruções para [migrar da versão 1.x para a 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html) do AWS SDK para Java.

Em seguida, siga as instruções para [Começar a usar a API do DynamoDB Enhanced Client.](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started.html)

Antes de configurar sua tabela para usar a biblioteca Java de criptografia do lado do cliente para o DynamoDB, você precisa gerar `TableSchema` [usando uma classe de dados anotada](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html#ddb-en-client-gs-tableschema-anno-bean) e [criar um cliente aprimorado](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).

## Etapa 1: preparar para ler e gravar itens criptografados
<a name="ddb-java-add-step1"></a>

Conclua as etapas a seguir para preparar seu cliente SDK AWS de criptografia de banco de dados para ler e gravar itens criptografados. Depois de implantar as alterações a seguir, seu cliente continuará lendo e gravando itens de texto simples. Ele não criptografará nem assinará nenhum novo item gravado na tabela, mas poderá descriptografar itens criptografados assim que eles aparecerem. Essas mudanças preparam o cliente para começar a [criptografar novos itens](#ddb-java-add-step2). As alterações a seguir devem ser implantadas em cada leitor antes de prosseguir para a próxima etapa.

**1. Definir suas [ações de atributos](concepts.md#crypt-actions)**  
Atualize sua classe de dados anotada para incluir ações de atributos que definam quais valores de atributos serão criptografados e assinados, quais serão somente assinados e quais serão ignorados.  
Consulte o [SimpleClassarquivo.java](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass.java) no repositório aws-database-encryption-sdk -dynamodb em GitHub para obter mais orientações sobre as anotações do DynamoDB Enhanced Client.  
Por padrão, os atributos da chave primária são assinados, mas não criptografados (`SIGN_ONLY`), e todos os outros atributos são criptografados e assinados (`ENCRYPT_AND_SIGN`). Para especificar exceções, use as anotações de criptografia definidas na biblioteca de criptografia do lado do cliente para Java do DynamoDB. Por exemplo, se você quiser que um atributo específico seja assinado, use apenas a anotação `@DynamoDbEncryptionSignOnly`. Se você quiser que um atributo específico seja assinado e incluído no contexto de criptografia, use a `@DynamoDbEncryptionSignAndIncludeInEncryptionContext` anotação. Se desejar que um atributo específico não seja assinado nem criptografado (`DO_NOTHING`), use a anotação `@DynamoDbEncryptionDoNothing`.  
Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. [Para ver um exemplo que mostra as anotações usadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte SimpleClass 4.java.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java)
Por obter exemplos de anotações, consulte [Uso de uma classe de dados anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).

**2. Definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presumirá que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-java-using.md#allowed-unauth).  

```
final String unsignedAttrPrefix = ":";
```

**3. Criar um [token de autenticação](keyrings.md)**  
O exemplo a seguir cria um [token de autenticação do AWS KMS](use-kms-keyring.md). O AWS KMS chaveiro usa criptografia simétrica ou RSA assimétrica AWS KMS keys para gerar, criptografar e descriptografar chaves de dados.  
Este exemplo usa `CreateMrkMultiKeyring` para criar um token de autenticação do AWS KMS com uma chave do KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
final MaterialProviders matProv = MaterialProviders.builder()
        .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
        .build();
final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
        .generator(kmsKeyId)
        .build();
final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**4. Definir a configuração de criptografia de tabelas do DynamoDB **  
O exemplo a seguir define um mapa `tableConfigs` que representa a configuração de criptografia dessa tabela do DynamoDB.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-java-using.md#logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-java-using.md#ddb-config-encrypt).  
Você deve especificar `FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT` como substituição de texto simples. Essa política continua lendo e gravando itens de texto simples, lendo itens criptografados e preparando o cliente para gravar itens criptografados.  

```
final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .schemaOnEncrypt(tableSchema)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .plaintextOverride(PlaintextOverride.FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT)
        .build();
tableConfigs.put(ddbTableName, config);
```

**5. Criar a `DynamoDbEncryptionInterceptor`**  
O exemplo a seguir cria o `DynamoDbEncryptionInterceptor` usando `tableConfigs` da **Etapa 3**.  

```
DynamoDbEncryptionInterceptor interceptor = DynamoDbEncryptionInterceptor.builder()
        .config(DynamoDbTablesEncryptionConfig.builder()
                .tableEncryptionConfigs(tableConfigs)                
                .build())
        .build();
```

## Etapa 2: gravar itens criptografados e assinados
<a name="ddb-java-add-step2"></a>

Atualize a política de texto simples em sua configuração `DynamoDbEncryptionInterceptor` para permitir que o cliente grave itens criptografados e assinados. Depois de implantar a seguinte alteração, o cliente criptografará e assinará novos itens com base nas ações de atributos que você configurou na **Etapa 1**. O cliente poderá ler itens de texto simples e itens criptografados e assinados.

Antes de prosseguir para a [Etapa 3](#ddb-java-add-step3), você deve criptografar e assinar todos os itens de texto sem formatação existentes em sua tabela. Não há uma única métrica ou consulta que você possa executar para criptografar rapidamente seus itens de texto sem formatação existentes. Use o processo que faz mais sentido para o seu sistema. Por exemplo, é possível usar um processo assíncrono que varre lentamente a tabela e reescreve os itens usando as ações de atributos e a configuração de criptografia que você definiu. Para identificar os itens de texto simples em sua tabela, recomendamos escanear todos os itens que não contêm os `aws_dbe_foot` atributos `aws_dbe_head` e que o SDK de criptografia de AWS banco de dados adiciona aos itens quando eles são criptografados e assinados.

O exemplo a seguir atualiza a configuração de criptografia de tabela da **Etapa 1**. Você deve atualizar a substituição de texto simples com `FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`. Essa política continua lendo itens de texto simples, mas também lê e grava itens criptografados. Crie um novo `DynamoDbEncryptionInterceptor` usando o atualizado`tableConfigs`.

```
final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .schemaOnEncrypt(tableSchema)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        .plaintextOverride(PlaintextOverride.FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT)
        .build();
tableConfigs.put(ddbTableName, config);
```

## Etapa 3: somente ler itens criptografados e assinados
<a name="ddb-java-add-step3"></a>

Depois de criptografar e assinar todos os seus itens, atualize a substituição de texto simples na configuração `DynamoDbEncryptionInterceptor` para permitir que o cliente somente leia e grave itens criptografados e assinados. Depois de implantar a seguinte alteração, o cliente criptografará e assinará novos itens com base nas ações de atributos que você configurou na **Etapa 1**. O cliente só poderá ler itens criptografados e assinados.

O exemplo a seguir atualiza a configuração de criptografia de tabela da **Etapa 2**. É possível atualizar a substituição de texto sem formatação com `FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT` ou remover a política de texto sem formatação da sua configuração. Por padrão, o cliente só lê e grava itens criptografados e assinados. Crie um novo `DynamoDbEncryptionInterceptor` usando o atualizado`tableConfigs`.

```
final Map<String, DynamoDbTableEncryptionConfig> tableConfigs = new HashMap<>();
final DynamoDbTableEncryptionConfig config = DynamoDbTableEncryptionConfig.builder()
        .logicalTableName(ddbTableName)
        .partitionKeyName("partition_key")
        .sortKeyName("sort_key")
        .schemaOnEncrypt(tableSchema)
        .keyring(kmsKeyring)
        .allowedUnsignedAttributePrefix(unsignedAttrPrefix)
        // Optional: you can also remove the plaintext policy from your configuration
        .plaintextOverride(PlaintextOverride.FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT)
        .build();
tableConfigs.put(ddbTableName, config);
```

# Migrar para a versão 3.x da biblioteca Java de criptografia do lado do cliente para o DynamoDB
<a name="ddb-java-migrate"></a>


****  

|  | 
| --- |
| 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 Versão 3.*x* da biblioteca Java de criptografia do lado do cliente para DynamoDB é uma grande reescrita da base de código 2.*x*. Ela inclui muitas atualizações, como um novo formato de dados estruturados, suporte aprimorado para multilocação, alterações de esquema contínuas e suporte à criptografia pesquisável. Este tópico fornece orientação sobre como migrar seu código para a versão 3.*x*.

## Migrar da versão 1.x para a versão 2.x
<a name="ddb-java-v1-to-v2"></a>

Migre para a versão 2.*x* antes de migrar para a versão 3.*x.*. A versão 2.*x* mudou o símbolo do provedor mais recente de `MostRecentProvider` para `CachingMostRecentProvider`. Se você usa atualmente a versão 1.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB com o símbolo `MostRecentProvider`, você deverá atualizar o nome do símbolo em seu código para `CachingMostRecentProvider`. Para obter mais informações, consulte [Atualizações do provedor mais recente](most-recent-provider.md#mrp-versions).

## Migrar da versão 2.x para a versão 3.x
<a name="ddb-java-v2-to-v3"></a>

Os procedimentos a seguir descrevem como migrar seu código da versão 2.*x* para a versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB.

### Etapa 1. Preparar para ler itens no novo formato
<a name="ddb-java-migrate-step1"></a>

Conclua as etapas a seguir para preparar seu cliente SDK do AWS Database Encryption para ler itens no novo formato. Depois de implantar as alterações a seguir, seu cliente continuará se comportando da mesma maneira que na versão 2.*x*. Seu cliente continuará lendo e gravando itens no formato da versão 2.*x*, mas essas alterações preparam o cliente para [ler itens no novo formato](#ddb-java-migrate-step2).

**Atualize seu AWS SDK para Java para a versão 2.x**  
A versão 3.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB requer o [DynamoDB Enhanced Client](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html). O DynamoDB Enhanced Client substitui o [DBMapperDynamo usado nas versões anteriores](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html). Para usar o cliente aprimorado, você deve usar o AWS SDK for Java 2.x.   
Siga as instruções para [migrar da versão 1.x para a 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html) do AWS SDK para Java.  
Para obter mais informações sobre quais AWS SDK for Java 2.x módulos são necessários, consulte[Pré-requisitos](ddb-java.md#ddb-java-prerequisites).

**Configurar seu cliente para ler itens criptografados por versões legadas**  
Os procedimentos a seguir fornecem uma visão geral das etapas demonstradas no exemplo de código abaixo.  

1. Crie um [token de autenticação](keyrings.md).

   Os tokens de autenticação e os [gerenciadores de materiais criptográficos](concepts.md#crypt-materials-manager) substituem os fornecedores de materiais criptográficos usados nas versões anteriores da biblioteca Java de criptografia do lado do cliente para o DynamoDB.
**Importante**  
As chaves de empacotamento que você especifica ao criar um token de autenticação devem ser as mesmas que você usou com seu provedor de materiais criptográficos na versão 2.*x*.

1. Crie um esquema de tabela sobre sua classe anotada.

   Essa etapa define as ações de atributos que serão usadas quando você começar a gravar itens no novo formato.

   Para obter orientação sobre como usar o novo DynamoDB Enhanced Client, consulte [Gerar um `TableSchema`](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-gs-tableschema.html) no *Guia do desenvolvedor do AWS SDK para Java *.

   O exemplo a seguir pressupõe que você atualizou sua classe anotada da versão 2.*x* usando as novas anotações de ações de atributos. Para obter mais orientações sobre como anotar suas ações de atributos, consulte [Uso de uma classe de dados anotada](ddb-java-using.md#ddb-attribute-actions-annotated-data-class).
**nota**  
Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. [Para ver um exemplo que mostra as anotações usadas para definir`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, consulte SimpleClass 4.java.](https://github.com/aws/aws-database-encryption-sdk-dynamodb//blob/main/Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/enhanced/SimpleClass4.java)

1. Defina quais [atributos serão excluídos das assinaturas](ddb-java-using.md#allowed-unauth).

1. Configure um mapa explícito das ações de atributos configuradas em sua classe modelada na versão 2.x.

   Essa etapa define as ações de atributos usadas para gravar itens no formato antigo.

1. Configure o `DynamoDBEncryptor` que você usou na versão 2.*x* da biblioteca Java de criptografia do lado do cliente para o DynamoDB.

1. Configure o comportamento legado.

1. Crie um `DynamoDbEncryptionInterceptor`.

1. Crie um novo cliente AWS SDK do DynamoDB.

1. Crie o `DynamoDBEnhancedClient` e crie uma tabela com sua classe modelada.

   Para obter mais informações sobre o DynamoDB Enhanced Client, consulte [criar um cliente aprimorado](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).

```
public class MigrationExampleStep1 {

    public static void MigrationStep1(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Create a Keyring.
        //    This example creates an AWS KMS Keyring that specifies the 
        //    same kmsKeyId previously used in the version 2.x configuration.
        //    It uses the 'CreateMrkMultiKeyring' method to create the 
        //    keyring, so that the keyring can correctly handle both single
        //    region and Multi-Region KMS Keys.
        //    Note that this example uses the AWS SDK for Java v2 KMS client.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        // 2. Create a Table Schema over your annotated class.
        //    For guidance on using the new attribute actions 
        //    annotations, see SimpleClass.java in the 
        //    aws-database-encryption-sdk-dynamodb GitHub repository. 
        //    All primary key attributes must be signed but not encrypted 
        //    and by default all non-primary key attributes 
        //    are encrypted and signed (ENCRYPT_AND_SIGN).
        //    If you want a particular non-primary key attribute to be signed but
        //    not encrypted, use the 'DynamoDbEncryptionSignOnly' annotation.
        //    If you want a particular attribute to be neither signed nor encrypted
        //    (DO_NOTHING), use the 'DynamoDbEncryptionDoNothing' annotation.
        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        // 3. Define which attributes the client should expect to be excluded 
        //    from the signature when reading items.
        //    This value represents all unsigned attributes across the entire 
        //    dataset.
        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");

        // 4. Configure an explicit map of the attribute actions configured 
        //    in your version 2.x modeled class.
        final Map<String, CryptoAction> legacyActions = new HashMap<>();
        legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
        legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute3", CryptoAction.DO_NOTHING);

        // 5. Configure the DynamoDBEncryptor that you used in version 2.x.
        final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
        final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
        final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);

        // 6. Configure the legacy behavior.
        //    Input the DynamoDBEncryptor and attribute actions created in 
        //    the previous steps. For Legacy Policy, use 
        //    'FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy continues to read 
        //    and write items using the old format, but will be able to read
        //    items written in the new format as soon as they appear.
        final LegacyOverride legacyOverride = LegacyOverride
                .builder()
                .encryptor(oldEncryptor)
                .policy(LegacyPolicy.FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
                .attributeActionsOnEncrypt(legacyActions)
                .build();

        // 7. Create a DynamoDbEncryptionInterceptor with the above configuration.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .legacyOverride(legacyOverride)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 8. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 7.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 9. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb client 
        //    created in Step 8, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```

### Etapa 2. Gravar itens no novo formato
<a name="ddb-java-migrate-step2"></a>

Depois de implantar as alterações da Etapa 1 em todos os leitores, conclua as etapas a seguir para configurar seu cliente SDK do AWS Database Encryption para gravar itens no novo formato. Depois de implantar as seguintes alterações, seu cliente continuará lendo itens no formato antigo e começará a gravar e ler itens no novo formato.

Os procedimentos a seguir fornecem uma visão geral das etapas demonstradas no exemplo de código abaixo.

1. Continue configurando seu token de autenticação, esquema de tabela, ações de atributos herdados e `allowedUnsignedAttributes` e `DynamoDBEncryptor` como você fez na [**Etapa 1**](#ddb-java-migrate-step1).

1. Atualize seu comportamento legado para gravar somente novos itens usando o novo formato.

1. Criar uma `DynamoDbEncryptionInterceptor `

1. Crie um novo cliente AWS SDK do DynamoDB.

1. Crie o `DynamoDBEnhancedClient` e crie uma tabela com sua classe modelada.

   Para obter mais informações sobre o DynamoDB Enhanced Client, consulte [criar um cliente aprimorado](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).

```
public class MigrationExampleStep2 {

    public static void MigrationStep2(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Continue to configure your keyring, table schema, legacy 
        //    attribute actions, allowedUnsignedAttributes, and 
        //    DynamoDBEncryptor as you did in Step 1.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");

        final Map<String, CryptoAction> legacyActions = new HashMap<>();
        legacyActions.put("partition_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("sort_key", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN);
        legacyActions.put("attribute2", CryptoAction.SIGN_ONLY);
        legacyActions.put("attribute3", CryptoAction.DO_NOTHING);

        final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient();
        final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId);
        final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp);

        // 2. Update your legacy behavior to only write new items using the new
        //    format. 
        //    For Legacy Policy, use 'FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy
        //    continues to read items in both formats, but will only write items
        //    using the new format.
        final LegacyOverride legacyOverride = LegacyOverride
                .builder()
                .encryptor(oldEncryptor)
                .policy(LegacyPolicy.FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT)
                .attributeActionsOnEncrypt(legacyActions)
                .build();

        // 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .legacyOverride(legacyOverride)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 4. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 3.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 5. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb Client created
        //    in Step 4, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```

Depois de implantar as alterações da Etapa 2, você deve criptografar novamente todos os itens antigos em sua tabela com o novo formato antes de continuar na [Etapa 3](#ddb-java-migrate-step3). Não há uma única métrica ou consulta que você possa executar para criptografar rapidamente seus itens existentes. Use o processo que faz mais sentido para o seu sistema. Por exemplo, é possível usar um processo assíncrono que varre lentamente a tabela e reescreve os itens usando as ações do novo atributo e a configuração de criptografia que você definiu.

### Etapa 3. Ler e gravar somente itens no novo formato
<a name="ddb-java-migrate-step3"></a>

Depois de criptografar novamente todos os itens da tabela com o novo formato, é possível remover o comportamento legado da configuração. Conclua as etapas a seguir para configurar o cliente para ler e gravar somente itens no novo formato.

Os procedimentos a seguir fornecem uma visão geral das etapas demonstradas no exemplo de código abaixo.

1. Continue configurando seu token de autenticação, esquema de tabela e `allowedUnsignedAttributes` como você fez na [**Etapa 1**](#ddb-java-migrate-step1). Remova as ações do atributo legado e `DynamoDBEncryptor` da sua configuração.

1. Crie um `DynamoDbEncryptionInterceptor`.

1. Crie um novo cliente AWS SDK do DynamoDB.

1. Crie o `DynamoDBEnhancedClient` e crie uma tabela com sua classe modelada.

   Para obter mais informações sobre o DynamoDB Enhanced Client, consulte [criar um cliente aprimorado](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-getting-started-dynamodbTable.html#ddb-en-client-getting-started-dynamodbTable-eclient).

```
public class MigrationExampleStep3 {

    public static void MigrationStep3(String kmsKeyId, String ddbTableName, int sortReadValue) {
        // 1. Continue to configure your keyring, table schema,
        //    and allowedUnsignedAttributes as you did in Step 1.
        //    Do not include the configurations for the DynamoDBEncryptor or 
        //    the legacy attribute actions.
        final MaterialProviders matProv = MaterialProviders.builder()
                .MaterialProvidersConfig(MaterialProvidersConfig.builder().build())
                .build();
        final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder()
                .generator(kmsKeyId)
                .build();
        final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);

        final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class);

        final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3");


        // 3. Create a DynamoDbEncryptionInterceptor with the above configuration.
        //    Do not configure any legacy behavior.
        final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>();
        tableConfigs.put(ddbTableName,
                DynamoDbEnhancedTableEncryptionConfig.builder()
                        .logicalTableName(ddbTableName)
                        .keyring(kmsKeyring)
                        .allowedUnsignedAttributes(allowedUnsignedAttributes)
                        .schemaOnEncrypt(tableSchema)
                        .build());
        final DynamoDbEncryptionInterceptor interceptor =
                DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor(
                        CreateDynamoDbEncryptionInterceptorInput.builder()
                                .tableEncryptionConfigs(tableConfigs)
                                .build()
                );

        // 4. Create a new AWS SDK DynamoDb client using the 
        //    interceptor from Step 3.
        final DynamoDbClient ddb = DynamoDbClient.builder()
                .overrideConfiguration(
                        ClientOverrideConfiguration.builder()
                                .addExecutionInterceptor(interceptor)
                                .build())
                .build();

        // 5. Create the DynamoDbEnhancedClient using the AWS SDK Client 
        //    created in Step 4, and create a table with your modeled class.
        final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
                .dynamoDbClient(ddb)
                .build();
        final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema);
    }
}
```

# .NET
<a name="ddb-net"></a>

Este tópico explica como instalar e usar a versão 3. *x* da biblioteca de criptografia do lado do cliente.NET para o DynamoDB. Para obter detalhes sobre a programação com o SDK AWS de criptografia de banco de dados para DynamoDB, consulte os exemplos [do.NET no](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/) repositório -dynamodb em aws-database-encryption-sdk. GitHub

A biblioteca de criptografia do lado do cliente.NET para o DynamoDB é para desenvolvedores que estão escrevendo aplicativos em C\$1 e em outras linguagens de programação.NET. É compatível com Windows, macOS e Linux.

Todas as implementações da [linguagem de programação](ddb-programming-languages.md) do SDK de criptografia de AWS banco de dados para DynamoDB são interoperáveis. No entanto, o SDK para .NET não suporta valores vazios para tipos de dados de lista ou mapa. Isso significa que, se você usar a biblioteca de criptografia Java do lado do cliente para o DynamoDB para escrever um item que contém valores vazios para um tipo de dados de lista ou mapa, não poderá descriptografar e ler esse item usando a biblioteca de criptografia do lado do cliente.NET para o DynamoDB.

**Topics**
+ [Instalar](#ddb-net-install)
+ [Depuração](#ddb-net-debugging)
+ [Usando o cliente.NET](ddb-net-using.md)
+ [Exemplos do.NET](ddb-net-examples.md)
+ [Adicionar versão 3.x a uma tabela existente](ddb-net-config-existing-table.md)

## Instalação da biblioteca de criptografia do lado do cliente.NET para o DynamoDB
<a name="ddb-net-install"></a>

[A biblioteca de criptografia do lado do cliente.NET para o DynamoDB está disponível como AWS.Cryptography. DbEncryptionSDK. DynamoDb](https://www.nuget.org/packages/AWS.Cryptography.DbEncryptionSDK.DynamoDb/)pacote em NuGet. Para obter detalhes sobre como instalar e criar a biblioteca, consulte o [arquivo.NET README.md](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/runtimes/net/README.md) no repositório -dynamodb. aws-database-encryption-sdk A biblioteca de criptografia do lado do cliente.NET para o DynamoDB exige as chaves SDK para .NET mesmo que você não esteja usando (). AWS Key Management Service AWS KMS O SDK para .NET é instalado com o NuGet pacote.

Versão 3. *x* da biblioteca de criptografia do lado do cliente.NET para DynamoDB é compatível com o.NET 6.0 e .NET Framework net48 e versões posteriores.

## Depuração com o.NET
<a name="ddb-net-debugging"></a>

A biblioteca de criptografia do lado do cliente.NET para o DynamoDB não gera nenhum registro. As exceções na biblioteca de criptografia do lado do cliente.NET para o DynamoDB geram uma mensagem de exceção, mas não rastreiam a pilha.

Para ajudar na depuração, certifique-se de habilitar o login no SDK para .NET. Os registros e as mensagens de erro do SDK para .NET podem ajudá-lo a distinguir os erros decorrentes do e os da biblioteca de criptografia SDK para .NET do lado do cliente.NET para o DynamoDB. Para obter ajuda com o SDK para .NET registro, consulte [AWSLogging](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-other.html#config-setting-awslogging)o *Guia do AWS SDK para .NET desenvolvedor*. (Para ver o tópico, expanda a seção **Abrir para ver o conteúdo do .NET Framework**.)

# Usando a biblioteca de criptografia do lado do cliente.NET para o DynamoDB
<a name="ddb-net-using"></a>

Este tópico explica algumas das funções e classes auxiliares na versão 3. *x* da biblioteca de criptografia do lado do cliente.NET para o DynamoDB. 

Para obter detalhes sobre a programação com a biblioteca de criptografia do lado do cliente.NET para o DynamoDB, consulte os [exemplos do.NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/) no repositório -dynamodb em. aws-database-encryption-sdk GitHub

**Topics**
+ [Criptografadores de itens](#ddb-net-item-encryptors)
+ [Ações de atributos](#ddb-net-attribute-actions)
+ [Configuração de criptografia](#ddb-net-config-encrypt)
+ [Atualização de itens](#ddb-net-update-items)

## Criptografadores de itens
<a name="ddb-net-item-encryptors"></a>

Basicamente, o SDK AWS de criptografia de banco de dados para DynamoDB é um criptografador de itens. Você pode usar a versão 3. *x* da biblioteca de criptografia do lado do cliente.NET para que o DynamoDB criptografe, assine, verifique e descriptografe os itens da tabela do DynamoDB das seguintes maneiras.

**O SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB**  
Você pode usar sua [configuração de criptografia de tabela](#ddb-net-config-encrypt) para criar um cliente do DynamoDB que criptografe e assine automaticamente itens do lado do cliente com suas solicitações do DynamoDB. `PutItem` Você pode usar esse cliente diretamente ou criar um modelo de [documento ou modelo](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-document) de [persistência de objetos](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-object-persistence).  
[Você deve usar o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB para usar a criptografia pesquisável.](searchable-encryption.md)

**O `DynamoDbItemEncryptor` de nível inferior**  
O `DynamoDbItemEncryptor` de nível inferior criptografa, assina ou descriptografa e verifica diretamente os itens da tabela sem chamar o DynamoDB. Ele não faz solicitações `PutItem` ou `GetItem` para o DynamoDB. Por exemplo, é possível usar o `DynamoDbItemEncryptor` de nível inferior para descriptografar e verificar diretamente um item do DynamoDB que você já recuperou. Se você usar o nível inferior`DynamoDbItemEncryptor`, recomendamos usar o [modelo de programação de baixo nível SDK para .NET fornecido](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/dynamodb-intro.html#dynamodb-intro-apis-low-level) para comunicação com o DynamoDB.  
O nível inferior do `DynamoDbItemEncryptor` não oferece suporte à [criptografia pesquisável](searchable-encryption.md).

## Ações de atributos no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-net-attribute-actions"></a>

[As ações](concepts.md#crypt-actions) de atributo determinam quais valores de atributos são criptografados e assinados, quais são somente assinados, quais são assinados e incluídos no contexto de criptografia e quais são ignorados.

Para especificar ações de atributos com o cliente.NET, defina manualmente ações de atributos usando um modelo de objeto. Especifique suas ações de atributo criando um `Dictionary` objeto no qual os pares nome-valor representam os nomes dos atributos e as ações especificadas.

Especifique `ENCRYPT_AND_SIGN` para criptografar e assinar um atributo. Especifique `SIGN_ONLY` para assinar, mas não criptografar um atributo. Especifique `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` para assinar um atributo e incluí-lo no contexto de criptografia. Não é possível criptografar um atributo sem também assiná-lo. Especifique `DO_NOTHING` para ignorar um atributo.

Os atributos de partição e classificação devem ser `SIGN_ONLY` ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você definir qualquer atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

**nota**  
Depois de definir suas ações de atributo, você deverá definir quais atributos serão excluídos das assinaturas. Para facilitar a adição de novos atributos não assinados no futuro, recomendamos escolher um prefixo distinto (como "`:`") para identificar os atributos não assinados. Inclua esse prefixo no nome do atributo para todos os atributos marcados como `DO_NOTHING` ao definir o esquema e as ações de atributos do DynamoDB.

O modelo de objeto a seguir demonstra como especificar`ENCRYPT_AND_SIGN`, `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, e `DO_NOTHING` atribuir ações com o cliente.NET. Este exemplo usa o prefixo "`:`" para identificar `DO_NOTHING` atributos.

**nota**  
Para usar a ação `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` criptográfica, você deve usar a versão 3.3 ou posterior do SDK de criptografia de AWS banco de dados. Implante a nova versão para todos os leitores antes de [atualizar seu modelo de dados](ddb-update-data-model.md) para incluí-la`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
var attributeActionsOnEncrypt = new Dictionary<string, CryptoAction>
{
    ["partition_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The partition attribute must be signed
    ["sort_key"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, // The sort attribute must be signed
    ["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
    ["attribute2"] = CryptoAction.SIGN_ONLY,
    ["attribute3"] = CryptoAction.SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT,
    [":attribute4"] = CryptoAction.DO_NOTHING
};
```

## Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-net-config-encrypt"></a>

Ao usar o AWS Database Encryption SDK, você deve definir explicitamente uma configuração de criptografia para sua tabela do DynamoDB. Os valores necessários em sua configuração de criptografia dependem se você definiu suas ações de atributo manualmente ou com uma classe de dados anotada.

O trecho a seguir define uma configuração de criptografia de tabela do DynamoDB usando o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB e atributos não assinados permitidos definidos por um prefixo distinto.

```
Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix,
    // Optional: SearchConfig only required if you use beacons
    Search = new SearchConfig
    {
        WriteVersion = 1, // MUST be 1
        Versions = beaconVersions
    }    
};
tableConfigs.Add(ddbTableName, config);
```

**Nome da tabela lógica**  
Um nome de tabela lógica para sua tabela do DynamoDB.  
O nome da tabela lógica é vinculado criptograficamente a todos os dados armazenados na tabela para simplificar as operações de restauração do DynamoDB. É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Você deve sempre especificar o mesmo nome de tabela lógica. Para que a descriptografia seja bem-sucedida, o nome da tabela lógica deve corresponder ao nome especificado na criptografia. Se o nome da tabela do DynamoDB mudar após a [restauração da tabela do DynamoDB a partir de um backup](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html), o nome da tabela lógica garantirá que a operação de descriptografia ainda reconheça a tabela.

**Atributos não assinados permitidos**  
Os atributos marcados `DO_NOTHING` em suas ações de atributos.  
Os atributos não assinados permitidos informam ao cliente quais atributos são excluídos das assinaturas. O cliente presume que todos os outros atributos estão incluídos na assinatura. Em seguida, ao descriptografar um registro, o cliente determina quais atributos ele precisa verificar e quais ignorar dos atributos não assinados permitidos que você especificou. Não é possível remover um atributo dos atributos não assinados permitidos.  
É possível definir explicitamente os atributos não assinados permitidos criando uma matriz que lista todos os atributos `DO_NOTHING`. Também é possível especificar um prefixo distinto ao nomear os atributos `DO_NOTHING` e usar o prefixo para informar ao cliente quais atributos não estão assinados. É altamente recomendável especificar um prefixo distinto, pois isso simplifica o processo de adicionar um novo atributo `DO_NOTHING` no futuro. Para obter mais informações, consulte [Atualizar seu modelo de dados](ddb-update-data-model.md).  
Se você não especificar um prefixo para todos os atributos `DO_NOTHING`, poderá configurar uma matriz `allowedUnsignedAttributes` que liste explicitamente todos os atributos que o cliente deve esperar que não estejam assinados ao encontrá-los na descriptografia. Você só deve definir explicitamente seus atributos não assinados permitidos se for absolutamente necessário.

**Configuração de pesquisa (opcional)**  
O `SearchConfig` define a [versão do beacon](using-beacons.md#beacon-version).  
O `SearchConfig` deve ser especificado para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons).

**Conjunto de algoritmos (opcional)**  
O `algorithmSuiteId` define qual conjunto de algoritmos o SDK de criptografia de banco de dados da AWS usará.  
A menos que você especifique explicitamente um conjunto alternativo de algoritmos, o SDK do AWS Database Encryption usa o conjunto de [algoritmos padrão](supported-algorithms.md#recommended-algorithms). O conjunto de algoritmos padrão usa o algoritmo AES-GCM com derivação de chaves, [assinaturas digitais](concepts.md#digital-sigs) e [comprometimento de chaves](concepts.md#key-commitment). Embora o conjunto de algoritmos padrão provavelmente seja adequado para a maioria dos aplicativos, é possível escolher um conjunto alternativo de algoritmos. Por exemplo, alguns modelos de confiança seriam satisfeitos com um pacote de algoritmos sem assinaturas digitais. Para obter informações sobre os conjuntos de algoritmos compatíveis com o SDK do AWS Database Encryption, consulte[Suítes de algoritmos compatíveis no SDK AWS de criptografia de banco de dados](supported-algorithms.md).  
Para selecionar o [conjunto de algoritmos AES-GCM sem assinaturas digitais ECDSA](supported-algorithms.md#other-algorithms), inclua o seguinte trecho em sua configuração de criptografia de tabela.  

```
AlgorithmSuiteId = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_SYMSIG_HMAC_SHA384
```

## Atualização de itens com o SDK AWS de criptografia de banco de dados
<a name="ddb-net-update-items"></a>

O SDK AWS de criptografia de banco de dados não oferece suporte a [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para itens que incluem atributos criptografados ou assinados. Para atualizar um atributo criptografado ou assinado, você deve usar [ddb: PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html). Se algum item existir em uma tabela específica com a mesma chave primária de um item existente na consulta `PutItem`, o novo item substituirá completamente o item já existente. Também é possível usar o [CLOBBER](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapperConfig.SaveBehavior.html#CLOBBER) para limpar e substituir todos os atributos ao salvar após atualizar seus itens.

# Exemplos do.NET
<a name="ddb-net-examples"></a>

Os exemplos a seguir mostram como usar a biblioteca de criptografia do lado do cliente.NET para o DynamoDB para proteger os itens da tabela em seu aplicativo. Para encontrar mais exemplos (e contribuir com seus próprios), consulte os [exemplos do.NET](https://github.com/aws/aws-database-encryption-sdk-dynamodb//tree/main/Examples/runtimes/net/src) no repositório aws-database-encryption-sdk -dynamodb em. GitHub

Os exemplos a seguir demonstram como configurar a biblioteca de criptografia do lado do cliente.NET para o DynamoDB em uma nova tabela não preenchida do Amazon DynamoDB. Se você quiser configurar suas tabelas existentes do Amazon DynamoDB para criptografia do lado do cliente, consulte [Adicionar versão 3.x a uma tabela existente](ddb-net-config-existing-table.md).

**Topics**
+ [Usando o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB](#ddb-net-lowlevel-API-example)
+ [Usando o nível inferior `DynamoDbItemEncryptor`](#ddb-net-itemencryptor)

## Usando o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB
<a name="ddb-net-lowlevel-API-example"></a>

O exemplo a seguir mostra como usar o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB com um [AWS KMS chaveiro](use-kms-keyring.md) para criptografar e assinar automaticamente itens do lado do cliente com suas solicitações do DynamoDB. `PutItem`

Você pode usar qualquer [chaveiro](keyrings.md) compatível, mas recomendamos usar um dos AWS KMS chaveiros sempre que possível.

**Veja o exemplo de código completo**: [BasicPutGetExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/BasicPutGetExample.cs)

**Etapa 1: criar o AWS KMS chaveiro**  
O exemplo a seguir é usado `CreateAwsKmsMrkMultiKeyring` para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**Etapa 2: Configurar ações de atributos**  
O exemplo a seguir define um `attributeActionsOnEncrypt` dicionário que representa exemplos de [ações de atributos](concepts.md#crypt-actions) para um item da tabela.  
O exemplo a seguir não define nenhum atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
var attributeActionsOnEncrypt = new Dictionary<string, CryptoAction>
{
    ["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
    ["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
    ["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
    ["attribute2"] = CryptoAction.SIGN_ONLY,
    [":attribute3"] = CryptoAction.DO_NOTHING
};
```

**Etapa 3: definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presume que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).  

```
const String unsignAttrPrefix = ":";
```

**Etapa 4: definir a configuração de criptografia de tabelas do DynamoDB**  
O exemplo a seguir define um mapa `tableConfigs` que representa a configuração de criptografia dessa tabela do DynamoDB.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-net-using.md#net-logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-net-using.md#ddb-net-config-encrypt).  
Para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons), você também deve incluir [`SearchConfig`](ddb-java-using.md#ddb-search-config) na configuração de criptografia.

```
Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix
};
tableConfigs.Add(ddbTableName, config);
```

**Etapa 5: criar um novo cliente AWS SDK do DynamoDB**  
**O exemplo a seguir cria um novo cliente AWS SDK do DynamoDB usando `TableEncryptionConfigs` o da Etapa 4.**  

```
var ddb = new Client.DynamoDbClient(
    new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });
```

**Etapa 6: criptografar e assinar um item de tabela do DynamoDB**  
O exemplo a seguir define um `item` dicionário que representa um item de tabela de amostra e coloca o item na tabela do DynamoDB. O item é criptografado e assinado no lado do cliente antes de ser enviado ao DynamoDB.  

```
var item = new Dictionary<String, AttributeValue>
{
    ["partition_key"] = new AttributeValue("BasicPutGetExample"),
    ["sort_key"] = new AttributeValue { N = "0" },
    ["attribute1"] = new AttributeValue("encrypt and sign me!"),
    ["attribute2"] = new AttributeValue("sign me!"),
    [":attribute3"] = new AttributeValue("ignore me!")
};

PutItemRequest putRequest = new PutItemRequest
{
    TableName = ddbTableName,
    Item = item
};

PutItemResponse putResponse = await ddb.PutItemAsync(putRequest);
```

## Usando o nível inferior `DynamoDbItemEncryptor`
<a name="ddb-net-itemencryptor"></a>

O exemplo a seguir mostra como usar o nível inferior de `DynamoDbItemEncryptor` com um [token de autenticação do AWS KMS](use-kms-keyring.md) para criptografar e assinar diretamente os itens da tabela. O `DynamoDbItemEncryptor` não coloca o item na tabela do DynamoDB.

Você pode usar qualquer [chaveiro](keyrings.md) compatível com o DynamoDB Enhanced Client, mas recomendamos usar um dos AWS KMS chaveiros sempre que possível.

**nota**  
O nível inferior do `DynamoDbItemEncryptor` não oferece suporte à [criptografia pesquisável](searchable-encryption.md). Use o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB para usar criptografia pesquisável.

**Veja o exemplo de código completo**: [ItemEncryptDecryptExample.cs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/tree/main/Examples/runtimes/net/src/itemencryptor/ItemEncryptDecryptExample.cs)

**Etapa 1: criar o AWS KMS chaveiro**  
O exemplo a seguir é usado `CreateAwsKmsMrkMultiKeyring` para criar um AWS KMS chaveiro com uma chave KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**Etapa 2: Configurar ações de atributos**  
O exemplo a seguir define um `attributeActionsOnEncrypt` dicionário que representa exemplos de [ações de atributos](concepts.md#crypt-actions) para um item da tabela.  
O exemplo a seguir não define nenhum atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
var attributeActionsOnEncrypt = new Dictionary<String, CryptoAction>
{
    ["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
    ["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
    ["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
    ["attribute2"] = CryptoAction.SIGN_ONLY,
    [":attribute3"] = CryptoAction.DO_NOTHING
};
```

**Etapa 3: definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presume que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).  

```
String unsignAttrPrefix = ":";
```

**Etapa 4: definir a configuração de `DynamoDbItemEncryptor`**  
O exemplo a seguir define a configuração para `DynamoDbItemEncryptor`.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-net-using.md#net-logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Para obter mais informações, consulte [Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-net-using.md#ddb-net-config-encrypt).  

```
var config = new DynamoDbItemEncryptorConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix
};
```

**Etapa 5: criar o perfil do `DynamoDbItemEncryptor`**  
O exemplo a seguir cria um novo `DynamoDbItemEncryptor` usando `config` da **Etapa 4**.  

```
var itemEncryptor = new DynamoDbItemEncryptor(config);
```

**Etapa 6: criptografar e assinar diretamente um item da tabela**  
O exemplo a seguir criptografa e assina diretamente um item usando o `DynamoDbItemEncryptor`. O `DynamoDbItemEncryptor` não coloca o item na tabela do DynamoDB.  

```
var originalItem = new Dictionary<String, AttributeValue>
{
    ["partition_key"] = new AttributeValue("ItemEncryptDecryptExample"),
    ["sort_key"] = new AttributeValue { N = "0" },
    ["attribute1"] = new AttributeValue("encrypt and sign me!"),
    ["attribute2"] = new AttributeValue("sign me!"),
    [":attribute3"] = new AttributeValue("ignore me!")
};

var encryptedItem = itemEncryptor.EncryptItem(
    new EncryptItemInput { PlaintextItem = originalItem }
).EncryptedItem;
```

# Configurar uma tabela existente do DynamoDB para usar o SDK de criptografia de banco de dados para AWS o DynamoDB
<a name="ddb-net-config-existing-table"></a>

Com a versão 3. *x* da biblioteca de criptografia do lado do cliente.NET para o DynamoDB, você pode configurar suas tabelas existentes do Amazon DynamoDB para criptografia do lado do cliente. Este tópico fornece orientação sobre as três etapas que você deve seguir para adicionar a versão 3.*x* para uma tabela existente e preenchida do DynamoDB.

## Etapa 1: preparar para ler e gravar itens criptografados
<a name="ddb-net-add-step1"></a>

Conclua as etapas a seguir para preparar seu cliente SDK AWS de criptografia de banco de dados para ler e gravar itens criptografados. Depois de implantar as alterações a seguir, seu cliente continuará lendo e gravando itens de texto simples. Ele não criptografará nem assinará nenhum novo item gravado na tabela, mas poderá descriptografar itens criptografados assim que eles aparecerem. Essas mudanças preparam o cliente para começar a [criptografar novos itens](#ddb-net-add-step2). As alterações a seguir devem ser implantadas em cada leitor antes de prosseguir para a próxima etapa.

**1. Definir suas [ações de atributos](concepts.md#crypt-actions)**  
Crie um modelo de objeto para definir quais valores de atributos serão criptografados e assinados, quais serão somente assinados e quais serão ignorados.  
Por padrão, os atributos da chave primária são assinados, mas não criptografados (`SIGN_ONLY`), e todos os outros atributos são criptografados e assinados (`ENCRYPT_AND_SIGN`).  
Especifique `ENCRYPT_AND_SIGN` para criptografar e assinar um atributo. Especifique `SIGN_ONLY` para assinar, mas não criptografar um atributo. Especifique `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` para assinar e atribuir e incluí-los no contexto de criptografia. Não é possível criptografar um atributo sem também assiná-lo. Especifique `DO_NOTHING` para ignorar um atributo. Para obter mais informações, consulte [Ações de atributos no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-net-using.md#ddb-net-attribute-actions).  
Se você especificar algum `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` atributo, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

```
var attributeActionsOnEncrypt = new Dictionary<string, CryptoAction>
{
    ["partition_key"] = CryptoAction.SIGN_ONLY, // The partition attribute must be SIGN_ONLY
    ["sort_key"] = CryptoAction.SIGN_ONLY, // The sort attribute must be SIGN_ONLY
    ["attribute1"] = CryptoAction.ENCRYPT_AND_SIGN,
    ["attribute2"] = CryptoAction.SIGN_ONLY,
    [":attribute3"] = CryptoAction.DO_NOTHING
};
```

**2. Definir quais atributos são excluídos das assinaturas**  
O exemplo a seguir pressupõe que todos os atributos `DO_NOTHING` compartilham o prefixo distinto "`:`" e usam o prefixo para definir os atributos não assinados permitidos. O cliente presumirá que qualquer nome de atributo com o prefixo "`:`" está excluído das assinaturas. Para obter mais informações, consulte [Allowed unsigned attributes](ddb-net-using.md#net-allowed-unauth).  

```
const String unsignAttrPrefix = ":";
```

**3. Criar um [token de autenticação](keyrings.md)**  
O exemplo a seguir cria um [token de autenticação do AWS KMS](use-kms-keyring.md). O AWS KMS chaveiro usa criptografia simétrica ou RSA assimétrica AWS KMS keys para gerar, criptografar e descriptografar chaves de dados.  
Este exemplo usa `CreateMrkMultiKeyring` para criar um token de autenticação do AWS KMS com uma chave do KMS de criptografia simétrica. O método `CreateAwsKmsMrkMultiKeyring` garante que o token de autenticação manipule corretamente chaves de região única e de várias regiões.  

```
var matProv = new MaterialProviders(new MaterialProvidersConfig());
var keyringInput = new CreateAwsKmsMrkMultiKeyringInput { Generator = kmsKeyId };
var kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput);
```

**4. Definir a configuração de criptografia de tabelas do DynamoDB **  
O exemplo a seguir define um mapa `tableConfigs` que representa a configuração de criptografia dessa tabela do DynamoDB.  
Este exemplo especifica o nome da tabela do DynamoDB como o [nome lógico da tabela.](ddb-net-using.md#net-logical-table-name) É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez.  
Você deve especificar `FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT` como substituição de texto simples. Essa política continua lendo e gravando itens de texto simples, lendo itens criptografados e preparando o cliente para gravar itens criptografados.  
Para obter mais informações sobre os valores incluídos na configuração de criptografia da tabela, consulte[Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB](ddb-java-using.md#ddb-config-encrypt).  

```
Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix,
    PlaintextOverride = FORCE_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```

**5. Crie um novo cliente AWS SDK do DynamoDB**  
**O exemplo a seguir cria um novo cliente AWS SDK do DynamoDB usando `TableEncryptionConfigs` o da Etapa 4.**  

```
var ddb = new Client.DynamoDbClient(
    new DynamoDbTablesEncryptionConfig { TableEncryptionConfigs = tableConfigs });
```

## Etapa 2: gravar itens criptografados e assinados
<a name="ddb-net-add-step2"></a>

Atualize a política de texto simples em sua configuração de criptografia de tabela para permitir que o cliente grave itens criptografados e assinados. Depois de implantar a seguinte alteração, o cliente criptografará e assinará novos itens com base nas ações de atributos que você configurou na **Etapa 1**. O cliente poderá ler itens de texto simples e itens criptografados e assinados.

Antes de prosseguir para a [Etapa 3](#ddb-net-add-step3), você deve criptografar e assinar todos os itens de texto sem formatação existentes em sua tabela. Não há uma única métrica ou consulta que você possa executar para criptografar rapidamente seus itens de texto sem formatação existentes. Use o processo que faz mais sentido para o seu sistema. Por exemplo, é possível usar um processo assíncrono que varre lentamente a tabela e reescreve os itens usando as ações de atributos e a configuração de criptografia que você definiu. Para identificar os itens de texto simples em sua tabela, recomendamos escanear todos os itens que não contêm os `aws_dbe_foot` atributos `aws_dbe_head` e que o SDK de criptografia de AWS banco de dados adiciona aos itens quando eles são criptografados e assinados.

O exemplo a seguir atualiza a configuração de criptografia de tabela da **Etapa 1**. Você deve atualizar a substituição de texto simples com `FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT`. Essa política continua lendo itens de texto simples, mas também lê e grava itens criptografados. Crie um novo cliente AWS SDK do DynamoDB usando o atualizado. `TableEncryptionConfigs`

```
Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix,
    PlaintextOverride = FORBID_WRITE_PLAINTEXT_ALLOW_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```

## Etapa 3: somente ler itens criptografados e assinados
<a name="ddb-net-add-step3"></a>

Depois de criptografar e assinar todos os seus itens, atualize a substituição de texto simples na configuração de criptografia de tabela para permitir que o cliente leia e grave somente itens criptografados e assinados. Depois de implantar a seguinte alteração, o cliente criptografará e assinará novos itens com base nas ações de atributos que você configurou na **Etapa 1**. O cliente só poderá ler itens criptografados e assinados.

O exemplo a seguir atualiza a configuração de criptografia de tabela da **Etapa 2**. É possível atualizar a substituição de texto sem formatação com `FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT` ou remover a política de texto sem formatação da sua configuração. Por padrão, o cliente só lê e grava itens criptografados e assinados. Crie um novo cliente AWS SDK do DynamoDB usando o atualizado. `TableEncryptionConfigs`

```
Dictionary<String, DynamoDbTableEncryptionConfig> tableConfigs =
    new Dictionary<String, DynamoDbTableEncryptionConfig>();
DynamoDbTableEncryptionConfig config = new DynamoDbTableEncryptionConfig
{
    LogicalTableName = ddbTableName,
    PartitionKeyName = "partition_key",
    SortKeyName = "sort_key",
    AttributeActionsOnEncrypt = attributeActionsOnEncrypt,
    Keyring = kmsKeyring,
    AllowedUnsignedAttributePrefix = unsignAttrPrefix,
    // Optional: you can also remove the plaintext policy from your configuration
    PlaintextOverride = FORBID_WRITE_PLAINTEXT_FORBID_READ_PLAINTEXT
};
tableConfigs.Add(ddbTableName, config);
```

# Rust
<a name="ddb-rust"></a>

Este tópico explica como instalar e usar a versão 1. *x* da biblioteca de criptografia do lado do cliente Rust para DynamoDB. Para obter detalhes sobre a programação com o SDK AWS de criptografia de banco de dados para DynamoDB, consulte os exemplos de [Rust no](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/) repositório -dynamodb em. aws-database-encryption-sdk GitHub

Todas as implementações da linguagem de programação do SDK de criptografia de AWS banco de dados para DynamoDB são interoperáveis.

**Topics**
+ [Pré-requisitos](#ddb-rust-prerequisites)
+ [Instalação](#ddb-rust-install)
+ [Usando o cliente Rust](ddb-rust-using.md)

## Pré-requisitos
<a name="ddb-rust-prerequisites"></a>

Antes de instalar a biblioteca de criptografia do lado do cliente Rust para o DynamoDB, verifique se você tem os seguintes pré-requisitos.

**Instale Rust and Cargo**  
Instale a versão estável atual do [Rust](https://www.rust-lang.org/) usando o [rustup](https://rustup.rs/).  
Para obter mais informações sobre como baixar e instalar o rustup, consulte os [procedimentos de instalação](https://doc.rust-lang.org/cargo/getting-started/installation.html) no The Cargo Book.

## Instalação
<a name="ddb-rust-install"></a>

A biblioteca de criptografia do lado do cliente Rust para o DynamoDB está disponível como caixa em Crates.io. [aws-db-esdk](https://crates.io/crates/aws-db-esdk) Para obter detalhes sobre como instalar e criar a biblioteca, consulte o arquivo [README.md](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) no repositório -dynamodb. aws-database-encryption-sdk GitHub 

**Manualmente**  
[Para instalar a biblioteca de criptografia do lado do cliente Rust para o DynamoDB, clone ou baixe o repositório -dynamodb. aws-database-encryption-sdk](https://github.com/aws/aws-database-encryption-sdk-dynamodb/) GitHub 

**Para instalar a versão mais recente**  
Execute o seguinte comando Cargo no diretório do seu projeto:  

```
cargo add aws-db-esdk
```
Ou adicione a seguinte linha ao seu Cargo.toml:  

```
aws-db-esdk = "<version>"
```

# Usando a biblioteca de criptografia do lado do cliente Rust para o DynamoDB
<a name="ddb-rust-using"></a>

Este tópico explica algumas das funções e classes auxiliares na versão 1. *x* da biblioteca de criptografia do lado do cliente Rust para DynamoDB. 

Para obter detalhes sobre a programação com a biblioteca de criptografia do lado do cliente Rust para o DynamoDB, consulte os exemplos do [Rust](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/) no repositório -dynamodb em. aws-database-encryption-sdk GitHub

**Topics**
+ [Criptografadores de itens](#ddb-rust-item-encryptors)
+ [Ações de atributos](#ddb-rust-attribute-actions)
+ [Configuração de criptografia](#ddb-rust-config-encrypt)
+ [Atualização de itens](#ddb-rust-update-items)

## Criptografadores de itens
<a name="ddb-rust-item-encryptors"></a>

Basicamente, o SDK AWS de criptografia de banco de dados para DynamoDB é um criptografador de itens. Você pode usar a versão 1. *x* da biblioteca de criptografia do lado do cliente Rust para que o DynamoDB criptografe, assine, verifique e descriptografe os itens da tabela do DynamoDB das seguintes maneiras.

**O SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB**  
Você pode usar sua [configuração de criptografia de tabela](#ddb-rust-config-encrypt) para criar um cliente do DynamoDB que criptografe e assine automaticamente itens do lado do cliente com suas solicitações do DynamoDB. `PutItem`  
[Você deve usar o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB para usar a criptografia pesquisável.](searchable-encryption.md)  
[Para ver um exemplo de como usar o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB, consulte basic\$1get\$1put\$1example.rs no repositório -dynamodb em.](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/basic_get_put_example.rs) aws-database-encryption-sdk GitHub

**O `DynamoDbItemEncryptor` de nível inferior**  
O `DynamoDbItemEncryptor` de nível inferior criptografa, assina ou descriptografa e verifica diretamente os itens da tabela sem chamar o DynamoDB. Ele não faz solicitações `PutItem` ou `GetItem` para o DynamoDB. Por exemplo, é possível usar o `DynamoDbItemEncryptor` de nível inferior para descriptografar e verificar diretamente um item do DynamoDB que você já recuperou.  
O nível inferior do `DynamoDbItemEncryptor` não oferece suporte à [criptografia pesquisável](searchable-encryption.md).  
Para ver um exemplo demonstrando como usar o nível inferior, consulte `DynamoDbItemEncryptor` [item\$1encrypt\$1decrypt.rs](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/releases/rust/db_esdk/examples/itemencryptor/item_encrypt_decrypt.rs) no repositório -dynamodb em. aws-database-encryption-sdk GitHub

## Ações de atributos no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-rust-attribute-actions"></a>

[As ações](concepts.md#crypt-actions) de atributo determinam quais valores de atributos são criptografados e assinados, quais são somente assinados, quais são assinados e incluídos no contexto de criptografia e quais são ignorados.

Para especificar ações de atributos com o cliente Rust, defina manualmente as ações de atributos usando um modelo de objeto. Especifique suas ações de atributo criando um `HashMap` objeto no qual os pares nome-valor representam os nomes dos atributos e as ações especificadas.

Especifique `ENCRYPT_AND_SIGN` para criptografar e assinar um atributo. Especifique `SIGN_ONLY` para assinar, mas não criptografar um atributo. Especifique `SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT` para assinar um atributo e incluí-lo no contexto de criptografia. Não é possível criptografar um atributo sem também assiná-lo. Especifique `DO_NOTHING` para ignorar um atributo.

Os atributos de partição e classificação devem ser `SIGN_ONLY` ou`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`. Se você definir qualquer atributo como`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, os atributos de partição e classificação também deverão ser`SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`.

**nota**  
Depois de definir suas ações de atributo, você deverá definir quais atributos serão excluídos das assinaturas. Para facilitar a adição de novos atributos não assinados no futuro, recomendamos escolher um prefixo distinto (como "`:`") para identificar os atributos não assinados. Inclua esse prefixo no nome do atributo para todos os atributos marcados como `DO_NOTHING` ao definir o esquema e as ações de atributos do DynamoDB.

O modelo de objeto a seguir demonstra como especificar`ENCRYPT_AND_SIGN`, `SIGN_ONLY``SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT`, e `DO_NOTHING` atribuir ações com o cliente Rust. Este exemplo usa o prefixo "`:`" para identificar `DO_NOTHING` atributos.

```
let attribute_actions_on_encrypt = HashMap::from([
    ("partition_key".to_string(), CryptoAction::SignOnly),
    ("sort_key".to_string(), CryptoAction::SignOnly),
    ("attribute1".to_string(), CryptoAction::EncryptAndSign),
    ("attribute2".to_string(), CryptoAction::SignOnly),
    (":attribute3".to_string(), CryptoAction::DoNothing),
]);
```

## Configuração de criptografia no SDK AWS de criptografia de banco de dados para DynamoDB
<a name="ddb-rust-config-encrypt"></a>

Ao usar o AWS Database Encryption SDK, você deve definir explicitamente uma configuração de criptografia para sua tabela do DynamoDB. Os valores necessários em sua configuração de criptografia dependem se você definiu suas ações de atributo manualmente ou com uma classe de dados anotada.

O trecho a seguir define uma configuração de criptografia de tabela do DynamoDB usando o SDK de criptografia de AWS banco de dados de baixo nível para a API do DynamoDB e atributos não assinados permitidos definidos por um prefixo distinto.

```
let table_config = DynamoDbTableEncryptionConfig::builder()
    .logical_table_name(ddb_table_name)
    .partition_key_name("partition_key")
    .sort_key_name("sort_key")
    .attribute_actions_on_encrypt(attribute_actions_on_encrypt)
    .keyring(kms_keyring)
    .allowed_unsigned_attribute_prefix(UNSIGNED_ATTR_PREFIX)
    // Specifying an algorithm suite is optional
    .algorithm_suite_id(
        DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
    )
    .build()?;

let table_configs = DynamoDbTablesEncryptionConfig::builder()
    .table_encryption_configs(HashMap::from([(ddb_table_name.to_string(), table_config)]))
    .build()?;
```

**Nome da tabela lógica**  
Um nome de tabela lógica para sua tabela do DynamoDB.  
O nome da tabela lógica é vinculado criptograficamente a todos os dados armazenados na tabela para simplificar as operações de restauração do DynamoDB. É altamente recomendável especificar o nome da tabela do DynamoDB como o nome lógico da tabela ao definir a configuração de criptografia pela primeira vez. Você deve sempre especificar o mesmo nome de tabela lógica. Para que a descriptografia seja bem-sucedida, o nome da tabela lógica deve corresponder ao nome especificado na criptografia. Se o nome da tabela do DynamoDB mudar após a [restauração da tabela do DynamoDB a partir de um backup](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Restore.Tutorial.html), o nome da tabela lógica garantirá que a operação de descriptografia ainda reconheça a tabela.

**Atributos não assinados permitidos**  
Os atributos marcados `DO_NOTHING` em suas ações de atributos.  
Os atributos não assinados permitidos informam ao cliente quais atributos são excluídos das assinaturas. O cliente presume que todos os outros atributos estão incluídos na assinatura. Em seguida, ao descriptografar um registro, o cliente determina quais atributos ele precisa verificar e quais ignorar dos atributos não assinados permitidos que você especificou. Não é possível remover um atributo dos atributos não assinados permitidos.  
É possível definir explicitamente os atributos não assinados permitidos criando uma matriz que lista todos os atributos `DO_NOTHING`. Também é possível especificar um prefixo distinto ao nomear os atributos `DO_NOTHING` e usar o prefixo para informar ao cliente quais atributos não estão assinados. É altamente recomendável especificar um prefixo distinto, pois isso simplifica o processo de adicionar um novo atributo `DO_NOTHING` no futuro. Para obter mais informações, consulte [Atualizar seu modelo de dados](ddb-update-data-model.md).  
Se você não especificar um prefixo para todos os atributos `DO_NOTHING`, poderá configurar uma matriz `allowedUnsignedAttributes` que liste explicitamente todos os atributos que o cliente deve esperar que não estejam assinados ao encontrá-los na descriptografia. Você só deve definir explicitamente seus atributos não assinados permitidos se for absolutamente necessário.

**Configuração de pesquisa (opcional)**  
O `SearchConfig` define a [versão do beacon](using-beacons.md#beacon-version).  
O `SearchConfig` deve ser especificado para usar [criptografia pesquisável](searchable-encryption.md) ou [beacons assinados](configure.md#signed-beacons).

**Suíte de algoritmos (opcional)**  
O `algorithmSuiteId` define qual conjunto de algoritmos o SDK de criptografia de banco de dados da AWS usará.  
A menos que você especifique explicitamente um conjunto alternativo de algoritmos, o SDK do AWS Database Encryption usa o conjunto de [algoritmos padrão](supported-algorithms.md#recommended-algorithms). O conjunto de algoritmos padrão usa o algoritmo AES-GCM com derivação de chaves, [assinaturas digitais](concepts.md#digital-sigs) e [comprometimento de chaves](concepts.md#key-commitment). Embora o conjunto de algoritmos padrão provavelmente seja adequado para a maioria dos aplicativos, é possível escolher um conjunto alternativo de algoritmos. Por exemplo, alguns modelos de confiança seriam satisfeitos com um pacote de algoritmos sem assinaturas digitais. Para obter informações sobre os conjuntos de algoritmos compatíveis com o SDK do AWS Database Encryption, consulte[Suítes de algoritmos compatíveis no SDK AWS de criptografia de banco de dados](supported-algorithms.md).  
Para selecionar o [conjunto de algoritmos AES-GCM sem assinaturas digitais ECDSA](supported-algorithms.md#other-algorithms), inclua o seguinte trecho em sua configuração de criptografia de tabela.  

```
.algorithm_suite_id(
    DbeAlgorithmSuiteId::AlgAes256GcmHkdfSha512CommitKeyEcdsaP384SymsigHmacSha384,
)
```

## Atualização de itens com o SDK AWS de criptografia de banco de dados
<a name="ddb-rust-update-items"></a>

O SDK AWS de criptografia de banco de dados não oferece suporte a [ddb: UpdateItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html) para itens que incluem atributos criptografados ou assinados. Para atualizar um atributo criptografado ou assinado, você deve usar [ddb: PutItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html). Se algum item existir em uma tabela específica com a mesma chave primária de um item existente na consulta `PutItem`, o novo item substituirá completamente o item já existente.

# Cliente legado de criptografia do DynamoDB
<a name="legacy-dynamodb-encryption-client"></a>

Em 9 de junho de 2023, nossa biblioteca de criptografia do lado do cliente foi renomeada para AWS Database Encryption SDK. O SDK do AWS Database Encryption continua oferecendo suporte às versões antigas do DynamoDB Encryption Client. Para obter mais informações sobre as diferentes partes da biblioteca de criptografia do lado do cliente que foram alteradas com a renomeação, consulte [Renomeação do Amazon DynamoDB Encryption Client](DDBEC-rename.md).

Para migrar para a versão mais recente da biblioteca Java de criptografia do lado do cliente para o DynamoDB, consulte [Migrar para a versão 3.x](ddb-java-migrate.md).

**Topics**
+ [AWS Suporte à versão SDK de criptografia de banco de dados para DynamoDB](#legacy-support)
+ [Como o DynamoDB Encryption Client funciona](DDBEC-legacy-how-it-works.md)
+ [Conceitos do Amazon DynamoDB Encryption Client](DDBEC-legacy-concepts.md)
+ [Provedor de materiais de criptografia](crypto-materials-providers.md)
+ [Linguagens de programação disponíveis do Amazon DynamoDB Encryption Client](programming-languages.md)
+ [Alterar seu modelo de dados](data-model.md)
+ [Solução de problemas em seu aplicativo DynamoDB Encryption Client](troubleshooting.md)

## AWS Suporte à versão SDK de criptografia de banco de dados para DynamoDB
<a name="legacy-support"></a>

Os tópicos a seguir do capítulo Legao fornecem informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e das versões 1.*x*—3*x* do DynamoDB Encryption Client para Python.

A tabela a seguir lista os idiomas e as versões que oferecem suporte à criptografia do lado do cliente no Amazon DynamoDB.


| Linguagem de programação | Versão | Fase do ciclo de vida da versão principal do SDK | 
| --- | --- | --- | 
|  Java  |  Versões 1.*x*  |  [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), em vigor em julho de 2022  | 
|  Java  |  Versões 2.*x*  |  [Disponibilidade geral](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA)  | 
|  Java  |  Versão 3.*x*  |  [Disponibilidade geral](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA)  | 
|  Python  |  Versões 1.*x*  |  [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), em vigor em julho de 2022  | 
|  Python  |  Versões 2.*x*  |  [End-of-Support fase](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle), em vigor em julho de 2022  | 
|  Python  |  Versões 3.*x*  |  [Disponibilidade geral](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html#version-life-cycle) (GA)  | 

# Como o DynamoDB Encryption Client funciona
<a name="DDBEC-legacy-how-it-works"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O DynamoDB Encryption Client foi criado especificamente para proteger os dados que você armazena no DynamoDB. As bibliotecas incluem implementações seguras que você pode estender ou usar inalteradas. Além disso, a maioria dos elementos é representada por elementos abstratos para que você possa criar e usar componentes personalizados compatíveis.

**Criptografar e assinar itens de tabela**

No núcleo do DynamoDB Encryption Client está um *item de criptografador* que criptografa, autentica, verifica e descriptografa os itens da tabela. Ele obtém informações sobre os itens da tabela e instruções sobre quais itens devem ser criptografados e assinados. Ele obtém os materiais de criptografia e as instruções sobre como usá-los de um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) que você seleciona e configura. 

O diagrama a seguir mostra uma visão de alto nível desse processo.

![\[Criptografar e assinar itens no DynamoDB Encryption Client\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/arch-encrypt.png)


Para criptografar e assinar um item de tabela, o DynamoDB Encryption Client precisa:
+ **Informações sobre a tabela. ** Ele obtém informações sobre a tabela de um contexto de criptografia do [DynamoDB](concepts.md#encryption-context) que você fornece. Alguns auxiliares obtêm as informações necessárias do DynamoDB e criam o contexto de criptografia do DynamoDB para você. 
**nota**  
O contexto de *criptografia do DynamoDB* no DynamoDB Encryption Client não está relacionado ao contexto de criptografia em () e *o.* AWS Key Management Service AWS KMS AWS Encryption SDK
+ **Quais atributos devem ser criptografados e assinados.** Ele obtém essas informações das [ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) que você fornece.
+ **Materiais de criptografia, incluindo chaves de criptografia e de assinatura.** Ele os obtém de um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que você seleciona e configura. 
+ **Instruções para criptografar e assinar o item**. O CMP adiciona instruções para usar os materiais de criptografia, incluindo algoritmos de criptografia e assinatura, à [descrição real do material](DDBEC-legacy-concepts.md#legacy-material-description).

O [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor) usa todos esses elementos para criptografar e assinar o item. O criptografador de itens também adiciona dois atributos ao item: um [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) que contém as instruções de criptografia e assinatura (a descrição real do material) e um atributo que contém a assinatura. Você pode interagir com o criptografador do item diretamente ou usar os recursos auxiliares que interagem com o criptografador do item para que você implemente um comportamento padrão seguro.

O resultado é um item do DynamoDB que contém dados criptografados e assinados.

**Verificar e descriptografar itens de tabela**

Esses componentes também funcionam juntos para verificar e descriptografar o item, conforme mostrado no diagrama a seguir.

![\[Verificando e descriptografando itens no DynamoDB Encryption Client\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/arch-decrypt.png)


Para verificar e descriptografar um item, o DynamoDB Encryption Client precisa dos mesmos componentes, componentes com a mesma configuração ou criados especialmente para a descriptografia de itens da seguinte maneira:
+ **Informações sobre a tabela** do [contexto de criptografia do ](concepts.md#encryption-context).
+ **Quais atributos verificar e descriptografar.** Ele os obtém das [ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions).
+ **Materiais de descriptografia, incluindo chaves de verificação e de descriptografia**, do [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que você seleciona e configura.

  O item criptografado não inclui registros do CMP que foi usado para criptografá-lo. Você deve fornecer o mesmo CMP, um CMP com a mesma configuração ou que foi criado para descriptografar itens.
+ **Informações sobre como o item foi criptografado e assinado**, incluindo os algoritmos de criptografia e assinatura. O cliente os obtém do [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) no item.

O [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor) usa todos esses elementos para verificar e descriptografar o item. Ele também remove os atributos de assinatura e descrição do material. O resultado é um item do DynamoDB em formato de texto simples.

# Conceitos do Amazon DynamoDB Encryption Client
<a name="DDBEC-legacy-concepts"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Este tópico explica a terminologia e os conceitos usados no Amazon DynamoDB Encryption Client. 

Para saber como os componentes do DynamoDB Encryption Client interagem, consulte [Como o DynamoDB Encryption Client funciona](DDBEC-legacy-how-it-works.md).

**Topics**
+ [Provedor de materiais de criptografia (CMP)](#concept-material-provider)
+ [Criptografadores de itens](#item-encryptor)
+ [Ações de atributos](#legacy-attribute-actions)
+ [Descrição do material](#legacy-material-description)
+ [Contexto de criptografia do DynamoDB](#legacy-encryption-context)
+ [Armazenamento de provedores](#provider-store)

## Provedor de materiais de criptografia (CMP)
<a name="concept-material-provider"></a>

Ao implementar o DynamoDB Encryption Client, uma das suas primeiras tarefas é [selecionar um provedor de materiais de criptografia](crypto-materials-providers.md) (CMP) (também conhecido como *provedor de materiais criptográficos*). Sua escolha determina muito do restante da implementação. 

O *provedor de materiais de criptografia* (CMP) coleta, monta e retorna os materiais criptográficos que o [criptografador de itens](#item-encryptor) usa para criptografar e assinar os itens de sua tabela. O CMP determina os algoritmos de criptografia a serem usados e como gerar e proteger a criptografia e as chaves de assinatura.

O CMP interage com o criptografador do item. O criptografador do item solicita materiais de criptografia ou de descriptografia do CMP, e o CMP os retorna ao criptografador do item. Então, o criptografador do item usa os materiais de criptografia para criptografar e assinar, ou verificar e descriptografar, o item.

Você especifica o CMP ao configurar o cliente. Você pode criar uma CMP personalizada compatível ou usar uma das várias CMPs da biblioteca. A maioria CMPs está disponível para várias linguagens de programação. 

## Criptografadores de itens
<a name="item-encryptor"></a>

O *criptografador do itens* é um componente de nível inferior que executa operações de criptografia para o DynamoDB Encryption Client. Ele solicita materiais de criptografia de um [provedor de materiais de criptografia](#concept-material-provider) (CMP) e usa os materiais que o CMP retorna para criptografar e assinar, ou verificar e descriptografar, o item da tabela.

É possível interagir com o criptografador do item diretamente ou usar os auxiliares fornecidos pela biblioteca. Por exemplo, o DynamoDB Encryption Client para Java inclui uma classe auxiliar `AttributeEncryptor` que é possível usar com o `DynamoDBMapper`, em vez de interagir diretamente com o criptografador de itens `DynamoDBEncryptor`. A biblioteca Python inclui as classes auxiliares `EncryptedTable`, `EncryptedClient` e `EncryptedResource` que interagem com o criptografador do item para você.

## Ações de atributos
<a name="legacy-attribute-actions"></a>

As *Ações de atributos* informam ao criptografador de itens quais ações executar em cada atributo de item. 

Os valores das ações de atributo podem ser um destes:
+ **Criptografar e assinar** – Criptografa o valor do atributo. Incluir o atributo (nome e valor) na assinatura do item.
+ **Apenas assinar** – Inclui o atributo na assinatura do item.
+ **Não fazer nada** – Não criptografa nem assina o atributo.

Para qualquer atributo que possa armazenar dados confidenciais, use **Criptografar e assinar**. Para atributos de chave primária (chave de partição e chave de classificação), use **Apenas assinar**. O [atributo de descrição do material](#legacy-material-description) e o atributo de assinatura não são assinados nem criptografados. Não é necessário especificar ações para esses atributos.

Escolha suas ações de atributos com cuidado. Em caso de dúvida, use **Criptografar e assinar**. Depois de usar o DynamoDB Encryption Client para proteger seus itens de tabela, não será possível alterar a ação de um atributo sem arriscar um erro de validação de assinatura. Para obter detalhes, consulte [Alterar seu modelo de dados](data-model.md).

**Atenção**  
Não criptografe os atributos da chave primária. Eles devem permanecer em texto simples para que o DynamoDB possa encontrar o item sem executar uma varredura completa da tabela.

Se o [contexto de criptografia do DynamoDB](concepts.md#encryption-context) identificar os atributos de chave primária, o cliente gerará um erro se você tentar criptografá-los.

A técnica usada para especificar as ações de atributo é diferente para cada linguagem de programação. Ela também pode ser específica das classes auxiliares que você usa.

Para ver detalhes, consulte a documentação da sua linguagem de programação.
+ [Python](python-using.md#python-attribute-actions)
+ [Java](java-using.md#attribute-actions-java)

## Descrição do material
<a name="legacy-material-description"></a>

A *descrição do material* para um item de tabela criptografado consiste em informações, como algoritmos de criptografia, sobre como o item de tabela é criptografado e assinado. O [provedor de materiais de criptografia](#concept-material-provider) (CMP) registra a descrição do material à medida que monta os materiais para criptografia e assinatura. Depois, quando precisar montar materiais de criptografia para verificar e descriptografar o item, ele usará a descrição do material como guia. 

No DynamoDB Encryption Client, a descrição do material refere-se a três elementos relacionados:

**Descrição do material solicitado**  
Alguns [fornecedores de materiais criptográficos](#concept-material-provider) (CMPs) permitem que você especifique opções avançadas, como um algoritmo de criptografia. Para indicar suas opções, adicione pares de nome-valor à propriedade de descrição do material do [contexto de criptografia do DynamoDB](concepts.md#encryption-context) na solicitação para criptografar um item da tabela. Esse elemento é conhecido como a *descrição do material solicitado*. Os valores válidos na descrição solicitada do material são definidos pelo CMP escolhido.   
Como a descrição do material pode substituir valores padrão seguros, recomendamos que você omita a descrição solicitada do material, a menos que tenha um bom motivo para usá-la.

**Descrição real do material**  
A descrição do material que os [fornecedores de materiais criptográficos](#concept-material-provider) (CMPs) retornam é conhecida como a *descrição real do material*. Ela descreve os valores reais que o CMP usou quando montou os materiais de criptografia. Ela consiste na descrição solicitada do material, se houver, com adições e alterações.

**Atributo de descrição do material**  
O cliente salva a descrição real do material no *atributo de descrição do material* do item criptografado. O nome do atributo de descrição do material é `amzn-ddb-map-desc`, e seu valor é a descrição real do material. O cliente usa os valores do atributo de descrição do material para verificar e descriptografar o item.

## Contexto de criptografia do DynamoDB
<a name="legacy-encryption-context"></a>

O *contexto de criptografia do DynamoDB* fornece informações sobre a tabela e o item ao [provedor de materiais de criptografia](#concept-material-provider) (CMP). Em implementações avançadas, o contexto de criptografia do DynamoDB pode incluir uma [descrição do material solicitado](#legacy-material-description).

Quando você criptografa itens de tabela, o contexto de criptografia do DynamoDB é vinculado criptograficamente aos valores dos atributos criptografados. Ao descriptografar, se o contexto de criptografia do DynamoDB não for correspondência exata de maiúsculas e minúsculas do contexto de criptografia do DynamoDB usado para criptografar, a operação de descriptografia falhará. Se você interagir com o [criptografador de itens](#item-encryptor) diretamente, forneça um contexto de criptografia do DynamoDB ao chamar um método de criptografia ou de descriptografia. A maioria das classes auxiliares cria o contexto de criptografia do DynamoDB para você.

**nota**  
O contexto de *criptografia do DynamoDB* no DynamoDB Encryption Client não está relacionado ao contexto de criptografia em () e *o.* AWS Key Management Service AWS KMS AWS Encryption SDK

O contexto de criptografia do DynamoDB pode incluir os campos a seguir. Todos os campos e valores são opcionais.
+ Nome da tabela
+ Nome da chave de partição
+ Nome da chave de classificação
+ Pares de nome-valor do atributo
+ [Descrição do material solicitado](#legacy-material-description)

## Armazenamento de provedores
<a name="provider-store"></a>

Uma *loja de fornecedores* é um componente que retorna [fornecedores de materiais criptográficos](#concept-material-provider) (CMPs). A loja do provedor pode criá-los CMPs ou obtê-los de outra fonte, como outra loja do provedor. O repositório do provedor salva as versões do CMPs que ele cria em um armazenamento persistente, no qual cada CMP armazenado é identificado pelo nome do material do solicitante e pelo número da versão. 

O [provedor mais recente](most-recent-provider.md) no DynamoDB Encryption Client os obtém CMPs de uma loja de provedores, mas você pode usar a loja de provedores para CMPs fornecer qualquer componente. Cada provedor mais recente está associado a uma loja de provedores, mas uma loja de provedores pode fornecer CMPs a vários solicitantes em vários hosts.

A loja do provedor cria novas versões CMPs sob demanda e retorna versões novas e existentes. Ele também retorna o número da versão mais recente de um determinado nome de material. Assim, o solicitante sabe quando o armazenamento do provedor tem uma nova versão do CMP que ele pode solicitar.

O DynamoDB Encryption Client inclui [ MetaStore](most-recent-provider.md#about-metastore)um, que é um repositório de provedores que cria CMPs Wrapped com chaves armazenadas no DynamoDB e criptografadas usando um DynamoDB Encryption Client interno. 

**Saiba mais:**
+ Armazenamento de provedores: [Java](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/store/ProviderStore.html), [Python](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/src/dynamodb_encryption_sdk/material_providers/store/__init__.py)
+ MetaStore: [Java](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/store/MetaStore.html), [Python](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/materials_providers/metastore.html#module-dynamodb_encryption_sdk.material_providers.store.meta)

# Provedor de materiais de criptografia
<a name="crypto-materials-providers"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Uma das decisões mais importantes que você precisa tomar ao usar o DynamoDB Encryption Client é selecionar um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP). O CMP monta e retorna materiais de criptografia ao criptografador do item. Ele também determina como as chaves de criptografia e assinatura são geradas, se os novos materiais de chaves são gerados para cada item ou reutilizados e os algoritmos de criptografia e assinatura que são usados. 

Você pode escolher um CMP das implementações fornecidas nas bibliotecas do DynamoDB Encryption Client ou criar um CMP compatível personalizado. Sua escolha de CMP também pode ter como base a [linguagem de programação](programming-languages.md) usada.

Este tópico descreve os mais comuns CMPs e oferece alguns conselhos para ajudá-lo a escolher o melhor para seu aplicativo.

**Provedor direto de materiais do KMS**  
O provedor direto de materiais do KMS protege os itens da sua tabela sob uma [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) que nunca deixa o [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) sem criptografia. Seu aplicativo não precisa gerar ou gerenciar nenhum material de criptografia. Como ele usa o AWS KMS key para gerar chaves exclusivas de criptografia e assinatura para cada item, esse provedor liga AWS KMS sempre que criptografa ou descriptografa um item.   
Se você usa AWS KMS e uma AWS KMS chamada por transação é prática para seu aplicativo, esse provedor é uma boa escolha.  
Para obter detalhes, consulte [Provedor direto de materiais do KMS](direct-kms-provider.md).

**Provedor encapsulado de materiais (CMP encapsulado)**  
O provedor encapsulado de materiais (CMP encapsulado) permite gerar e gerenciar chaves encapsuladas e de assinatura fora do DynamoDB Encryption Client.   
O CMP encapsulado gera uma chave exclusiva de criptografia para cada item. E, então, ele usa as chaves encapsuladas (ou desencapsuladas) e de assinatura que você forneceu. Desse modo, você pode determinar como as chaves encapsuladas e de assinatura serão geradas e se elas serão exclusivas para cada item ou reutilizadas. O Wrapped CMP é uma alternativa segura ao [Direct KMS Provider](direct-kms-provider.md) para aplicativos que não usam AWS KMS e podem gerenciar com segurança materiais criptográficos.  
Para obter detalhes, consulte [Provedor encapsulado de materiais](wrapped-provider.md).

**Provedor mais recente**  
O *Provedor mais recente* é um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que foi projetado para trabalhar com um [armazenamento de provedores](DDBEC-legacy-concepts.md#provider-store). Ele é CMPs obtido da loja do fornecedor e obtém os materiais criptográficos que retorna do CMPs. O provedor mais recente normalmente usa cada CMP para atender a várias solicitações de materiais de criptografia, mas você pode usar os recursos do armazenamento de provedor para gerenciar a frequência com a qual os materiais são reutilizados, determinar a frequência de rotação do CMP e até mesmo alterar o tipo de CMP usado sem alterar o provedor mais recente.  
Você pode usar o provedor mais recente com qualquer armazenamento compatível de provedor. O DynamoDB Encryption Client inclui MetaStore um, que é um provedor de armazenamento que retorna Wrapped. CMPs  
O provedor mais recente é uma boa opção para aplicativos que precisam minimizar as chamadas para sua origem de criptografia e para aplicativos que podem reutilizar alguns materiais de criptografia sem violar os requisitos de segurança. Por exemplo, ele permite que você proteja seus materiais criptográficos sob um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) sem chamar AWS KMS toda vez que criptografar ou descriptografar um item.  
Para obter detalhes, consulte [Provedor mais recente](most-recent-provider.md).

**Provedor estático de materiais**  
O Static Materials Provider foi projetado para testes, proof-of-concept demonstrações e compatibilidade antiga. Ele não gera material exclusivo de criptografia para cada item. No entanto, ele retorna as mesmas chaves de criptografia e assinatura que você oferece, e essas chaves são usadas diretamente para criptografar, descriptografar e assinar os itens da sua tabela.   
O [Provedor estático assimétrico](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/AsymmetricStaticProvider.html) na biblioteca Java não é um provedor estático. Ele apenas oferece construtores alternativos para o [CMP encapsulado](wrapped-provider.md). Ele é seguro para fins de produção, mas você deve usar o CMP encapsulado diretamente sempre que possível.

**Topics**
+ [Provedor direto de materiais do KMS](direct-kms-provider.md)
+ [Provedor encapsulado de materiais](wrapped-provider.md)
+ [Provedor mais recente](most-recent-provider.md)
+ [Provedor estático de materiais](static-provider.md)

# Provedor direto de materiais do KMS
<a name="direct-kms-provider"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O *Provedor direto de materiais do KMS* (Direct KMS Provider) protege os itens da sua tabela sob um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) que nunca deixa [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS) sem criptografia. O [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) retorna uma chave de criptografia exclusiva e uma chave de assinatura para cada item da tabela. Para fazer isso, ele chama AWS KMS toda vez que você criptografa ou descriptografa um item.

Se você estiver processando itens do DynamoDB em alta frequência e em grande escala, poderá exceder os limites, causando atrasos AWS KMS [requests-per-secondno](https://docs.aws.amazon.com/kms/latest/developerguide/limits.html#requests-per-second) processamento. Caso seja necessário ultrapassar esses limites, visite o [Centro do AWS Support](https://console.aws.amazon.com/support/home) e crie um caso. Também é possível considerar usar um provedor de materiais criptográficos com reutilização limitada de chaves, como o [provedor mais recente](most-recent-provider.md).

[Para usar o Direct KMS Provider, o chamador deve ter pelo menos uma AWS KMS key permissão para ligar para as operações [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)e [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) no. Conta da AWS](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) AWS KMS key O AWS KMS key deve ser uma chave de criptografia simétrica; o DynamoDB Encryption Client não oferece suporte à criptografia assimétrica. Se você estiver usando uma [tabela global do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html), talvez queira especificar uma [chave multirregional do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html). Para obter detalhes, consulte [Como usar](#provider-kms-how-to-use).

**nota**  
Quando você usa o Direct KMS Provider, os nomes e valores de seus atributos de chave primária aparecem em texto simples no [contexto de AWS KMS criptografia](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) e nos AWS CloudTrail registros de operações relacionadas. AWS KMS No entanto, o DynamoDB Encryption Client nunca expõe o texto simples de nenhum valor de atributo criptografado.

O Direct KMS Provider é um dos vários [provedores de materiais criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) suportados pelo DynamoDB Encryption Client. Para obter informações sobre o outro CMPs, consulte[Provedor de materiais de criptografia](crypto-materials-providers.md).

**Para ver um código de exemplo, consulte:**
+ Java: [AwsKmsEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedItem.java)
+ Python:, [aws-kms-encrypted-table[aws-kms-encrypted-item](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)

**Topics**
+ [Como usar](#provider-kms-how-to-use)
+ [Como funciona](#provider-kms-how-it-works)

## Como usar
<a name="provider-kms-how-to-use"></a>

Para criar um Direct KMS Provider, use o parâmetro ID da chave para especificar uma [chave do KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) de criptografia simétrica em sua conta. O valor do parâmetro do ID da chave pode ser o ID, o ARN da chave ou um nome de alias ou um ARN de alias do AWS KMS key. Para obter detalhes sobre os identificadores de chave, consulte [Identificadores de chave](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id) no *Guia do desenvolvedor do AWS Key Management Service *.

O Direct KMS Provider exige uma chave do KMS de criptografia simétrica. Não é possível usar uma chave do KMS assimétrica. É possível usar uma chave do KMS multirregional, chaves do KMS com material de chave importado ou uma chave do KMS em um armazenamento de chaves personalizado. Você deve ter as permissões [kms: GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) e [kms:decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html) na chave KMS. Dessa forma, você deve usar uma chave gerenciada pelo cliente, não uma chave KMS AWS gerenciada ou de AWS propriedade.

O DynamoDB Encryption Client for Python determina a região para AWS KMS chamadas da região no valor do parâmetro de ID chave, se ele incluir um. Caso contrário, ele usa a Região no AWS KMS cliente, se você especificar uma, ou a Região que você configura no AWS SDK para Python (Boto3). Para obter informações sobre a seleção de regiões em Python, consulte [Configuração na Referência](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html) da API AWS SDK for Python (Boto3).

O DynamoDB Encryption Client for Java determina a região para AWS KMS chamadas da região no cliente, se AWS KMS o cliente que você especificar incluir uma região. Caso contrário, ela usa a região que você configura em AWS SDK para Java. Para obter informações sobre a seleção de regiões no AWS SDK para Java, consulte a [Região da AWS seleção](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-region-selection.html) no Guia do AWS SDK para Java desenvolvedor.

------
#### [ Java ]

```
// Replace the example key ARN and Region with valid values for your application
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```

------
#### [ Python ]

O exemplo a seguir usa o ARN de chave para especificar o AWS KMS key. Se seu identificador de chave não incluir um Região da AWS, o DynamoDB Encryption Client obtém a região da sessão de Botocore configurada, se houver, ou dos padrões do Boto.

```
# Replace the example key ID with a valid value
kms_key = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key)
```

------

Se você estiver usando tabelas [globais do Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html), recomendamos que você criptografe seus dados com uma chave multirregional. AWS KMS As chaves multirregionais são AWS KMS keys diferentes e Regiões da AWS podem ser usadas de forma intercambiável porque têm o mesmo ID de chave e material de chave. Para obter mais detalhes, consulte [Usar chaves de várias regiões](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html), no *Guia do desenvolvedor do AWS Key Management Service *.

**nota**  
Se você estiver usando a [versão 2017.11.29](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V1.html) de tabelas globais, deverá definir ações de atributos para que os campos de replicação reservados não sejam criptografados ou assinados. Para obter detalhes, consulte [Problemas com tabelas globais de versões mais antigas](troubleshooting.md#fix-global-tables).

Para usar uma chave multirregional com o DynamoDB Encryption Client, crie uma chave multirregional e replique-a nas regiões em que seu aplicativo é executado. Em seguida, configure o Direct KMS Provider para usar a chave multirregional na região em que o DynamoDB Encryption Client faz chamadas para o AWS KMS.

O exemplo a seguir configura o DynamoDB Encryption Client para criptografar dados na região Leste dos EUA (Norte da Virgínia) (us-east-1) e descriptografá-los na região Oeste dos EUA (Oregon) (us-west-2).

------
#### [ Java ]

Neste exemplo, o DynamoDB Encryption Client obtém a região para fazer AWS KMS chamadas da região no cliente. AWS KMS O valor `keyArn` identifica uma chave de várias regiões na mesma região.

```
// Encrypt in us-east-1

// Replace the example key ARN and Region with valid values for your application
final String usEastKey = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-east-1'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usEastKey);
```

```
// Decrypt in us-west-2

// Replace the example key ARN and Region with valid values for your application
final String usWestKey = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
final String region = 'us-west-2'
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, usWestKey);
```

------
#### [ Python ]

Neste exemplo, o DynamoDB Encryption Client obtém a região para fazer AWS KMS chamadas da região no ARN da chave.

```
# Encrypt in us-east-1

# Replace the example key ID with a valid value
us_east_key = 'arn:aws:kms:us-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_east_key)
```

```
# Decrypt in us-west-2

# Replace the example key ID with a valid value
us_west_key = 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=us_west_key)
```

------

## Como funciona
<a name="provider-kms-how-it-works"></a>

O Direct KMS Provider retorna as chaves de criptografia e assinatura que são protegidas por um AWS KMS key especificado, conforme exibido no diagrama a seguir.

![\[A entrada, o processamento e a saída de provedor direto do KMS no DynamoDB Encryption Client.\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/directKMS.png)

+ Para gerar materiais de criptografia, o Direct KMS Provider solicita AWS KMS a [geração de uma chave de dados exclusiva](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) para cada item usando uma AWS KMS key que você especifica. Ele deriva as chaves de criptografia e de assinatura do item da cópia de texto simples da [chave de dados](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys) e retorna essas chaves junto com a chave de dados criptografada, que é armazenada no [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) do item. 

  O criptografador do item usa as chaves de criptografia e assinatura e as remove da memória o mais rápido possível. Somente a cópia criptografada da chave de dados, da qual eles foram originados, é salva no item criptografado.
+ Para gerar materiais de decodificação, o Direct KMS Provider solicita a decodificação da chave AWS KMS de dados criptografada. Então, ele obtém chaves de verificação e assinatura provenientes da chave de dados em texto simples e as retorna para o criptografador de item.

  O criptografador de item verifica o item e, se a verificação for bem-sucedida, ele descriptografa os valores criptografados. Então, ele remove as chaves da memória o mais rápido possível.

### Obter materiais de criptografia
<a name="direct-kms-get-encryption-materials"></a>

Esta seção descreve detalhadamente as entradas, as saídas e o processamento do Direct KMS Provider quando ele recebe uma solicitação de materiais de criptografia do [criptografador de item](DDBEC-legacy-concepts.md#item-encryptor).

**Entrada ** (do aplicativo)
+ O ID da chave de um AWS KMS key. 

**Entrada** (do criptografador de itens)
+ [Contexto de criptografia do DynamoDB](concepts.md#encryption-context)

**Saída** (para o criptografador de itens)
+ Chave de criptografia (texto simples)
+ Chave de assinatura
+ Na [descrição do material atual](DDBEC-legacy-concepts.md#legacy-material-description): esses valores são salvos no atributo da descrição do material que o cliente adiciona ao item.
  + amzn-ddb-env-key: chave de dados codificada em Base64 criptografada pelo AWS KMS key
  + amzn-ddb-env-alg: Algoritmo de criptografia, por padrão [AES/256](https://csrc.nist.gov/projects/cryptographic-standards-and-guidelines/archived-crypto-projects/aes-development)
  + amzn-ddb-sig-alg: algoritmo de assinatura, por padrão, [Hmac /256 SHA256](https://en.wikipedia.org/wiki/HMAC)
  + amzn-ddb-wrap-alg: kms

**Processamento**

1. O Direct KMS Provider envia AWS KMS uma solicitação para usar o especificado AWS KMS key para [gerar uma chave de dados exclusiva](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html) para o item. A operação retorna uma chave de texto simples e uma cópia criptografada de acordo com a AWS KMS key. Essa operação também é conhecida como o *material de chave inicial*.

   A solicitação inclui os seguintes valores em texto simples no [contexto de criptografia do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context). Esses valores não confidenciais estão vinculados de maneira criptográfica ao objeto criptografado, assim, o mesmo contexto de criptografia será necessário na descriptografia. Você pode usar esses valores para identificar a chamada AWS KMS nos [AWS CloudTrail registros](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-overview.html).
   + amzn-ddb-env-alg — Algoritmo de criptografia, por padrão AES/256
   + amzn-ddb-sig-alg — Algoritmo de assinatura, por padrão Hmac /256 SHA256
   + (Opcional) aws-kms-table — *table name*
   + (Opcional) *partition key name* — *partition key value* (os valores binários são codificados em Base64)
   + (Opcional) *sort key name* — *sort key value* (os valores binários são codificados em Base64)

   O Direct KMS Provider obtém os valores para o contexto de AWS KMS criptografia do contexto de [criptografia do DynamoDB](concepts.md#encryption-context) para o item. Se o contexto de criptografia do DynamoDB não incluir um valor, como o nome da tabela, esse par nome-valor será omitido do contexto de criptografia. AWS KMS 

1. O Direct KMS Provider obtém uma chave de criptografia simétrica e uma chave de assinatura a partir da chave de dados. Por padrão, ele usa o [Secure Hash Algorithm (SHA) 256](https://en.wikipedia.org/wiki/SHA-2) e a [função de derivação de chave RFC5869 baseada em HMAC para derivar uma chave](https://tools.ietf.org/html/rfc5869) de criptografia simétrica AES de 256 bits e uma chave de assinatura HMAC-SHA-256 de 256 bits. 

1. O Direct KMS Provider retorna a saída para o criptografador do item.

1. O criptografador do item usa a chave de criptografia para criptografar os atributos especificados e a chave de assinatura para assiná-los, usando os algoritmos especificados na real descrição do material. Ele remove as chaves de texto simples da memória o mais rápido possível.

### Obter materiais de descriptografia
<a name="direct-kms-get-decryption-materials"></a>

Esta seção descreve detalhadamente as entradas, as saídas e o processamento do Direct KMS Provider quando ele recebe uma solicitação de materiais de descriptografia do [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor).

**Entrada ** (do aplicativo)
+ O ID da chave de um AWS KMS key. 

  O valor do ID da chave pode ser o ID, o ARN da chave ou um nome de alias ou um ARN de alias do AWS KMS key. Todos os valores que não forem incluídos no ID, como a região, deverão estar disponíveis no [perfil nomeado da AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles). O ARN da chave fornece todos os valores necessários para o AWS KMS .

**Entrada** (do criptografador de itens)
+ Uma cópia do [contexto de criptografia do DynamoDB](concepts.md#encryption-context) com o conteúdo do atributo de descrição do material.

**Saída** (para o criptografador de itens)
+ Chave de criptografia (texto simples)
+ Chave de assinatura

**Processamento**

1. O Direct KMS Provider obtém a chave de dados criptografada a partir do atributo de descrição do material no item criptografado. 

1. Ele solicita AWS KMS o uso do especificado AWS KMS key para [descriptografar a chave de dados criptografada](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html). A operação retorna uma chave de texto simples.

   Essa solicitação deve usar o mesmo [contexto de criptografia do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#encrypt_context) que foi usado para gerar e criptografar a chave de dados.
   + aws-kms-table – *table name*
   + *partition key name*— *partition key value* (os valores binários são codificados em Base64)
   + (Opcional) *sort key name* — *sort key value* (os valores binários são codificados em Base64)
   + amzn-ddb-env-alg — Algoritmo de criptografia, por padrão AES/256
   + amzn-ddb-sig-alg — Algoritmo de assinatura, por padrão Hmac /256 SHA256

1. O Direct KMS Provider usa o [Secure Hash Algorithm (SHA) 256](https://en.wikipedia.org/wiki/SHA-2) e a [função de derivação de chave RFC5869 baseada em HMAC para derivar uma chave](https://tools.ietf.org/html/rfc5869) de criptografia simétrica AES de 256 bits e uma chave de assinatura HMAC-SHA-256 de 256 bits da chave de dados. 

1. O Direct KMS Provider retorna a saída para o criptografador do item.

1. O criptografador do item usa a chave de assinatura para verificar o item. Se ele for bem-sucedido, usará a chave de criptografia simétrica para descriptografar os valores de atributos criptografados. Essas operações usam os algoritmos de criptografia e assinatura especificados na real descrição material. O criptografador do item remove as chaves de texto simples da memória o mais rápido possível.

# Provedor encapsulado de materiais
<a name="wrapped-provider"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O *provedor empacotado de materiais* (CMP empacotado) permite usar chaves encapsuladas e de assinatura a partir de qualquer origem com o DynamoDB Encryption Client. O Wrapped CMP não depende de nenhum AWS serviço. No entanto, você deve gerar e gerenciar suas chaves de empacotamento e assinatura fora do cliente, incluindo o fornecimento das chaves corretas para verificar e descriptografar o item. 

O CMP encapsulado gera uma chave exclusiva de criptografia para cada item. Ele encapsula a chave de criptografia do item com a chave de empacotamento que você fornece, e salva a chave de criptografia de item encapsulada no [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) do item. Como fornece as chaves de empacotamento e assinatura, você determina como as chaves de empacotamento e assinatura serão geradas e se elas serão exclusivas de cada item ou reutilizadas. 

O CMP encapsulado é uma implementação segura e uma boa opção para aplicativos que podem gerenciar materiais de criptografia.

O Wrapped CMP é um dos vários [fornecedores de materiais criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) compatíveis com o DynamoDB Encryption Client. Para obter informações sobre o outro CMPs, consulte[Provedor de materiais de criptografia](crypto-materials-providers.md).

**Para ver um código de exemplo, consulte:**
+ Java: [AsymmetricEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AsymmetricEncryptedItem.java)
+ Python:, [wrapped-rsa-encrypted-table[wrapped-symmetric-encrypted-table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/wrapped_symmetric_encrypted_table.py)](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/wrapped_rsa_encrypted_table.py)

**Topics**
+ [Como usar](#wrapped-cmp-how-to-use)
+ [Como funciona](#wrapped-cmp-how-it-works)

## Como usar
<a name="wrapped-cmp-how-to-use"></a>

Para criar um CMP empacotado, especifique uma chave de empacotamento (necessária para a criptografia), uma chave de desempacotamento (necessária para a descriptografia) e uma chave de assinatura. É necessário fornecer chaves ao criptografar e descriptografar itens.

As chaves de empacotamento, desempacotamento e assinatura podem ser chaves simétricas ou pares de chaves assimétricos. 

------
#### [ Java ]

```
// This example uses asymmetric wrapping and signing key pairs
final KeyPair wrappingKeys = ...
final KeyPair signingKeys = ...

final WrappedMaterialsProvider cmp = 
    new WrappedMaterialsProvider(wrappingKeys.getPublic(),
                                 wrappingKeys.getPrivate(),
                                 signingKeys);
```

------
#### [ Python ]

```
# This example uses symmetric wrapping and signing keys
wrapping_key = ...
signing_key  = ...

wrapped_cmp = WrappedCryptographicMaterialsProvider(
    wrapping_key=wrapping_key,
    unwrapping_key=wrapping_key,
    signing_key=signing_key
)
```

------

## Como funciona
<a name="wrapped-cmp-how-it-works"></a>

O CMP encapsulado gera uma nova chave de criptografia para cada item. Ele usa as chaves de empacotamento, desempacotamento e assinatura que você fornece, conforme mostrado no diagrama a seguir.

![\[A entrada, o processamento e a saída do provedor empacotado de materiais no DynamoDB Encryption Client\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/wrappedCMP.png)


### Obter materiais de criptografia
<a name="wrapped-cmp-get-encryption-materials"></a>

Esta seção descreve em detalhes as entradas, as saídas e o processamento do provedor encapsulado de materiais (CMP encapsulado) quando ele recebe uma solicitação de materiais de criptografia. 

**Entrada** (do aplicativo)
+ Chave de empacotamento: uma chave simétrica do [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) ou uma chave pública [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)). Obrigatória se houver valores de atributo criptografados. Caso contrário, ela é opcional e ignorada.
+ Chave de descriptografia: opcional e ignorada. 
+ Chave de assinatura

**Entrada** (do criptografador de itens)
+ [Contexto de criptografia do DynamoDB](concepts.md#encryption-context)

**Saída** (para o criptografador de itens):
+ Chave de criptografia do item de texto simples
+ Chave de assinatura (inalterada)
+ [Descrição real do material](DDBEC-legacy-concepts.md#legacy-material-description): esses valores são salvos no [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) que o cliente adiciona ao item. 
  + `amzn-ddb-env-key`: chave de criptografia de item encapsulado codificada em Base64
  + `amzn-ddb-env-alg`: algoritmo de criptografia usado para criptografar o item. O padrão é AES-256-CBC.
  + `amzn-ddb-wrap-alg`: o algoritmo de empacotamento que o CMP empacotado usou para encapsular a chave de criptografia de item. Se a chave de empacotamento for uma chave do AES, ela será encapsulada com o `AES-Keywrap` não preenchido, conforme definido na [RFC 3394](https://tools.ietf.org/html/rfc3394.html). Se a chave de empacotamento for uma chave RSA, a chave será criptografada usando RSA OAEP com preenchimento. MGF1 

**Processamento**

Quando você criptografa um item, transmite uma chave de empacotamento e outra de assinatura. A chave de descriptografia é opcional e ignorada.

1. O CMP encapsulado gera uma chave exclusiva de criptografia simétrica para o item de tabela.

1. Ele usa a chave de empacotamento que você especifica para encapsular a chave de criptografia de item. Depois, ele a remove da memória o mais rápido possível.

1. Ele retorna a chave de criptografia do item de texto sem formatação, a chave de assinatura que você forneceu e uma [descrição real do material](DDBEC-legacy-concepts.md#legacy-material-description) que inclui a chave de criptografia do item empacotado e os algoritmos de criptografia e empacotamento.

1. O criptografador do item usa a chave de criptografia de texto simples para criptografar o item. Ele usa a chave de assinatura que você forneceu para assinar o item. Depois, ele remove as chaves de texto simples da memória o mais rápido possível. Ele copia os campos na descrição real do material, incluindo a chave de criptografia encapsulada (`amzn-ddb-env-key`), para o atributo de descrição do material do item.

### Obter materiais de descriptografia
<a name="wrapped-cmp-get-decryption-materials"></a>

Esta seção descreve em detalhes as entradas, as saídas e o processamento do provedor encapsulado de materiais (CMP encapsulado) quando ele recebe uma solicitação de materiais de descriptografia. 

**Entrada** (do aplicativo)
+ Chave de criptografia: opcional e ignorada.
+ Chave de descriptografia: a mesma chave simétrica [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) ou a chave privada [RSA](https://en.wikipedia.org/wiki/RSA_(cryptosystem)) que corresponde à chave pública RSA usada para criptografia. Obrigatória se houver valores de atributo criptografados. Caso contrário, ela é opcional e ignorada.
+ Chave de assinatura

**Entrada** (do criptografador de itens)
+ Uma cópia do [contexto de criptografia do DynamoDB](concepts.md#encryption-context) com o conteúdo do atributo de descrição do material.

**Saída** (para o criptografador de itens)
+ Chave de criptografia do item de texto simples
+ Chave de assinatura (inalterada)

**Processamento**

Quando você descriptografa um item, transmite uma chave de desempacotamento e outra de assinatura. A chave de empacotamento é opcional e ignorada.

1. O CMP encapsulado obtém a chave de criptografia de item encapsulado do atributo de descrição do material do item.

1. Ele usa o algoritmo e a chave de desempacotamento para desencapsular a chave de criptografia de item. 

1. Ele retorna a chave de criptografia de item de texto simples, a chave de assinatura e os algoritmos de criptografia e assinatura para o criptografador do item.

1. O criptografador do item usa a chave de assinatura para verificar o item. Quando consegue fazer isso, ele usa a chave de criptografia de item para descriptografar o item. Depois, ele remove as chaves de texto simples da memória o mais rápido possível.

# Provedor mais recente
<a name="most-recent-provider"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O *Provedor mais recente* é um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) que foi projetado para trabalhar com um [armazenamento de provedores](DDBEC-legacy-concepts.md#provider-store). Ele é CMPs obtido da loja do fornecedor e obtém os materiais criptográficos que retorna do CMPs. Normalmente, ele usa cada CMP para atender a várias solicitações de materiais de criptografia. Mas você pode usar os recursos do armazenamento de provedores para gerenciar a frequência com a qual os materiais são reutilizados, determinar a frequência de rotação do CMP e até mesmo alterar o tipo de CMP usado sem alterar o provedor mais recente.

**nota**  
O código associado ao símbolo `MostRecentProvider` do provedor mais recente pode armazenar materiais criptográficos na memória durante a vida útil do processo. Isso pode permitir que um chamador use chaves que não está mais autorizado a usar.   
O símbolo `MostRecentProvider` está obsoleto nas versões mais antigas compatíveis do DynamoDB Encryption Client e foi removido da versão 2.0.0. Ele é substituído pelo símbolo `CachingMostRecentProvider`. Para obter detalhes, consulte [Atualizações do provedor mais recente](#mrp-versions).

O provedor mais recente é uma boa opção para aplicativos que precisam minimizar as chamadas para o armazenamento de provedores, sua origem de criptografia e aplicativos que podem reutilizar alguns materiais de criptografia sem violar os requisitos de segurança. Por exemplo, ele permite que você proteja seus materiais criptográficos sob um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)(AWS KMS) sem chamar AWS KMS toda vez que você criptografa ou descriptografa um item.

O repositório do provedor que você escolher determina o tipo do CMPs que o provedor mais recente usa e com que frequência ele obtém um novo CMP. Você pode usar qualquer armazenamento compatível de provedores com o provedor mais recente, incluindo os armazenamentos de provedores personalizados que você criar. 

O DynamoDB Encryption Client inclui *MetaStore*um que cria e [retorna Wrapped Materials Providers (Wrapped](wrapped-provider.md)). CMPs Ele MetaStore salva várias versões do Wrapped CMPs que ele gera em uma tabela interna do DynamoDB e as protege com criptografia do lado do cliente por uma instância interna do DynamoDB Encryption Client. 

Você pode configurar o MetaStore para usar qualquer tipo de CMP interno para proteger os materiais na tabela, incluindo um [provedor de KMS direto](direct-kms-provider.md) que gera materiais criptográficos protegidos por você AWS KMS key, um CMP empacotado que usa chaves de empacotamento e assinatura fornecidas por você ou um CMP personalizado compatível que você cria.

**Para ver um código de exemplo, consulte:**
+ Java: [MostRecentEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/MostRecentEncryptedItem.java)
+ Python: [most\$1recent\$1provider\$1encrypted\$1table](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/most_recent_provider_encrypted_table.py)

**Topics**
+ [Como usar](#mrp-how-to-use-it)
+ [Como funciona](#mrp-how-it-works)
+ [Atualizações do provedor mais recente](#mrp-versions)

## Como usar
<a name="mrp-how-to-use-it"></a>

Para criar um provedor mais recente, você precisa criar e configurar um armazenamento de provedores e, em seguida, criar um provedor mais recente que usa o armazenamento de provedores. 

[Os exemplos a seguir mostram como criar um provedor mais recente que usa MetaStore e protege as versões em sua tabela interna do DynamoDB com materiais criptográficos de um provedor de KMS direto.](direct-kms-provider.md) Estes exemplos usam o símbolo [`CachingMostRecentProvider`](#mrp-versions). 

Cada provedor mais recente tem um nome que o identifica CMPs na MetaStore tabela, uma configuração [time-to-live](#most-recent-provider-ttl)(TTL) e uma configuração de tamanho de cache que determina quantas entradas o cache pode conter. Esses exemplos definem o tamanho do cache para 1000 entradas e um TTL de 60 segundos.

------
#### [ Java ]

```
// Set the name for MetaStore's internal table
final String keyTableName = 'metaStoreTable'

// Set the Region and AWS KMS key
final String region = 'us-west-2'
final String keyArn = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'

// Set the TTL and cache size
final long ttlInMillis = 60000;
final long cacheSize = 1000;

// Name that identifies the MetaStore's CMPs in the provider store
final String materialName = 'testMRP'

// Create an internal DynamoDB client for the MetaStore
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build();

// Create an internal Direct KMS Provider for the MetaStore
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider kmsProv = new DirectKmsMaterialProvider(kms, keyArn);

// Create an item encryptor for the MetaStore,
// including the Direct KMS Provider
final DynamoDBEncryptor keyEncryptor = DynamoDBEncryptor.getInstance(kmsProv);

// Create the MetaStore
final MetaStore metaStore = new MetaStore(ddb, keyTableName, keyEncryptor);

//Create the Most Recent Provider
final CachingMostRecentProvider cmp = new CachingMostRecentProvider(metaStore, materialName, ttlInMillis, cacheSize);
```

------
#### [ Python ]

```
# Designate an AWS KMS key
kms_key_id = 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'

# Set the name for MetaStore's internal table
meta_table_name = 'metaStoreTable'

# Name that identifies the MetaStore's CMPs in the provider store
material_name = 'testMRP'

# Create an internal DynamoDB table resource for the MetaStore
meta_table = boto3.resource('dynamodb').Table(meta_table_name)

# Create an internal Direct KMS Provider for the MetaStore
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
    
# Create the MetaStore with the Direct KMS Provider
meta_store = MetaStore(
    table=meta_table,
    materials_provider=kms_cmp
)

# Create a Most Recent Provider using the MetaStore
#    Sets the TTL (in seconds) and cache size (# entries)
most_recent_cmp = MostRecentProvider(
    provider_store=meta_store,
    material_name=material_name,
    version_ttl=60.0,
    cache_size=1000
)
```

------

## Como funciona
<a name="mrp-how-it-works"></a>

O fornecedor mais recente CMPs vem de uma loja de fornecedores. Em seguida, ele usa o CMP para gerar os materiais de criptografia que retorna ao criptografador de item.

### Sobre o provedor mais recente
<a name="about-mrp"></a>

O Provedor mais recente obtém um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) de um [armazenamento de provedores](DDBEC-legacy-concepts.md#provider-store). Em seguida, ele usa o CMP para gerar os materiais de criptografia que retorna. Cada provedor mais recente está associado a uma loja de provedores, mas uma loja de provedores pode fornecer CMPs a vários provedores em vários hosts.

O provedor mais recente pode trabalhar com qualquer CMP compatível de qualquer armazenamento de provedores. Ele solicita materiais de criptografia ou de descriptografia do CMP e retorna a saída ao criptografador do item. Não executa nenhuma operação de criptografia.

Para solicitar um CMP do armazenamento de provedores, o provedor mais recente fornece o nome de material e a versão de um CMP existente que deseja usar. Para materiais de criptografia, o provedor mais recente sempre solicita a versão mais recente. Para materiais de descriptografia, ele solicita a versão do CMP que foi usada para criar os materiais de criptografia, conforme exibido no diagrama a seguir.

![\[Um Provedor mais recente\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/most-recent-provider-1.png)


O provedor mais recente salva as versões do CMPs que o provedor armazena retornou em um cache local de uso menos recente (LRU) na memória. O cache permite que o provedor mais recente obtenha o CMPs que precisa sem chamar a loja do provedor para cada item. Você pode limpar o cache sob demanda.

O provedor mais recente usa um [time-to-livevalor](#most-recent-provider-ttl) configurável que você pode ajustar com base nas características do seu aplicativo.

### Sobre o MetaStore
<a name="about-metastore"></a>

Você pode usar um provedor mais recente com qualquer armazenamento de provedores, incluindo um armazenamento de provedores personalizado compatível. O DynamoDB Encryption Client inclui MetaStore uma implementação segura que você pode configurar e personalizar.

*MetaStore*A é um [repositório de provedores](DDBEC-legacy-concepts.md#provider-store) que cria e retorna [Wrapped CMPs](wrapped-provider.md) configurados com a chave de empacotamento, a chave de desempacotamento e a chave de assinatura exigidas pelo Wrapped. CMPs MetaStore A é uma opção segura para um provedor mais recente porque o Wrapped CMPs sempre gera chaves de criptografia de item exclusivas para cada item. Somente a chave de empacotamento que protege a chave de criptografia do item e as chaves de assinatura é reutilizada.

O diagrama a seguir mostra os componentes do MetaStore e como ele interage com o provedor mais recente.

![\[A MetaStore\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/most-recent-provider-2.png)


O MetaStore gera o Wrapped e CMPs, em seguida, o armazena (em formato criptografado) em uma tabela interna do DynamoDB. A chave de partição é o nome do material do provedor mais recente; a chave de classificação, seu número de versão. Os materiais na tabela são protegidos por um DynamoDB Encryption Client interno, incluindo um criptografador de item e um [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) interno.

Você pode usar qualquer tipo de CMP interno em seu MetaStore, incluindo um [provedor de KMS direto](wrapped-provider.md), um CMP empacotado com materiais criptográficos fornecidos por você ou um CMP personalizado compatível. Se o CMP interno do seu MetaStore for um provedor de KMS direto, suas chaves reutilizáveis de empacotamento e assinatura serão protegidas por um in (). [AWS KMS key[AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)AWS KMS As MetaStore chamadas AWS KMS sempre que ele adiciona uma nova versão do CMP à tabela interna ou obtém uma versão do CMP da tabela interna.

### Definindo um time-to-live valor
<a name="most-recent-provider-ttl"></a>

Você pode definir um valor time-to-live (TTL) para cada provedor mais recente que você criar. Em geral, use o valor TTL mais baixo que seja prático para a sua aplicação.

O uso do valor TTL é alterado no símbolo `CachingMostRecentProvider` do provedor mais recente. 

**nota**  
O símbolo `MostRecentProvider` do Provedor mais recente está obsoleto nas versões mais antigas compatíveis do DynamoDB Encryption Client e foi removido da versão 2.0.0. Ele é substituído pelo símbolo `CachingMostRecentProvider`. Recomendamos que você atualize seu código o mais rápido possível. Para obter detalhes, consulte [Atualizações do provedor mais recente](#mrp-versions).

**`CachingMostRecentProvider`**  
O `CachingMostRecentProvider` usa o valor TTL de duas maneiras diferentes.   
+ O TTL determina com que frequência o provedor mais recente verifica o armazenamento do provedor em busca de uma nova versão do CMP. Se uma nova versão estiver disponível, o provedor mais recente substituirá o CMP e atualizará os materiais criptográficos. Caso contrário, ele continuará usando o CMP atual e os materiais criptográficos.
+ O TTL determina por quanto tempo CMPs o cache pode ser usado. Antes de usar uma CMP em cache para criptografia, o provedor mais recente avalia seu tempo no cache. Se o tempo de cache do CMP exceder o TTL, o CMP será removido do cache e o provedor mais recente obterá um novo CMP da versão mais recente do repositório do provedor.

**`MostRecentProvider`**  
No `MostRecentProvider`, o TTL determina com que frequência o provedor mais recente verifica o armazenamento do provedor em busca de uma nova versão do CMP. Se uma nova versão estiver disponível, o provedor mais recente substituirá o CMP e atualizará os materiais criptográficos. Caso contrário, ele continuará usando o CMP atual e os materiais criptográficos.

O TTL não determina com que frequência uma nova versão do CMP é criada. Crie novas versões do CMP [alternando os materiais criptográficos](#most-recent-provider-rotate).

Um valor ideal de TTL varia de acordo com o aplicativo e suas metas de latência e disponibilidade. Um TTL mais baixo melhora seu perfil de segurança ao reduzir o tempo em que os materiais criptográficos são armazenados na memória. Além disso, um TTL mais baixo atualiza as informações críticas com mais frequência. Por exemplo, se seu CMP interno for um [Direct KMS Provider](direct-kms-provider.md), ele verificará com mais frequência se o chamador ainda está autorizado a usar um AWS KMS key.

No entanto, se o TTL for muito breve, as chamadas frequentes para o armazenamento do provedor podem aumentar seus custos e fazer com que o armazenamento do provedor reduza as solicitações do seu aplicativo e de outros aplicativos que compartilham sua conta de serviço. Também é possível se beneficiar da coordenação do TTL com a taxa na qual você alterna os materiais criptográficos. 

Durante o teste, varie o tamanho do TTL e do cache em diferentes cargas de trabalho até encontrar uma configuração que funcione para seu aplicativo e seus padrões de segurança e desempenho.

### Alternar os materiais de criptografia
<a name="most-recent-provider-rotate"></a>

Quando um provedor mais recente precisa de materiais de criptografia, ele sempre usa a versão mais recente de seu CMP que conhece. A frequência com que ele verifica uma versão mais recente é determinada pelo valor [time-to-live](#most-recent-provider-ttl)(TTL) que você define ao configurar o provedor mais recente. 

Quando o TTL expira, o provedor mais recente verifica o armazenamento do provedor em busca de uma nova versão do CMP. Se houver um disponível, o provedor mais recente o obterá e substituirá o CMP em seu cache. Ele usa esse CMP e seus materiais criptográficos até descobrir que o armazenamento do provedor tem uma versão mais recente.

Para solicitar que o armazenamento de provedores crie uma nova versão de um CMP para um provedor mais recente, chame a operação Criar Novo Provedor do armazenamento de provedores com o nome do material do provedor mais recente. O armazenamento de provedores cria um novo CMP e salva uma cópia criptografada em seu armazenamento interno com um número da versão mais recente. (Ele também retorna um CMP, mas você pode descartá-lo.) Como resultado, na próxima vez que o provedor mais recente consultar o repositório do provedor para obter o número máximo de versão CMPs, ele obterá o novo número de versão maior e o usará em solicitações subsequentes à loja para ver se uma nova versão da CMP foi criada.

Você pode programar as chamadas da operação Criar Novo Provedor com base no tempo, no número de itens ou de atributos processados ou em qualquer outra métrica que seja aceitável para seu aplicativo.

### Obter materiais de criptografia
<a name="most-recent-provider-encrypt"></a>

O provedor mais recente usa o seguinte processo, mostrado neste diagrama, para obter os materiais de criptografia retornados ao criptografador de item. A saída depende do tipo de CMP que o armazenamento de provedores retorna. O provedor mais recente pode usar qualquer loja de provedores compatível, incluindo a MetaStore que está incluída no DynamoDB Encryption Client.

![\[A entrada, o processamento e a saída do Provedor mais recente no DynamoDB Encryption Client.\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/most-recent-provider-provider-store.png)


Ao criar um provedor mais recente usando o [`CachingMostRecentProvider`símbolo](#mrp-versions), você especifica um repositório de provedores, um nome para o provedor mais recente e um valor [time-to-live](#most-recent-provider-ttl)(TTL). Também é possível especificar opcionalmente um tamanho de cache, que determina o número máximo de materiais criptográficos que podem existir no cache.

Quando o criptografador de item solicita ao provedor mais recente os materiais de criptografia, esse provedor começa pesquisando em seu cache a versão mais recente do CMP.
+ Se ele encontrar a versão mais recente do CMP no cache e o CMP não tiver excedido o valor TTL, o provedor mais recente usará o CMP para gerar materiais de criptografia. Em seguida, ele retorna os materiais de criptografia ao criptografador de item. Essa operação não requer uma chamada para o armazenamento de provedores.
+ Se a versão mais recente do CMP não estiver no cache, ou se estiver no cache mas tiver excedido o valor TTL, o provedor mais recente solicitará um CMP do armazenamento de provedores. A solicitação inclui o nome do material do provedor mais recente e o número da versão mais recente que ele conhece.

  1. O armazenamento de provedores retorna um CMP de seu armazenamento persistente. Se o repositório do provedor for um MetaStore, ele obterá uma CMP encriptada encriptada de sua tabela interna do DynamoDB usando o nome do material Most Recent Provider como chave de partição e o número da versão como chave de classificação. O MetaStore usa seu criptografador de itens interno e CMP interno para descriptografar o Wrapped CMP. Em seguida, ele retorna o CMP com texto simples ao provedor mais recente. Se o CMP interno for um [Direct KMS Provider](direct-kms-provider.md), esta etapa incluirá uma chamada ao [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS).

  1. O CMP adiciona o campo `amzn-ddb-meta-id` à [descrição real do material](DDBEC-legacy-concepts.md#legacy-material-description). O valor é o nome do material e a versão do CMP em sua tabela interna. O armazenamento de provedores retorna o CMP ao provedor mais recente.

  1. O provedor mais recente armazena o CMP na memória.

  1. O provedor mais recente usa o CMP para gerar materiais de criptografia. Em seguida, ele retorna os materiais de criptografia ao criptografador de item.

### Obter materiais de descriptografia
<a name="most-recent-provider-decrypt"></a>

Quando o criptografador do item solicita ao provedor mais recente os materiais de descriptografia, esse provedor usa o seguinte processo para obtê-los e retorná-los.

1. O provedor mais recente solicita ao armazenamento de provedores o número da versão dos materiais de criptografia que foram usados para criptografar o item. Ele passa a descrição real do material a partir do [atributo de descrição do material](DDBEC-legacy-concepts.md#legacy-material-description) do item.

1. O armazenamento de provedores obtém o número da versão do CMP criptografado a partir do campo `amzn-ddb-meta-id` na descrição real do material e o retorna ao provedor mais recente.

1. O provedor mais recente pesquisa seu cache em busca da versão do CMP que foi usada para criptografar e assinar o item.
+ Se descobrir que a versão correspondente do CMP está em seu cache e o CMP não excedeu o [valor time-to-live (TTL)](#most-recent-provider-ttl), o provedor mais recente usa o CMP para gerar materiais de descriptografia. Em seguida, ele retorna os materiais de descriptografia ao criptografador de item. Essa operação não requer uma chamada para o armazenamento de provedores ou qualquer outro CMP.
+ Se a versão do CMP correspondente não estiver no cache, ou se o AWS KMS key estiver no cache mas tiver excedido o valor TTL, o provedor mais recente solicitará um CMP do armazenamento de provedores. Ele envia o nome do material e o número da versão do CMP criptografado na solicitação.

  1. O armazenamento de provedores pesquisa seu armazenamento persistente em busca do CMP usando o nome do provedor mais recente como a chave de partição e o número da versão como a chave de classificação.
     + Se o nome e o número da versão não estiverem no armazenamento persistente, o armazenamento de provedores gera uma exceção. Se o armazenamento de provedores foi usado para gerar o CMP, o CMP deve ser armazenado no armazenamento persistente, a menos que tenha sido intencionalmente excluído.
     + Se o CMP com o nome e o número de versão correspondentes estiverem no armazenamento persistente do armazenamento de provedores, este retornará o CMP especificado ao provedor mais recente. 

       Se o repositório do provedor for um MetaStore, ele obterá o CMP criptografado de sua tabela do DynamoDB. Em seguida, ele usa materiais de criptografia do CMP interno para descriptografar o CMP criptografado antes de retornar o CMP ao provedor mais recente. Se o CMP interno for um [Direct KMS Provider](direct-kms-provider.md), esta etapa incluirá uma chamada ao [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/) (AWS KMS).

  1. O provedor mais recente armazena o CMP na memória.

  1. O provedor mais recente usa o CMP para gerar materiais de descriptografia. Em seguida, ele retorna os materiais de descriptografia ao criptografador de item.

## Atualizações do provedor mais recente
<a name="mrp-versions"></a>

O símbolo do provedor mais recente é alterado de `MostRecentProvider` para `CachingMostRecentProvider`. 

**nota**  
O símbolo `MostRecentProvider`, que representa o provedor mais recente, foi descontinuado na versão 1.15 do DynamoDB Encryption Client for Java e na versão 1.3 do DynamoDB Encryption Client for Python e removido das versões 2.0.0 do DynamoDB Encryption Client nas duas implementações de linguagem. Use a `CachingMostRecentProvider` em vez disso.

O `CachingMostRecentProvider` implementa as seguintes mudanças:
+ O remove `CachingMostRecentProvider` periodicamente materiais criptográficos da memória quando seu tempo na memória excede o valor configurado [time-to-live (TTL).](#most-recent-provider-ttl) 

  O `MostRecentProvider` pode armazenar materiais criptográficos na memória durante toda a vida útil do processo. Como resultado, o provedor mais recente pode não estar ciente das alterações na autorização. Ele pode usar chaves de criptografia depois que as permissões do chamador para usá-las forem revogadas. 

  Se você não conseguir atualizar para essa nova versão, poderá obter um efeito semelhante chamando periodicamente o método `clear()` no cache. Esse método limpa manualmente o conteúdo do cache e exige que o provedor mais recente solicite um novo CMP e novos materiais criptográficos. 
+ O `CachingMostRecentProvider` também inclui uma configuração de tamanho de cache que oferece mais controle sobre o cache.

Para atualizar para o `CachingMostRecentProvider`, você precisa alterar o nome do símbolo em seu código. Em todos os outros aspectos, o `CachingMostRecentProvider` é totalmente compatível com versões anteriores do `MostRecentProvider`. Você não precisa criptografar novamente nenhum item da tabela.

No entanto, o `CachingMostRecentProvider` gera mais chamadas para a infraestrutura principal subjacente. Ele chama a loja do provedor pelo menos uma vez em cada intervalo time-to-live (TTL). Aplicativos com vários ativos CMPs (devido à rotação frequente) ou aplicativos com grandes frotas provavelmente serão sensíveis a essa mudança. 

Antes de lançar seu código atualizado, teste-o minuciosamente para garantir que as chamadas mais frequentes não prejudiquem seu aplicativo nem causem limitação por serviços dos quais seu provedor depende, como AWS Key Management Service () ou AWS KMS Amazon DynamoDB. Para mitigar quaisquer problemas de desempenho, ajuste o tamanho do cache e o time-to-live do `CachingMostRecentProvider` com base nas características de desempenho observadas. Para obter orientações, consulte [Definindo um time-to-live valor](#most-recent-provider-ttl).

# Provedor estático de materiais
<a name="static-provider"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O *Static Materials Provider* (Static CMP) é um [provedor de materiais criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) muito simples, destinado a testes, proof-of-concept demonstrações e compatibilidade antiga.

Para usar o CMP estático para criptografar um item de tabela, forneça uma chave de criptografia simétrica do [Advanced Encryption Standard](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) (AES) e uma chave de assinatura ou um par de chaves. Você deve fornecer as mesmas chaves para descriptografar o item criptografado. O CMP estático não realiza operações de criptografia. Em vez disso, ele transmite inalteradas as chaves de criptografia que você fornece ao criptografador do item. O criptografador do item criptografa os itens diretamente na chave de criptografia. Depois, ele usa a chave de assinatura diretamente para assiná-los. 

Como o CMP estático não gera nenhum material exclusivo de criptografia, todos os itens da tabela que você processa são criptografados com a mesma chave de criptografia e assinados pela mesma chave de assinatura. Ao usar a mesma chave para criptografar os valores de atributos em diversos itens ou a mesma chave ou par de chaves para assinar todos os itens, você corre o risco de ultrapassar os limites de criptografia das chaves. 

**nota**  
O [Provedor estático assimétrico](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/providers/AsymmetricStaticProvider.html) na biblioteca Java não é um provedor estático. Ele apenas oferece construtores alternativos para o [CMP encapsulado](wrapped-provider.md). Ele é seguro para fins de produção, mas você deve usar o CMP encapsulado diretamente sempre que possível.

O Static CMP é um dos vários [fornecedores de materiais criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMPs) compatíveis com o DynamoDB Encryption Client. Para obter informações sobre o outro CMPs, consulte[Provedor de materiais de criptografia](crypto-materials-providers.md).

**Para ver um código de exemplo, consulte:**
+ Java: [SymmetricEncryptedItem](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/SymmetricEncryptedItem.java)

**Topics**
+ [Como usar](#static-cmp-how-to-use)
+ [Como funciona](#static-cmp-how-it-works)

## Como usar
<a name="static-cmp-how-to-use"></a>

Para criar um provedor estático, forneça uma chave de criptografia ou um par de chaves e uma chave de assinatura ou um par de chaves. É necessário fornecer material de chave para criptografar e descriptografar os itens de tabela.

------
#### [ Java ]

```
// To encrypt
SecretKey cek = ...;        // Encryption key
SecretKey macKey =  ...;    // Signing key
EncryptionMaterialsProvider provider = new SymmetricStaticProvider(cek, macKey);

// To decrypt
SecretKey cek = ...;        // Encryption key
SecretKey macKey =  ...;    // Verification key
EncryptionMaterialsProvider provider = new SymmetricStaticProvider(cek, macKey);
```

------
#### [ Python ]

```
# You can provide encryption materials, decryption materials, or both
encrypt_keys = EncryptionMaterials(
    encryption_key = ...,
    signing_key = ...
)

decrypt_keys = DecryptionMaterials(
    decryption_key = ...,
    verification_key = ...
)

static_cmp = StaticCryptographicMaterialsProvider(
    encryption_materials=encrypt_keys
    decryption_materials=decrypt_keys
)
```

------

## Como funciona
<a name="static-cmp-how-it-works"></a>

O provedor estático transmite as chaves de criptografia e assinatura que você fornece ao criptografador do item, onde elas são usadas diretamente para criptografar e assinar os itens da tabela. As mesmas chaves são usadas para todos os itens, a menos que você forneça chaves diferentes para cada um deles.

![\[A entrada, o processamento e a saída do Provedor estático de materiais no DynamoDB Encryption Client.\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/staticCMP.png)


### Obter materiais de criptografia
<a name="static-cmp-get-encryption-materials"></a>

Esta seção descreve em detalhes as entradas, as saídas e o processamento do provedor estático de materiais (CMP estático) quando ele recebe uma solicitação de materiais de criptografia.

**Entrada** (do aplicativo)
+ Chave de criptografia - deve ser uma chave simétrica, como uma chave do [Advanced Encryption Standard](https://tools.ietf.org/html/rfc3394.html) (AES). 
+ Chave de assinatura - Pode ser uma chave simétrica ou um par de chaves assimétrico. 

**Entrada** (do criptografador de itens)
+ [Contexto de criptografia do DynamoDB](concepts.md#encryption-context)

**Saída** (para o criptografador de itens)
+ A chave de criptografia transmitida como entrada.
+ A chave de assinatura transmitida como entrada.
+ Descrição real do material: a [descrição solicitada do material](DDBEC-legacy-concepts.md#legacy-material-description), se houver, inalterada.

### Obter materiais de descriptografia
<a name="static-cmp-get-decryption-materials"></a>

Esta seção descreve em detalhes as entradas, as saídas e o processamento do provedor estático de materiais (CMP estático) quando ele recebe uma solicitação de materiais de descriptografia.

Embora ela inclua métodos separados para obter materiais de criptografia e de descriptografia, o comportamento é o mesmo. 

**Entrada** (do aplicativo)
+ Chave de criptografia - deve ser uma chave simétrica, como uma chave do [Advanced Encryption Standard](https://tools.ietf.org/html/rfc3394.html) (AES). 
+ Chave de assinatura - Pode ser uma chave simétrica ou um par de chaves assimétrico. 

**Entrada** (do criptografador de itens)
+ [Contexto de criptografia do DynamoDB](concepts.md#encryption-context) (não usado)

**Saída** (para o criptografador de itens)
+ A chave de criptografia transmitida como entrada.
+ A chave de assinatura transmitida como entrada.

# Linguagens de programação disponíveis do Amazon DynamoDB Encryption Client
<a name="programming-languages"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

O Amazon DynamoDB Encryption Client está disponível para as linguagens de programação a seguir. As bibliotecas específicas de linguagem variam, mas as implementações resultantes são interoperáveis. Por exemplo, é possível criptografar (e assinar) um item com o cliente de Java e descriptografá-lo com o cliente Python.

Para obter mais informações, consulte o tópico correspondente.

**Topics**
+ [Java](java.md)
+ [Python](python.md)

# Amazon DynamoDB Encryption Client para Java
<a name="java"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Este tópico explica como instalar e usar o Amazon DynamoDB Encryption Client para Java. Para obter detalhes sobre a programação com o DynamoDB Encryption Client, consulte [os exemplos de Java, os](java-examples.md) exemplos no repositório GitHub em e [o](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) [Javadoc](https://aws.github.io/aws-dynamodb-encryption-java/) para aws-dynamodb-encryption-java o DynamoDB Encryption Client.

**nota**  
Versões 1. *x.* *x* do DynamoDB Encryption Client for Java estão [end-of-support em](what-is-database-encryption-sdk.md#support) fase a partir de julho de 2022. Atualize para uma versão mais recente o mais rápido possível.

**Topics**
+ [Pré-requisitos](#java-prerequisites)
+ [Instalação](#java-installation)
+ [Uso do DynamoDB Encryption Client para Java](java-using.md)
+ [Exemplos de Java](java-examples.md)

## Pré-requisitos
<a name="java-prerequisites"></a>

Antes de instalar o Amazon DynamoDB Encryption Client para Java, verifique se você tem os pré-requisitos a seguir.

**Um ambiente de desenvolvimento Java**  
Você precisará do Java 8 ou posterior. No site da Oracle, acesse [Java SE Downloads](https://www.oracle.com/java/technologies/downloads/) e faça download e instale o Java SE Development Kit (JDK).  
Se você usa o Oracle JDK, também precisara fazer download e instalar os [arquivos de política de jurisdição de força ilimitada JCE (Java Cryptography Extension)](http://www.oracle.com/java/technologies/javase-jce8-downloads.html).

**AWS SDK para Java**  
O DynamoDB Encryption Client exige o módulo DynamoDB do mesmo que seu aplicativo não interaja com AWS SDK para Java o DynamoDB. É possível instalar todo o SDK ou apenas esse módulo. Se você usa o Maven, adicione `aws-java-sdk-dynamodb` ao arquivo `pom.xml`.   
Para obter mais informações sobre como instalar e configurar o AWS SDK para Java, consulte [AWS SDK para Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/getting-started.html).

## Instalação
<a name="java-installation"></a>

É possível instalar o Amazon DynamoDB Encryption Client para Java usando as opções a seguir.

**Manualmente**  
Para instalar o Amazon DynamoDB Encryption Client para Java, clone ou baixe o repositório. [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/) GitHub 

**Uso do Apache Maven**  
O Amazon DynamoDB Encryption Client para Java está disponível por meio do [Apache Maven](https://maven.apache.org/) com a definição de dependência a seguir.  

```
<dependency>
  <groupId>com.amazonaws</groupId>
  <artifactId>aws-dynamodb-encryption-java</artifactId>
  <version>version-number</version>
</dependency>
```

Depois de instalar o SDK, comece examinando o código de exemplo neste guia e o Javadoc do [DynamoDB Encryption Client ativado.](https://aws.github.io/aws-dynamodb-encryption-java/) GitHub

# Uso do DynamoDB Encryption Client para Java
<a name="java-using"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Este tópico explica alguns dos recursos do DynamoDB Encryption Client para Java que talvez não sejam encontrados em outras implementações de linguagem de programação. 

[Para obter detalhes sobre a programação com o DynamoDB Encryption Client, consulte [os exemplos em Java, os](java-examples.md) exemplos em GitHub on e [o](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) Javadoc para `aws-dynamodb-encryption-java repository` o DynamoDB Encryption Client.](https://aws.github.io/aws-dynamodb-encryption-java/)



**Topics**
+ [Criptografadores de itens](#attribute-encryptor)
+ [Configurar o comportamento de salvamento](#save-behavior)
+ [Ações de atributos em Java](#attribute-actions-java)
+ [Substituir nomes de tabelas](#override-table-name)

## Criptografadores de itens: AttributeEncryptor e Dynamo DBEncryptor
<a name="attribute-encryptor"></a>

[O DynamoDB Encryption Client em Java tem [dois criptografadores de itens](DDBEC-legacy-concepts.md#item-encryptor): o Dynamo de nível inferior e o. DBEncryptor [AttributeEncryptor](#attribute-encryptor)](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) 

`AttributeEncryptor`É uma classe auxiliar que ajuda você a usar [o Dynamo AWS SDK para Java com o DBMapper](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html) no DynamoDB `DynamoDB Encryptor` Encryption Client. Ao usar o `AttributeEncryptor` com o `DynamoDBMapper`, ele criptografa e assina seus itens de forma transparente quando você os salva. Ele também verifica e descriptografa seus itens de forma transparente quando você os carrega.

## Configurar o comportamento de salvamento
<a name="save-behavior"></a>

É possível usar o `AttributeEncryptor` e o `DynamoDBMapper` para adicionar ou substituir itens de tabela com atributos assinados somente ou criptografados e assinados. Para essas tarefas, recomendamos que você o configure para usar o comportamento de salvamento `PUT`, conforme mostrado no exemplo a seguir. Caso contrário, talvez você não possa descriptografar os dados. 

```
DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```

Se você usar o comportamento padrão de salvamento, que atualiza somente os atributos que são modelados no item da tabela, os atributos não serão incluídos na assinatura e não serão alterado nas gravações da tabela. Como resultado, em leituras posteriores de todos os atributos, a assinatura não será validada porque não inclui atributos não modelados.

Também é possível usar o comportamento de salvamento `CLOBBER`. Esse comportamento é idêntico ao comportamento de salvamento `PUT`, exceto pelo fato de que ele desabilita o bloqueio otimista e substitui o item na tabela.

Para evitar erros de assinatura, o DynamoDB Encryption Client lança uma exceção de runtime se um `AttributeEncryptor` for usado com um `DynamoDBMapper` que não esteja configurado com um comportamento de salvamento de `CLOBBER` ou `PUT`.

Para ver esse código usado em um exemplo, consulte [Usando o Dynamo DBMapper](java-examples.md#java-example-dynamodb-mapper) o exemplo [AwsKmsEncryptedObjectde.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java) no `aws-dynamodb-encryption-java` repositório em. GitHub

## Ações de atributos em Java
<a name="attribute-actions-java"></a>

As [Ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) determinam quais valores de atributo são criptografados e assinados, quais são apenas assinados e quais são ignorados. [O método usado para especificar ações de atributos depende de você usar o `DynamoDBMapper` e ou o `AttributeEncryptor` Dynamo de nível inferior. DBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html)

**Importante**  
Depois de usar as ações do atributo para criptografar os itens da tabela, adicionar ou remover atributos do modelo de dados poderá gerar um erro de validação de assinatura que impede a descriptografia dos dados. Para obter uma explicação detalhada, consulte [Alterar seu modelo de dados](data-model.md).

### Ações de atributos para o Dynamo DBMapper
<a name="attribute-action-java-mapper"></a>

Ao usar o `DynamoDBMapper` e o `AttributeEncryptor`, use anotações para especificar as ações de atributos. O DynamoDB Encryption Client usa as [anotações de atributo padrão do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Annotations.html) que definem o tipo do atributo para determinar como proteger um atributo. Por padrão, todos os atributos são criptografados e assinados, exceto as chaves primárias, que são assinadas, mas não são criptografadas.

**nota**  
Não criptografe o valor dos atributos com a [anotação @Dynamo DBVersion Attribute](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptimisticLocking.html), embora você possa (e deva) assiná-los. Caso contrário, as condições que usam o valor terão efeitos indesejados.

```
// Attributes are encrypted and signed
@DynamoDBAttribute(attributeName="Description")

// Partition keys are signed but not encrypted
@DynamoDBHashKey(attributeName="Title")

// Sort keys are signed but not encrypted
@DynamoDBRangeKey(attributeName="Author")
```

Para especificar exceções, use as anotações de criptografia definidas no DynamoDB Encryption Client para Java. Se você especificá-las no nível da classe, elas se tornam o valor padrão para a classe.

```
// Sign only
@DoNotEncrypt

// Do nothing; not encrypted or signed
@DoNotTouch
```

Por exemplo, essas anotações assinam, mas não criptografam o atributo `PublicationYear`, e não criptografam nem assinam o valor de atributo `ISBN`.

```
// Sign only (override the default)
@DoNotEncrypt
@DynamoDBAttribute(attributeName="PublicationYear")

// Do nothing (override the default)
@DoNotTouch
@DynamoDBAttribute(attributeName="ISBN")
```

### Ações de atributos para o Dynamo DBEncryptor
<a name="attribute-action-default"></a>

Para especificar ações de atributos ao usar [o Dynamo DBEncryptor](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) diretamente, crie um `HashMap` objeto no qual os pares nome-valor representem os nomes dos atributos e as ações especificadas. 

Os valores válidos para as ações de atributo estão definidos no tipo enumerado de `EncryptionFlags`. Você pode usar `ENCRYPT` e `SIGN` juntos, usar `SIGN` isoladamente ou omitir os dois. No entanto, se você usar `ENCRYPT` sozinho, o DynamoDB Encryption Client gerará um erro. Você não pode criptografar um atributo que você não assine.

```
ENCRYPT
SIGN
```

**Atenção**  
Não criptografe os atributos da chave primária. Eles devem permanecer em texto simples para que o DynamoDB possa encontrar o item sem executar uma varredura completa da tabela.

Se você especificar uma chave primária no contexto de criptografia e especificar `ENCRYPT` na ação de um atributo de chave primária, o DynamoDB Encryption Client gerará uma exceção.

Por exemplo, o código Java a seguir cria um `actions` HashMap que criptografa e assina todos os atributos no `record` item. As exceções são os atributos de chave de partição e de chave de classificação que são assinados, mas não criptografados, e o atributo `test` que não é assinado nem criptografado.

```
final EnumSet<EncryptionFlags> signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet<EncryptionFlags> encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map<String, Set<EncryptionFlags>> actions = new HashMap<>();

for (final String attributeName : record.keySet()) {
  switch (attributeName) {
    case partitionKeyName: // no break; falls through to next case
    case sortKeyName:
      // Partition and sort keys must not be encrypted, but should be signed
      actions.put(attributeName, signOnly);
      break;
    case "test":
      // Don't encrypt or sign
      break;
    default:
      // Encrypt and sign everything else
      actions.put(attributeName, encryptAndSign);
      break;
  }
}
```

Ao chamar o método [encryptRecord](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html#encryptRecord-java.util.Map-java.util.Map-com.amazonaws.services.dynamodbv2.datamodeling.encryption.EncryptionContext-) do `DynamoDBEncryptor`, especifique o mapa como o valor do parâmetro `attributeFlags`. Por exemplo, esta chamada para `encryptRecord` usa o mapa `actions`.

```
// Encrypt the plaintext record
final Map<String, AttributeValue> encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```

## Substituir nomes de tabelas
<a name="override-table-name"></a>

No DynamoDB Encryption Client, o nome da tabela do DynamoDB é um elemento do [contexto de criptografia do DynamoDB](concepts.md#encryption-context) que é passado para os métodos de criptografia e de descriptografia. Quando você criptografa ou assina itens de tabela, o contexto de criptografia do DynamoDB, inclusive o nome da tabela, é vinculado criptograficamente ao texto cifrado. Se o contexto de criptografia do DynamoDB passado para o método de descriptografia não corresponder ao contexto de criptografia do DynamoDB passado para o método de criptografia, a operação de descriptografia falhará.

Ocasionalmente, o nome de uma tabela muda, como quando você faz backup de uma tabela ou executa uma [point-in-time recuperação](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/PointInTimeRecovery.html). Ao descriptografar ou verificar a assinatura desses itens, passe o mesmo contexto de criptografia do DynamoDB usado para criptografar e assinar os itens, inclusive o nome da tabela original. O nome da tabela atual não é necessário. 

Quando você usa o `DynamoDBEncryptor`, você monta o contexto de criptografia do manualmente. No entanto, se você estiver usando o `DynamoDBMapper`, o `AttributeEncryptor` criará o contexto de criptografia do DynamoDB para você, incluindo o nome da tabela atual. Para informar ao `AttributeEncryptor` para criar um contexto de criptografia com um nome de tabela diferente, use o `EncryptionContextOverrideOperator`. 

Por exemplo, o código a seguir cria instâncias do provedor de materiais de criptografia (CMP) e do `DynamoDBEncryptor`. Depois, ele chama o método `setEncryptionContextOverrideOperator` do `DynamoDBEncryptor`. Ele usa o operador `overrideEncryptionContextTableName`, que substitui um nome de tabela. Quando ele é configurado dessa maneira, o `AttributeEncryptor` cria um contexto de criptografia do DynamoDB que inclui `newTableName` no lugar de `oldTableName`. Para ver um exemplo completo, consulte [EncryptionContextOverridesWithDynamoDBMapper.java.](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/EncryptionContextOverridesWithDynamoDBMapper.java)

```
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);

encryptor.setEncryptionContextOverrideOperator(EncryptionContextOperators.overrideEncryptionContextTableName(
                oldTableName, newTableName));
```

Quando você chama o método de carregamento do `DynamoDBMapper`, que descriptografa e verifica o item, você especifica o nome da tabela original.

```
mapper.load(itemClass, DynamoDBMapperConfig.builder()
                .withTableNameOverride(DynamoDBMapperConfig.TableNameOverride.withTableNameReplacement(oldTableName))
                .build());
```

Também é possível usar o operador `overrideEncryptionContextTableNameUsingMap`, que substitui vários nomes de tabela. 

Normalmente, os operadores de substituição de nome de tabela são usados ao descriptografar dados e verificar assinaturas. No entanto, é possível usá-los para definir o nome da tabela no contexto de criptografia do DynamoDB como um valor diferente ao criptografar e assinar.

Não use os operadores de substituição de nome de tabela se estiver usando o `DynamoDBEncryptor`. Em vez disso, crie um contexto de criptografia com o nome da tabela original e envie-o para o método de descriptografia.

# Código de exemplo para o DynamoDB Encryption Client para Java
<a name="java-examples"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Os exemplos a seguir mostram como usar o DynamoDB Encryption Client para Java para proteger a tabela do DynamoDB no aplicativo. Você pode encontrar mais exemplos (e contribuir com os seus) no diretório de [exemplos](https://github.com/aws/aws-dynamodb-encryption-java/tree/master/examples) do [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/)repositório em GitHub.

**Topics**
+ [Usando o Dynamo DBEncryptor](#java-example-ddb-encryptor)
+ [Usando o Dynamo DBMapper](#java-example-dynamodb-mapper)

## Usando o Dynamo DBEncryptor
<a name="java-example-ddb-encryptor"></a>

Este exemplo mostra como usar o [Dynamo de nível inferior DBEncryptor com o](https://aws.github.io/aws-dynamodb-encryption-java/com/amazonaws/services/dynamodbv2/datamodeling/encryption/DynamoDBEncryptor.html) [Direct](direct-kms-provider.md) KMS Provider. O Direct KMS Provider gera e protege seus materiais criptográficos sob um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys)in AWS Key Management Service (AWS KMS) especificado por você.

Você pode usar qualquer [provedor de materiais criptográficos](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) compatível com o. e você pode usar o Direct KMS Provider com e. `DynamoDBEncryptor` `DynamoDBMapper` [AttributeEncryptor](java-using.md#attribute-encryptor)

**Veja a amostra de código completa**: [AwsKmsEncryptedItem.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedItem.java)

Etapa 1: crie um Direct KMS Provider  
Crie uma instância do AWS KMS cliente com a região especificada. Em seguida, use a instância do cliente para criar uma instância de Direct KMS Provider com o AWS KMS key de sua preferência.   
Este exemplo usa o Amazon Resource Name (ARN) para identificar o AWS KMS key, mas você pode usar [qualquer identificador de chave válido](https://docs.aws.amazon.com/kms/latest/developerguide/viewing-keys.html#find-cmk-id-arn).   

```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```

Etapa 2: crie um item  
Este exemplo define um `record` HashMap que representa um item de tabela de amostra.  

```
final String partitionKeyName = "partition_attribute";
final String sortKeyName = "sort_attribute";

final Map<String, AttributeValue> record = new HashMap<>();
record.put(partitionKeyName, new AttributeValue().withS("value1"));
record.put(sortKeyName, new AttributeValue().withN("55"));
record.put("example", new AttributeValue().withS("data"));
record.put("numbers", new AttributeValue().withN("99"));
record.put("binary", new AttributeValue().withB(ByteBuffer.wrap(new byte[]{0x00, 0x01, 0x02})));
record.put("test", new AttributeValue().withS("test-value"));
```

Etapa 3: criar um Dynamo DBEncryptor  
Crie uma instância do `DynamoDBEncryptor` com o Direct KMS Provider.  

```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
```

Etapa 4: crie um contexto de criptografia do DynamoDB  
O [Contexto de criptografia do DynamoDB](concepts.md#encryption-context) contém informações sobre a estrutura da tabela e de como ela é criptografada e assinada. Se você usar o `DynamoDBMapper`, o `AttributeEncryptor` cria o contexto de criptografia para você.  

```
final String tableName = "testTable";

final EncryptionContext encryptionContext = new EncryptionContext.Builder()
    .withTableName(tableName)
    .withHashKeyName(partitionKeyName)
    .withRangeKeyName(sortKeyName)
    .build();
```

Etapa 5: crie o objeto de ações de atributo  
As [Ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) determinam os atributos do item que são criptografados e assinados, que são somente assinados e que não são criptografados nem assinados.  
Em Java, para especificar ações de atributos, você cria pares HashMap de nome e `EncryptionFlags` valor do atributo.   
Por exemplo, o código Java a seguir cria um `actions` HashMap que criptografa e assina todos os atributos no `record` item, exceto os atributos da chave de partição e da chave de classificação, que são assinados, mas não criptografados, e o `test` atributo, que não está assinado ou criptografado.  

```
final EnumSet<EncryptionFlags> signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet<EncryptionFlags> encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map<String, Set<EncryptionFlags>> actions = new HashMap<>();

for (final String attributeName : record.keySet()) {
  switch (attributeName) {
    case partitionKeyName: // fall through to the next case
    case sortKeyName:
      // Partition and sort keys must not be encrypted, but should be signed
      actions.put(attributeName, signOnly);
      break;
    case "test":
      // Neither encrypted nor signed
      break;
    default:
      // Encrypt and sign all other attributes
      actions.put(attributeName, encryptAndSign);
      break;
  }
}
```

Etapa 6: criptografe e assine o item  
Para criptografar e assinar o item da tabela, chame o método `encryptRecord` na instância do `DynamoDBEncryptor`. Especifique o item da tabela (`record`), as ações de atributo (`actions`) e o contexto de criptografia (`encryptionContext`).  

```
final Map<String, AttributeValue> encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```

Etapa 7: coloque o item na tabela do DynamoDB  
Finalmente, coloque o item criptografado e assinado na tabela do DynamoDB.  

```
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.defaultClient();
ddb.putItem(tableName, encrypted_record);
```

## Usando o Dynamo DBMapper
<a name="java-example-dynamodb-mapper"></a>

O exemplo a seguir mostra como usar a classe auxiliar do mapeador do DynamoDB com o [Direct KMS Provider](direct-kms-provider.md). O Direct KMS Provider gera e protege seus materiais criptográficos sob um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys) no AWS Key Management Service (AWS KMS) especificado por você.

Você pode usar qualquer [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) (CMP) compatível com o `DynamoDBMapper`, e usar o Direct KMS Provider com o `DynamoDBEncryptor` de baixo nível.

**Veja a amostra de código completa**: [AwsKmsEncryptedObject.java](https://github.com/aws/aws-dynamodb-encryption-java/blob/master/examples/src/main/java/com/amazonaws/examples/AwsKmsEncryptedObject.java)

Etapa 1: crie um Direct KMS Provider  
Crie uma instância do AWS KMS cliente com a região especificada. Em seguida, use a instância do cliente para criar uma instância de Direct KMS Provider com o AWS KMS key de sua preferência.   
Este exemplo usa o Amazon Resource Name (ARN) para identificar o AWS KMS key, mas você pode usar [qualquer identificador de chave válido](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#key-id).   

```
final String keyArn = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab";
final String region = "us-west-2";
      
final AWSKMS kms = AWSKMSClientBuilder.standard().withRegion(region).build();
final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kms, keyArn);
```

Etapa 2: criar o DynamoDB Encryptor e o Dynamo DBMapper  
Use o Direct KMS Provider que você criou na etapa anterior para criar uma instância do [DynamoDB Encryptor](java-using.md#attribute-encryptor). Você precisa instanciar o DynamoDB Encryptor de nível inferior para usar o DynamoDB Mapper.  
Em seguida, crie uma instância de seu banco de dados do DynamoDB e uma configuração de mapeador e use-as para criar uma instância do Mapeador do DynamoDB.   
Ao usar o `DynamoDBMapper` para adicionar ou editar itens assinados (ou criptografados e assinados), configure-o para [usar um comportamento de salvamento](java-using.md#save-behavior), como `PUT`, que inclua todos os atributos, conforme mostrado no exemplo a seguir. Caso contrário, talvez você não possa descriptografar os dados. 

```
final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp)
final AmazonDynamoDB ddb = AmazonDynamoDBClientBuilder.standard().withRegion(region).build();

DynamoDBMapperConfig mapperConfig = DynamoDBMapperConfig.builder().withSaveBehavior(SaveBehavior.PUT).build();
DynamoDBMapper mapper = new DynamoDBMapper(ddb, mapperConfig, new AttributeEncryptor(encryptor));
```

Etapa 3: Definir a tabela do DynamoDB  
Em seguida, defina sua tabela do DynamoDB. Use anotações para especificar as [ações de atributos](java-using.md#attribute-actions-java). Este exemplo cria uma tabela do DynamoDB, `ExampleTable`, e uma classe `DataPoJo` que representa itens da tabela.   
Nessa tabela de exemplo, os atributos de chave primária serão assinados, mas não criptografados. Isso se aplica ao `partition_attribute`, que é anotado com a `@DynamoDBHashKey`, e ao `sort_attribute`, que é anotado com a `@DynamoDBRangeKey`.   
Os atributos que são anotadas com o `@DynamoDBAttribute`, como o `some numbers`, serão criptografados e assinados. As exceções são os atributos que usam as anotações de criptografia `@DoNotEncrypt` (apenas assinar) ou `@DoNotTouch` (não criptografar nem assinar) definidos pelo DynamoDB Encryption Client. Por exemplo, como o atributo `leave me` tem uma anotação `@DoNotTouch`, ele não será criptografado nem assinado.  

```
@DynamoDBTable(tableName = "ExampleTable")
public static final class DataPoJo {
  private String partitionAttribute;
  private int sortAttribute;
  private String example;
  private long someNumbers;
  private byte[] someBinary;
  private String leaveMe;

  @DynamoDBHashKey(attributeName = "partition_attribute")
  public String getPartitionAttribute() {
    return partitionAttribute;
  }

  public void setPartitionAttribute(String partitionAttribute) {
    this.partitionAttribute = partitionAttribute;
  }

  @DynamoDBRangeKey(attributeName = "sort_attribute")
  public int getSortAttribute() {
    return sortAttribute;
  }

  public void setSortAttribute(int sortAttribute) {
    this.sortAttribute = sortAttribute;
  }

  @DynamoDBAttribute(attributeName = "example")
  public String getExample() {
    return example;
  }

  public void setExample(String example) {
    this.example = example;
  }

  @DynamoDBAttribute(attributeName = "some numbers")
  public long getSomeNumbers() {
    return someNumbers;
  }

  public void setSomeNumbers(long someNumbers) {
    this.someNumbers = someNumbers;
  }

  @DynamoDBAttribute(attributeName = "and some binary")
  public byte[] getSomeBinary() {
    return someBinary;
  }

  public void setSomeBinary(byte[] someBinary) {
    this.someBinary = someBinary;
  }

  @DynamoDBAttribute(attributeName = "leave me")
  @DoNotTouch
  public String getLeaveMe() {
    return leaveMe;
  }

  public void setLeaveMe(String leaveMe) {
    this.leaveMe = leaveMe;
  }

  @Override
  public String toString() {
    return "DataPoJo [partitionAttribute=" + partitionAttribute + ", sortAttribute="
        + sortAttribute + ", example=" + example + ", someNumbers=" + someNumbers
        + ", someBinary=" + Arrays.toString(someBinary) + ", leaveMe=" + leaveMe + "]";
  }
}
```

Etapa 4: Criptografar e salvar um item da tabela  
Agora, quando você cria um item da tabela e usa o Mapeador do DynamoDB para salvá-lo, o item é automaticamente criptografado e assinado antes de ser adicionado à tabela.  
Este exemplo define um item da tabela chamado `record`. Antes de serem salvos na tabela, seus atributos são criptografados e assinados com base nas anotações na classe `DataPoJo`. Nesse caso, todos os atributos, com exceção de `PartitionAttribute`, `SortAttribute` e `LeaveMe` são criptografados e assinados. O `PartitionAttribute` e `SortAttributes` são só assinados. O atributo `LeaveMe` não é criptografado nem assinado.  
Para criptografar e assinar o item `record` e, em seguida, adicioná-lo à `ExampleTable`, chame o método `save` da classe `DynamoDBMapper`. Como o DynamoDB Mapper é configurado para usar o comportamento de salvamento de `PUT`, o item substitui qualquer item com as mesmas chaves primárias, em vez de atualizá-los. Isso garante que as assinaturas correspondam e que você possa descriptografar o item ao obtê-lo da tabela.  

```
DataPoJo record = new DataPoJo();
record.setPartitionAttribute("is this");
record.setSortAttribute(55);
record.setExample("data");
record.setSomeNumbers(99);
record.setSomeBinary(new byte[]{0x00, 0x01, 0x02});
record.setLeaveMe("alone");

mapper.save(record);
```

# DynamoDB Encryption Client para Python
<a name="python"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Este tópico explica como instalar e usar o DynamoDB Encryption Client para Python. Você pode encontrar o código no [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/)repositório em GitHub, incluindo um [código de amostra](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) completo e testado para ajudar você a começar.

**nota**  
Versões 1. *x.* *x* e 2. *x.* *x* [do DynamoDB Encryption Client para Python estão end-of-support em fase a partir de julho de 2022.](what-is-database-encryption-sdk.md#support) Atualize para uma versão mais recente o mais rápido possível.

**Topics**
+ [Pré-requisitos](#python-prerequisites)
+ [Instalação](#python-installation)
+ [Uso do DynamoDB Encryption Client para Python](python-using.md)
+ [Exemplos de Python](python-examples.md)

## Pré-requisitos
<a name="python-prerequisites"></a>

Antes de instalar o Amazon DynamoDB Encryption Client para Python, verifique se você tem os pré-requisitos a seguir.

**Uma versão compatível do Python**  
O Python 3.8 ou posterior é exigido pelo Amazon DynamoDB Encryption Client para Python nas versões 3.3.0 e posteriores. Para fazer download do Python, consulte [Downloads do Python](https://www.python.org/downloads/).  
As versões anteriores do Amazon DynamoDB Encryption Client for Python oferecem suporte ao Python 2.7 e ao Python 3.4 e versões posteriores, mas recomendamos que você use a versão mais recente do DynamoDB Encryption Client.

**A ferramenta de instalação do pip para Python**  
O Python 3.6 e versões posteriores incluem **pip**, embora você possa querer atualizá-lo. Para obter mais informações sobre a atualização ou a instalação do pip, consulte [Installation](https://pip.pypa.io/en/latest/installation/) na documentação do **pip**.

## Instalação
<a name="python-installation"></a>

Use o **pip** para instalar o Amazon DynamoDB Encryption Client para Python, conforme mostrado nos exemplos a seguir.

**Para instalar a versão mais recente**  

```
pip install dynamodb-encryption-sdk
```

Para obter mais detalhes sobre o uso do **pip** para instalar e atualizar pacotes, consulte [Installing Packages](https://packaging.python.org/tutorials/installing-packages/).

O DynamoDB Encryption Client requer a [biblioteca de criptografia](https://cryptography.io/en/latest/) em todas as plataformas. Todas as versões do **pip** instalam e criam a biblioteca de **criptografia** no Windows e no OS X. **pip** 8.1 e posterior instala e cria a **criptografia** no Linux. Se estiver usando uma versão anterior do **pip**, e seu ambiente Linux não tiver as ferramentas necessárias para criar a biblioteca de **criptografia**, será necessário instalá-las. Para obter mais informações, consulte [Criação de criptografia no Linux](https://cryptography.io/en/latest/installation/#building-cryptography-on-linux).

Você pode obter a versão de desenvolvimento mais recente do DynamoDB Encryption Client no repositório em. [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) GitHub

Depois de instalar o DynamoDB Encryption Client, veja o código de exemplo do Python neste guia.

# Uso do DynamoDB Encryption Client para Python
<a name="python-using"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Este tópico explica alguns dos recursos do DynamoDB Encryption Client para Python que talvez não sejam encontrados em outras implementações de linguagem de programação. Esses atributos são projetados para facilitar o uso do DynamoDB Encryption Client da forma mais confiável possível. A menos que você tenha um caso de uso incomum, recomendamos que você os use.

Para obter detalhes sobre a programação com o DynamoDB Encryption Client, consulte os exemplos do [Python](python-examples.md) neste guia, os exemplos no repositório GitHub e [a documentação do](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) [Python](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/) para aws-dynamodb-encryption-python o DynamoDB Encryption Client.

**Topics**
+ [Classes auxiliares do cliente](#python-helpers)
+ [TableInfo classe](#table-info)
+ [Ações de atributos em Python](#python-attribute-actions)

## Classes auxiliares do cliente
<a name="python-helpers"></a>

O DynamoDB Encryption Client para Python inclui várias classes auxiliares do cliente que espelham as classes do Boto 3 para o DynamoDB. Essas classes auxiliares são projetadas para facilitar a adição da criptografia e da assinatura ao seu aplicativo DynamoDB existente e evitar os problemas mais comuns:
+ Evite que você criptografe a chave primária em seu item, adicionando uma ação de substituição da chave primária ao [AttributeActions](#python-attribute-actions)objeto ou lançando uma exceção se seu `AttributeActions` objeto solicitar explicitamente ao cliente que criptografe a chave primária. Se a ação padrão no objeto `AttributeActions` for `DO_NOTHING`, as classes auxiliares do cliente usarão a ação para a chave primária. Caso contrário, eles usarão `SIGN_ONLY`.
+ Crie um [TableInfo objeto](#python-helpers) e preencha o contexto de [criptografia do DynamoDB com base em uma chamada para o DynamoDB](concepts.md#encryption-context). Isso ajuda a garantir que o contexto de criptografia do DynamoDB seja preciso e o cliente possa identificar a chave primária.
+ Métodos de suporte, como `put_item` e `get_item`, que criptografam e descriptografam de modo transparente os itens da tabela quando você grava ou lê em uma tabela do DynamoDB. Somente o método `update_item` não é compatível.

É possível usar a classe auxiliar do cliente em vez de interagir diretamente com o [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor) de nível inferior. Use essas classes a menos que você precise definir opções avançadas no criptografador do item.

As classes auxiliares do cliente incluem:
+ [EncryptedTable](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html#module-dynamodb_encryption_sdk.encrypted.table)para aplicativos que usam o recurso [Tabela](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#table) no DynamoDB para processar uma tabela por vez.
+ [EncryptedResource](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html)para aplicativos que usam a classe [Service Resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#service-resource) no DynamoDB para processamento em lote.
+ [EncryptedClient](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html)para aplicativos que usam o [cliente de nível inferior](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb.html#client) no DynamoDB.

Para usar as classes auxiliares do cliente, o chamador deve ter permissão para chamar a operação do DynamoDB na tabela de destino. [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)

## TableInfo classe
<a name="table-info"></a>

A [TableInfo](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/structures.html#dynamodb_encryption_sdk.structures.TableInfo)classe é uma classe auxiliar que representa uma tabela do DynamoDB, completa com campos para sua chave primária e índices secundários. Com ela, você pode obter informações precisas e em tempo real sobre a tabela.

Se você utilizar uma [classe auxiliar do cliente](#python-helpers), ela criará e usará um objeto `TableInfo` para você. Caso contrário, você pode criar um explicitamente. Para ver um exemplo, consulte [Usar o criptografador de item](python-examples.md#python-example-item-encryptor).

Quando você chama o `refresh_indexed_attributes` método em um `TableInfo` objeto, ele preenche os valores da propriedade do objeto chamando a operação do DynamoDB. [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) Consultar a tabela é muito mais confiável que consultar os nomes de índice de hard-coding. A classe `TableInfo` também inclui uma propriedade `encryption_context_values` que fornece os valores necessários para o [contexto de criptografia do DynamoDB](concepts.md#encryption-context). 

Para usar o `refresh_indexed_attributes` método, o chamador deve ter permissão para chamar a operação do [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)DynamoDB na tabela de destino.

## Ações de atributos em Python
<a name="python-attribute-actions"></a>

As [Ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) informam ao criptografador de itens quais ações executar em cada atributo de item. Para especificar ações de atributo em Python, crie um objeto `AttributeActions` com uma ação padrão e todas as exceções dos atributos específicos. Os valores válidos estão definidos no tipo enumerado `CryptoAction`.

**Importante**  
Depois de usar as ações do atributo para criptografar os itens da tabela, adicionar ou remover atributos do modelo de dados poderá gerar um erro de validação de assinatura que impede a descriptografia dos dados. Para obter uma explicação detalhada, consulte [Alterar seu modelo de dados](data-model.md).

```
DO_NOTHING = 0
SIGN_ONLY = 1
ENCRYPT_AND_SIGN = 2
```

Por exemplo, o objeto `AttributeActions` estabelece `ENCRYPT_AND_SIGN` como o padrão para todos os atributos e define as exceções para os atributos `ISBN` e `PublicationYear`.

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={
        'ISBN': CryptoAction.DO_NOTHING,
        'PublicationYear': CryptoAction.SIGN_ONLY
    }
)
```

Se você usar uma [classe auxiliar do cliente](#python-helpers), não será necessário especificar uma ação de atributo para os atributos de chave primária. As classes auxiliares do cliente evitam que você criptografe sua chave primária.

Se você não utiliza uma classe auxiliar do cliente e a ação padrão é `ENCRYPT_AND_SIGN`, é necessário especificar uma ação para a chave primária. A ação recomendada para chaves primárias é `SIGN_ONLY`. Para facilitar esse procedimento, use o método `set_index_keys`, que usa SIGN\$1ONLY para chaves primárias ou DO\$1NOTHING, quando essa é a ação padrão.

**Atenção**  
Não criptografe os atributos da chave primária. Eles devem permanecer em texto simples para que o DynamoDB possa encontrar o item sem executar uma varredura completa da tabela.

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
)
actions.set_index_keys(*table_info.protected_index_keys())
```

# Código de exemplo para o DynamoDB Encryption Client para Python
<a name="python-examples"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Os exemplos a seguir mostram como usar o DynamoDB Encryption Client para Python para proteger os dados do DynamoDB no aplicativo. Você pode encontrar mais exemplos (e contribuir com os seus) no diretório de [exemplos](https://github.com/aws/aws-dynamodb-encryption-python/tree/master/examples) do [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/)repositório em GitHub.

**Topics**
+ [Use a classe auxiliar EncryptedTable do cliente](#python-example-table)
+ [Usar o criptografador de item](#python-example-item-encryptor)

## Use a classe auxiliar EncryptedTable do cliente
<a name="python-example-table"></a>

O exemplo a seguir mostra como usar o [Direct KMS Provider](direct-kms-provider.md) com a `EncryptedTable` [classe auxiliar do cliente](python-using.md#python-helpers). Este exemplo usa o mesmo [provedor de materiais de criptografia](DDBEC-legacy-concepts.md#concept-material-provider) que o [Usar o criptografador de item](#python-example-item-encryptor) exemplo a seguir. No entanto, ele usa a classe `EncryptedTable` em vez de interagir diretamente com o [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor) de nível inferior.

Comparando esses casos, você poderá visualizar o trabalho que a classe auxiliar do cliente faz para você. Isso inclui a criação do [Contexto de criptografia do DynamoDB](concepts.md#encryption-context) e a verificação de que os atributos de chave primária são sempre assinados, mas nunca criptografados. Para criar o contexto de criptografia e descobrir a chave primária, as classes auxiliares do cliente chamam a operação do DynamoDB. [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html) Para executar esse código, você deve ter permissão para chamar essa operação.

**Consulte o exemplo de código completo**: [ aws\$1kms\$1encrypted\$1table.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py)

Etapa 1: crie a tabela  
Comece criando uma instância de uma tabela padrão do DynamoDB com o nome da tabela.  

```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```

Etapa 2: crie um provedor de materiais de criptografia  
Crie uma instância do [provedor de materiais de criptografia](crypto-materials-providers.md) (CMP) que você selecionou.  
Este exemplo usa o [Direct KMS Provider](direct-kms-provider.md), mas você pode usar qualquer CMP compatível. Para criar um Direct KMS Provider, especifique um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys). Este exemplo usa o Amazon Resource Name (ARN) do AWS KMS key, mas você pode usar qualquer identificador de chave válido.  

```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```

Etapa 3: crie o objeto de ações de atributo  
As [Ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) informam ao criptografador de itens quais ações executar em cada atributo de item. O objeto `AttributeActions` neste exemplo criptografa e assina todos os itens exceto o atributo `test`, que é ignorado.  
Não especifique ações de atributo para os atributos de chave primária ao usar uma classe auxiliar do cliente. A classe `EncryptedTable` assina, mas nunca criptografa os atributos de chave primária.  

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={'test': CryptoAction.DO_NOTHING}
)
```

Etapa 4: crie a tabela criptografada  
Crie a tabela criptografada usando a tabela padrão, o Direct KMS Provider e as ações de atributo. Essa etapa conclui a configuração.   

```
encrypted_table = EncryptedTable(
    table=table,
    materials_provider=kms_cmp,
    attribute_actions=actions
)
```

Etapa 5: coloque o item de texto simples na tabela  
Ao chamar o método `put_item` no `encrypted_table`, os itens da tabela são criptografados, assinados e adicionados à tabela do DynamoDB de maneira transparente.  
Primeiro, defina o item da tabela.  

```
plaintext_item = {
    'partition_attribute': 'value1',
    'sort_attribute': 55
    'example': 'data',
    'numbers': 99,
    'binary': Binary(b'\x00\x01\x02'),
    'test': 'test-value'
}
```
Em seguida, coloque-o na tabela.  

```
encrypted_table.put_item(Item=plaintext_item)
```

Para obter o item da tabela do `get_item` na forma criptografada, chame o método no objeto `table`. Para obter o item descriptografado, chame o método `get_item` no objeto `encrypted_table`.

## Usar o criptografador de item
<a name="python-example-item-encryptor"></a>

Este exemplo mostra como interagir diretamente com o [criptografador de itens](DDBEC-legacy-concepts.md#item-encryptor) no DynamoDB Encryption Client ao criptografar itens de tabela, em vez de usar as [classes auxiliares do cliente](python-using.md#python-helpers) que interagem com o criptografador de itens para você. 

Ao usar essa técnica, crie o contexto de criptografia e o objeto de configuração (`CryptoConfig`) do DynamoDB manualmente. Além disso, criptografe os itens em uma chamada e coloque-os na tabela do DynamoDB em uma chamada separada. Isso permite personalizar suas chamadas do `put_item` e usar o DynamoDB Encryption Client para criptografar e assinar dados estruturados que nunca são enviados ao DynamoDB.

Este exemplo usa o [Direct KMS Provider](direct-kms-provider.md), mas você pode usar qualquer CMP compatível.

**Consulte o exemplo de código completo**: [ aws\$1kms\$1encrypted\$1item.py](https://github.com/aws/aws-dynamodb-encryption-python/blob/master/examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py)

Etapa 1: crie a tabela  
Comece criando uma instância de um recurso de tabela padrão do DynamoDB com o nome da tabela.  

```
table_name='test-table'
table = boto3.resource('dynamodb').Table(table_name)
```

Etapa 2: crie um provedor de materiais de criptografia  
Crie uma instância do [provedor de materiais de criptografia](crypto-materials-providers.md) (CMP) que você selecionou.  
Este exemplo usa o [Direct KMS Provider](direct-kms-provider.md), mas você pode usar qualquer CMP compatível. Para criar um Direct KMS Provider, especifique um [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#master_keys). Este exemplo usa o Amazon Resource Name (ARN) do AWS KMS key, mas você pode usar qualquer identificador de chave válido.  

```
kms_key_id='arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab'
kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=kms_key_id)
```

Etapa 3: usar a TableInfo classe auxiliar  
Para obter informações sobre a tabela do DynamoDB, crie uma instância da [TableInfo](python-using.md#python-helpers)classe auxiliar. Ao trabalhar diretamente com o criptografador de item, você precisa criar uma instância `TableInfo` e chamar seus métodos. As [classes auxiliares do cliente](python-using.md#python-helpers) fazem isso para você.  
O `refresh_indexed_attributes` método de `TableInfo` usa a operação do [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)DynamoDB para obter informações precisas e em tempo real sobre a tabela. Isso inclui sua chave primária e seus índices secundários locais e globais. O chamador precisa ter permissão para chamar `DescribeTable`.  

```
table_info = TableInfo(name=table_name)
table_info.refresh_indexed_attributes(table.meta.client)
```

Etapa 4: crie o contexto de criptografia do DynamoDB  
O [Contexto de criptografia do DynamoDB](concepts.md#encryption-context) contém informações sobre a estrutura da tabela e de como ela é criptografada e assinada. Este exemplo cria um contexto de criptografia do DynamoDB explicitamente, pois interage com o criptografador de item. As [classes auxiliares do cliente](python-using.md#python-helpers) criam o contexto de criptografia do DynamoDB para você.   
Para obter a chave de partição e a chave de classificação, você pode usar as propriedades da classe [TableInfo](python-using.md#python-helpers)auxiliar.   

```
index_key = {
    'partition_attribute': 'value1',
    'sort_attribute': 55
}

encryption_context = EncryptionContext(
    table_name=table_name,
    partition_key_name=table_info.primary_index.partition,
    sort_key_name=table_info.primary_index.sort,
    attributes=dict_to_ddb(index_key)
)
```

Etapa 5: crie o objeto de ações de atributo  
As [Ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) informam ao criptografador de itens quais ações executar em cada atributo de item. O objeto `AttributeActions` neste exemplo criptografa e assina todos os itens, exceto para os atributos de chave primária, que são assinados, mas não criptografados, e o atributo `test`, que é ignorado.  
Ao interagir diretamente com o criptografador de item, e a ação padrão ser `ENCRYPT_AND_SIGN`, você deve especificar uma ação alternativa para a chave primária. Você pode usar o método `set_index_keys`, que utiliza `SIGN_ONLY` para a chave primária ou usa `DO_NOTHING` se é o padrão.  
Para especificar a chave primária, este exemplo usa as chaves de índice no [TableInfo](python-using.md#python-helpers)objeto, que são preenchidas por uma chamada para o DynamoDB. Esta técnica é mais segura do que nomes de chave primária de hard-code.  

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={'test': CryptoAction.DO_NOTHING}
)
actions.set_index_keys(*table_info.protected_index_keys())
```

Etapa 6: crie a configuração para o item  
Para configurar o DynamoDB Encryption Client, use os objetos que você acabou de criar em [CryptoConfig](https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html)uma configuração para o item da tabela. As classes auxiliares do cliente criam o CryptoConfig para você.   

```
crypto_config = CryptoConfig(
    materials_provider=kms_cmp,
    encryption_context=encryption_context,
    attribute_actions=actions
)
```

Etapa 7: criptografe o item  
Essa etapa criptografa e assina o item, mas não o coloca em uma tabela do DynamoDB.   
Quando você usa uma classe auxiliar do cliente, seus itens são criptografados e assinados de maneira transparente e, em seguida, adicionados à tabela do DynamoDB quando você chama o método `put_item` da classe auxiliar. Ao usar o criptografador de item diretamente, as ações de criptografia e colocação são independentes.  
Primeiro, crie um item de texto simples.  

```
plaintext_item = {
    'partition_attribute': 'value1',
    'sort_key': 55,
    'example': 'data',
    'numbers': 99,
    'binary': Binary(b'\x00\x01\x02'),
    'test': 'test-value'
}
```
Em seguida, criptografe e assine o item. O método `encrypt_python_item` requer o objeto de configuração `CryptoConfig`.  

```
encrypted_item = encrypt_python_item(plaintext_item, crypto_config)
```

Etapa 8: coloque o item na tabela  
Essa etapa coloca o item criptografado e assinado na tabela do DynamoDB.  

```
table.put_item(Item=encrypted_item)
```

Para visualizar o item criptografado, chame o método `get_item` no objeto original `table`, em vez do objeto `encrypted_table`. Ele obtém o item de tabela do DynamoDB sem verificá-la e descriptografá-la.

```
encrypted_item = table.get_item(Key=partition_key)['Item']
```

A imagem a seguir mostra parte de um item de tabela criptografado e assinado.

Os valores de atributos criptografados são dados binários. Os nomes e valores de atributos de chave primária (`partition_attribute` e `sort_attribute`) e o atributo `test` permanecem em texto simples. A saída também mostra o atributo que contém a assinatura (`*amzn-ddb-map-sig*`) e o [atributo de descrição de materiais](DDBEC-legacy-concepts.md#legacy-material-description) (`*amzn-ddb-map-desc*`).

![\[Um trecho de um item criptografado e assinado\]](http://docs.aws.amazon.com/pt_br/database-encryption-sdk/latest/devguide/images/encrypted-item-closeup.png)


# Alterar seu modelo de dados
<a name="data-model"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Sempre que criptografa ou descriptografa um item, você precisa fornecer d[ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) que informam ao DynamoDB Encryption Client quais atributos criptografar e assinar, quais assinar (mas não criptografar) e quais ignorar. As ações de atributos não são salvas no item criptografado e o DynamoDB Encryption Client não atualiza as ações de atributos automaticamente.

**Importante**  
O DynamoDB Encryption Client não oferece suporte à criptografia de dados de tabela do DynamoDB existentes e não criptografados.

Sempre que alterar seu modelo de dados, ou seja, ao adicionar ou remover atributos de seus itens de tabela, você corre o risco de um erro. Se as ações de atributo especificadas por você não justificam todos os atributos no item, ele não poderá ser criptografado nem assinado como você deseja. O mais importante é que se as ações dos atributos fornecidas por você ao descriptografar um item forem diferentes das ações de atributos fornecidas ao criptografar o item, poderá ocorrer uma falha na verificação da assinatura. 

Por exemplo, se as ações de atributo usadas para criptografar o item o instruem a assinar o atributo `test`, a assinatura no item incluirá o atributo `test`. Mas se as ações de atributo usadas para descriptografar o item não justificam o atributo `test`, ocorrerá uma falha na verificação porque o cliente tentará verificar uma assinatura que não inclui o atributo `test`. 

Esse é um problema específico quando vários aplicativos leem e gravam os mesmos itens do DynamoDB porque o DynamoDB Encryption Client precisa calcular a mesma assinatura para itens em todos os aplicativos. Também é um problema para qualquer aplicativo distribuído porque as alterações nas ações de atributos devem ser propagadas para todos os hosts. Mesmo que suas tabelas do DynamoDB sejam acessadas por um único host em um processo, o estabelecimento de um processo de melhores práticas ajudará a evitar erros se o projeto se tornar mais complexo.

Para evitar erros de validação de assinatura que impedem a leitura de itens de tabela, use as orientações a seguir.
+ [Adicionar um atributo](#add-attribute) — Se o novo atributo alterar as ações de atributo, implante totalmente a alteração da ação de atributo antes de incluir o novo atributo em um item.
+ [Remover um atributo](#remove-attribute) — Se você parar de usar um atributo nos itens, não altere as suas ações de atributo. 
+ Alterar a ação — Depois de usar uma configuração de ações de atributo para criptografar os itens da tabela, não será possível alterar com segurança a ação padrão ou a ação de um atributo existente sem recriptografar cada item da tabela.

Erros de validação de assinatura podem ser extremamente difíceis de resolver, portanto, a melhor abordagem é evitá-los. 

**Topics**
+ [Adicionar um atributo](#add-attribute)
+ [Remover um atributo](#remove-attribute)

## Adicionar um atributo
<a name="add-attribute"></a>

Ao adicionar um novo atributo a itens de tabela, talvez seja necessário alterar as ações de seus atributos. Para evitar erros de validação de assinatura, é recomendável implementar essa alteração em um processo de dois estágios. Verifique se o primeiro estágio está completo antes de iniciar o segundo estágio.

1. Altere as ações de atributos em todos os aplicativos que leem ou gravam na tabela. Implante essas alterações e confirme se a atualização foi propagada para todos os hosts de destino. 

1. Grave valores para o novo atributo em seus itens de tabela.

Essa abordagem em dois estágios garante que todos os aplicativos e hosts tenham as mesmas ações de atributos e calculará a mesma assinatura, antes de qualquer encontro com o novo atributo. Isso é importante mesmo quando a ação do atributo for *Não fazer nada* (não criptografar ou assinar), porque o padrão para alguns criptografadores é criptografar e assinar.

Os exemplos a seguir mostram o código para o primeiro estágio desse processo. Eles adicionam um novo atributo de item, `link`, que armazena um link para outro item da tabela. Como esse link deve permanecer em texto simples, o exemplo atribui a ele a ação somente assinar. Depois de implantar totalmente essa alteração e verificar se todos os aplicativos e hosts têm as novas ações de atributos, é possível começar a usar o atributo `link` em seus itens de tabela.

------
#### [ Java DynamoDB Mapper ]

Por padrão, ao usar o `DynamoDB Mapper` e o `AttributeEncryptor`, todos os atributos são criptografados e assinados, exceto as chaves primárias que são assinadas, mas não são criptografadas. Para especificar uma ação de somente assinatura, use a anotação `@DoNotEncrypt`. 

Este exemplo usa a anotação `@DoNotEncrypt` para o novo atributo `link`.

```
@DynamoDBTable(tableName = "ExampleTable")
public static final class DataPoJo {
  private String partitionAttribute;
  private int sortAttribute;
  private String link;

  @DynamoDBHashKey(attributeName = "partition_attribute")
  public String getPartitionAttribute() {
    return partitionAttribute;
  }
    
  public void setPartitionAttribute(String partitionAttribute) {
    this.partitionAttribute = partitionAttribute;
  }

  @DynamoDBRangeKey(attributeName = "sort_attribute")
  public int getSortAttribute() {
    return sortAttribute;
  }

  public void setSortAttribute(int sortAttribute) {
    this.sortAttribute = sortAttribute;
  }

  @DynamoDBAttribute(attributeName = "link")
  @DoNotEncrypt
  public String getLink() {
    return link;
  }

  public void setLink(String link) {
    this.link = link;
  }

  @Override
  public String toString() {
    return "DataPoJo [partitionAttribute=" + partitionAttribute + ",
        sortAttribute=" + sortAttribute + ",
        link=" + link + "]";
  }
}
```

------
#### [ Java DynamoDB encryptor ]

 No DynamoDB Encryptor de nível inferior, você deve definir ações para cada atributo. Este exemplo usa uma instrução switch em que o padrão é `encryptAndSign` e exceções são especificadas para a chave de partição, a chave de classificação e o novo atributo `link`. Neste exemplo, se o código do atributo link não for totalmente implantado antes de ser usado, o atributo link será criptografado e assinado por alguns aplicativos, mas somente assinado por outros.

```
for (final String attributeName : record.keySet()) {
    switch (attributeName) {
        case partitionKeyName:
            // fall through to the next case
        case sortKeyName:
            // partition and sort keys must be signed, but not encrypted
            actions.put(attributeName, signOnly);
            break;
        case "link":
            // only signed
            actions.put(attributeName, signOnly);
            break;
        default:
            // Encrypt and sign all other attributes
            actions.put(attributeName, encryptAndSign);
            break;
    }
}
```

------
#### [ Python ]

No DynamoDB Encryption Client para Python, é possível especificar uma ação padrão para todos os atributos e especificar exceções. 

Se você usa uma [classe auxiliar do cliente](python-using.md#python-helpers) do Python, não será necessário especificar uma ação de atributo para os atributos de chave primária. As classes auxiliares do cliente evitam que você criptografe sua chave primária. No entanto, se você não estiver usando uma classe auxiliar do cliente, defina a ação SIGN\$1ONLY em sua chave de partição e em sua chave de classificação. Se você criptografar acidentalmente sua chave de partição ou de classificação, não será possível recuperar seus dados sem uma verificação completa da tabela.

Este exemplo especifica uma exceção para o novo atributo `link`, que obtém a ação `SIGN_ONLY`.

```
actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={
      'example': CryptoAction.DO_NOTHING,  
      'link': CryptoAction.SIGN_ONLY
    }
)
```

------

## Remover um atributo
<a name="remove-attribute"></a>

Se você não precisar mais de um atributo em itens que foram criptografados com o DynamoDB Encryption Client, poderá parar de usar o atributo. No entanto, não exclua nem altere a ação desse atributo. Se o fizer e depois encontrar um item com esse atributo, a assinatura calculada para o item não corresponderá à assinatura original, e a validação da assinatura falhará.

Embora você possa ser tentado a remover todos os traços do atributo do seu código, adicione um comentário informando que o item não é mais usado em vez de excluí-lo. Mesmo que você faça uma verificação de tabela completa para excluir todas as instâncias do atributo, um item criptografado com esse atributo pode ser armazenado em cache ou em processo em algum lugar da configuração.

# Solução de problemas em seu aplicativo DynamoDB Encryption Client
<a name="troubleshooting"></a>

**nota**  
Nossa biblioteca de criptografia do lado do cliente foi [renomeada como SDK de criptografia de banco de dados da AWS](DDBEC-rename.md). O tópico a seguir fornece informações sobre as versões 1.*x*—2.*x* do DynamoDB Encryption Client para Java e versões 1.*x*—3*x* do DynamoDB Encryption Client para Python. Para obter mais informações, consulte [SDK de criptografia de banco de dados da AWS para obter suporte à versão do DynamoDB](legacy-dynamodb-encryption-client.md#legacy-support).

Esta seção descreve os problemas que você pode encontrar ao usar o DynamoDB Encryption Client e oferece sugestões para resolvê-los.

Para fornecer feedback sobre o DynamoDB Encryption Client, registre um problema no [aws-dynamodb-encryption-java](https://github.com/aws/aws-dynamodb-encryption-java/)repositório or. [aws-dynamodb-encryption-python](https://github.com/aws/aws-dynamodb-encryption-python/) GitHub 

Para fornecer feedback sobre esta documentação, use o link de feedback em qualquer página.

**Topics**
+ [Acesso negado](#kms-permissions)
+ [Falhas na verificação da assinatura](#change-data-model)
+ [Problemas com tabelas globais de versões mais antigas](#fix-global-tables)
+ [Baixo desempenho do fornecedor mais recente](#mrp-ttl-delay)

## Acesso negado
<a name="kms-permissions"></a>

**Problema**: o acesso a um recurso necessário é negado ao aplicativo.

**Sugestão**: saiba mais sobre as permissões necessárias e adicione-as ao contexto de segurança em que o aplicativo é executado.

**Detalhes**

Para executar um aplicativo que usa uma biblioteca do DynamoDB Encryption Client, o chamador deve ter permissão para usar os componentes. Caso contrário, eles terão o acesso negado aos elementos necessários. 
+ O DynamoDB Encryption Client não exige uma conta Amazon Web Services (AWS) nem depende de nenhum serviço da AWS . No entanto, se seu aplicativo usa AWS, você precisa de [um](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) [usuário Conta da AWS e que tenham permissão](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html) para usar a conta.
+ O DynamoDB Encryption Client não exige o Amazon DynamoDB. No entanto, se o aplicativo que usa o cliente criar tabelas do DynamoDB, colocar os itens em uma tabela ou obtiver itens de uma tabela, o chamador deverá ter permissão para usar as operações do DynamoDB necessárias em sua Conta da AWS. Para obter detalhes, consulte os [tópicos de controle de acesso](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/access-control-overview.html) no *Amazon DynamoDB Developer Guide*.
+ Se seu aplicativo usa uma [classe auxiliar de cliente](python-using.md#python-helpers) no DynamoDB Encryption Client for Python, o chamador deverá ter permissão para chamar a operação do DynamoDB. [DescribeTable](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html)
+ O DynamoDB Encryption Client não AWS Key Management Service exige ().AWS KMS No entanto, se seu aplicativo usa um provedor [direto de materiais KMS ou usa um provedor](direct-kms-provider.md) [mais recente](most-recent-provider.md) com uma loja de provedores que usa AWS KMS, o chamador deve ter permissão para usar as operações AWS KMS [GenerateDataKey](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)e [Decrypt](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html).

## Falhas na verificação da assinatura
<a name="change-data-model"></a>

**Problema**: um item não pode ser descriptografado porque ocorre uma falha na verificação de assinatura. O item também pode não ser criptografado e assinado como você deseja.

**Sugestão**: verifique se as ações de atributos fornecidas justificam todos os atributos no item. Ao descriptografar um item, forneça as ações de atributos que correspondam às ações usadas para criptografar o item.

**Detalhes**

As [ações de atributos](DDBEC-legacy-concepts.md#legacy-attribute-actions) fornecidas informam ao DynamoDB Encryption Client quais atributos criptografar e assinar, quais atributos assinar (mas não criptografar) e quais ignorar. 

Se as ações de atributo especificadas por você não justificam todos os atributos no item, ele não poderá ser criptografado nem assinado como você deseja. Se as ações de atributo fornecidas por você ao descriptografar um item são diferentes das ações de atributo fornecidas por você ao criptografar o item, pode ocorrer uma falha na verificação de assinatura. Este é um problema específico para aplicativos distribuídos em que novas ações de atributo talvez não tenham sigo propagadas para todos os hosts.

Erros de validação de assinatura são difíceis de resolver. Para ajudar a evitá-los, tome precauções extras ao alterar seu modelo de dados. Para obter detalhes, consulte [Alterar seu modelo de dados](data-model.md).

## Problemas com tabelas globais de versões mais antigas
<a name="fix-global-tables"></a>

**Problema**: os itens em uma versão mais antiga da tabela global do Amazon DynamoDB não podem ser descriptografados porque a verificação da assinatura falha.

**Sugestão**: defina ações de atributo para que os campos de replicação reservados não sejam criptografados ou assinados.

**Detalhes**

É possível usar o DynamoDB Encryption Client com as [tabelas globais do DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GlobalTables.html). Recomendamos que você use tabelas globais com uma chave [KMS multirregional e replique a chave](https://docs.aws.amazon.com/kms/latest/developerguide/multi-region-keys-overview.html) KMS em todos os Regiões da AWS lugares onde a tabela global é replicada.

A partir da [versão 2019.11.21](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V2.html) de tabelas globais, é possível usar tabelas globais com o DynamoDB Encryption Client sem nenhuma configuração especial. No entanto, se você usar tabelas globais [versão 2017.11.29](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/globaltables.V1.html), deverá garantir que os campos de replicação reservados não sejam criptografados ou assinados.

[Se você estiver usando a versão de tabelas globais 2017.11.29, deverá definir as ações de atributo para os atributos a seguir `DO_NOTHING` em [Java](java-using.md#attribute-actions-java) ou `@DoNotTouch` em Python](python-using.md#python-attribute-actions).
+ `aws:rep:deleting`
+ `aws:rep:updatetime`
+ `aws:rep:updateregion`

Se você estiver usando qualquer outra versão das tabelas globais, nenhuma ação será necessária.

## Baixo desempenho do fornecedor mais recente
<a name="mrp-ttl-delay"></a>

**Problema**: seu aplicativo responde menos, especialmente após a atualização para uma versão mais recente do DynamoDB Encryption Client.

**Sugestão**: ajuste o time-to-live valor e o tamanho do cache.

**Detalhes**

O provedor mais recente foi projetado para melhorar o desempenho dos aplicativos que usam o DynamoDB Encryption Client, permitindo a reutilização limitada de materiais criptográficos. Ao configurar o provedor mais recente para seu aplicativo, você precisa equilibrar o desempenho aprimorado com as preocupações de segurança decorrentes do armazenamento em cache e da reutilização. 

Nas versões mais recentes do DynamoDB Encryption Client, time-to-live o valor (TTL) determina por quanto tempo os provedores de material criptográfico em cache () podem ser usados. CMPs O TTL também determina com que frequência o provedor mais recente verifica em busca de uma nova versão do CMP. 

Se o TTL for muito longo, seu aplicativo poderá violar suas regras de negócios ou padrões de segurança. Se o TTL for muito breve, as chamadas frequentes para o armazenamento do provedor podem fazer com que o armazenamento do provedor reduza as solicitações do seu aplicativo e de outros aplicativos que compartilham sua conta de serviço. Para resolver esse problema, ajuste o TTL e o tamanho do cache para um valor que atenda às suas metas de latência e disponibilidade e esteja em conformidade com seus padrões de segurança. Para obter mais detalhes, consulte [Definindo um time-to-live valor](most-recent-provider.md#most-recent-provider-ttl).