php aws_Amazon S3 客户端加密与 AWS SDK for PHP 版本 3 - 适用于 PHP 的 AWS 开发工具包...

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon S3 客户端加密与 AWS SDK for PHP 版本 3

使用客户端加密，数据可在您的环境中直接加密和解密。这就意味着，数据在传输到 Amazon S3 之前已加密，您无需使用外部服务来处理加密。对于新实施,我们建议对弃用的

S3EncryptionClientV2 和 S3EncryptionMultipartUploaderV2 使用 S3EncryptionClient 和 S3EncryptionMultipartUploader。 建议旧实施仍使用弃用的版本尝试迁移。S3EncryptionClientV2 维护对解密使用旧 S3EncryptionClient 加密的数据的支持。

迁移指南

对于尝试从已弃用客户端迁移到新客户端的用户,此处提供了迁移指南。

Setup

要开始使用客户端加密，您需要：

运行任何示例代码之前，请配置您的 AWS 凭证。请参阅适用于 PHP 的 AWS 开发工具包版本 3 的凭证。

Encryption

在 S3EncryptionClientV2 中上传加密对象时,除了使用标准 PutObject 参数外,还需要使用三个其他参数:

'@KmsEncryptionContext' 是一个键/值对,可用于为加密对象添加额外的安全层。加密客户端必须传入同一密钥,它将自动在获取调用中传递该密钥。如果不需要其他上下文,则传入一个空数组。

@CipherOptions 是加密的其他配置,包括要使用的密码和密钥大小。

@MaterialsProvider 是处理密码密钥和初始化向量生成以及加密密钥的提供程序。

use Aws\S3\S3Client;

use Aws\S3\Crypto\S3EncryptionClientV2;

use Aws\Kms\KmsClient;

use Aws\Crypto\KmsMaterialsProviderV2;

// Let's construct our S3EncryptionClient using an S3Client

$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,

// Additional configuration options

];

$result = $encryptionClient->putObject([

'@MaterialsProvider' => $materialsProvider,

'@CipherOptions' => $cipherOptions,

'@KmsEncryptionContext' => ['context-key' => 'context-value'],

'Bucket' => $bucket,

'Key' => $key,

'Body' => fopen('file-to-encrypt.txt', 'r'),

]);

注意

如果 '@CipherOptions' 配置不正确，除了基于 Amazon S3 和 AWS KMS 的服务错误，您可能还会收到引发的 InvalidArgumentException 对象。

Decryption

下载和解密对象有四个附加参数,其中两个是必需的,以及标准 GetObject 参数。客户端将为您检测基本密码选项。

'@SecurityProfile': 如果设置为“V2”,则仅在与 V2 兼容的情况下加密的对象

格式可以解密。将此参数设置为“V2_AND_LEGACY”还允许解密以与 V1 兼容的格式加密的对象。要支持迁移,请将 @SecurityProfile 设置为“V2_AND_LEGACY”。仅将“V2”用于新应用程序开发。

'@MaterialsProvider' 是用于生成密码密钥和初始化向量的提供商,如

以及加密密钥。

'@KmsAllowDecryptWithAnyCmk':(可选)将此参数设置为 true 会启用解密

,但不向 MaterialsProvider 的构造函数提供 KMS 密钥 ID。 默认值为 false。

'@CipherOptions'(可选)是加密的其他配置,包括

要使用的密码和密钥大小。

$result = $encryptionClient->getObject([

'@KmsAllowDecryptWithAnyCmk' => true,

'@SecurityProfile' => 'V2_AND_LEGACY',

'@MaterialsProvider' => $materialsProvider,

'@CipherOptions' => $cipherOptions,

'Bucket' => $bucket,

'Key' => $key,

]);

注意

如果 '@CipherOptions' 配置不正确，除了基于 Amazon S3 和 AWS KMS 的服务错误，您可能还会收到引发的 InvalidArgumentException 对象。

密码配置

'Cipher'(字符串)

加密客户端在加密时使用的密码方法。目前仅支持“gcm”。

