View a markdown version of this page

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

La versione AWS SDK per Java 1.x ha raggiunto la fine del supporto il 31 dicembre 2025. Ti consigliamo di eseguire la migrazione alla versione per continuare AWS SDK for Java 2.x a 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 del 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:

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 AWS SDK per 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 utilizza più AWS SDK, è necessario aggiornare ciascun SDK separatamente.

  2. Esegui la migrazione dei client di crittografia e decrittografia alla V2. Una volta che tutti i client di crittografia V1 sono 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 AWS SDK per Java non supportati dalle versioni precedenti.

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 per Java(Ti consigliamo di eseguire l'aggiornamento alla versione più recente, che puoi trovare 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 per Java Quindi, ricostruisci il tuo progetto e ridistribuiscilo.

Completare questo passaggio prima di distribuire il nuovo codice dell'applicazione aiuta a garantire che le operazioni di crittografia e decrittografia rimangano coerenti in tutto il parco macchine durante il processo di migrazione.

Esempio di utilizzo di Maven

Frammento 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'
}

Migra i client di crittografia e decrittografia alla V2

Una volta che il progetto è stato aggiornato con l'ultima versione SDK, puoi 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 i materiali di crittografia utilizzando un metodo sul generatore 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 per 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 il valore cryptoMode di. AuthenticatedEncryption 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 AmazonS3EncryptionClientV2.encryptionBuilder chiamando ().

È 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 scritto da un client di crittografia V1 purché gli si consenta di farlo configurando il client di crittografia V2 in modo che utilizzi 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 with EncryptionMaterials () nel generatore del client di crittografia è stato rinominato with EncryptionMaterialsProvider (). Questa è solo 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 i fornitori di materiali di crittografia

Puoi continuare a utilizzare gli stessi fornitori di materiali di crittografia e gli stessi oggetti di materiali di crittografia che stai già utilizzando con il client di crittografia V1. Queste classi sono responsabili della fornitura delle chiavi utilizzate dal client di crittografia per proteggere i dati. Possono essere utilizzati 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 suo costruttore predefinito e quindi modificando le sue 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

Nota che non EncryptionOnly è supportato cryptoMode nel client di crittografia V2. Il client di crittografia V2 crittografa sempre i contenuti utilizzando la crittografia autenticata e protegge le chiavi di crittografia dei contenuti (CEK) utilizzando oggetti V2. KeyWrap

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

V1 

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

V2 

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

Esempi aggiuntivi

Gli esempi seguenti dimostrano come affrontare casi d'uso specifici relativi a una migrazione da V1 a V2.

Configurare un Service Client per leggere gli oggetti creati dal V1 Encryption Client

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 Service Client per ottenere intervalli di byte di oggetti

Per poter ottenere 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, consulta l' AWS SDK per Java API CryptoRangeGetMode Reference.

Se prevedi di utilizzare il Amazon S3 TransferManager per eseguire download in più parti di Amazon S3 oggetti crittografati utilizzando il client di crittografia V2, devi 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);