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 de clientes de cifrado de Amazon S3 (de la V1 a la V2) en el AWS SDK para PHP Versión 3
<a name="s3-encryption-migration-v1-v2"></a>

**nota**  
Si utiliza la versión 2 (V2) del cliente de cifrado de Amazon S3 y desea migrar a la versión 3 (V3), consulte[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](s3-encryption-migration-v2-v3.md).

En este tema se muestra cómo migrar las aplicaciones de la versión 1 (V1) del cliente de cifrado Amazon Simple Storage Service (Amazon S3) a la versión 2 (V2) y cómo garantizar la disponibilidad de las aplicaciones durante todo el proceso de migración.

## Información general sobre la migración
<a name="migration-overview-v1-v2"></a>

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 de la versión V1 descifrar los objetos escritos por los nuevos clientes de la versión V2. Si su aplicación usa varios AWS SDK, debe actualizar cada SDK por separado.

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

## Actualizar los clientes existentes para leer nuevos formatos
<a name="update-existing-clients-to-read-new-formats-v1-v2"></a>

El cliente de cifrado de la versión V2 utiliza algoritmos de cifrado 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 V1 a la versión más reciente del SDK. Tras completar este paso, los clientes de la versión 1 de la aplicación podrán descifrar los objetos cifrados por los clientes de cifrado de la versión 2. A continuación puede consultar los detalles de cada versión principal de AWS SDK para PHP.

### Mejora AWS SDK para PHP Versión 3
<a name="upgrading-aws-sdk-for-php-version-3-v1-v2"></a>

La versión 3 es la versión más reciente de AWS SDK para PHP. Para completar la migración, debe utilizar la versión 3.148.0 o una posterior del paquete de `aws/aws-sdk-php`.

 **Instalación desde la línea de comandos** 

En el caso de los proyectos que se instalaron mediante Composer, en el archivo Composer, actualice el paquete del SDK a la versión 3.148.0 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`](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar).

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

Para proyectos que se instalaron mediante el archivo ZIP, descargue el archivo actualizado: [``](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip).

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

## Migrar clientes de cifrado y descifrado a la versión V2
<a name="migrate-encryption-and-decryption-clients-to-v2-v1-v2"></a>

Después de actualizar sus clientes para leer los nuevos formatos de cifrado, puede actualizar sus aplicaciones a la versión V2 de los clientes de cifrado y descifrado. En los siguientes pasos, se muestra cómo migrar correctamente el código de la versión V1 a la V2.

### Requisitos para actualizar a los clientes a la versión 2
<a name="requirements-for-updating-to-v2-clients-v1-v2"></a>

1. El contexto de AWS KMS cifrado debe pasarse a los `S3EncryptionClientV2::putObjectAsync` métodos `S3EncryptionClientV2::putObject` y. AWS KMS el contexto de cifrado es una matriz asociativa de pares clave-valor, que debe agregar al contexto de cifrado para el cifrado de claves. AWS KMS Si no se requiere ningún contexto adicional, puede pasar una matriz vacía.

2. `@SecurityProfile` se debe pasar a los métodos `getObject` y `getObjectAsync` en `S3EncryptionClientV2`. `@SecurityProfile`es un nuevo parámetro obligatorio de los métodos `getObject...`. Si se establece en`'V2'`, solo se pueden descifrar los objetos cifrados en V2-compatible formato. Si se establece este parámetro en, `'V2_AND_LEGACY'` también se pueden descifrar los objetos cifrados en V1-compatible formato. Para permitir la migración, establezca `@SecurityProfile` en `'V2_AND_LEGACY'`. Use `'V2'` solo para desarrollar nuevas aplicaciones.

3. (opcional) Incluya el parámetro `@KmsAllowDecryptWithAnyCmk` en `S3EncryptionClientV2::getObject` y `S3EncryptionClientV2::getObjectAsync* methods.` Se ha añadido un nuevo parámetro llamado `@KmsAllowDecryptWithAnyCmk`. Al establecer este parámetro en `true`, se habilita el descifrado sin necesidad de proporcionar una clave KMS. El valor predeterminado es `false`.

4. Para el descifrado con un cliente de la versión V2, si el parámetro `@KmsAllowDecryptWithAnyCmk` no está establecido en `true` para las llamadas al método `"getObject..."`, se debe proporcionar `kms-key-id` al constructor de `KmsMaterialsProviderV2`.

## Ejemplos de migración
<a name="migration-examples-v1-v2"></a>

### Ejemplo 1: Migración a clientes de la versión V2
<a name="example-1-migrating-to-v2-clients-v1-v2"></a>

 **Pre-migration** 

```
use Aws\S3\Crypto\S3EncryptionClient;
use Aws\S3\S3Client;

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

 **Post-migration** 

```
use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;

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

### Ejemplo 2: Uso AWS KMS con kms-key-id
<a name="example-2-using-kms-with-kms-key-id-v1-v2"></a>

**nota**  
En estos ejemplos se utilizan las importaciones y las variables definidas en el ejemplo 1. Por ejemplo, `$encryptionClient`.

 **Pre-migration** 

```
use Aws\Crypto\KmsMaterialsProvider;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProvider(
    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,
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

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

 **Post-migration** 

```
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

$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',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);
```