重要

PHP 在版本 7.1 中进行了更新,以包含使用 进行 GCM 加密加密时加密和OpenSSL解密所需的额外参数。对于 PHP 版本 7.0 及更早版本, S3EncryptionClientV2 和 S3EncryptionMultipartUploaderV2 加密客户端提供并使用 Polyfill for GCM 支持。 但是,使用 Polyfill 时,大型输入的性能要比使用 PHP 7.1 版以上的本机实现慢得多,因此,要有效地使用它们,可能需要升级较早的

PHP 版本环境。

'KeySize' (int)

生成的用于加密的内容加密密钥的长度。默认为 256 位。有效的配置选项为 256 位和 128 位。

'Aad'(字符串)

可添加到加密负载中的可选“附加身份验证数据”。解密时将验证此信息。Aad 仅在使用“gcm”密码时可用。

重要

并非所有 AWS SDKs都支持其他身份验证数据,因此,其他 SDKs 可能无法解密使用此参数加密的文件。

元数据策略

您还可以选择提供实现 Aws\Crypto\MetadataStrategyInterface 的类的实例。 这个简单的接口可保存和加载包含您的信封加密材料的 Aws\Crypto\MetadataEnvelope。开发工具包提供了两个类来实施此操作: Aws\S3\Crypto\HeadersMetadataStrategy 和 Aws\S3\Crypto\InstructionFileMetadataStrategy。默认情况下使用 HeadersMetadataStrategy。

$strategy = new InstructionFileMetadataStrategy(

$s3Client

);

$encryptionClient->putObject([

'@MaterialsProvider' => $materialsProvider,

'@MetadataStrategy' => $strategy,

'@KmsEncryptionContext' => [],

'@CipherOptions' => $cipherOptions,

'Bucket' => $bucket,

'Key' => $key,

'Body' => fopen('file-to-encrypt.txt', 'r'),

]);

$result = $encryptionClient->getObject([

'@KmsAllowDecryptWithAnyCmk' => false,

'@MaterialsProvider' => $materialsProvider,

'@SecurityProfile' => 'V2',

'@MetadataStrategy' => $strategy,

'@CipherOptions' => $cipherOptions,

'Bucket' => $bucket,

'Key' => $key,

]);

调用 ::class 也可提供 HeadersMetadataStrategy 和 InstructionFileMetadataStrategy 的类名常量。

$result = $encryptionClient->putObject([

'@MaterialsProvider' => $materialsProvider,

'@MetadataStrategy' => HeadersMetadataStrategy::class,

'@CipherOptions' => $cipherOptions,

'Bucket' => $bucket,

'Key' => $key,

'Body' => fopen('file-to-encrypt.txt', 'r'),

]);

注意

如果构造文件上传后发生错误，不会自动删除该文件。

分段上传

也可以利用客户端加密执行分段上传。在上传之前准备源流进行加密。Aws\S3\Crypto\S3EncryptionMultipartUploaderV2创建一个请求接受与使用 Aws\S3\MultipartUploader和 Aws\S3\Crypto\S3EncryptionClientV2 类似的体验。 可以处理与 S3EncryptionMultipartUploaderV2 相同的 '@MetadataStrategy' 选项以及所有可用的 S3EncryptionClientV2 配置。'@CipherOptions'

$kmsKeyId = 'kms-key-id';

$materialsProvider = new KmsMaterialsProviderV2(

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 S3EncryptionMultipartUploaderV2(

new S3Client([

'region' => 'us-east-1',

'version' => 'latest',

'profile' => 'default',

]),

fopen('large-file-to-encrypt.txt', 'r'),

[

'@MaterialsProvider' => $materialsProvider,

'@CipherOptions' => $cipherOptions,

'bucket' => $bucket,

'key' => $key,

]

);

$multipartUploader->upload();

注意

如果 '@CipherOptions' 配置不正确，除了基于 Amazon S3 和 AWS KMS 的服务错误，您可能还会收到引发的 InvalidArgumentException 对象。