A versão 4 (V4) do AWS SDK para .NET foi lançada!

Para obter informações sobre mudanças significativas e migrar seus aplicativos, consulte o tópico de migraçã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 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 (S3) para a versão 4 (V4) e garantir a disponibilidade dos aplicativos durante todo o processo de migração. A V4 usa AES-GCM com comprometimento chave a criptografia de conteúdo e introduz políticas de compromisso para aprimorar a segurança contra ataques de substituição de chaves.

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

Entendendo os conceitos da V4

A V4 usa AES-GCM com compromisso fundamental a 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 decodificação. A V4 suporta três políticas de compromisso:

AES GCM com compromisso fundamental

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

Atualizar clientes existentes para ler 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 pacote

Atualize seus aplicativos para usar a versão mais recente do Amazon.Extensions.S3.Encryption NuGet pacote que inclui suporte para 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 pelos clientes V4, garantindo a compatibilidade durante o processo de migração.

Migrar 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. Esta 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 V2

Migre para o cliente V4 enquanto mantém um comportamento idêntico ao V2. Esta etapa usa a ForbidEncryptAllowDecrypt 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.ForbidEncryptAllowDecrypt, 
    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 confirmados e não confirmados. Idêntico ao comportamento da V2.

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

Comece a criptografar com o compromisso de chave e, ao mesmo tempo, mantenha a compatibilidade com versões anteriores da decodificação. Esta etapa usa a RequireEncryptAllowDecrypt 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.RequireEncryptAllowDecrypt, 
    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 confirmados e não confirmados. 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. Esta etapa usa a RequireEncryptRequireDecrypt 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.RequireEncryptRequireDecrypt, 
    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, apenas 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 suporte legado

Para permitir que os clientes V4 leiam objetos criptografados pelos 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(SecurityProfile.V4AndLegacy, CommitmentPolicy.RequireEncryptAllowDecrypt)
{
    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(SecurityProfile.V4, CommitmentPolicy.RequireEncryptAllowDecrypt)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata

Arquivo de instruções

var configuration = new AmazonS3CryptoConfigurationV4(SecurityProfile.V4, CommitmentPolicy.RequireEncryptAllowDecrypt)
{
    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 na fase de migração:

Fase de migração (compatibilidade com V2)

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

Fase de transição (recomendada)

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

Fase de segurança total

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

Comece ForbidEncryptAllowDecrypt durante a migração inicial, passe RequireEncryptAllowDecrypt para a fase de transição e, finalmente, use RequireEncryptRequireDecrypt quando todos os clientes tiverem sido atualizados e todos os objetos tiverem sido criptografados novamente com comprometimento.