La AWS SDK for Java versión 1.x entró en modo de mantenimiento el 31 de julio de 2024 y estará disponible el 31 de end-of-support
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 for Java Funciona con el kit de desarrollo Java SE de Oracle
y con distribuciones del kit de desarrollo Open Java (OpenJDK) Amazon Corretto , como Red Hat Open JDK y. AdoptOpenJDK -
El paquete criptográfico Bouncy Castle
. Puede colocar el archivo.jar de Bouncy Castle en la ruta de clases de su entorno de aplicaciones o añadir una dependencia en el archivo Maven artifactId bcprov-ext-jdk15on(con el signo groupId deorg.bouncycastle).pom.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 y vuelva a implementar la aplicación. AWS SDK for 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 utiliza varios AWS SDKs, debe actualizar cada uno por separado. SDK
-
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 la aplicación para utilizar 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 for 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 for Java. (Le recomendamos que actualice a la versión más reciente, que encontrará en la versión 1.x de API referencia 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 for 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 el proyecto se haya actualizado con la última SDK versión, 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 for 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 AmazonS3 V2. EncryptionClient 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 que se 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
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 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 deSecureRandom -
rangeGetMode=CryptoRangeGetMode.DISABLED -
unsafeUndecryptableObjectPassthrough=false
Tenga en cuenta que no EncryptionOnlyes compatible con el cryptoMode 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, consulte CryptoRangeGetModela AWS SDK for Java API Referencia.
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);
