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á.
# Criptografia do lado do cliente do Amazon S3 na versão 3 AWS SDK para PHP
Com a criptografia do lado do cliente, os dados são criptografados e descriptografados diretamente em seu ambiente. Isso significa que esses dados são criptografados antes de serem transferidos para o Amazon S3, e você não depende de um serviço externo para tratar da criptografia para você. Para novas implementações, sugerimos o uso de `S3EncryptionClientV3` e `S3EncryptionMultipartUploaderV3` sobre o `S3EncryptionClientV2` e `S3EncryptionMultipartUploaderV2` e o obsoleto e. `S3EncryptionClient` `S3EncryptionMultipartUploader` É recomendável que implementações mais antigas que ainda usam as versões obsoletas tentem migrar. O `S3EncryptionClientV3` mantém o suporte para descriptografar dados que foram criptografados usando o `S3EncryptionClient` legado.
O AWS SDK para PHP implementa a [criptografia de envelope e usa](https://docs.aws.amazon.com/kms/latest/developerguide/workflow.html) o [OpenSSL](https://www.openssl.org/) para criptografar e descriptografar. A implementação é interoperável com [outras SDKs que correspondam ao suporte de recursos](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html). Também é compatível com [o fluxo de trabalho assíncrono com base em promessa do SDK](guide_promises.md).
## Guia de migração
[Para aqueles que estão tentando migrar dos clientes obsoletos para os novos clientes, há um guia de migração para migrar da v1 para a v2 [aqui e um guia de migração para a v3 aqui](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-encryption-migration-v1-v2-section.html).](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-encryption-migration-v2-v3-section.html)
## Configuração
Para começar a usar a criptografia do lado do cliente, você precisa do seguinte:
+ Uma [chave de criptografia do AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)
+ Um [bucket do S3](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html)
Antes de executar qualquer código de exemplo, configure suas AWS credenciais. Consulte [Credenciais para a AWS SDK para PHP versão 3](guide_credentials.md).
## Criptografia
O upload de um objeto criptografado `S3EncryptionClientV3` usa quatro parâmetros adicionais além dos `PutObject` parâmetros padrão:
+ `'@KmsEncryptionContext'` é um par de chave-valor que pode ser usado para adicionar uma camada extra de segurança ao objeto criptografado. O cliente de criptografia deve passar a mesma chave, o que será feito automaticamente em uma chamada get. Se nenhum contexto adicional for desejado, passe uma matriz vazia.
+ `@CipherOptions` são configurações adicionais para a criptografia, incluindo qual cifra usar e o tamanho da chave.
+ `@MaterialsProvider` é um provedor que gerencia a geração de uma chave cifrada e um vetor de inicialização, além de criptografar sua chave cifrada.
+ `@CommitmentPolicy`é uma opção de política que determina como um objeto é lido com ou sem comprometimento chave e como um objeto é escrito com ou sem comprometimento chave.
```
use Aws\S3\S3Client;
use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\Kms\KmsClient;
use Aws\Crypto\KmsMaterialsProviderV3;
// Let's construct our S3EncryptionClient using an S3Client
$encryptionClient = new S3EncryptionClientV3(
new S3Client([
'profile' => 'default',
'region' => 'us-east-1',
'version' => 'latest',
])
);
$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,
// Additional configuration options
];
$result = $encryptionClient->putObject([
'@MaterialsProvider' => $materialsProvider,
'@CipherOptions' => $cipherOptions,
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
'@KmsEncryptionContext' => ['context-key' => 'context-value'],
'Bucket' => $bucket,
'Key' => $key,
'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
```
**nota**
Além dos erros de serviço AWS KMS baseados e do Amazon S3, você pode receber `InvalidArgumentException` objetos lançados se não `'@CipherOptions'` estiverem configurados corretamente.
## Descriptografia
Baixar e descriptografar um objeto tem cinco parâmetros adicionais, dois dos quais são obrigatórios, além dos parâmetros padrão. `GetObject` O cliente detectará as opções básicas de criptografia para você.
+
** `'@SecurityProfile'`: se definido como 'V3', somente objetos criptografados em compatibilidade com V3**
podem ser descriptografados. Definir esse parâmetro como 'V3\$1AND\$1LEGACY' também permite que objetos criptografados em formato compatível com V1 sejam descriptografados. Para oferecer suporte à migração, defina @ como SecurityProfile 'V3\$1AND\$1LEGACY'. Use 'V3' somente para o desenvolvimento de novos aplicativos.
+
** `'@MaterialsProvider'` é um provedor que gerencia a geração de uma chave cifrada e um vetor de inicialização, bem**
como criptografar sua chave cifrada.
+
** `'@KmsAllowDecryptWithAnyCmk'`: (opcional) definir esse parâmetro como verdadeiro permite a descriptografia**
sem fornecer um ID de chave KMS para o construtor do. MaterialsProvider O valor padrão é falso.
+
** `'@CipherOptions'` (opcional) são configurações adicionais para a criptografia, incluindo qual**
cifra a ser usada e o tamanho da chave.
+
** `@CommitmentPolicy`opção de política que determina como um objeto é lido com **
comprometimento chave ou sem comprometimento chave e como um objeto é escrito com ou sem comprometimento chave.
```
$result = $encryptionClient->getObject([
'@KmsAllowDecryptWithAnyCmk' => true,
'@SecurityProfile' => 'V2_AND_LEGACY',
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
'@MaterialsProvider' => $materialsProvider,
'@CipherOptions' => $cipherOptions,
'Bucket' => $bucket,
'Key' => $key,
]);
```
**nota**
Além dos erros de serviço AWS KMS baseados e do Amazon S3, você pode receber `InvalidArgumentException` objetos lançados se não `'@CipherOptions'` estiverem configurados corretamente.
## Configuração da criptografia
** `'Cipher'` (string)**
O método de codificação que o cliente de criptografia usa ao criptografar. Somente “gcm” é compatível no momento.
**Importante**
O PHP foi [atualizado na versão 7.1](http://php.net/manual/en/migration71.new-features.php) para incluir os parâmetros adicionais necessários para [criptografar](http://php.net/manual/en/function.openssl-encrypt.php) e [descriptografar](http://php.net/manual/en/function.openssl-decrypt.php) usando a criptografia do OpenSSL para GCM. Para as versões 7.0 e anteriores do PHP, um polyfill para suporte ao GCM é fornecido e usado pelos clientes de criptografia `S3EncryptionClientV2` e `S3EncryptionMultipartUploaderV2`. No entanto, o desempenho de entradas grandes será muito mais lento usando o polyfill do que usando a implementação nativa do PHP 7.1\$1, portanto, pode ser necessário atualizar ambientes de versões mais antigas do PHP para usá-los de forma eficaz.
** `'KeySize'` (int)**
O comprimento da chave de criptografia do conteúdo a ser gerada para a criptografia. O padrão é 256 bits. As opções de configuração válidas são 256 bits.
** `'Aad'` (string)**
'Additional authentication data - Dados de autenticação adicionais' opcionais a serem incluídos com seu conteúdo criptografado. Essas informações são validadas na descriptografia. O `Aad` está disponível somente ao usar o código "gcm".
**Importante**
Dados de autenticação adicionais não são suportados por todos AWS SDKs e, como tal, outros SDKs podem não conseguir descriptografar arquivos criptografados usando esse parâmetro.
## Estratégias de metadados
Você também tem a opção de fornecer uma instância de uma classe que implementa a `Aws\Crypto\MetadataStrategyInterface`. Essa interface simples lida com o salvamento e o carregamento do `Aws\Crypto\MetadataEnvelope` que contém o material da criptografia de envelope. O SDK fornece duas classes que implementam isso: `Aws\S3\Crypto\HeadersMetadataStrategy` e `Aws\S3\Crypto\InstructionFileMetadataStrategy`. A `HeadersMetadataStrategy` é usada por padrão.
```
$strategy = new InstructionFileMetadataStrategy(
$s3Client
);
$encryptionClient->putObject([
'@MaterialsProvider' => $materialsProvider,
'@MetadataStrategy' => $strategy,
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
'@KmsEncryptionContext' => [],
'@CipherOptions' => $cipherOptions,
'Bucket' => $bucket,
'Key' => $key,
'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
$result = $encryptionClient->getObject([
'@KmsAllowDecryptWithAnyCmk' => false,
'@MaterialsProvider' => $materialsProvider,
'@SecurityProfile' => 'V3',
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
'@MetadataStrategy' => $strategy,
'@CipherOptions' => $cipherOptions,
'Bucket' => $bucket,
'Key' => $key,
]);
```
Constantes de nomes de classe para `HeadersMetadataStrategy` e `InstructionFileMetadataStrategy` podem ser fornecidas chamando *::class*.
```
$result = $encryptionClient->putObject([
'@MaterialsProvider' => $materialsProvider,
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
'@MetadataStrategy' => HeadersMetadataStrategy::class,
'@CipherOptions' => $cipherOptions,
'Bucket' => $bucket,
'Key' => $key,
'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
```
**nota**
Se houver uma falha depois que um arquivo de instrução for carregado, ele não será excluído automaticamente.
## Carregamentos fracionados
A execução de um multipart upload com a criptografia do lado do cliente também é possível. O `Aws\S3\Crypto\S3EncryptionMultipartUploaderV3` prepara o fluxo de origem da criptografia antes do upload. A criação de um enfrenta uma experiência semelhante a usar o `Aws\S3\MultipartUploader` e o `Aws\S3\Crypto\S3EncryptionClientV3`. O `S3EncryptionMultipartUploaderV3` pode lidar com a mesma opção `'@MetadataStrategy'` que o `S3EncryptionClientV3`, bem como com todas as configurações disponíveis de `'@CipherOptions'`.
```
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
new KmsClient([
'region' => 'us-east-1',
'version' => 'latest',
'profile' => 'default',
]),
$kmsKeyId
);
$bucket = 'the-bucket-name';
$key = 'the-upload-key';
$cipherOptions = [
'Cipher' => 'gcm'
'KeySize' => 256,
// Additional configuration options
];
$multipartUploader = new S3EncryptionMultipartUploaderV3(
new S3Client([
'region' => 'us-east-1',
'version' => 'latest',
'profile' => 'default',
]),
fopen('large-file-to-encrypt.txt', 'r'),
[
'@MaterialsProvider' => $materialsProvider,
'@CipherOptions' => $cipherOptions,
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
'bucket' => $bucket,
'key' => $key,
]
);
$multipartUploader->upload();
```
**nota**
Além dos erros de serviço AWS KMS baseados e do Amazon S3, você pode receber `InvalidArgumentException` objetos lançados se não `'@CipherOptions'` estiverem configurados corretamente.