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á. # Uso do biblioteca Java de criptografia do lado do cliente para o DynamoDB **** | | | --- | | 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 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 [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 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 tableSchema = TableSchema.fromBean(SimpleClass.class); ``` ### Definir as ações de atributos manualmente 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 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 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 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 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 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.