Amazon S3 Migrazione dei client di crittografia - AWS SDK for Java 1. x
PrerequisitiPanoramica sulla migrazioneAggiorna i client esistenti per leggere nuovi formatiMigrazione dei client di crittografia e decrittografia alla V2Esempi aggiuntivi

La AWS SDK for Java versione 1.x è entrata in modalità manutenzione il 31 luglio 2024 e sarà disponibile il 31 end-of-supportdicembre 2025. Ti consigliamo di eseguire la migrazione a per continuare AWS SDK for Java 2.xa ricevere nuove funzionalità, miglioramenti della disponibilità e aggiornamenti di sicurezza.

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Amazon S3 Migrazione dei client di crittografia

Questo argomento mostra come migrare le applicazioni dalla versione 1 (V1) del client di crittografia () alla versione 2 Amazon Simple Storage Service (V2 Amazon S3) e garantire la disponibilità delle applicazioni durante tutto il processo di migrazione.

Prerequisiti

Amazon S3 la crittografia lato client richiede quanto segue:

  • Java 8 o versione successiva installata nell'ambiente applicativo. AWS SDK for Java Funziona con Oracle Java SE Development Kit e con distribuzioni di Open Java Development Kit (OpenJDK) come Amazon CorrettoRed Hat Open JDK e AdoptOpenJDK.

  • Il pacchetto Bouncy Castle Crypto. Puoi inserire il file.jar di Bouncy Castle nel classpath del tuo ambiente applicativo o aggiungere una dipendenza da artifactId bcprov-ext-jdk15on (con of) al tuo file Maven. groupId org.bouncycastle pom.xml

Panoramica sulla migrazione

Questa migrazione avviene in due fasi:

  1. Aggiorna i client esistenti per leggere nuovi formati. Aggiorna l'applicazione per utilizzare la versione 1.11.837 o successiva di AWS SDK for Java e ridistribuisci l'applicazione. Ciò consente ai Amazon S3 client del servizio di crittografia lato client dell'applicazione di decrittografare gli oggetti creati dai client del servizio V2. Se l'applicazione ne utilizza più di uno AWS SDKs, è necessario aggiornarli separatamente. SDK

  2. Migra i client di crittografia e decrittografia alla V2. Una volta che tutti i client di crittografia V1 saranno in grado di leggere i formati di crittografia V2, aggiorna i Amazon S3 client di crittografia e decrittografia lato client nel codice dell'applicazione per utilizzare i loro equivalenti V2.

Aggiorna i client esistenti per leggere nuovi formati

Il client di crittografia V2 utilizza algoritmi di crittografia che le versioni precedenti di AWS SDK for Java non supportano.

Il primo passaggio della migrazione consiste nell'aggiornare i client di crittografia V1 per utilizzare la versione 1.11.837 o successiva di. AWS SDK for Java(Si consiglia di eseguire l'aggiornamento alla versione più recente, disponibile nella versione 1.x di Java API Reference.) A tale scopo, aggiorna la dipendenza nella configurazione del progetto. Dopo aver aggiornato la configurazione del progetto, ricostruisci il progetto e ridistribuiscilo.

Una volta completati questi passaggi, i client di crittografia V1 dell'applicazione saranno in grado di leggere gli oggetti scritti dai client di crittografia V2.

Aggiorna la dipendenza nella configurazione del tuo progetto

Modifica il file di configurazione del progetto (ad esempio, pom.xml o build.gradle) per utilizzare la versione 1.11.837 o successiva di. AWS SDK for Java Quindi, ricostruisci il progetto e ridistribuiscilo.

Il completamento di questo passaggio prima di implementare il nuovo codice applicativo aiuta a garantire che le operazioni di crittografia e decrittografia rimangano coerenti in tutta la flotta durante il processo di migrazione.

Esempio di utilizzo di Maven

Frammento di codice da un file 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>

Esempio di utilizzo di Gradle

Frammento da un file build.gradle:

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

Migrazione dei client di crittografia e decrittografia alla V2

Una volta aggiornato il progetto con la SDK versione più recente, è possibile modificare il codice dell'applicazione per utilizzare il client V2. Per fare ciò, aggiorna prima il codice per utilizzare il nuovo service client builder. Quindi fornisci materiali di crittografia utilizzando un metodo sul builder che è stato rinominato e configura ulteriormente il client di servizio secondo necessità.

Questi frammenti di codice dimostrano come utilizzare la crittografia lato client con e forniscono confronti tra i AWS SDK for Java client di crittografia V1 e 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'esempio precedente imposta cryptoMode suAuthenticatedEncryption. Questa è un'impostazione che consente a un client di crittografia V2 di leggere oggetti scritti da un client di crittografia V1. Se il tuo client non ha bisogno della capacità di leggere oggetti scritti da un client V1, ti consigliamo di utilizzare invece l'impostazione predefinita di. StrictAuthenticatedEncryption

