AWS SDK para Java 1.x ha entrado en modo de mantenimiento el 31 de julio de 2024 y llegará al final de soporte
Migración de clientes de cifrado de Amazon S3
En este tema se muestra cómo migrar las aplicaciones de la Versión 1 (V1) del cliente 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
El cifrado del cliente Amazon S3 requiere lo siguiente:
-
Java 8 o una versión posterior instalada en el entorno de la aplicación. El AWS SDK para Java funciona con el Kit de desarrollo Java SE de Oracle
y con distribuciones del Open Java Development Kit (OpenJDK) como Amazon Corretto , Red Hat OpenJDK y AdoptOpenJDK. -
El paquete criptográfico Bouncy Castle
. 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 deorg.bouncycastle) a su archivo Mavenpom.xml.
Información general sobre la migración
Esta migración se produce en dos fases:
-
Actualizar los clientes existentes para leer nuevos formatos. Actualice la aplicación para que utilice la versión 1.11.837 o posterior del AWS SDK para Java y vuelva a implementar la aplicación. Esto permite a los clientes del servicio de cifrado de cliente de Amazon S3 descifrar los objetos creados por los clientes del servicio V2. Si su aplicación usa varios SDK de AWS, debe actualizar cada SDK por separado.
-
Migrar 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 clientes de cifrado y descifrado del cliente Amazon S3 en el código de la aplicación para usar sus equivalentes en V2.
Actualizar los clientes existentes para leer nuevos formatos
El cliente de cifrado de la versión 2 utiliza algoritmos de cifrado que las versiones anteriores del AWS SDK para Java no admiten.
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). 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:
<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>
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 cliente con el AWS SDK para Java, y proporcionan comparaciones entre ellos entre los clientes de cifrado V1 y 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();
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 AmazonS3EncryptionClientV2.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 autorice configurando el cliente de cifrado V2 para que utilice el `cryptoMode `AuthenticatedEncryption.
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
CryptoConfigurationV2para configurar el cliente en lugar de un objetoCryptoConfiguration. Este parámetro es obligatorio. -
La configuración
cryptoModepredeterminada para el cliente de cifrado V2 esStrictAuthenticatedEncryption. Para el cliente de cifrado V1 esEncryptionOnly. -
Se ha cambiado el nombre del método withEncryptionMaterials () del creador 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 deSecureRandom -
rangeGetMode=CryptoRangeGetMode.DISABLED -
unsafeUndecryptableObjectPassthrough=false
Tenga en cuenta que EncryptionOnly no es un cryptoMode compatible con el cliente de cifrado V2. El cliente de cifrado V2 siempre cifra el contenido mediante un cifrado autenticado y protege las claves de cifrado de contenido (CEK) mediante objetos KeyWrap V2.
El siguiente ejemplo muestra cómo especificar la configuración criptográfica en la V1 y cómo crear una instancia de un objeto CryptoConfigurationV2 para pasarlo al generador de clientes de cifrado V2.
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, consulte CryptoRangeGetMode en la Referencia de la API de AWS SDK para Java
Si planea usar el TransferManager Amazon S3 para hacer descargas multiparte de objetos cifrados Amazon S3 mediante el cliente de cifrado V2, primero debe habilitar la configuración rangeGetMode 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);
