Migração do cliente de criptografia do Amazon S3 com o AWS SDK para PHP versão 3

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

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 a aplicação 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

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 da V1 da aplicação poderão descriptografar objetos criptografados por clientes de criptografia da V2. Veja os detalhes abaixo para cada versão principal do AWS SDK para PHP.

Upgrade do AWS SDK para PHP versão 3

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.

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

Para projetos que foram instalados usando o arquivo Zip, baixe o arquivo atualizado: .

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

Migrar clientes de criptografia e descriptografia para a V2

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

1. O contexto de criptografia do AWS KMS deve ser passado para os métodos S3EncryptionClientV2::putObject e S3EncryptionClientV2::putObjectAsync. O contexto de criptografia do AWS KMS é uma matriz associativa de pares de chave-valor, que você deve adicionar ao contexto de criptografia para criptografia de chaves do 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 formato compatível com a V2 podem ser descriptografados. Definir esse parâmetro como ‘V2_AND_LEGACY’ também permite que objetos criptografados em formato compatível com a V1 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

Exemplo 1: migração para clientes da V2

Pré-migração

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

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

Pós-migração

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

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

Exemplo 2: uso do AWS KMS com kms-key-id

Pré-migração

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

Pós-migração

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