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](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) 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:
+ Java 8 o versione successiva installata nell'ambiente applicativo. AWS SDK per Java Funziona con l'[Oracle Java SE Development Kit ](https://www.oracle.com/java/technologies/javase-downloads.html) e con le distribuzioni di Open Java Development Kit (OpenJDK) come [Amazon Corretto](https://aws.amazon.com/corretto/) [ Red Hat OpenJDK e JDK. ](https://developers.redhat.com/products/openjdk) [ AdoptOpen ](https://adoptopenjdk.net/)
+ Il pacchetto Bouncy Castle Crypto. [https://www.bouncycastle.org/download/bouncy-castle-java/](https://www.bouncycastle.org/download/bouncy-castle-java/) Puoi inserire il file .jar di Bouncy Castle nel classpath del tuo ambiente applicativo o aggiungere una dipendenza dall'`bcprov-ext-jdk15on`artifactID (con groupId di) al tuo file Maven. `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 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.
1. **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.) ](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc) 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:
```
com.amazonaws
aws-java-sdk-bom
1.11.837
pom
import
```
#### 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'`cryptoMode`impostazione 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'`cryptoMode`impostazione del client. Per ulteriori informazioni, consulta l' AWS SDK per Java API [ CryptoRangeGetMode ](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoRangeGetMode.html) 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'`rangeGetMode`impostazione 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);
```