A versão 4 (V4) do AWS SDK for .NET foi lançada\!
Para obter informações sobre mudanças significativas e migrar seus aplicativos, consulte o [tópico de migração](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html).
[](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/net-dg-v4.html)
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)
**nota**
Se você estiver usando a V1 e quiser migrar para a V4, primeiro deverá migrar para a V2. Consulte [Migração do cliente de criptografia S3 (V1 para V2)](s3-encryption-migration-v1-v2.md).
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 compromisso de chave para 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 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet pacote.
**Importante**
**Alterações importantes:** clientes V4 configurados com `RequireEncryptRequireDecrypt` política não podem descriptografar objetos criptografados com clientes V1 ou V2. Somente os clientes V2 mais recentes podem descriptografar V4-encrypted objetos com comprometimento fundamental. Antes de passar para a `RequireEncryptRequireDecrypt` política, você deve criptografar novamente todos os seus dados existentes usando clientes V4 com o compromisso de chave ativado.
## Compreendendo 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 oferece suporte a três políticas de compromisso:
`ForbidEncryptAllowDecrypt`
*Criptografia:* sem compromisso
*Descriptografia:* permite que objetos não confirmem
*Segurança:* não impõe o compromisso e pode permitir a adulteração
*Compatibilidade:* todas as implementações V2 e V4 podem ler objetos criptografados com esta política
`RequireEncryptAllowDecrypt`
*Criptografia:* com compromisso fundamental
*Descriptografia:* permite que objetos confirmados e não confirmados
*Segurança:* novos objetos são protegidos contra ataques de substituição de chaves, objetos antigos ainda podem ser lidos
*Compatibilidade:* somente a V4 oferece suporte a essa política
`RequireEncryptRequireDecrypt`(Padrão para V4)
*Criptografia:* com compromisso fundamental
*Descriptografia:* somente confirmando objetos
*Segurança:* cumprimento total do compromisso para máxima segurança
*Compatibilidade:* somente a V4 oferece suporte a essa política
### AES GCM com compromisso fundamental
A V4 usa AES-GCM com compromisso fundamental a criptografia de conteúdo, o que fornece segurança aprimorada:
+ *Proteção contra adulteração:* protege contra ataques de substituição de chave vinculando criptograficamente a chave aos dados criptografados.
+ *Compatibilidade de versão:* objetos criptografados com comprometimento de chave só podem ser descriptografados por clientes V4 e versões mais recentes.
**Atenção**
Antes de ativar a criptografia de comprometimento de chave na produção, certifique-se de que todos os aplicativos que precisam descriptografar seus objetos tenham sido atualizados para a V4 ou mais recente, pois o cliente V2 está se tornando obsoleto.
## 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 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet pacote que inclui suporte à V4. Execute as seguintes etapas em cada um dos seus aplicativos:
1. Atualize para o [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption)pacote mais recente. Se seu projeto depende diretamente dos **AWSSDK.KeyManagementService**pacotes **AWSSDK.S3**ou, você deve atualizar essas dependências ou removê-las para que suas versões atualizadas sejam integradas com esse novo pacote.
1. Certifique-se de que suas `using` declarações façam referência ao namespace correto:
```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
```
1. Reconstrua e reimplante o aplicativo.
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 seu pacote:
1. Crie seu aplicativo para garantir que todas as dependências sejam resolvidas corretamente.
1. Teste seu aplicativo em um ambiente de desenvolvimento para verificar se a funcionalidade existente continua funcionando.
1. Implante o aplicativo atualizado em seu ambiente de produção.
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.
1. **Etapa 0: Cliente V2 (ponto de partida)** - Sua implementação V2 existente
1. **Etapa 1: V4 com compatibilidade V2** - Migre para o cliente V4 enquanto mantém o comportamento de criptografia V2-compatible
1. **Etapa 2: V4 com gravações de compromisso de chave** - Comece a criptografar com compromisso de chave enquanto permite a descriptografia de objetos legados
1. **Etapa 3: V4 com aplicação total** - Exigir comprometimento de chave para criptografia e decodificação
### 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();
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 `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();
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 comprometidos e não confirmados. 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 `RequireEncryptAllowDecrypt` política.
**Atenção**
Antes de implantar a Etapa 2, certifique-se de que todos os leitores tenham sido atualizados para a Etapa 1 ou posterior para lidar com a criptografia de compromisso de chave.
```
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();
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 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 `RequireEncryptRequireDecrypt` política para máxima segurança.
**Atenção**
Antes de implantar a Etapa 3, certifique-se de que todos os objetos em seu sistema tenham sido criptografados novamente com o comprometimento da chave (Etapa 2). Essa etapa falhará ao descriptografar objetos criptografados sem compromisso.
```
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();
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, 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(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 que melhor se adapta 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 fase de migração:
**Fase de migração (compatibilidade 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 completa**
```
// 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 compromisso.