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 V3) dans le AWS SDK pour PHP Version 3

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 3 (V3) et garantir la disponibilité des applications tout au long du processus de migration. La version 3 introduit AES GCM avec un engagement clé et des politiques d'engagement pour renforcer la sécurité et protéger contre la falsification des clés de données.

Aperçu de la migration

Cette migration s'effectue en deux phases :

1. Mettez à jour les clients existants pour qu'ils puissent lire les nouveaux formats. Tout d'abord, déployez une version mise AWS SDK pour PHP à jour de celui-ci dans votre application. Cela permet aux clients de chiffrement V2 existants de déchiffrer les objets écrits par les nouveaux clients V3. Si votre application utilise plusieurs AWS kits de développement logiciel, vous devez les mettre à niveau séparément.

2. Migrez les clients de chiffrement et de déchiffrement vers la version V3. Une fois que tous vos clients de chiffrement V2 peuvent lire les nouveaux formats, vous pouvez migrer vos clients de chiffrement et de déchiffrement existants vers leurs versions V3 respectives.

Comprendre les concepts de la V3

La version 3 du client de chiffrement Amazon S3 introduit deux améliorations de sécurité clés : les politiques d'engagement et l'algorithme AES GCM avec Key Commitment. Il est essentiel de comprendre ces concepts pour réussir la migration.

Politique d'engagement

Une 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 version 3 propose trois options de politique :

AES GCM avec un engagement clé

L'algorithme AES GCM avec Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) est un nouvel algorithme de chiffrement introduit dans la version V3 qui fournit une protection contre les attaques par falsification des clés de données.

Amélioration de la sécurité : ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY protège contre la falsification des clés de données en liant cryptographiquement la clé de données au contenu chiffré. Cela empêche les attaquants de remplacer une clé de données différente lors du déchiffrement, ce qui pourrait entraîner le déchiffrement de données indésirables.

Compatibilité des versions : les objets chiffrés ne ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY peuvent être déchiffrés que par la version V3 et les dernières implémentations V2 du client de chiffrement Amazon S3. Les clients V1 ne peuvent pas déchiffrer les objets chiffrés avec cet algorithme.

Mettre à jour les clients existants pour lire les nouveaux formats

Le client de chiffrement V3 utilise des algorithmes de chiffrement et des fonctionnalités d'engagement clés que les anciennes versions du client ne prenaient pas en charge. La première étape de la migration consiste à mettre à jour vos clients de déchiffrement V2 vers la dernière version du SDK. Une fois cette étape terminée, les clients V2 de votre application seront en mesure de déchiffrer les objets chiffrés par les clients de chiffrement V3. Voir les détails ci-dessous pour chaque méthode d'installation du AWS SDK pour PHP.

Création et installation de la dernière version du SDK

Pour terminer cette migration, vous devez utiliser la dernière version du aws/aws-sdk-php package qui inclut la prise en charge du client de chiffrement V3.

Installation depuis Composer

Pour les projets installés à l'aide de Composer, dans le fichier Composer, mettez à jour le package SDK vers la dernière version du SDK, puis exécutez la commande suivante.

composer update aws/aws-sdk-php

Installation à l'aide du fichier Phar ou Zip

Utilisez l’une des méthodes suivantes. Veillez à placer le fichier SDK mis à jour à l'emplacement requis par votre code, qui est déterminé par l'instruction require.

Pour les projets installés à l'aide du fichier Phar, téléchargez le fichier mis à jour : aws.phar.

<?php
  require '/path/to/aws.phar';
?>

Pour les projets installés à l'aide du fichier Zip, téléchargez le fichier mis à jour : .

<?php
  require '/path/to/aws-autoloader.php';
?>

Création, installation et déploiement d'applications

Après la mise à jour du SDK, reconstruisez et redéployez votre application pour vous assurer que tous les composants utilisent la version mise à jour. Cette étape est essentielle pour garantir que vos clients V2 peuvent lire les objets chiffrés par les clients V3.