Costruisci un client di crittografia V2

Il client di crittografia V2 può essere creato chiamando AmazonS3 V2. EncryptionClient encryptionBuilder().

È possibile sostituire tutti i client di crittografia V1 esistenti con client di crittografia V2. Un client di crittografia V2 sarà sempre in grado di leggere qualsiasi oggetto che è stato scritto da un client di crittografia V1, purché gli si consenta di farlo configurando il client di crittografia V2 per utilizzare il `. AuthenticatedEncryption `cryptoMode

La creazione di un nuovo client di crittografia V2 è molto simile a come si crea un client di crittografia V1. Tuttavia, ci sono alcune differenze:

  • Utilizzerai un CryptoConfigurationV2 oggetto per configurare il client anziché un CryptoConfiguration oggetto. Questo parametro è obbligatorio.

  • L'cryptoModeimpostazione predefinita per il client di crittografia V2 èStrictAuthenticatedEncryption. Per il client di crittografia V1 lo è. EncryptionOnly

  • Il metodo withEncryptionMaterials() sul generatore del client di crittografia è stato rinominato withEncryptionMaterialsProvider (). Si tratta semplicemente di una modifica estetica che riflette in modo più accurato il tipo di argomento. È necessario utilizzare il nuovo metodo quando si configura il client di servizio.

Nota

Quando decifrate con AES -GCM, leggete l'intero oggetto fino alla fine prima di iniziare a utilizzare i dati decrittografati. Questo serve a verificare che l'oggetto non sia stato modificato da quando è stato crittografato.

Utilizza fornitori di materiali di crittografia

Puoi continuare a utilizzare gli stessi fornitori di materiali di crittografia e gli stessi oggetti di materiale di crittografia che stai già utilizzando con il client di crittografia V1. Queste classi hanno la responsabilità di fornire le chiavi utilizzate dal client di crittografia per proteggere i dati. Possono essere utilizzate in modo intercambiabile con il client di crittografia V2 e V1.

Configurare il client di crittografia V2

Il client di crittografia V2 è configurato con un CryptoConfigurationV2 oggetto. Questo oggetto può essere costruito chiamando il relativo costruttore predefinito e quindi modificandone le proprietà come richiesto dai valori predefiniti.

I valori predefiniti per sono: CryptoConfigurationV2

  • cryptoMode = CryptoMode.StrictAuthenticatedEncryption

  • storageMode = CryptoStorageMode.ObjectMetadata

  • secureRandom= istanza di SecureRandom

  • rangeGetMode = CryptoRangeGetMode.DISABLED

  • unsafeUndecryptableObjectPassthrough = false

Si noti che non EncryptionOnlyè supportato cryptoMode nel client di crittografia V2. Il client di crittografia V2 crittograferà sempre i contenuti utilizzando la crittografia autenticata e proteggerà le chiavi di crittografia dei contenuti () CEKs utilizzando oggetti V2. KeyWrap

L'esempio seguente mostra come specificare la configurazione di crittografia in V1 e come creare un'istanza di un oggetto V2 da passare al generatore del client di crittografia CryptoConfigurationV2.

V1 

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

V2 

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

Esempi aggiuntivi

Gli esempi seguenti mostrano come affrontare casi d'uso specifici relativi a una migrazione dalla V1 alla V2.

Configurare un client di servizio per leggere gli oggetti creati dal client di crittografia V1

Per leggere oggetti scritti in precedenza utilizzando un client di crittografia V1, imposta su. cryptoMode AuthenticatedEncryption Il seguente frammento di codice mostra come costruire un oggetto di configurazione con questa impostazione.

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

Configura un client di servizio per ottenere intervalli di byte di oggetti

Per poter recuperare get un intervallo di byte da un oggetto S3 crittografato, abilita la nuova impostazione di configurazione. rangeGetMode Per impostazione predefinita, questa impostazione è disabilitata sul client di crittografia V2. Nota che, anche se abilitato, un intervallo funziona get solo su oggetti che sono stati crittografati utilizzando algoritmi supportati dall'cryptoModeimpostazione del client. Per ulteriori informazioni, vedere CryptoRangeGetModenella Guida di riferimento. AWS SDK for Java API

Se si prevede di utilizzare il Amazon S3 TransferManager per eseguire download in più parti di Amazon S3 oggetti crittografati utilizzando il client di crittografia V2, è necessario prima abilitare l'rangeGetModeimpostazione sul client di crittografia V2.

Il seguente frammento di codice mostra come configurare il client V2 per l'esecuzione di un intervallo. 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);