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 (V2 para V3) na versão 3 AWS SDK para PHP

Este tópico mostra como migrar seus aplicativos da versão 2 (V2) do cliente de criptografia Amazon Simple Storage Service (Amazon S3) para a versão 3 (V3) e garantir a disponibilidade dos aplicativos durante todo o processo de migração. A versão 3 apresenta o AES GCM com as principais políticas de compromisso e compromisso para aprimorar a segurança e proteger contra a adulteração de chaves de dados.

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 V2 existentes descriptografem objetos escritos pelos novos clientes V3. Se seu aplicativo usa vários AWS SDKs, você deve atualizar cada SDK separadamente.

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

Entendendo os conceitos da V3

A versão 3 do cliente de criptografia Amazon S3 apresenta dois principais aprimoramentos de segurança: políticas de compromisso e o algoritmo AES GCM com compromisso de chave. Compreender esses conceitos é essencial para uma migração bem-sucedida.

Política de compromisso

Uma política de compromisso controla como o cliente de criptografia lida com o comprometimento da chave durante as operações de criptografia e descriptografia. A versão 3 fornece três opções de política:

AES GCM com compromisso fundamental

O algoritmo AES GCM with Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) é um novo algoritmo de criptografia introduzido na V3 que fornece proteção contra ataques de adulteração de chaves de dados.

Aprimoramento da segurança: ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY protege contra a adulteração da chave de dados vinculando criptograficamente a chave de dados ao conteúdo criptografado. Isso evita que os invasores substituam uma chave de dados diferente durante a descriptografia, o que pode levar à decodificação de dados não intencionais.

Compatibilidade de versão: objetos criptografados só ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY podem ser descriptografados pela V3 e pelas implementações mais recentes da V2 do cliente de criptografia Amazon S3. Os clientes V1 não podem descriptografar objetos criptografados com esse algoritmo.

Atualizar os clientes existentes para ler novos formatos

O cliente de criptografia V3 usa algoritmos de criptografia e os principais recursos de comprometimento que as versões mais antigas do cliente não suportam. A primeira etapa da migração é atualizar seus clientes de descriptografia V2 para a versão mais recente do SDK. Depois de concluir essa etapa, os clientes V2 do seu aplicativo poderão descriptografar objetos criptografados por clientes de criptografia V3. Veja os detalhes abaixo para cada método de instalação do AWS SDK para PHP.

Criando e instalando a versão mais recente do SDK

Para concluir essa migração, você deve usar a versão mais recente do aws/aws-sdk-php pacote que inclui suporte ao cliente de criptografia V3.

Instalando a partir do Composer

Para projetos que foram instalados usando o Composer, no arquivo Composer, atualize o pacote SDK para a versão mais recente 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';
?>

Construindo, instalando e implantando aplicativos

Depois de atualizar o SDK, reconstrua e reimplante seu aplicativo para garantir que todos os componentes estejam usando a versão atualizada. Essa etapa é fundamental para garantir que seus clientes V2 possam ler objetos criptografados por clientes V3.

Siga os procedimentos de implantação padrão da sua organização para implantar o aplicativo atualizado. Certifique-se de que todas as instâncias do seu aplicativo estejam atualizadas antes de prosseguir com a migração dos clientes de criptografia e descriptografia para a V3.

Após a implantação, verifique se seu aplicativo ainda pode descriptografar objetos existentes e se nenhum erro ocorre durante as operações normais. Isso confirma que a atualização do SDK foi bem-sucedida e que seu aplicativo está pronto para a próxima fase da migração.

Migre clientes de criptografia e descriptografia para a V3

Depois de atualizar seus clientes para ler os novos formatos de criptografia, você pode atualizar seus aplicativos para os clientes de criptografia e descriptografia V3. Os exemplos a seguir mostram como migrar com sucesso seu código da V2 para a V3.

Usando clientes de criptografia V3

V3 introduz a S3EncryptionClientV3 classe e substitui KmsMaterialsProviderV3 os equivalentes V2. As principais diferenças na V3 são:

Exemplo: migração da V2 para a V3 com criptografia KMS

Pré-migração (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 a migração (V3 com compatibilidade com versões 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,
]);

Pós-migração (V3 com compromisso fundamental)

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

Principais diferenças na V3:

Exemplos adicionais

Os exemplos a seguir demonstram opções de configuração adicionais disponíveis na V3 que podem ajudá-lo a gerenciar o processo de migração e controlar o comportamento da criptografia.

Habilitar o suporte ao herdado

Durante a migração, talvez seja necessário descriptografar objetos que foram criptografados com V1 ou V2 do cliente de criptografia Amazon S3. O @SecurityProfile parâmetro controla quais versões de criptografia seu cliente V3 pode descriptografar.

Quando usar essa configuração: use o perfil 'V3_AND_LEGACY' de segurança quando seu aplicativo precisar ler objetos criptografados por clientes V1 ou V2. Isso é comum durante o período de migração, quando você tem uma mistura de objetos criptografados antigos e novos em seus buckets.

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

O parâmetro @SecurityProfile aceita os seguintes valores:

Configurando o método de armazenamento

O cliente de criptografia Amazon S3 pode armazenar metadados de criptografia de duas maneiras: nos cabeçalhos de metadados do objeto ou em um arquivo de instruções separado. O @MetadataStrategy parâmetro controla qual método de armazenamento é usado.

Quando usar essa configuração: use 'INSTRUCTION_FILE' quando precisar preservar os metadados do objeto original ou ao trabalhar com objetos que tenham restrições de tamanho de metadados. Use 'METADATA' (o padrão) para implantações mais simples, nas quais os metadados de criptografia podem ser armazenados junto com o 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'),
]);

O parâmetro @MetadataStrategy aceita os seguintes valores: