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