La AWS SDK para Java 1.x se alcanzó end-of-support el 31 de diciembre de 2025. Le recomendamos que migre a [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) para seguir recibiendo nuevas características, mejoras de disponibilidad y actualizaciones de seguridad.
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Amazon S3 Migración de clientes de cifrado
En este tema, se muestra cómo migrar las aplicaciones de la versión 1 (V1) del cliente de cifrado Amazon Simple Storage Service (Amazon S3) a la versión 2 (V2) y cómo garantizar la disponibilidad de las aplicaciones durante todo el proceso de migración.
## Requisitos previos
Amazon S3 El cifrado del lado del cliente requiere lo siguiente:
+ Java 8 o una versión posterior instalada en el entorno de la aplicación. AWS SDK para Java [Funciona con el [kit de desarrollo Java SE de Oracle](https://www.oracle.com/java/technologies/javase-downloads.html) y con distribuciones del Open Java Development Kit (OpenJDK) [Amazon Corretto](https://aws.amazon.com/corretto/), como [Red Hat OpenJDK](https://developers.redhat.com/products/openjdk) y JDK. AdoptOpen](https://adoptopenjdk.net/)
+ El [paquete criptográfico Bouncy Castle](https://www.bouncycastle.org/download/bouncy-castle-java/). Puede colocar el archivo .jar de Bouncy Castle en la ruta de clases del entorno de su aplicación o añadir una dependencia del ArtifactiD `bcprov-ext-jdk15on` (con el GroupID de `org.bouncycastle`) a su archivo Maven `pom.xml`.
## Información general sobre la migración
Esta migración se produce en dos fases:
1. **Actualizar los clientes existentes para leer nuevos formatos.** Actualice la aplicación para que utilice la versión 1.11.837 o posterior y vuelva a implementar la aplicación. AWS SDK para Java Esto permite a los clientes del servicio de cifrado Amazon S3 del lado del cliente de su aplicación descifrar los objetos creados por los clientes del servicio V2. Si su aplicación usa varios AWS SDKs, debe actualizar cada SDK por separado.
1. **Migue los clientes de cifrado y descifrado a la versión V2.** Una vez que todos sus clientes de cifrado V1 puedan leer los formatos de cifrado V2, actualice los Amazon S3 clientes de cifrado y descifrado del lado del cliente en el código de su aplicación para usar sus equivalentes V2.
## Actualizar los clientes existentes para leer nuevos formatos
El cliente de cifrado V2 utiliza algoritmos de cifrado que las versiones anteriores no admiten. AWS SDK para Java
El primer paso de la migración consiste en actualizar los clientes de cifrado de la versión 1 para que utilicen la versión 1.11.837 o posterior del AWS SDK para Java. (Le recomendamos que actualice a la versión más reciente, que encontrará en la versión 1.x de la [Referencia de la API de Java](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc)). Para ello, actualice la dependencia en la configuración de su proyecto. Una vez actualizada la configuración del proyecto, reconstruya el proyecto y vuelva a implementarlo.
Cuando haya completado estos pasos, los clientes de cifrado V1 de su aplicación podrán leer los objetos escritos por los clientes de cifrado V2.
### Actualizar la dependencia en la configuración de su proyecto.
Modificar el archivo de configuración del proyecto (por ejemplo, pom.xml o build.gradle) para usar la versión 1.11.837 o posterior de AWS SDK para Java. A continuación, reconstruya su proyecto y vuelva a implementarlo.
Completar este paso antes de implementar el nuevo código de aplicación ayuda a garantizar que las operaciones de cifrado y descifrado permanezcan consistentes en toda la flota durante el proceso de migración.
#### Ejemplo de uso de Maven
Fragmento de un archivo pom.xml:
```
com.amazonaws
aws-java-sdk-bom
1.11.837
pom
import
```
#### Ejemplo de uso de Gradle
Fragmento de un archivo build.gradle:
```
dependencies {
implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
implementation 'com.amazonaws:aws-java-sdk-s3'
}
```
## Migrar clientes de cifrado y descifrado a la versión V2
Una vez que tu proyecto se haya actualizado con la última versión del SDK, puede modificar el código de la aplicación para usar el cliente V2. Para ello, primero actualice el código para usar el nuevo generador de clientes de servicios. A continuación, proporcione los materiales de cifrado mediante un método del generador al que se le haya cambiado el nombre y configure el cliente de servicio según sea necesario.
Estos fragmentos de código muestran cómo utilizar el cifrado del lado del cliente con los AWS SDK para Java clientes de cifrado V1 y V2 y proporcionan comparaciones entre ellos.
**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();
```
En el ejemplo anterior se establece el `cryptoMode` como `AuthenticatedEncryption`. Esta es una configuración que permite a un cliente de cifrado V2 leer objetos escritos por un cliente de cifrado V1. Si su cliente no necesita leer objetos escritos por un cliente V1, le recomendamos que utilice la configuración predeterminada `StrictAuthenticatedEncryption`.
### Crear un cliente de cifrado V2
El cliente de cifrado V2 se puede crear llamando a *EncryptionClientAmazonS3* v2.encryptionBuilder ().
Puede sustituir todos sus clientes de cifrado V1 existentes por clientes de cifrado V2. Un cliente de cifrado V2 siempre podrá leer cualquier objeto que haya escrito un cliente de cifrado V1 siempre y cuando usted lo permita configurando el cliente de cifrado V2 para que utilice `. AuthenticatedEncryption ``cryptoMode`
La creación de un nuevo cliente de cifrado V2 es muy similar a la creación de un cliente de cifrado V1. Sin embargo, hay algunas diferencias:
+ Utilizará un objeto `CryptoConfigurationV2` para configurar el cliente en lugar de un objeto `CryptoConfiguration`. Este parámetro es obligatorio.
+ La configuración `cryptoMode` predeterminada para el cliente de cifrado V2 es `StrictAuthenticatedEncryption`. Para el cliente de cifrado V1 es`EncryptionOnly`.
+ Se ha cambiado el nombre del método *withEncryptionMaterials()* del generador del cliente de cifrado a *withEncryptionMaterialsProvider ()*. Se trata simplemente de un cambio estético que refleja con mayor precisión el tipo de argumento. Debe utilizar el nuevo método al configurar el cliente de servicio.
**nota**
Al descifrar con AES-GCM, lea todo el objeto hasta el final antes de empezar a utilizar los datos descifrados. Esto se hace para verificar que el objeto no se ha modificado desde que se cifró.
### Utilizar proveedores de materiales de cifrado
Puede seguir utilizando los mismos proveedores de materiales de cifrado y los mismos objetos de materiales de cifrado que ya utiliza con el cliente de cifrado V1. Estas clases son responsables de proporcionar las claves que el cliente de cifrado utiliza para proteger sus datos. Se pueden usar indistintamente con el cliente de cifrado V2 y V1.
### Configurar el cliente de cifrado V2
El cliente de cifrado V2 se configura con un objeto `CryptoConfigurationV2`. Este objeto se puede crear llamando a su constructor predeterminado y, a continuación, modificando sus propiedades según sea necesario a partir de los valores predeterminados.
Los valores predeterminados para `CryptoConfigurationV2` son:
+ `cryptoMode` = `CryptoMode.StrictAuthenticatedEncryption`
+ `storageMode` = `CryptoStorageMode.ObjectMetadata`
+ `secureRandom` = instancia de `SecureRandom`
+ `rangeGetMode` = `CryptoRangeGetMode.DISABLED`
+ `unsafeUndecryptableObjectPassthrough` = `false`
Tenga en cuenta que no *EncryptionOnly*es compatible con `cryptoMode` el cliente de cifrado V2. El cliente de cifrado V2 siempre cifra el contenido mediante un cifrado autenticado y protege las claves de cifrado del contenido (CEKs) mediante objetos V2. `KeyWrap`
En el siguiente ejemplo, se muestra cómo especificar la configuración criptográfica en la versión 1 y cómo crear una instancia de un objeto de la *CryptoConfigurationversión* 2 para pasarlo al generador de clientes de cifrado de la versión 2.
**V1**
```
CryptoConfiguration cryptoConfiguration = new CryptoConfiguration()
.withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);
```
**V2**
```
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
.withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);
```
## Ejemplos adicionales
Los ejemplos siguientes muestran cómo abordar casos prácticos específicos relacionados con la migración de la V1 a la V2.
### Configurar un cliente de servicio para leer los objetos creados por el cliente de cifrado V1
Para leer objetos que se escribieron anteriormente con un cliente de cifrado V1, defina `cryptoMode` como `AuthenticatedEncryption`. El siguiente fragmento de código muestra cómo crear un objeto de configuración con esta configuración.
```
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
.withCryptoMode(CryptoMode.AuthenticatedEncryption);
```
### Configurar un cliente de servicio para obtener rangos de bytes de objetos
Para poder `get` un rango de bytes de un objeto S3 cifrado, habilite el nuevo ajuste de configuración `rangeGetMode`. Esta configuración está deshabilitada en el cliente de cifrado V2 de forma predeterminada. Tenga en cuenta que, aunque esté activado, un `get` con rango solo funciona en objetos que se hayan cifrado mediante algoritmos compatibles con la configuración `cryptoMode` del cliente. Para obtener más información, consulta la referencia [CryptoRangeGetMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoRangeGetMode.html)de la AWS SDK para Java API.
Si planea utilizar el Amazon S3 TransferManager para realizar descargas multiparte de Amazon S3 objetos cifrados mediante el cliente de cifrado V2, primero debe habilitar la `rangeGetMode` configuración en el cliente de cifrado V2.
El siguiente fragmento de código muestra cómo configurar el cliente V2 para efectuar un `get` con rango.
```
// 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);
```