La version 4 (V4) du AWS SDK pour .NET est sortie !

Pour commencer à utiliser la nouvelle version du SDK, consultez le guide du développeur AWS SDK pour .NET (V4), en particulier la rubrique relative à la migration vers la version 4.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Migration du client de chiffrement Amazon S3 (V2 vers V4)

Cette rubrique explique comment migrer vos applications de la version 2 (V2) du client de chiffrement Amazon Simple Storage Service (Amazon S3) vers la version 4 (V4) et comment garantir la disponibilité des applications tout au long du processus de migration. La V4 utilise l'AES-GCM avec un engagement clé pour le chiffrement du contenu et introduit des politiques d'engagement pour améliorer la sécurité contre les attaques par substitution de clés.

Le client V4 est disponible dans le package NuGet Amazon.Extensions.S3.Encryption.

Comprendre les concepts de la V4

La V4 utilise l'AES-GCM avec un engagement clé en matière de chiffrement de contenu et introduit des concepts de sécurité clés qui améliorent la protection de vos données chiffrées :

Politique d'engagement

La politique d'engagement contrôle la manière dont le client de chiffrement gère l'engagement des clés lors des opérations de chiffrement et de déchiffrement. V4 soutient trois politiques d'engagement :

AES GCM avec un engagement clé

La V4 utilise l'AES-GCM avec un engagement clé pour le chiffrement du contenu, ce qui améliore la sécurité :

Mettre à jour les clients existants pour lire les formats V4

Le client de chiffrement V4 utilise des algorithmes de chiffrement que les anciennes versions du client ne prennent pas en charge. La première étape de la migration consiste à mettre à jour vos clients V2 afin qu'ils puissent lire le nouveau format V4.

Mettre à jour les dépendances NuGet du package

Mettez à jour vos applications pour utiliser la dernière version du package Amazon.Extensions.S3.Encryption NuGet qui inclut le support V4. Effectuez les étapes suivantes sur chacune de vos applications :

Vos clients V2 existants continueront de fonctionner avec le package mis à jour et pourront déchiffrer les objets chiffrés par les clients V4 (en fonction de la politique d'engagement utilisée).

Création et déploiement d'applications

Après avoir mis à jour les dépendances de votre NuGet package :

Cette mise à jour permet à vos clients V2 existants de déchiffrer les objets qui seront chiffrés par les clients V4, garantissant ainsi la compatibilité pendant le processus de migration.

Migrer vers des clients V4

Après avoir mis à jour vos clients existants pour lire le nouveau format de chiffrement, vous pouvez procéder à la mise à jour sécurisée de vos applications afin d'utiliser les clients de chiffrement et de déchiffrement V4. Le client V4 fournit une sécurité renforcée grâce à un engagement clé tout en maintenant la compatibilité avec les objets chiffrés existants.

Processus de migration en 4 étapes

La migration de la V2 vers la V4 suit un processus structuré en 4 étapes pour garantir la compatibilité et la sécurité. Chaque étape représente une configuration spécifique qui doit être déployée dans toutes vos applications avant de passer à l'étape suivante.

Étape 0 : Client V2 (point de départ)

Cela représente la configuration de votre client V2 existante. Cette étape montre l'état de départ avant la migration.

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

Étape 1 : compatibilité V4 avec V2

Migrez vers le client V4 tout en conservant un comportement identique à celui de la V2. Cette étape utilise une FORBID_ENCRYPT_ALLOW_DECRYPT politique pour chiffrer sans engagement et permettre le déchiffrement de tous les objets.

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

Comportement : chiffre sans engagement, peut déchiffrer à la fois les objets validants et non validants. Comportement identique à celui de la V2.

Étape 2 : V4 avec des écritures d'engagement clés

Commencez à chiffrer avec un engagement clé tout en maintenant la rétrocompatibilité pour le déchiffrement. Cette étape utilise REQUIRE_ENCRYPT_ALLOW_DECRYPT la politique.

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

Comportement : chiffre avec engagement, permet de déchiffrer à la fois les objets validants et non validants. Les nouveaux objets sont protégés contre les attaques de substitution de clés.

Étape 3 : V4 avec mise en œuvre complète

Exigez un engagement clé pour le chiffrement et le déchiffrement. Cette étape utilise une REQUIRE_ENCRYPT_REQUIRE_DECRYPT politique pour une sécurité maximale.

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

Comportement : chiffre avec engagement, déchiffre uniquement les objets chiffrés avec engagement. Sécurité maximale contre les attaques par substitution de clés.

Exemples de configuration supplémentaires

Cette section fournit des exemples supplémentaires pour configurer les clients V4 avec différentes options lors de la migration.

Permettre le support existant

Pour permettre aux clients V4 de lire les objets chiffrés par les clients V1 et V2, configurez le client avec une politique d'engagement qui autorise le déchiffrement traditionnel :

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

Utilisez cette configuration lors de la migration lorsque vous devez déchiffrer des objets chiffrés par des clients plus anciens tout en vous assurant que les nouveaux objets sont chiffrés avec une sécurité renforcée.

Configuration de la méthode de stockage

La V4 prend en charge deux méthodes de stockage pour les métadonnées de chiffrement. Choisissez la méthode qui convient le mieux à votre cas d'utilisation :

Métadonnées d'objet (par défaut)

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

Fichier d'instructions

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

À utiliser InstructionFile lorsque vous devez conserver les métadonnées d'objets à d'autres fins ou lorsque vous travaillez avec des objets dont la taille des métadonnées est limitée.

Configuration de la politique d'engagement

Choisissez la politique d'engagement appropriée en fonction de vos exigences de sécurité et de la phase de migration :

Phase de migration (compatibilité V2)

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

Phase de transition (recommandée)

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

Phase de sécurité complète

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

Commencez par FORBID_ENCRYPT_ALLOW_DECRYPT la migration initiale, passez à la phase REQUIRE_ENCRYPT_ALLOW_DECRYPT de transition, puis utilisez-la REQUIRE_ENCRYPT_REQUIRE_DECRYPT lorsque tous les clients ont été mis à niveau et que tous les objets ont été rechiffrés avec engagement.