Amazon S3 Migration du client de chiffrement - AWS SDK for Java 1. x
PrérequisPrésentation de la migrationMettre à jour les clients existants pour lire les nouveaux formatsMigrer les clients de chiffrement et de déchiffrement vers la version V2Exemples supplémentaires

La AWS SDK for Java version 1.x est entrée en mode maintenance le 31 juillet 2024 et atteindra end-of-supportle 31 décembre 2025. Nous vous recommandons de migrer vers le pour continuer AWS SDK for Java 2.xà bénéficier des nouvelles fonctionnalités, des améliorations de disponibilité et des mises à jour de sécurité.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Amazon S3 Migration du client de chiffrement

Cette rubrique explique comment migrer vos applications de la version 1 (V1) du client de chiffrement Amazon Simple Storage Service (Amazon S3) vers la version 2 (V2) et garantir la disponibilité des applications tout au long du processus de migration.

Prérequis

Amazon S3 le chiffrement côté client nécessite les éléments suivants :

  • Java 8 ou version ultérieure installé dans votre environnement d'application. Il AWS SDK for Java fonctionne avec le kit de développement Oracle Java SE et avec les distributions du kit de développement Open Java (OpenJDK) telles Amazon Correttoque Red Hat Open JDK et AdoptOpenJDK.

  • Le package Bouncy Castle Crypto. Vous pouvez placer le fichier .jar de Bouncy Castle sur le chemin de classe de votre environnement d'application ou ajouter une dépendance à votre fichier Maven artifactId bcprov-ext-jdk15on (avec le signe groupId oforg.bouncycastle). pom.xml

Présentation de la migration

Cette migration s'effectue en deux phases :

  1. Mettez à jour les clients existants pour lire les nouveaux formats. Mettez à jour votre application pour utiliser la version 1.11.837 ou ultérieure AWS SDK for Java et redéployez l'application. Cela permet aux Amazon S3 clients du service de chiffrement côté client de votre application de déchiffrer les objets créés par les clients du service V2. Si votre application en utilise plusieurs AWS SDKs, vous devez les mettre à jour SDK séparément.

  2. Migrez les clients de chiffrement et de déchiffrement vers la version V2. Une fois que tous vos clients de chiffrement V1 peuvent lire les formats de chiffrement V2, mettez à jour les Amazon S3 clients de chiffrement et de déchiffrement côté client dans le code de votre application pour utiliser leurs équivalents V2.

Mettre à jour les clients existants pour lire les nouveaux formats

Le client de chiffrement V2 utilise des algorithmes de chiffrement que les anciennes versions AWS SDK for Java ne prennent pas en charge.

La première étape de la migration consiste à mettre à jour vos clients de chiffrement V1 afin qu'ils utilisent la version 1.11.837 ou ultérieure du. AWS SDK for Java(Nous vous recommandons de passer à la dernière version, que vous trouverez dans la version de API référence Java 1.x.) Pour ce faire, mettez à jour la dépendance dans la configuration de votre projet. Une fois la configuration de votre projet mise à jour, reconstruisez votre projet et redéployez-le.

Une fois ces étapes terminées, les clients de chiffrement V1 de votre application pourront lire les objets écrits par les clients de chiffrement V2.

Mettre à jour la dépendance dans la configuration de votre projet

Modifiez le fichier de configuration de votre projet (par exemple, pom.xml ou build.gradle) pour utiliser la version 1.11.837 ou ultérieure du. AWS SDK for Java Reconstruisez ensuite votre projet et redéployez-le.

L'exécution de cette étape avant le déploiement du nouveau code d'application permet de garantir la cohérence des opérations de chiffrement et de déchiffrement au sein de votre flotte pendant le processus de migration.

Exemple d'utilisation de Maven

Extrait d'un fichier 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>

Exemple d'utilisation de Gradle

Extrait d'un fichier build.gradle :

dependencies {
  implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
  implementation 'com.amazonaws:aws-java-sdk-s3'
}

Migrer les clients de chiffrement et de déchiffrement vers la version V2

Une fois que votre projet a été mis à jour avec la dernière SDK version, vous pouvez modifier le code de votre application pour utiliser le client V2. Pour ce faire, commencez par mettre à jour votre code afin d'utiliser le nouveau générateur de clients de services. Fournissez ensuite du matériel de chiffrement à l'aide d'une méthode du générateur qui a été renommée, et configurez davantage votre client de service selon les besoins.

Ces extraits de code montrent comment utiliser le chiffrement côté client avec le et fournissent des comparaisons entre AWS SDK for Java les clients de chiffrement V1 et 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();

L'exemple ci-dessus définit la valeur cryptoMode àAuthenticatedEncryption. Il s'agit d'un paramètre qui permet à un client de chiffrement V2 de lire des objets écrits par un client de chiffrement V1. Si votre client n'a pas besoin de pouvoir lire des objets écrits par un client V1, nous vous recommandons d'utiliser StrictAuthenticatedEncryption plutôt le paramètre par défaut de.

