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.
# Cifrado del lado del cliente de Amazon S3 en la AWS SDK para PHP versión 3
Con el cifrado en el lado del cliente, los datos se cifran y se descifran directamente en su entorno. Esto significa que estos datos se cifran antes de transferirse a Amazon S3 y, por lo tanto, no tendrá que confiar en un servicio externo que gestione el cifrado. Para las nuevas implementaciones, sugerimos el uso de `S3EncryptionClientV3` y `S3EncryptionMultipartUploaderV3` over the `S3EncryptionClientV2` and `S3EncryptionMultipartUploaderV2` y el obsoleto `S3EncryptionClient` y. `S3EncryptionMultipartUploader` It is recommendSe recomienda que las implementaciones más antiguas que aún utilicen las versiones obsoletas intenten migrar. `S3EncryptionClientV3` mantiene la compatibilidad con el descifrado de datos cifrados mediante `S3EncryptionClient`.
AWS SDK para PHP Implementa el [cifrado de sobres](https://docs.aws.amazon.com/kms/latest/developerguide/workflow.html) y utiliza [OpenSSL](https://www.openssl.org/) para su cifrado y descifrado. La implementación es interoperable con [otras compatibles con sus funciones SDKs ](https://docs.aws.amazon.com/general/latest/gr/aws_sdk_cryptography.html). También es compatible con el [flujo de trabajo asíncrono basado en promesas del SDK](guide_promises.md).
## Guía de migración
[Para aquellos que estén intentando migrar de los clientes obsoletos a los nuevos, aquí encontrará una guía de migración para migrar de la versión 1 a la versión 2 y una guía de migración para pasar de la versión 2 a la versión 3 [aquí](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)
## Configuración
Para comenzar a utilizar el cifrado del lado del cliente, necesita lo siguiente:
+ Una [clave de cifrado de AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)
+ Un [bucket de S3](https://docs.aws.amazon.com/AmazonS3/latest/gsg/CreatingABucket.html)
Antes de ejecutar cualquier código de ejemplo, configure sus credenciales. AWS Consulte [Credenciales para la AWS SDK para PHP versión 3](guide_credentials.md).
## Cifrado
La carga de un objeto cifrado `S3EncryptionClientV3` requiere cuatro parámetros adicionales además de los `PutObject` parámetros estándar:
+ `'@KmsEncryptionContext'` es un par clave-valor que puede utilizarse para añadir una capa adicional de seguridad a su objeto encriptado. El cliente de cifrado tiene que introducir la misma clave, lo que hará automáticamente al recibir una llamada. Si no se necesita ningún contexto adicional, introduzca una matriz vacía.
+ `@CipherOptions` son configuraciones adicionales para el cifrado, incluyendo qué cifrado usar y el tamaño de la clave.
+ `@MaterialsProvider` es un proveedor que se encarga de generar una clave de cifrado y un vector de inicialización, así como de cifrar su clave de cifrado.
+ `@CommitmentPolicy`es una opción política que dicta cómo se lee un objeto con o sin compromiso clave y cómo se escribe un objeto con compromiso clave o sin compromiso clave.
```
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**
Además de los errores de Amazon S3 y del servicio AWS KMS basado, es posible que reciba `InvalidArgumentException` objetos `'@CipherOptions'` lanzados si no está configurado correctamente.
## Descifrado
La descarga y el descifrado de un objeto tienen cinco parámetros adicionales, dos de los cuales son obligatorios, además de los `GetObject` parámetros estándar. El cliente detectará las opciones de cifrado básicas por usted.
+
** `'@SecurityProfile'`: Si se establece en «V3», solo los objetos que estén cifrados son compatibles con la versión 3**
el formato se puede descifrar. Si se establece este parámetro en «V3\$1AND\$1LEGACY», también se pueden descifrar los objetos cifrados en un formato compatible con la V1. Para permitir la migración, defina @ en «V3\$1AND\$1LEGACY». SecurityProfile Utilice «V3» únicamente para el desarrollo de nuevas aplicaciones.
+
** `'@MaterialsProvider'` es un proveedor que se encarga de generar una clave de cifrado y un vector de inicialización, como**
así como de cifrar su clave de cifrado.
+
** `'@KmsAllowDecryptWithAnyCmk'`: (opcional) Establecer este parámetro en true habilita el descifrado**
sin proporcionar un identificador de clave KMS al constructor del MaterialsProvider. El valor predeterminado es false.
+
** `'@CipherOptions'` (opcional) son configuraciones adicionales para la encriptación incluyendo que**
el cifrado que se va a utilizar y el tamaño de la clave.
+
** `@CommitmentPolicy`opción de política que dicta cómo se lee un objeto, ya sea con **
compromiso clave o sin compromiso clave y cómo se escribe un objeto con compromiso clave o sin compromiso clave.
```
$result = $encryptionClient->getObject([
'@KmsAllowDecryptWithAnyCmk' => true,
'@SecurityProfile' => 'V2_AND_LEGACY',
'@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
'@MaterialsProvider' => $materialsProvider,
'@CipherOptions' => $cipherOptions,
'Bucket' => $bucket,
'Key' => $key,
]);
```
**nota**
Además de los errores de Amazon S3 y del servicio AWS KMS basado, es posible que reciba `InvalidArgumentException` objetos `'@CipherOptions'` lanzados si no está configurado correctamente.
## Configuración de Cipher
** `'Cipher'` (cadena)**
Es el método Cipher que utiliza el cliente para cifrar. Por el momento, solo se admite “gcm".
**importante**
PHP se [ha actualizado a la versión 7.1](http://php.net/manual/en/migration71.new-features.php) para incluir los parámetros adicionales necesarios para [cifrar](http://php.net/manual/en/function.openssl-encrypt.php) y [descifrar](http://php.net/manual/en/function.openssl-decrypt.php) mediante el cifrado OpenSSL para GCM. En las versiones 7.0 y anteriores de PHP, los clientes de cifrado `S3EncryptionClientV2` y `S3EncryptionMultipartUploaderV2` las utilizan un polyfill para soportar GCM. Sin embargo, el rendimiento con entradas de gran tamaño será mucho más lento si se utiliza el polyfill que si se utiliza la implementación nativa de PHP 7.1 o versiones posteriores, por lo que puede ser necesario actualizar los entornos de la versión de PHP anteriores para que funcionen correctamente.
** `'KeySize'` (int)**
Es la longitud de la clave de cifrado del contenido que se genera para el cifrado. La opción por defecto son 256 bits. Las opciones de configuración válidas son de 256 bits.
** `'Aad'` (cadena)**
Son datos de autenticación adicionales que se incluyen en la carga cifrada. Esta información se valida en el descifrado. `Aad` solo está disponible cuando se utiliza el cifrado “gcm”.
**importante**
No todos admiten datos de autenticación adicionales AWS SDKs y, por lo tanto, es SDKs posible que otras personas no puedan descifrar los archivos cifrados con este parámetro.
## Estrategias de metadatos
También tiene la opción de proporcionar una instancia de una clase que implementa `Aws\Crypto\MetadataStrategyInterface`. Esta interfaz sencilla gestiona la grabación y la carga de `Aws\Crypto\MetadataEnvelope` que contiene sus materiales de cifrado de sobres. El SDK proporciona dos clases que implementan lo siguiente: `Aws\S3\Crypto\HeadersMetadataStrategy` y `Aws\S3\Crypto\InstructionFileMetadataStrategy`. `HeadersMetadataStrategy` se utiliza de forma predeterminada.
```
$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,
]);
```
Las constantes del nombre de la clase de `HeadersMetadataStrategy` y `InstructionFileMetadataStrategy` también se pueden suministrar invocando *::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**
Si se produce un error después cargar un archivo de instrucciones, no se eliminará automáticamente.
## Cargas multiparte
También se puede realizar una carga multiparte con el cifrado del lado del cliente. El `Aws\S3\Crypto\S3EncryptionMultipartUploaderV3` prepara el flujo de origen para el cifrado antes de cargarlo. Su creación es similar al uso de `Aws\S3\MultipartUploader` y `Aws\S3\Crypto\S3EncryptionClientV3`. `S3EncryptionMultipartUploaderV3` puede gestionar la misma opción `'@MetadataStrategy'` que `S3EncryptionClientV3`, así como todas las configuraciones `'@CipherOptions'` disponibles.
```
$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**
Además de los errores de Amazon S3 y del servicio AWS KMS basado, es posible que reciba `InvalidArgumentException` objetos `'@CipherOptions'` lanzados si no está configurado correctamente.