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 (de la versión 2 a la versión 3) en 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 AES GCM con políticas de compromiso y compromiso clave para mejorar la seguridad y proteger 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 SDK, debe actualizar cada SDK por separado.

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

Comprender los conceptos de la V3

La versión 3 del cliente de cifrado de Amazon S3 presenta dos mejoras de seguridad clave: las políticas de compromiso y el AES GCM con el algoritmo de compromiso clave. Comprender 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 la confirmación de las 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 AES GCM con el algoritmo Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) es un nuevo algoritmo de cifrado introducido en la versión 3 que brinda protección contra los ataques de manipulación de 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 solo ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY pueden descifrarse con la versión 3 y las implementaciones más recientes de la versión 2 del cliente de cifrado de Amazon S3. Los clientes de la versión 1 no pueden descifrar 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 confirmación de claves 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 conocer cada método de instalación del. AWS SDK para PHP

Creación e instalación de la versión más reciente del SDK

Para completar esta migración, debe usar la versión más reciente 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, actualiza el paquete del SDK a la versión más reciente del SDK y, a continuación, ejecuta 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 V2 puedan leer los objetos cifrados por los clientes de la V3.

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 V3.

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

Migre los clientes de cifrado y descifrado a la V3

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 versión 3. 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 presenta la S3EncryptionClientV3 clase y reemplaza KmsMaterialsProviderV3 a los equivalentes de la V2. Las principales diferencias en la V3 son:

Ejemplo: migración de la versión 2 a la versión 3 con el cifrado KMS

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

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

Post-migration (V3 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 V3 que pueden ayudarlo a administrar 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 de 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 los clientes V1 o V2. Esto es habitual durante el período de migración, cuando tienes una combinación de objetos cifrados antiguos y nuevos en tus 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:

Configuración del método de almacenamiento

El cliente de cifrado de 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 originales del objeto o cuando trabaje con objetos que tengan restricciones de tamaño de metadatos. 'METADATA'Utilícela (la 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: