Código de exemplo para o DynamoDB Encryption Client para Java - AWS SDK de criptografia de banco de dados
Uso do DynamoDBEncryptorUsar o DynamoDBMapper

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 Java

nota

Nossa biblioteca de criptografia do lado do cliente foi renomeada como SDK de criptografia de banco de dados da AWS. 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—3x 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.

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 exemplos do repositório aws-dynamodb-encryption-java no GitHub.

Uso do DynamoDBEncryptor

Este exemplo mostra como usar o DynamoDBEncryptor de nível inferior com o Provedor direto do KMS. O Direct KMS Provider gera e protege seus materiais criptográficos sob um AWS KMS key no AWS Key Management Service (AWS KMS) especificado por você.

Você pode usar qualquer provedor de materiais de criptografia (CMP - cryptographic materials provider) compatível com o DynamoDBEncryptor e usar o provedor direto do KMS com o DynamoDBMapper e o AttributeEncryptor.

Consulte o exemplo de código completo: AwsKmsEncryptedItem.java

Etapa 1: crie um provedor direto do KMS

Crie uma instância do cliente do AWS KMS com a região especificada. Em seguida, use a instância do cliente para criar uma instância de provedor direto do KMS com o AWS KMS key de sua preferência.

Este exemplo usa o nome do recurso da Amazon (ARN) para identificar o AWS KMS key, mas você pode usar qualquer identificador válido da chave. 

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 HashMap record que representa um item de tabela de exemplo.

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: crie um DynamoDBEncryptor

Crie uma instância do DynamoDBEncryptor com o provedor direto do KMS.

final DynamoDBEncryptor encryptor = DynamoDBEncryptor.getInstance(cmp);
Etapa 4: crie um contexto de criptografia do DynamoDB

O Contexto de criptografia do DynamoDB 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 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 atributo, crie um HashMap de nome de atributo e pares de valor EncryptionFlags.

Por exemplo, o código Java a seguir cria um HashMap actions que criptografa e assina todos os atributos no item record, exceto 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: // 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);

Usar o DynamoDBMapper

O exemplo a seguir mostra como usar a classe auxiliar do mapeador do DynamoDB com o Direct KMS Provider. O Direct KMS Provider gera e protege seus materiais criptográficos sob um AWS KMS key no AWS Key Management Service (AWS KMS) especificado por você.

Você pode usar qualquer provedor de materiais de criptografia (CMP) compatível com o DynamoDBMapper, e usar o provedor direto do KMS com o DynamoDBEncryptor de baixo nível.

Consulte o exemplo de código completo: AwsKmsEncryptedObject.java

Etapa 1: crie um provedor direto do KMS

Crie uma instância do cliente do AWS KMS com a região especificada. Em seguida, use a instância do cliente para criar uma instância de provedor direto do KMS com o AWS KMS key de sua preferência.

Este exemplo usa o nome do recurso da Amazon (ARN) para identificar o AWS KMS key, mas você pode usar qualquer identificador válido da chave. 

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 DynamoDBMapper

Use o Provedor direto do KMS que você criou na etapa anterior para criar uma instância do DynamoDB 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.

Importante

Ao usar o DynamoDBMapper para adicionar ou editar itens assinados (ou criptografados e assinados), configure-o para usar um comportamento de salvamento, 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. 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);