O AWS SDK para Java 1.x entrou no modo de manutenção em 31 de julho de 2024 e o fim do suporte está previsto para 31 de dezembro de 2025. Recomendamos que você migre para o AWS SDK for Java 2.x para continuar recebendo novos recursos, melhorias de disponibilidade e atualizações de segurança.

Migração de cliente de criptografia Amazon S3

Este tópico mostra como migrar suas aplicações da Versão 1 (V1) do cliente de criptografia do Amazon Simple Storage Service (Amazon S3) para a Versão 2 (V2) e garantir a disponibilidade da aplicação durante todo o processo de migração.

Pré-requisitos

A criptografia do lado do cliente do Amazon S3 exige o seguinte:

Visão geral da migração

Essa migração acontece em duas fases:

Atualizar os clientes existentes para ler novos formatos

O cliente de criptografia V2 usa algoritmos de criptografia incompatíveis com as versões mais antigas do AWS SDK para Java.

A primeira etapa da migração é atualizar seus clientes de criptografia V1 para usar a versão 1.11.837 ou posterior do. AWS SDK para Java (Recomendamos que você atualize para a versão mais recente, que pode ser encontrada na Referência de API do Java versão 1.x.) Para fazer isso, atualize a dependência na configuração do seu projeto. Depois que a configuração do projeto for atualizada, recrie seu projeto e reimplante-o.

Depois de concluir essas etapas, os clientes de criptografia V1 do seu aplicativo poderão ler objetos escritos por clientes de criptografia V2.

Atualizar a dependência na configuração do seu projeto

Modifique o arquivo de configuração do projeto (por exemplo, pom.xml ou build.gradle) para usar a versão 1.11.837 ou posterior do AWS SDK para Java. Em seguida, recrie seu projeto e reimplante-o.

Concluir essa etapa antes de implantar o novo código do aplicativo ajuda a garantir que as operações de criptografia e descriptografia permaneçam consistentes em toda a sua frota durante o processo de migração.

Exemplos usando o Maven

Trecho de um arquivo pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>
      <version>1.11.837</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Exemplo usando o Gradle

Trecho de um arquivo build.gradle:

dependencies {
  implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
  implementation 'com.amazonaws:aws-java-sdk-s3'
}

Migrar clientes de criptografia e descriptografia para a V2

Depois que seu projeto for atualizado com a versão mais recente do SDK, você poderá modificar o código do aplicativo para usar o cliente V2. Para fazer isso, primeiro atualize seu código para usar o novo criador de clientes de serviço. Em seguida, forneça materiais de criptografia usando um método no construtor que tenha sido renomeado e configure ainda mais seu cliente de serviço conforme necessário.

Esses trechos de código demonstram como usar a criptografia do lado do cliente com o AWS SDK para Java e fornecem comparações entre os clientes de criptografia V1 e V2.

V1

// minimal configuration in V1; default CryptoMode.EncryptionOnly.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder()
             .withEncryptionMaterials(encryptionMaterialsProvider)
             .build();

V2

// minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder()
             .withEncryptionMaterialsProvider(encryptionMaterialsProvider)
             .withCryptoConfiguration(new CryptoConfigurationV2()
                           // The following setting allows the client to read V1 encrypted objects
                           .withCryptoMode(CryptoMode.AuthenticatedEncryption)
             )
             .build();

O exemplo acima define o cryptoMode como AuthenticatedEncryption. Essa é uma configuração que permite que um cliente de criptografia V2 leia objetos que foram escritos por um cliente de criptografia V1. Se seu cliente não precisar da capacidade de ler objetos escritos por um cliente V1, recomendamos usar a configuração padrão StrictAuthenticatedEncryption em vez disso.

Construir um cliente de criptografia V2

O cliente de criptografia V2 pode ser construído chamando AmazonS3EncryptionClientV2.encryptionBuilder().

Você pode substituir todos os seus clientes de criptografia V1 existentes por clientes de criptografia V2. Um cliente de criptografia V2 sempre poderá ler qualquer objeto que tenha sido escrito por um cliente de criptografia V1, desde que você permita isso configurando o cliente de criptografia V2 para usar o `AuthenticatedEncryption`cryptoMode.

A criação de um novo cliente de criptografia V2 é muito semelhante à criação de um cliente de criptografia V1. No entanto, há algumas diferenças:

Usar fornecedores de materiais de criptografia

Você pode continuar usando os mesmos provedores de materiais de criptografia e objetos de materiais de criptografia que você já está usando com o cliente de criptografia V1. Essas classes são responsáveis por fornecer as chaves que o cliente de criptografia usa para proteger seus dados. Elas podem ser usadas alternadamente com o cliente de criptografia V2 e V1.

Configurar o cliente de criptografia V2

O cliente de criptografia V2 é configurado com um objeto CryptoConfigurationV2. Esse objeto pode ser construído chamando seu construtor padrão e, em seguida, modificando suas propriedades conforme exigido dos padrões.

Os valores padrão para CryptoConfigurationV2 são:

Observe que o EncryptionOnly não é um cryptoMode compatível com o cliente de criptografia V2. O cliente de criptografia V2 sempre criptografará o conteúdo usando criptografia autenticada e protegerá as chaves de criptografia de conteúdo (CEKs) usando objetos KeyWrap V2.

O exemplo a seguir demonstra como especificar a configuração de criptografia na V1 e como instanciar um objeto CryptoConfigurationV2 para passar para o criador do cliente de criptografia V2.

V1

CryptoConfiguration cryptoConfiguration = new CryptoConfiguration()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

V2

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

Exemplos adicionais

Os exemplos a seguir demonstram como abordar casos de uso específicos relacionados à migração da V1 para a V2.

Configurar um cliente de serviço para ler objetos criados pelo cliente de criptografia V1

Para ler objetos que foram gravados anteriormente usando um cliente de criptografia V1, defina cryptoMode como AuthenticatedEncryption. O trecho de código a seguir demonstra como criar um objeto de configuração com essa configuração.

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.AuthenticatedEncryption);

Configurar um cliente de serviço para obter intervalos de bytes de objetos

Para poder get uma faixa de bytes de um objeto S3 criptografado, habilite a nova configuração definindo rangeGetMode. Por padrão, essa configuração está desativada no cliente de criptografia V2. Observe que, mesmo quando ativado, um get de intervalo só funciona em objetos que foram criptografados usando algoritmos suportados pela configuração cryptoMode do cliente. Para obter mais informações, consulte CryptoRangeGetMode na Referência de API do AWS SDK para Java.

Se você planeja usar o TransferManager do Amazon S3 para realizar downloads de várias partes de objetos do Amazon S3 criptografados usando o cliente de criptografia V2, primeiro ative a configuração rangeGetMode no cliente de criptografia V2.

O trecho de código a seguir demonstra como configurar o cliente V2 para realizar um get de intervalo.

// Allows range gets using AES/CTR, for V2 encrypted objects only
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withRangeGetMode(CryptoRangeGetMode.ALL);

// Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withCryptoMode(CryptoMode.AuthenticatedEncryption)
       .withRangeGetMode(CryptoRangeGetMode.ALL);