Création d'un client de chiffrement V2

Le client de chiffrement V2 peut être créé en appelant AmazonS3 EncryptionClient V2. encryptionBuilder().

Vous pouvez remplacer tous vos clients de chiffrement V1 existants par des clients de chiffrement V2. Un client de chiffrement V2 sera toujours en mesure de lire tout objet écrit par un client de chiffrement V1 tant que vous l'autorisez à le faire en configurant le client de chiffrement V2 pour qu'il utilise le `AuthenticatedEncryption`cryptoMode.

La création d'un nouveau client de chiffrement V2 est très similaire à la création d'un client de chiffrement V1. Toutefois, il existe quelques différences :

  • Vous utiliserez un CryptoConfigurationV2 objet pour configurer le client au lieu d'un CryptoConfiguration objet. Ce paramètre est obligatoire.

  • Le cryptoMode paramètre par défaut pour le client de chiffrement V2 estStrictAuthenticatedEncryption. Pour le client de chiffrement V1, c'est le casEncryptionOnly.

  • La méthode withEncryptionMaterials() du générateur de clients de chiffrement a été renommée withEncryptionMaterialsProvider (). Il s'agit simplement d'un changement cosmétique qui reflète plus précisément le type d'argument. Vous devez utiliser la nouvelle méthode lorsque vous configurez votre client de service.

Note

Lorsque vous déchiffrez avec AES -GCM, lisez l'objet entier jusqu'à la fin avant de commencer à utiliser les données déchiffrées. Cela permet de vérifier que l'objet n'a pas été modifié depuis qu'il a été chiffré.

Utiliser des fournisseurs de matériel de chiffrement

Vous pouvez continuer à utiliser les mêmes fournisseurs de matériel de chiffrement et les mêmes objets de matériel de chiffrement que ceux que vous utilisez déjà avec le client de chiffrement V1. Ces classes sont chargées de fournir les clés que le client de chiffrement utilise pour sécuriser vos données. Ils peuvent être utilisés de manière interchangeable avec le client de chiffrement V2 et V1.

Configuration du client de chiffrement V2

Le client de chiffrement V2 est configuré avec un CryptoConfigurationV2 objet. Cet objet peut être construit en appelant son constructeur par défaut, puis en modifiant ses propriétés selon les besoins à partir des valeurs par défaut.

Les valeurs par défaut pour CryptoConfigurationV2 sont les suivantes :

  • cryptoMode = CryptoMode.StrictAuthenticatedEncryption

  • storageMode = CryptoStorageMode.ObjectMetadata

  • secureRandom= instance de SecureRandom

  • rangeGetMode = CryptoRangeGetMode.DISABLED

  • unsafeUndecryptableObjectPassthrough = false

Notez que cela n'EncryptionOnlyest pas pris en charge cryptoMode dans le client de chiffrement V2. Le client de chiffrement V2 chiffre toujours le contenu à l'aide d'un chiffrement authentifié et protège les clés de chiffrement du contenu (CEKs) à l'aide d'objets V2. KeyWrap

L'exemple suivant montre comment spécifier la configuration cryptographique dans la version 1 et comment instancier un objet CryptoConfigurationV2 à transmettre au générateur de clients de chiffrement V2.

V1 

CryptoConfiguration cryptoConfiguration = new CryptoConfiguration()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

V2 

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);

Exemples supplémentaires

Les exemples suivants montrent comment traiter des cas d'utilisation spécifiques liés à une migration de la V1 à la V2.

Configurer un client de service pour lire les objets créés par le client de chiffrement V1

Pour lire des objets précédemment écrits à l'aide d'un client de chiffrement V1, définissez la valeur cryptoMode surAuthenticatedEncryption. L'extrait de code suivant montre comment créer un objet de configuration avec ce paramètre.

CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.AuthenticatedEncryption);

Configuration d'un client de service pour obtenir des plages d'octets d'objets

Pour pouvoir accéder à get une plage d'octets à partir d'un objet S3 chiffré, activez le nouveau paramètre de configurationrangeGetMode. Ce paramètre est désactivé par défaut sur le client de chiffrement V2. Notez que même lorsqu'elle est activée, une plage get ne fonctionne que sur les objets chiffrés à l'aide d'algorithmes pris en charge par le cryptoMode paramètre du client. Pour plus d'informations, reportez-vous CryptoRangeGetModeà la section AWS SDK for Java API Référence.

Si vous prévoyez d'utiliser le Amazon S3 TransferManager pour effectuer des téléchargements partitionnés d' Amazon S3 objets chiffrés à l'aide du client de chiffrement V2, vous devez d'abord activer le rangeGetMode paramètre sur le client de chiffrement V2.

L'extrait de code suivant montre comment configurer le client V2 pour effectuer une opération à distance. get

// 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);