¡Se AWS SDK para .NET ha publicado la versión 4 (V4) del!

Para obtener información sobre los cambios más importantes y la migración de sus aplicaciones, consulte el tema sobre migración.

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Migración de un cliente de cifrado S3 (de V2 a V4)

En este tema se muestra cómo migrar las aplicaciones de la versión 2 (V2) del cliente de cifrado Amazon Simple Storage Service (S3) a la versión 4 (V4) y cómo garantizar la disponibilidad de las aplicaciones durante todo el proceso de migración. La versión 4 utiliza AES-GCM con un compromiso clave para el cifrado de contenido e introduce políticas de compromiso para mejorar la seguridad contra los ataques de sustitución de claves.

El cliente V4 está disponible en el paquete Amazon.Extensions.S3.Encryption. NuGet

Comprender los conceptos de la versión 4

La versión 4 utiliza AES-GCM con un compromiso clave con el cifrado de contenido e introduce conceptos de seguridad clave que mejoran la protección de sus datos cifrados:

Política de compromiso

La política de compromiso controla la forma en que el cliente de cifrado gestiona el compromiso de claves durante las operaciones de cifrado y descifrado. La versión 4 admite tres políticas de compromiso:

AES GCM con un compromiso clave

La V4 utiliza el AES-GCM con un compromiso clave para el cifrado de contenido, lo que proporciona una seguridad mejorada:

Actualice los clientes existentes para leer los formatos V4

El cliente de cifrado V4 utiliza algoritmos de cifrado que las versiones anteriores del cliente no admiten. El primer paso de la migración consiste en actualizar los clientes de la versión 2 para que puedan leer el nuevo formato de la versión 4.

Update NuGet Package Dependencies

Actualice sus aplicaciones para utilizar la última versión del paquete NuGet Amazon.Extensions.S3.Encryption, que incluye compatibilidad con la versión 4. Realice los siguientes pasos en cada una de sus aplicaciones:

Sus clientes V2 actuales seguirán trabajando con el paquete actualizado y podrán descifrar los objetos cifrados por los clientes V4 (en función de la política de compromiso utilizada).

Cree e implemente aplicaciones

Tras actualizar las dependencias de sus NuGet paquetes:

Esta actualización permite a sus clientes de V2 existentes descifrar los objetos que serán cifrados por los clientes de V4, lo que garantiza la compatibilidad durante el proceso de migración.

Migre a clientes V4

Tras actualizar sus clientes actuales para que lean el nuevo formato de cifrado, puede proceder a actualizar sus aplicaciones de forma segura para que utilicen clientes de cifrado y descifrado V4. El cliente V4 proporciona una seguridad mejorada mediante el compromiso con las claves y, al mismo tiempo, mantiene la compatibilidad con los objetos cifrados existentes.

Proceso de migración en 4 pasos

La migración de la V2 a la V4 sigue un proceso estructurado de 4 pasos para garantizar la compatibilidad y la seguridad. Cada paso representa una configuración específica que debe implementarse en todas las aplicaciones antes de continuar con el siguiente paso.

Paso 0: Cliente V2 (punto de partida)

Esto representa la configuración de su cliente V2 existente. Este paso muestra el estado inicial antes de la migración.

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

Paso 1: Compatibilidad entre V4 y V2

Migre al cliente V4 manteniendo un comportamiento idéntico al de la V2. En este paso se utiliza una ForbidEncryptAllowDecrypt política para cifrar sin compromiso y permitir el descifrado de todos los 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
});

Comportamiento: cifra sin compromiso, puede descifrar tanto los objetos que se están confirmando como los que no lo están. Comportamiento idéntico al de la V2.

Paso 2: V4 con escrituras clave

Comience a cifrar con el compromiso de clave y, al mismo tiempo, mantenga la compatibilidad con versiones anteriores para el descifrado. En este paso se utiliza RequireEncryptAllowDecrypt la 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
});

Comportamiento: cifra con compromiso, puede descifrar tanto los objetos confirmados como los que no se comprometen. Los objetos nuevos están protegidos contra los ataques de sustitución de claves.

Paso 3: V4 con plena aplicación

Exija un compromiso clave tanto para el cifrado como para el descifrado. En este paso se utiliza una RequireEncryptRequireDecrypt política para garantizar la máxima seguridad.

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

Comportamiento: cifra con compromiso, solo descifra los objetos cifrados con compromiso. Máxima seguridad contra los ataques de sustitución de claves.

Ejemplos de configuración adicionales

En esta sección se proporcionan ejemplos adicionales para configurar los clientes de la versión 4 con diferentes opciones durante la migración.

Habilitación de Legacy Support

Para permitir que los clientes V4 lean los objetos cifrados por los clientes V1 y V2, configure el cliente con una política de compromiso que permita el descifrado tradicional:

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

Utilice esta configuración durante la migración cuando necesite descifrar objetos cifrados por clientes antiguos y, al mismo tiempo, garantizar que los nuevos objetos estén cifrados con mayor seguridad.

Configuración del método de almacenamiento

La versión 4 admite dos métodos de almacenamiento para los metadatos de cifrado. Elija el método que mejor se adapte a su caso de uso:

Metadatos de objetos (predeterminados)

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

Archivo de instrucciones

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

Úselo InstructionFile cuando necesite conservar los metadatos de los objetos para otros fines o cuando trabaje con objetos que tienen limitaciones de tamaño de los metadatos.

Configuración de la política de compromiso

Elija la política de compromiso adecuada en función de sus requisitos de seguridad y de la fase de migración:

Fase de migración (compatibilidad con la versión 2)

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

Fase de transición (recomendada)

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

Fase de seguridad total

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

Comience con ForbidEncryptAllowDecrypt la migración inicial, pase a la fase de transición y, RequireEncryptAllowDecrypt por último, utilícela RequireEncryptRequireDecrypt cuando todos los clientes se hayan actualizado y todos los objetos se hayan vuelto a cifrar con compromiso.