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 del cliente de cifrado de Amazon S3 (V2 a V3) en la AWS SDK para PHP versión 3

En este tema se muestra cómo migrar las aplicaciones de la versión 2 (V2) del cliente de cifrado Amazon Simple Storage Service (Amazon S3) a la versión 3 (V3) y cómo garantizar la disponibilidad de las aplicaciones durante todo el proceso de migración. La versión 3 presenta el AES GCM con políticas clave de compromiso y compromiso para mejorar la seguridad y la protección contra la manipulación de las claves de datos.

Información general sobre la migración

Esta migración se produce en dos fases:

1. Actualice los clientes existentes para leer nuevos formatos. En primer lugar, implemente una versión actualizada de AWS SDK para PHP en su aplicación. Esto permite a los clientes de cifrado V2 existentes descifrar los objetos escritos por los nuevos clientes V3. Si su aplicación usa varios AWS SDKs, debe actualizar cada SDK por separado.

2. Migre los clientes de cifrado y descifrado a la versión 3. Una vez que todos sus clientes de cifrado V2 puedan leer nuevos formatos, puede migrar los clientes de cifrado y descifrado existentes a sus respectivas versiones V3.

Comprensión de los conceptos de la V3

La versión 3 del cliente de cifrado Amazon S3 presenta dos mejoras de seguridad clave: las políticas de compromiso y el algoritmo AES GCM con compromiso clave. Entender estos conceptos es esencial para una migración exitosa.

Política de compromiso

Una 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 3 ofrece tres opciones de política:

AES GCM con un compromiso clave

El algoritmo AES GCM con compromiso de clave (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) es un nuevo algoritmo de cifrado introducido en la versión 3 que proporciona protección contra los ataques de manipulación de las claves de datos.

Mejora de la seguridad: ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY protege contra la manipulación de las claves de datos al vincular criptográficamente la clave de datos al contenido cifrado. Esto evita que los atacantes sustituyan una clave de datos diferente durante el descifrado, lo que podría provocar el descifrado de datos no deseados.

Compatibilidad de versiones: los objetos cifrados con los que solo se ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY pueden descifrar con la versión 3 y las últimas implementaciones de la versión 2 del cliente de cifrado Amazon S3. Los clientes V1 no pueden descifrar los objetos cifrados con este algoritmo.

Actualizar los clientes existentes para leer nuevos formatos

El cliente de cifrado V3 utiliza algoritmos de cifrado y funciones de compromiso clave que las versiones anteriores del cliente no admiten. El primer paso de la migración consiste en actualizar los clientes de descifrado de la versión 2 a la versión más reciente del SDK. Tras completar este paso, los clientes V2 de su aplicación podrán descifrar los objetos cifrados por los clientes de cifrado V3. Consulte los detalles a continuación para ver cada método de instalación del. AWS SDK para PHP

Creación e instalación de la última versión del SDK

Para completar esta migración, debe usar la última versión del aws/aws-sdk-php paquete, que incluye la compatibilidad con el cliente de cifrado V3.

Instalación desde Composer

En el caso de los proyectos que se instalaron con Composer, en el archivo Composer, actualice el paquete del SDK a la última versión del SDK y, a continuación, ejecute el siguiente comando.

composer update aws/aws-sdk-php

Instalación con el archivo Phar o con el archivo ZIP

Utilice alguno de los métodos siguientes. Asegúrese de colocar el archivo SDK actualizado en la ubicación requerida por el código, que se determina mediante la instrucción require.

Para los proyectos que se instalaron mediante el archivo Phar, descargue el archivo actualizado: aws.phar.

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

Para proyectos que se instalaron mediante el archivo ZIP, descargue el archivo actualizado: .

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

Creación, instalación e implementación de aplicaciones

Tras actualizar el SDK, reconstruya y vuelva a implementar la aplicación para asegurarse de que todos los componentes utilizan la versión actualizada. Este paso es fundamental para garantizar que sus clientes de la versión 2 puedan leer los objetos cifrados por los clientes de la versión 3.

Siga los procedimientos de implementación estándar de su organización para implementar la aplicación actualizada. Asegúrese de que todas las instancias de su aplicación estén actualizadas antes de proceder a migrar sus clientes de cifrado y descifrado a la versión 3.

Tras la implementación, compruebe que la aplicación pueda seguir descifrando los objetos existentes y que no se produzcan errores durante las operaciones normales. Esto confirma que la actualización del SDK se ha realizado correctamente y que la aplicación está lista para la siguiente fase de migración.

Migre los clientes de cifrado y descifrado a la versión 3

Tras actualizar sus clientes para que lean los nuevos formatos de cifrado, puede actualizar sus aplicaciones a los clientes de cifrado y descifrado de la V3. Los siguientes ejemplos muestran cómo migrar correctamente el código de la V2 a la V3.

Uso de clientes de cifrado V3

La V3 introduce la S3EncryptionClientV3 clase y reemplaza KmsMaterialsProviderV3 a los equivalentes de la V2. Las principales diferencias en la V3 son:

Ejemplo: migración de la V2 a la V3 con cifrado KMS

Antes de la migración (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,
]);

Durante la migración (versión 3 con compatibilidad con versiones anteriores)

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

Después de la migración (versión 3 con un compromiso clave)

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

Diferencias clave en la V3:

Ejemplos adicionales

Los siguientes ejemplos muestran las opciones de configuración adicionales disponibles en la versión 3 que pueden ayudarle a gestionar el proceso de migración y controlar el comportamiento de cifrado.

Habilitación de la compatibilidad con heredado

Durante la migración, es posible que necesite descifrar los objetos que se cifraron con la versión 1 o la 2 del cliente de cifrado Amazon S3. El @SecurityProfile parámetro controla qué versiones de cifrado puede descifrar su cliente V3.

Cuándo utilizar esta configuración: utilice el perfil de 'V3_AND_LEGACY' seguridad cuando la aplicación necesite leer objetos cifrados por clientes V1 o V2. Esto es habitual durante el período de migración, cuando hay una mezcla de objetos cifrados antiguos y nuevos en los depósitos.

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

El parámetro @SecurityProfile acepta los siguientes valores:

Configurar el método de almacenamiento

El cliente de cifrado Amazon S3 puede almacenar los metadatos de cifrado de dos maneras: en los encabezados de metadatos del objeto o en un archivo de instrucciones independiente. El @MetadataStrategy parámetro controla el método de almacenamiento que se utiliza.

Cuándo usar esta configuración: utilícela 'INSTRUCTION_FILE' cuando necesite conservar los metadatos del objeto original o cuando trabaje con objetos que tienen restricciones de tamaño de los metadatos. 'METADATA'Utilícela (opción predeterminada) para implementaciones más sencillas en las que los metadatos de cifrado se puedan almacenar junto con el objeto.

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

El parámetro @MetadataStrategy acepta los siguientes valores: