O AWS SDK para .NET V3 entrou no modo de manutenção.

Recomendamos que você migre para a AWS SDK para .NET V4. Para obter detalhes e informações adicionais sobre como migrar, consulte nosso anúncio do modo de manutenção.

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Migração do cliente de criptografia Amazon S3 (V2 para V4)

Este tópico mostra como migrar seus aplicativos da versão 2 (V2) do cliente de criptografia Amazon Simple Storage Service (Amazon S3) para a versão 4 (V4) e garantir a disponibilidade dos aplicativos durante todo o processo de migração. A V4 usa o AES-GCM com o compromisso principal de criptografia de conteúdo e apresenta políticas de compromisso para aumentar a segurança contra ataques de substituição de chaves.

O cliente V4 está disponível no pacote NuGet Amazon.Extensions.S3.Encryption.

Compreendendo os conceitos da V4

A V4 usa o AES-GCM com o compromisso fundamental de criptografia de conteúdo e apresenta os principais conceitos de segurança que aprimoram a proteção de seus dados criptografados:

Política de compromisso

A Política de Compromisso controla como o cliente de criptografia lida com o comprometimento da chave durante as operações de criptografia e descriptografia. A V4 oferece suporte a três políticas de compromisso:

AES GCM com compromisso fundamental

A V4 usa o AES-GCM com o compromisso fundamental de criptografia de conteúdo, o que fornece segurança aprimorada:

Atualize os clientes existentes para ler os formatos V4

O cliente de criptografia V4 usa algoritmos de criptografia que as versões mais antigas do cliente não suportam. A primeira etapa da migração é atualizar seus clientes V2 para que eles possam ler o novo formato V4.

Atualizar dependências NuGet do Package

Atualize seus aplicativos para usar a versão mais recente do pacote NuGet Amazon.Extensions.S3.Encryption que inclui suporte à V4. Execute as seguintes etapas em cada um dos seus aplicativos:

Seus clientes V2 existentes continuarão trabalhando com o pacote atualizado e poderão descriptografar objetos criptografados por clientes V4 (dependendo da política de compromisso usada).

Crie e implante aplicativos

Depois de atualizar as dependências NuGet do pacote:

Essa atualização permite que seus clientes V2 existentes descriptografem objetos que serão criptografados por clientes V4, garantindo compatibilidade durante o processo de migração.

Migre para clientes V4

Depois de atualizar seus clientes existentes para ler o novo formato de criptografia, você pode continuar atualizando seus aplicativos com segurança para usar clientes de criptografia e descriptografia V4. O cliente V4 fornece segurança aprimorada por meio do comprometimento de chaves, mantendo a compatibilidade com objetos criptografados existentes.

Processo de migração em 4 etapas

A migração da V2 para a V4 segue um processo estruturado de 4 etapas para garantir compatibilidade e segurança. Cada etapa representa uma configuração específica que deve ser implantada em todos os seus aplicativos antes de prosseguir para a próxima etapa.

Etapa 0: Cliente V2 (ponto de partida)

Isso representa sua configuração de cliente V2 existente. Essa etapa demonstra o estado inicial antes da migração.

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

Etapa 1: V4 com compatibilidade com V2

Migre para o cliente V4 enquanto mantém um comportamento idêntico ao V2. Essa etapa usa a FORBID_ENCRYPT_ALLOW_DECRYPT política para criptografar sem compromisso e permitir a descriptografia de todos os objetos.

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: criptografa sem compromisso, pode descriptografar objetos comprometidos e não comprometidos. Idêntico ao comportamento da V2.

Etapa 2: V4 com gravações de compromisso importantes

Comece a criptografar com o compromisso de chave e, ao mesmo tempo, mantenha a compatibilidade com versões anteriores para decodificação. Essa etapa usa a REQUIRE_ENCRYPT_ALLOW_DECRYPT política.

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: criptografa com comprometimento, pode descriptografar objetos comprometidos e não comprometidos. Novos objetos são protegidos contra ataques de substituição de chaves.

Etapa 3: V4 com aplicação total

Exija o comprometimento da chave tanto para criptografia quanto para decodificação. Essa etapa usa a REQUIRE_ENCRYPT_REQUIRE_DECRYPT política para máxima segurança.

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: criptografa com compromisso, somente descriptografa objetos criptografados com compromisso. Segurança máxima contra ataques de substituição de chaves.

Exemplos adicionais de configuração

Esta seção fornece exemplos adicionais para configurar clientes V4 com opções diferentes durante a migração.

Habilitando o Legacy Support

Para permitir que clientes V4 leiam objetos criptografados por clientes V1 e V2, configure o cliente com uma política de compromisso que permita a descriptografia legada:

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

Use essa configuração durante a migração quando precisar descriptografar objetos criptografados por clientes mais antigos e, ao mesmo tempo, garantir que novos objetos sejam criptografados com segurança aprimorada.

Configurando o método de armazenamento

A V4 oferece suporte a dois métodos de armazenamento para metadados de criptografia. Escolha o método mais adequado ao seu caso de uso:

Metadados do objeto (padrão)

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

Arquivo de instruções

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

Use InstructionFile quando precisar preservar os metadados do objeto para outras finalidades ou ao trabalhar com objetos que tenham limitações de tamanho de metadados.

Configurando a política de compromisso

Escolha a política de compromisso apropriada com base em seus requisitos de segurança e fase de migração:

Fase de migração (compatibilidade V2)

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

Fase de transição (recomendada)

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

Fase de segurança completa

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

Comece FORBID_ENCRYPT_ALLOW_DECRYPT durante a migração inicial, passe REQUIRE_ENCRYPT_ALLOW_DECRYPT para a fase de transição e, finalmente, use REQUIRE_ENCRYPT_REQUIRE_DECRYPT quando todos os clientes tiverem sido atualizados e todos os objetos tiverem sido criptografados novamente com compromisso.