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á.
# Linguagens de programação disponíveis do Amazon DynamoDB Encryption Client
**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
**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
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
É 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.
```
com.amazonaws
aws-dynamodb-encryption-java
version-number
```
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
**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
[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
É 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
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
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
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 signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> 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 encrypted_record = encryptor.encryptRecord(record, actions, encryptionContext);
```
## Substituir nomes de tabelas
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
**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
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 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 signOnly = EnumSet.of(EncryptionFlags.SIGN);
final EnumSet encryptAndSign = EnumSet.of(EncryptionFlags.ENCRYPT, EncryptionFlags.SIGN);
final Map> 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 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
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
**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
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
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
**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
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 [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
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
**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
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
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)