Amazon S3 Migration des Verschlüsselungsclients - AWS SDK for Java 1.x
VoraussetzungenÜberblick über die MigrationAktualisieren Sie bestehende Clients, sodass sie neue Formate lesen könnenMigrieren Sie Verschlüsselungs- und Entschlüsselungsclients auf V2Weitere Beispiele

Version AWS SDK for Java 1.x wurde am 31. Juli 2024 in den Wartungsmodus versetzt und wird end-of-supportam 31. Dezember 2025 verfügbar sein. Wir empfehlen Ihnen, auf den zu migrieren AWS SDK for Java 2.x, um weiterhin neue Funktionen, Verfügbarkeitsverbesserungen und Sicherheitsupdates zu erhalten.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Amazon S3 Migration des Verschlüsselungsclients

In diesem Thema erfahren Sie, wie Sie Ihre Anwendungen von Version 1 (V1) des Verschlüsselungsclients Amazon Simple Storage Service (Amazon S3) auf Version 2 (V2) migrieren und die Anwendungsverfügbarkeit während des gesamten Migrationsprozesses sicherstellen.

Voraussetzungen

Amazon S3 Für die clientseitige Verschlüsselung ist Folgendes erforderlich:

  • Java 8 oder höher ist in Ihrer Anwendungsumgebung installiert. Das AWS SDK for Java funktioniert mit dem Oracle Java SE Development Kit und mit Distributionen von Open Java Development Kit (OpenJDK) wie Amazon CorrettoRed Hat Open JDK und AdoptOpenJDK.

  • Das Bouncy Castle Crypto-Paket. Sie können die Bouncy Castle-.jar-Datei im Klassenpfad Ihrer Anwendungsumgebung platzieren oder Ihrer Maven-Datei eine Abhängigkeit von artifactId bcprov-ext-jdk15on (mit dem groupId oforg.bouncycastle) hinzufügen. pom.xml

Überblick über die Migration

Diese Migration erfolgt in zwei Phasen:

  1. Aktualisieren Sie bestehende Clients, damit sie neue Formate lesen können. Aktualisieren Sie Ihre Anwendung so, dass sie Version 1.11.837 oder höher verwendet, AWS SDK for Java und stellen Sie die Anwendung erneut bereit. Dadurch können die Amazon S3 clientseitigen Verschlüsselungsdienstclients in Ihrer Anwendung Objekte entschlüsseln, die von V2-Dienstclients erstellt wurden. Wenn Ihre Anwendung mehrere verwendet AWS SDKs, müssen Sie jede Anwendung separat aktualisieren. SDK

  2. Migrieren Sie die Verschlüsselungs- und Entschlüsselungsclients auf V2. Sobald alle Ihre V1-Verschlüsselungsclients die V2-Verschlüsselungsformate lesen können, aktualisieren Sie die Amazon S3 clientseitigen Verschlüsselungs- und Entschlüsselungsclients in Ihrem Anwendungscode, sodass sie ihre V2-Entsprechungen verwenden.

Aktualisieren Sie bestehende Clients, sodass sie neue Formate lesen können

Der V2-Verschlüsselungsclient verwendet Verschlüsselungsalgorithmen, die ältere Versionen von AWS SDK for Java nicht unterstützen.

Der erste Schritt der Migration besteht darin, Ihre V1-Verschlüsselungsclients so zu aktualisieren, dass sie Version 1.11.837 oder höher von verwenden. AWS SDK for Java(Wir empfehlen Ihnen, auf die neueste Release-Version zu aktualisieren, die Sie in der APIJava-Referenzversion 1.x finden.) Aktualisieren Sie dazu die Abhängigkeit in Ihrer Projektkonfiguration. Nachdem Ihre Projektkonfiguration aktualisiert wurde, erstellen Sie Ihr Projekt neu und stellen Sie es erneut bereit.

Sobald Sie diese Schritte abgeschlossen haben, können die V1-Verschlüsselungsclients Ihrer Anwendung Objekte lesen, die von V2-Verschlüsselungsclients geschrieben wurden.

