O AWS SDK para Java 1.x chegou end-of-support em 31 de dezembro de 2025. Recomendamos que você migre para o [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) para 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:
+ Java 8 ou posterior instalado em seu ambiente de aplicativos. AWS SDK para Java [Funciona com o [Oracle Java SE Development Kit](https://www.oracle.com/java/technologies/javase-downloads.html) e com distribuições do Open Java Development Kit (OpenJDK) [Amazon Corretto](https://aws.amazon.com/corretto/), como [Red](https://developers.redhat.com/products/openjdk) Hat OpenJDK e JDK. AdoptOpen](https://adoptopenjdk.net/)
+ O [pacote Bouncy Castle Crypto](https://www.bouncycastle.org/download/bouncy-castle-java/). Você pode colocar o arquivo.jar do Bouncy Castle no classpath do ambiente do seu aplicativo ou adicionar uma dependência do `bcprov-ext-jdk15on` do artifactId (com o groupId de `org.bouncycastle`) ao seu arquivo`pom.xml` do Maven.
## Visão geral da migração
Essa migração acontece em duas fases:
1. **Atualizar os clientes existentes para ler novos formatos.** Atualize seu aplicativo para usar a versão 1.11.837 ou posterior do AWS SDK para Java e reimplante o aplicativo. Isso permite que os Amazon S3 clientes do serviço de criptografia do lado do cliente em seu aplicativo descriptografem objetos criados pelos clientes do serviço V2. Se seu aplicativo usa vários AWS SDKs, você deve atualizar cada SDK separadamente.
1. **Migrar clientes de criptografia e descriptografia para a V2.** Depois que todos os seus clientes de criptografia V1 puderem ler os formatos de criptografia V2, atualize os Amazon S3 clientes de criptografia e descriptografia do lado do cliente no código do aplicativo para usar seus equivalentes V2.
## 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 para 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 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](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc).) 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:
```
com.amazonaws
aws-java-sdk-bom
1.11.837
pom
import
```
#### 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 e fornecem comparações entre os AWS SDK para 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 *AmazonS3 EncryptionClient* 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:
+ Você usará um objeto `CryptoConfigurationV2` para configurar o cliente em vez de um objeto `CryptoConfiguration`. Esse parâmetro é obrigatório.
+ A configuração padrão `cryptoMode` para o cliente de criptografia V2 é `StrictAuthenticatedEncryption`. Para o cliente de criptografia V1, é `EncryptionOnly`.
+ O método *withEncryptionMaterials()* no construtor do cliente de criptografia foi renomeado para *withEncryptionMaterialsProvider ()*. Essa é apenas uma mudança cosmética que reflete com mais precisão o tipo de argumento. Você deve usar o novo método ao configurar seu cliente de serviço.
**nota**
Ao descriptografar com o AES-GCM, leia o objeto inteiro até o fim antes de começar a usar os dados descriptografados. Isso é para verificar se o objeto não foi modificado desde que foi criptografado.
### 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:
+ `cryptoMode` = `CryptoMode.StrictAuthenticatedEncryption`
+ `storageMode` = `CryptoStorageMode.ObjectMetadata`
+ `secureRandom` = instância de `SecureRandom`
+ `rangeGetMode` = `CryptoRangeGetMode.DISABLED`
+ `unsafeUndecryptableObjectPassthrough` = `false`
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 [CryptoRangeGetMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoRangeGetMode.html)a Referência AWS SDK para Java da API.
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);
```