È stata rilasciata la versione 4 (V4) di! AWS SDK per .NET

Per iniziare a utilizzare la nuova versione dell'SDK, consulta la Guida per gli sviluppatori AWS SDK per .NET (V4), in particolare l'argomento relativo alla migrazione alla versione 4.

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à.

Migrazione del client di crittografia Amazon S3 (da V2 a V4)

Questo argomento mostra come migrare le applicazioni dalla versione 2 (V2) del client di crittografia Amazon Simple Storage Service (Amazon S3) alla versione 4 (V4) e garantire la disponibilità delle applicazioni durante tutto il processo di migrazione. V4 utilizza AES-GCM con impegno fondamentale per la crittografia dei contenuti e introduce Commitment Policies per migliorare la sicurezza contro gli attacchi di sostituzione delle chiavi.

Il client V4 è disponibile nel pacchetto Amazon.Extensions.S3.Encryption. NuGet

Comprensione dei concetti della V4

V4 utilizza AES-GCM con un impegno fondamentale per la crittografia dei contenuti e introduce concetti chiave di sicurezza che migliorano la protezione dei dati crittografati:

Politica di impegno

La politica di impegno controlla il modo in cui il client di crittografia gestisce l'impegno delle chiavi durante le operazioni di crittografia e decrittografia. V4 supporta tre politiche di impegno:

AES GCM con impegno chiave

V4 utilizza AES-GCM con un impegno fondamentale per la crittografia dei contenuti, che offre una maggiore sicurezza:

Aggiorna i client esistenti per leggere i formati V4

Il client di crittografia V4 utilizza algoritmi di crittografia che le versioni precedenti del client non supportano. Il primo passo della migrazione consiste nell'aggiornare i client V2 in modo che possano leggere il nuovo formato V4.

Aggiorna le dipendenze dei NuGet pacchetti

Aggiorna le tue applicazioni per utilizzare la versione più recente del pacchetto NuGet Amazon.Extensions.S3.Encryption che include il supporto V4. Esegui i seguenti passaggi su ciascuna delle tue applicazioni:

I client V2 esistenti continueranno a funzionare con il pacchetto aggiornato e saranno in grado di decrittografare gli oggetti crittografati dai client V4 (a seconda della politica di impegno utilizzata).

Crea e distribuisci applicazioni

Dopo aver aggiornato le dipendenze dei NuGet pacchetti:

Questo aggiornamento consente ai client V2 esistenti di decrittografare gli oggetti che verranno crittografati dai client V4, garantendo la compatibilità durante il processo di migrazione.

Esegui la migrazione ai client V4

Dopo aver aggiornato i client esistenti per leggere il nuovo formato di crittografia, è possibile procedere all'aggiornamento sicuro delle applicazioni per utilizzare i client di crittografia e decrittografia V4. Il client V4 offre una maggiore sicurezza grazie all'impegno delle chiavi, pur mantenendo la compatibilità con gli oggetti crittografati esistenti.

Processo di migrazione in 4 fasi

La migrazione dalla V2 alla V4 segue un processo strutturato in 4 fasi per garantire compatibilità e sicurezza. Ogni passaggio rappresenta una configurazione specifica che deve essere implementata in tutte le applicazioni prima di procedere al passaggio successivo.

Fase 0: V2 Client (punto di partenza)

Rappresenta la configurazione del client V2 esistente. Questo passaggio dimostra lo stato iniziale prima della migrazione.

using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 0: V2 Client - Starting configuration
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext);

#pragma warning disable 0618
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
#pragma warning enable 0618

var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

Fase 1: compatibilità V4 con V2

Esegui la migrazione al client V4 mantenendo un comportamento identico a quello della V2. Questo passaggio utilizza una FORBID_ENCRYPT_ALLOW_DECRYPT politica per crittografare senza impegno e consentire la decrittografia di tutti gli oggetti.

using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 1: V4 Client with V2 compatibility
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcm);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

Comportamento: cripta senza impegno, può decrittografare sia gli oggetti che effettuano il commit che quelli che non effettuano il commit. Identico al comportamento della V2.

Fase 2: V4 con Key Commitment Writes

Inizia a crittografare con un impegno chiave, mantenendo al contempo la compatibilità con le versioni precedenti per la decrittografia. Questo passaggio utilizza la politica. REQUIRE_ENCRYPT_ALLOW_DECRYPT

using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 2: V4 Client with key commitment writes
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

Comportamento: cripta con impegno, può decrittografare sia gli oggetti che effettuano il commit che quelli che non effettuano il commit. I nuovi oggetti sono protetti dagli attacchi di sostituzione delle chiavi.

Fase 3: V4 con applicazione completa

Richiede un impegno fondamentale sia per la crittografia che per la decrittografia. Questo passaggio utilizza una REQUIRE_ENCRYPT_REQUIRE_DECRYPT politica per la massima sicurezza.

using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 3: V4 Client with full key commitment enforcement
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});

Comportamento: crittografa con impegno, decrittografa solo gli oggetti crittografati con impegno. Massima sicurezza contro gli attacchi di sostituzione delle chiavi.

Esempi di configurazione aggiuntivi

Questa sezione fornisce esempi aggiuntivi per la configurazione dei client V4 con diverse opzioni durante la migrazione.

Attivazione del supporto Legacy

Per consentire ai client V4 di leggere gli oggetti crittografati dai client V1 e V2, configura il client con una politica di impegno che consenta la decrittografia legacy:

using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

// Configure V4 client to read V1/V2 objects
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};

// This configuration allows:
// - Encryption: With commitment (secure)
// - Decryption: Both V2 (non-committing) and V4 (committing) objects

Utilizza questa configurazione durante la migrazione quando devi decrittografare oggetti crittografati da client precedenti, garantendo al contempo che i nuovi oggetti siano crittografati con una maggiore sicurezza.

Configurazione del metodo di archiviazione

V4 supporta due metodi di archiviazione per i metadati di crittografia. Scegli il metodo più adatto al tuo caso d'uso:

Metadati degli oggetti (impostazione predefinita)

var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata

File di istruzioni

var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.InstructionFile
};
// Encryption metadata is stored in a separate S3 object (instruction file)

Da utilizzare InstructionFile quando è necessario conservare i metadati degli oggetti per altri scopi o quando si lavora con oggetti con limitazioni di dimensione dei metadati.

Configurazione della politica di impegno

Scegliete la politica di impegno appropriata in base ai requisiti di sicurezza e alla fase di migrazione:

Fase di migrazione (compatibilità V2)

// For migration: encrypt without commitment, allow all decryption
var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT);

Fase di transizione (consigliata)

// For transition: encrypt with commitment, allow legacy decryption
var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);

Fase di sicurezza completa

// For maximum security: require commitment for both encryption and decryption
var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);

Inizia con FORBID_ENCRYPT_ALLOW_DECRYPT la migrazione iniziale, passa alla fase REQUIRE_ENCRYPT_ALLOW_DECRYPT di transizione e infine utilizza REQUIRE_ENCRYPT_REQUIRE_DECRYPT quando tutti i client sono stati aggiornati e tutti gli oggetti sono stati ricrittografati con impegno.