View a markdown version of this page

Amazon S3 Migration du client de chiffrement - AWS SDK pour Java 1.x
Conditions préalablesAperçu 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 version AWS SDK pour Java 1.x a atteint la fin du support le 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.

Conditions préalables

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 pour Java fonctionne avec le kit de développement Oracle Java SE et avec les distributions de l'Open Java Development Kit (OpenJDK) telles que Amazon Corretto Red Hat OpenJDK et JDK. AdoptOpen

  • Le package https://www.bouncycastle.org/download/bouncy-castle-java/ Bouncy Castle Crypto. Vous pouvez placer le fichier .jar Bouncy Castle sur le chemin de classe de votre environnement d'application ou ajouter une dépendance à l'artifactID bcprov-ext-jdk15on (avec le groupId de) à votre fichier Maven. org.bouncycastle pom.xml

Aperçu de la migration

Cette migration s'effectue en deux phases :

  1. Mettez à jour les clients existants pour qu'ils puissent lire les nouveaux formats. Mettez à jour votre application pour utiliser la version 1.11.837 ou ultérieure de l'application AWS SDK pour Java et redéployez-la. 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 utilise plusieurs AWS kits de développement logiciel, vous devez les mettre à jour séparément.

  2. Migrez les clients de chiffrement et de déchiffrement vers la 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 pour Java ne prennent pas en charge.

La première étape de la migration consiste à mettre à jour vos clients de chiffrement V1 pour qu'ils utilisent la version 1.11.837 ou ultérieure du. AWS SDK pour Java(Nous vous recommandons de passer à la dernière version, que vous trouverez dans la version 1.x de Java API Reference.) 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.

Mettez à 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 pour Java Ensuite, reconstruisez votre projet et redéployez-le.

Le fait de terminer cette étape avant de déployer le nouveau code d'application permet de garantir la cohérence des opérations de chiffrement et de déchiffrement sur l'ensemble de votre parc pendant le processus de migration.

Exemple utilisant 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 utilisant 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 version du SDK, vous pouvez modifier le code de votre application pour utiliser le client V2. Pour ce faire, mettez d'abord à jour votre code pour utiliser le nouveau générateur de clients de service. Fournissez ensuite le 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 si nécessaire.

Ces extraits de code montrent comment utiliser le chiffrement côté client avec les clients de chiffrement V1 et V2 et fournissent des comparaisons entre les clients de chiffrement V1 et V2. AWS SDK pour Java

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 qui ont été écrits par un client de chiffrement V1. Si votre client n'a pas besoin de pouvoir lire les objets écrits par un client V1, nous vous recommandons d'utiliser StrictAuthenticatedEncryption plutôt le paramètre par défaut.

Création d'un client de chiffrement V2

Le client de chiffrement V2 peut être créé en appelant AmazonS3EncryptionClientV2.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 n'importe quel 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 cryptage V1. Toutefois, il existe quelques différences :

  • Vous allez utiliser 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 with EncryptionMaterials () sur le générateur du client de chiffrement a été renommée with EncryptionMaterialsProvider (). 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

Lors du déchiffrement 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 vous utilisez déjà avec le client de chiffrement V1. Ces classes sont chargées de fournir les clés utilisées par le client de chiffrement 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 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 de contenu (CEK) à l'aide d'objets V2. KeyWrap

L'exemple suivant montre comment spécifier la configuration de chiffrement dans la V1 et comment instancier un objet CryptoConfiguration V2 à transmettre au générateur du client 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 vers 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 le paramètre 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);

Configurer 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 qui ont été chiffrés à l'aide d'algorithmes pris en charge par les cryptoMode paramètres du client. Pour plus d'informations, consultez CryptoRangeGetMode la référence de AWS SDK pour Java l'API.

Si vous envisagez d'utiliser le Amazon S3 TransferManager pour effectuer des téléchargements partiels 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 analyse à 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);