O AWS SDK for Java 1.x entrou no modo de manutenção em 31 de julho de 2024 e chegará end-of-supportem 31 de dezembro de 2025. Recomendamos que você migre para o AWS SDK for Java 2.xpara continuar recebendo novos recursos, melhorias de disponibilidade e atualizações de segurança.

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

Amazon S3 Migração do cliente de criptografia

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

Pré-requisitos

Amazon S3 a criptografia do lado do cliente 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 que as versões mais antigas AWS SDK for Java do não suportam.

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 for Java(Recomendamos que você atualize para a versão mais recente, que pode ser encontrada na versão 1.x do Java API Reference.) 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 for 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 SDK versão mais recente, 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 e fornecem comparações entre os AWS SDK for Java 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 o EncryptionClientAmazonS3 V2. 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 que ele faça 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 não EncryptionOnlyé compatível cryptoMode 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 V2. KeyWrap

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

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 CryptoRangeGetModena AWS SDK for Java API Referência.

Se você planeja usar o Amazon S3 TransferManager para realizar downloads em várias partes de Amazon S3 objetos criptografados usando o cliente de criptografia V2, primeiro ative a rangeGetMode configuração 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);