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

Présentation de la migration

Cette migration s'effectue en deux phases :

1. Mettez à jour les clients existants pour lire les nouveaux formats. Déployez d'abord une version mise AWS SDK pour PHP à jour du 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 en utilise plusieurs AWS SDKs, vous devez mettre à niveau chaque SDK séparément.

2. Migrez les clients de chiffrement et de déchiffrement vers la version 3. 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 with Key Commitment. Comprendre ces concepts est essentiel pour une migration réussie.

Politique d'engagement

Une 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. La version 3 propose trois options stratégiques :

AES GCM avec un engagement clé

L'algorithme AES GCM with Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) est un nouvel algorithme de chiffrement introduit dans la version 3 qui fournit une protection contre les attaques de 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 crypté. Cela empêche les attaquants de substituer une clé de données différente lors du déchiffrement, ce qui pourrait entraîner le déchiffrement de données involontaires.

Compatibilité des versions : les objets chiffrés avec ne ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY peuvent être déchiffrés que par la version 3 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 prennent 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. Consultez 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 le support 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 du SDK avec 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 avoir mis à jour le 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 entreprise 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 3.

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

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

Après avoir mis vos clients à jour pour qu'ils lisent les nouveaux formats de chiffrement, vous pouvez mettre à jour vos applications pour les clients de chiffrement et de déchiffrement V3. Les exemples suivants vous montrent comment migrer avec succès votre code de la V2 à la V3.

Utilisation de clients de chiffrement V3

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

Exemple : migration de la V2 vers la V3 avec le chiffrement KMS

Pré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,
]);

Après la 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 3 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 les versions V1 ou V2 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 de 'V3_AND_LEGACY' 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 buckets.

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 : Utilisez-la 'INSTRUCTION_FILE' lorsque vous devez conserver les métadonnées d'origine de l'objet ou lorsque vous travaillez avec des objets soumis à des contraintes de taille de métadonnées. À utiliser 'METADATA' (par défaut) pour des déploiements plus simples où 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 :