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

Pour plus d'informations sur l'interruption des modifications et la migration de vos applications, consultez la rubrique sur la migration.

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 S3 (V2 vers V4)

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

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

Comprendre les concepts de la V4

La version 4 utilise AES-GCM avec un engagement clé le cryptage du contenu et introduit des concepts de sécurité clés qui améliorent la protection de vos données crypté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 pendant les opérations de chiffrement et de déchiffrement. La V4 soutient trois politiques d'engagement :

AES GCM avec un engagement clé

La V4 utilise AES-GCM avec un engagement clé pour le cryptage du contenu, ce qui garantit une sécurité accrue :

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 prenaient 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 des NuGet packages

Mettez à jour vos applications pour utiliser la dernière version du Amazon.Extensions.S3.Encryption NuGet package qui inclut la prise en charge de la version 4. Effectuez les étapes suivantes pour chacune de vos applications :

Vos clients V2 existants continueront à 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éez et déployez des applications

Après avoir mis à jour les dépendances de vos NuGet packages :

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 pour 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 actuelle de votre client V2. 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 ForbidEncryptAllowDecrypt politique pour chiffrer sans engagement et autoriser 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.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
});

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

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

Commencez à chiffrer en utilisant l'engagement des clés tout en maintenant la rétrocompatibilité pour le déchiffrement. Cette étape utilise une RequireEncryptAllowDecrypt 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.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
});

Comportement : chiffre avec engagement, peut déchiffrer à la fois les objets en cours de validation et les objets qui ne le sont pas. Les nouveaux objets sont protégés contre les attaques par substitution de touches.

Étape 3 : V4 avec application complète

Exiger un engagement clé pour le chiffrement et le déchiffrement. Cette étape utilise une RequireEncryptRequireDecrypt 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.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
});

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 de configuration de clients V4 avec différentes options lors de la migration.

Activer 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(SecurityProfile.V4AndLegacy, CommitmentPolicy.RequireEncryptAllowDecrypt)
{
    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 d'anciens clients 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 version 4 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 de l'objet (par défaut)

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

Fichier d'instructions

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

À utiliser InstructionFile lorsque vous devez conserver les métadonnées des 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(SecurityProfile.V4, CommitmentPolicy.ForbidEncryptAllowDecrypt);

Phase de transition (recommandée)

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

Phase de sécurité complète

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

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