Aktualisieren Sie die Abhängigkeit in Ihrer Projektkonfiguration

Ändern Sie Ihre Projektkonfigurationsdatei (z. B. pom.xml oder build.gradle), um Version 1.11.837 oder höher von zu verwenden. AWS SDK for Java Erstellen Sie dann Ihr Projekt neu und stellen Sie es erneut bereit.

Wenn Sie diesen Schritt vor der Bereitstellung des neuen Anwendungscodes abschließen, können Sie sicherstellen, dass die Verschlüsselungs- und Entschlüsselungsvorgänge während des Migrationsprozesses in Ihrer gesamten Flotte konsistent bleiben.

Beispiel für die Verwendung von Maven

Ausschnitt aus einer Datei 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>

Beispiel mit Gradle

Ausschnitt aus einer build.gradle-Datei:

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

Migrieren Sie Verschlüsselungs- und Entschlüsselungsclients auf V2

Sobald Ihr Projekt mit der neuesten SDK Version aktualisiert wurde, können Sie Ihren Anwendungscode ändern, um den V2-Client zu verwenden. Aktualisieren Sie dazu zunächst Ihren Code, um den neuen Service Client Builder zu verwenden. Stellen Sie dann Verschlüsselungsmaterial mithilfe einer Methode auf dem Builder bereit, die umbenannt wurde, und konfigurieren Sie Ihren Service Client nach Bedarf weiter.

Diese Codefragmente demonstrieren, wie die clientseitige Verschlüsselung mit dem verwendet wird AWS SDK for Java, und bieten Vergleiche zwischen den V1- und V2-Verschlüsselungsclients.

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

Das obige Beispiel setzt den Wert cryptoMode aufAuthenticatedEncryption. Dies ist eine Einstellung, die es einem V2-Verschlüsselungsclient ermöglicht, Objekte zu lesen, die von einem V1-Verschlüsselungsclient geschrieben wurden. Wenn Ihr Client nicht die Fähigkeit benötigt, Objekte zu lesen, die von einem V1-Client geschrieben wurden, empfehlen wir, StrictAuthenticatedEncryption stattdessen die Standardeinstellung von zu verwenden.

Konstruieren Sie einen V2-Verschlüsselungsclient

Der V2-Verschlüsselungsclient kann durch Aufrufen von EncryptionClientAmazonS3 V2 erstellt werden. encryptionBuilder().

Sie können alle Ihre vorhandenen V1-Verschlüsselungsclients durch V2-Verschlüsselungsclients ersetzen. Ein V2-Verschlüsselungsclient kann immer jedes Objekt lesen, das von einem V1-Verschlüsselungsclient geschrieben wurde, solange Sie dies zulassen, indem Sie den V2-Verschlüsselungsclient für die Verwendung von `konfigurieren AuthenticatedEncryption`cryptoMode.

Das Erstellen eines neuen V2-Verschlüsselungsclients ist dem Erstellen eines V1-Verschlüsselungsclients sehr ähnlich. Es gibt jedoch einige Unterschiede:

  • Sie werden ein CryptoConfigurationV2 Objekt anstelle eines CryptoConfiguration Objekts verwenden, um den Client zu konfigurieren. Dieser Parameter muss angegeben werden.

  • Die cryptoMode Standardeinstellung für den V2-Verschlüsselungsclient istStrictAuthenticatedEncryption. Für den V1-Verschlüsselungsclient ist dies der FallEncryptionOnly.

  • Die Methode withEncryptionMaterials() im Encryption Client Builder wurde in withEncryptionMaterialsProvider () umbenannt. Dies ist lediglich eine kosmetische Änderung, die den Argumenttyp genauer wiedergibt. Sie müssen die neue Methode verwenden, wenn Sie Ihren Service-Client konfigurieren.

Anmerkung

