As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# Migração do cliente de criptografia Amazon S3 (V1 para V2) no AWS SDK para PHP Versão 3
<a name="s3-encryption-migration-v1-v2"></a>

**nota**  
Se você estiver usando a versão 2 (V2) do cliente de criptografia Amazon S3 e quiser migrar para a versão 3 (V3), consulte. [Migração do Amazon S3 Encryption Client (V2 para V3) no AWS SDK para PHP Versão 3](s3-encryption-migration-v2-v3.md)

Este tópico mostra como migrar as aplicações da versão 1 (V1) do cliente de criptografia do Amazon Simple Storage Service (Amazon S3) para a versão 2 (V2) e garantir a disponibilidade das aplicações durante todo o processo de migração.

## Visão geral da migração
<a name="migration-overview-v1-v2"></a>

Essa migração acontece em duas fases:

1. **Atualize os clientes existentes para ler novos formatos.** Primeiramente, implante a versão atualizada do AWS SDK para PHP na aplicação. Isso permite que os clientes de criptografia existentes da V1 descriptografem objetos escritos pelos novos clientes da V2. Se seu aplicativo usa vários AWS SDKs, você deve atualizar cada SDK separadamente.

2. **Migrar clientes de criptografia e descriptografia para a V2.** Depois que todos os seus clientes de criptografia da V1 puderem ler os novos formatos, você poderá migrar seus clientes de criptografia e descriptografia existentes para suas respectivas versões da V2.

## Atualizar os clientes existentes para ler novos formatos
<a name="update-existing-clients-to-read-new-formats-v1-v2"></a>

O cliente de criptografia da V2 usa algoritmos de criptografia incompatíveis com as versões mais antigas do cliente. A primeira etapa da migração é atualizar seus clientes de descriptografia da V1 para a versão mais recente do SDK. Depois de concluir essa etapa, os clientes V1 do seu aplicativo poderão descriptografar objetos criptografados por clientes de criptografia V2. Veja os detalhes abaixo para cada versão principal do AWS SDK para PHP.

### Atualizar AWS SDK para PHP Versão 3
<a name="upgrading-aws-sdk-for-php-version-3-v1-v2"></a>

A versão 3 é a mais recente do AWS SDK para PHP. Para concluir essa migração, é necessário usar a versão 3.148.0 ou posterior do pacote `aws/aws-sdk-php`.

 **Instalação pela linha de comando** 

Para projetos que foram instalados usando o Composer, no arquivo do Composer, atualize o pacote do SDK para a versão 3.148.0 do SDK e execute o comando a seguir.

```
composer update aws/aws-sdk-php
```

 **Instalação usando o arquivo Phar ou Zip** 

Use um dos métodos a seguir. Coloque o arquivo SDK atualizado no local exigido pelo código, que é determinado pela instrução da solicitação.

Para projetos que foram instalados usando o arquivo Phar, baixe o arquivo atualizado: [`aws.phar`](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar).

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

Para projetos que foram instalados usando o arquivo Zip, baixe o arquivo atualizado: [``](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip).

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

## Migrar clientes de criptografia e descriptografia para a V2
<a name="migrate-encryption-and-decryption-clients-to-v2-v1-v2"></a>

Depois de atualizar seus clientes para ler os novos formatos de criptografia, você pode atualizar suas aplicações para os clientes de criptografia e descriptografia da V2. As etapas a seguir mostram como migrar com sucesso seu código da V1 para a V2.

### Requisitos de atualização para clientes da V2
<a name="requirements-for-updating-to-v2-clients-v1-v2"></a>

1. O contexto de AWS KMS criptografia deve ser passado para `S3EncryptionClientV2::putObject` os `S3EncryptionClientV2::putObjectAsync` métodos e. AWS KMS o contexto de criptografia é uma matriz associativa de pares de valores-chave, que você deve adicionar ao contexto de criptografia para criptografia de chaves. AWS KMS Se nenhum contexto adicional for necessário, você poderá passar uma matriz vazia.

2. `@SecurityProfile` deve ser passado para os métodos `getObject` e `getObjectAsync` no `S3EncryptionClientV2`. `@SecurityProfile` é um novo parâmetro obrigatório dos métodos `getObject...`. Se definido como`'V2'`, somente objetos criptografados em V2-compatible formato podem ser descriptografados. Definir esse parâmetro para `'V2_AND_LEGACY'` também permite que objetos criptografados em V1-compatible formato sejam descriptografados. Para oferecer suporte à migração, defina `@SecurityProfile` como `'V2_AND_LEGACY'`. Use a `'V2'` somente para o desenvolvimento de novas aplicações.

3. (opcional) Inclua o parâmetro `@KmsAllowDecryptWithAnyCmk` no `S3EncryptionClientV2::getObject` e `S3EncryptionClientV2::getObjectAsync* methods.` Um novo parâmetro foi adicionado, chamado `@KmsAllowDecryptWithAnyCmk`. Defina esse parâmetro como `true` permitir a descriptografia sem fornecer uma chave do KMS. O valor padrão é `false`.

4. Para decodificação com um cliente da V2, se o parâmetro `@KmsAllowDecryptWithAnyCmk` não estiver definido como `true` para as chamadas do método `"getObject..."`, um `kms-key-id` deverá ser fornecido ao construtor de `KmsMaterialsProviderV2`.

## Exemplos de migração
<a name="migration-examples-v1-v2"></a>

### Exemplo 1: migração para clientes da 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',
    ])
);
```

### Exemplo 2: Usando AWS KMS com kms-key-id
<a name="example-2-using-kms-with-kms-key-id-v1-v2"></a>

**nota**  
Esses exemplos usam importações e variáveis definidas no Exemplo 1. Por exemplo, .`$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,
]);
```