Suivez les procédures de déploiement standard de votre organisation pour déployer l'application mise à jour. Assurez-vous que toutes les instances de votre application sont mises à jour avant de procéder à la migration de vos clients de chiffrement et de déchiffrement vers la version V3.

Après le déploiement, vérifiez que votre application peut toujours déchiffrer les objets existants et qu'aucune erreur ne se produit pendant les opérations normales. Cela confirme que la mise à jour du SDK a été effectuée avec succès et que votre application est prête pour la prochaine phase de migration.

Migrer les clients de chiffrement et de déchiffrement vers la version V3

Après avoir mis à jour vos clients pour qu'ils puissent lire les nouveaux formats de chiffrement, vous pouvez mettre à jour vos applications vers les clients de chiffrement et de déchiffrement V3. Les exemples suivants vous montrent comment réussir la migration de votre code de la V2 vers la V3.

Utilisation de clients de chiffrement V3

La V3 introduit la S3EncryptionClientV3 classe et KmsMaterialsProviderV3 remplace les équivalents V2. Les principales différences de la V3 sont les suivantes :

Exemple : migration de la V2 vers la V3 avec KMS Encryption

Pre-migration (V2)

use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

$encryptionClient = new S3EncryptionClientV2(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV2(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@KmsAllowDecryptWithAnyCmk' => true,
   '@SecurityProfile' => 'V2_AND_LEGACY',
   '@CommitmentPolicy' => 'FORBID_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Pendant la migration (V3 avec rétrocompatibilité)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3_AND_LEGACY',
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Post-migration (V3 avec engagement clé)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;
 
// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   new KmsClient([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ]),
   $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
   'Cipher' => 'gcm',
   'KeySize' => 256,
];

$encryptionClient->putObject([
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3',
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

Principales différences dans la V3 :

Exemples supplémentaires

Les exemples suivants illustrent les options de configuration supplémentaires disponibles dans la version V3 qui peuvent vous aider à gérer le processus de migration et à contrôler le comportement de chiffrement.

Activation de la prise en charge de hérité

Au cours de la migration, vous devrez peut-être déchiffrer des objets chiffrés avec la version V1 ou la version 2 du client de chiffrement Amazon S3. Le @SecurityProfile paramètre contrôle les versions de chiffrement que votre client V3 peut déchiffrer.

Quand utiliser cette configuration : utilisez le profil 'V3_AND_LEGACY' de sécurité lorsque votre application doit lire des objets chiffrés par des clients V1 ou V2. Cela est courant pendant la période de migration, lorsque vous avez un mélange d'anciens et de nouveaux objets chiffrés dans vos compartiments.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$encryptionClient = new S3EncryptionClientV3(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

// Decrypt objects encrypted with V1, V2, or V3
$result = $encryptionClient->getObject([
    '@SecurityProfile' => 'V3_AND_LEGACY',
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);

Le paramètre @SecurityProfile accepte les valeurs suivantes :

Configuration de la méthode de stockage

Le client de chiffrement Amazon S3 peut stocker les métadonnées de chiffrement de deux manières : dans les en-têtes de métadonnées de l'objet ou dans un fichier d'instructions distinct. Le @MetadataStrategy paramètre contrôle la méthode de stockage utilisée.

Quand utiliser cette configuration : à utiliser 'INSTRUCTION_FILE' lorsque vous devez conserver les métadonnées d'origine de l'objet ou lorsque vous travaillez avec des objets dont la taille des métadonnées est limitée. Utilisez 'METADATA' (valeur par défaut) pour des déploiements plus simples dans lesquels les métadonnées de chiffrement peuvent être stockées à côté de l'objet.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$encryptionClient = new S3EncryptionClientV3(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

// Store encryption metadata in a separate instruction file
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'INSTRUCTION_FILE',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

// Store encryption metadata in object headers (default)
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'METADATA',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

Le paramètre @MetadataStrategy accepte les valeurs suivantes :