Lesen Sie beim Entschlüsseln mit AES - GCM das gesamte Objekt bis zum Ende, bevor Sie die entschlüsselten Daten verwenden. Dadurch wird überprüft, ob das Objekt seit der Verschlüsselung nicht geändert wurde.

Verwenden Sie Anbieter von Verschlüsselungsmaterialien

Sie können weiterhin dieselben Anbieter für Verschlüsselungsmaterialien und Objekte für Verschlüsselungsmaterialien verwenden, die Sie bereits mit dem V1-Verschlüsselungsclient verwenden. Diese Klassen sind für die Bereitstellung der Schlüssel verantwortlich, die der Verschlüsselungsclient zum Schutz Ihrer Daten verwendet. Sie können sowohl mit dem V2- als auch mit dem V1-Verschlüsselungsclient synonym verwendet werden.

Konfigurieren Sie den V2 Encryption Client

Der V2-Verschlüsselungsclient ist mit einem CryptoConfigurationV2 Objekt konfiguriert. Dieses Objekt kann erstellt werden, indem sein Standardkonstruktor aufgerufen und dann seine Eigenschaften entsprechend den Standardeinstellungen geändert werden.

Die Standardwerte für CryptoConfigurationV2 sind:

  • cryptoMode = CryptoMode.StrictAuthenticatedEncryption

  • storageMode = CryptoStorageMode.ObjectMetadata

  • secureRandom= Instanz von SecureRandom

  • rangeGetMode = CryptoRangeGetMode.DISABLED

  • unsafeUndecryptableObjectPassthrough = false

Beachten Sie, EncryptionOnlydass dies cryptoMode im V2-Verschlüsselungsclient nicht unterstützt wird. Der V2-Verschlüsselungsclient verschlüsselt Inhalte immer mit authentifizierter Verschlüsselung und schützt Schlüssel zur Inhaltsverschlüsselung (CEKs) mithilfe von V2-Objekten. KeyWrap

Das folgende Beispiel zeigt, wie die Kryptokonfiguration in V1 angegeben wird und wie ein CryptoConfigurationV2-Objekt instanziiert wird, um es an den V2-Verschlüsselungs-Client-Builder zu übergeben.

V1 

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

V2 

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

Weitere Beispiele

Die folgenden Beispiele zeigen, wie bestimmte Anwendungsfälle im Zusammenhang mit einer Migration von V1 zu V2 behandelt werden können.

Konfigurieren Sie einen Service Client zum Lesen von Objekten, die vom V1 Encryption Client erstellt wurden

Um Objekte zu lesen, die zuvor mit einem V1-Verschlüsselungsclient geschrieben wurden, setzen Sie den cryptoMode Wert aufAuthenticatedEncryption. Der folgende Codeausschnitt zeigt, wie ein Konfigurationsobjekt mit dieser Einstellung erstellt wird.

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

Konfigurieren Sie einen Service Client für das Abrufen von Bytebereichen von Objekten

Um aus get einem verschlüsselten S3-Objekt auf einen Bytebereich zugreifen zu können, aktivieren Sie die neue KonfigurationseinstellungrangeGetMode. Diese Einstellung ist auf dem V2-Verschlüsselungsclient standardmäßig deaktiviert. Beachten Sie, dass ein Bereich, auch wenn er aktiviert ist, get nur für Objekte funktioniert, die mit Algorithmen verschlüsselt wurden, die von der cryptoMode Einstellung des Clients unterstützt werden. Weitere Informationen finden Sie CryptoRangeGetModein der AWS SDK for Java API Referenz.

Wenn Sie den verwenden möchten, Amazon S3 TransferManager um mehrteilige Downloads verschlüsselter Amazon S3 Objekte mithilfe des V2-Verschlüsselungsclients durchzuführen, müssen Sie zuerst die rangeGetMode Einstellung auf dem V2-Verschlüsselungsclient aktivieren.

Der folgende Codeausschnitt zeigt, wie der V2-Client für die Ausführung eines Ranges konfiguriert wird. 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);