适用于 PHP 的 AWS 开发工具包
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用AWS SDK for PHP版本 3 进行的 Amazon S3 客户端加密

AWS SDK for PHP提供一个 S3EncryptionClient。使用客户端加密,数据可在您的环境中直接加密和解密。这就意味着,数据在传输到 Amazon S3 之前已加密,您无需依靠外部服务处理加密。

AWS SDK for PHP实施信封加密,并使用 OpenSSL 进行加密和解密。此实施可与匹配其功能支持的其他开发工具包实现互操作。它还与开发工具包基于 Promise 的异步工作流程相兼容。

设置

要开始使用客户端加密,您需要:

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

加密

通过 PutObject 操作上传加密对象具有类似的界面,需要两个新参数。

use Aws\S3\S3Client; use Aws\S3\Crypto\S3EncryptionClient; use Aws\Kms\KmsClient; use Aws\Crypto\KmsMaterialsProvider; // Let's construct our S3EncryptionClient using an S3Client $encryptionClient = new S3EncryptionClient( new S3Client([ 'profile' => 'default', 'region' => 'us-east-1', 'version' => 'latest', ]) ); $kmsKeyArn = 'arn-to-the-kms-key'; // This materials provider handles generating a cipher key and // initialization vector, as well as encrypting your cipher key via AWS KMS $materialsProvider = new KmsMaterialsProvider( new KmsClient([ 'profile' => 'default', 'region' => 'us-east-1', 'version' => 'latest', ]), $kmsKeyArn ); $bucket = 'the-bucket-name'; $key = 'the-file-name'; $cipherOptions = [ 'Cipher' => 'gcm', 'KeySize' => 256, // Additional configuration options ]; $result = $encryptionClient->putObject([ '@MaterialsProvider' => $materialsProvider, '@CipherOptions' => $cipherOptions, 'Bucket' => $bucket, 'Key' => $key, 'Body' => fopen('file-to-encrypt.txt', 'r'), ]);

注意

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

解密

下载和解密对象需要为 GetObject 添加另外一个参数,客户端可以为您检测基本密码选项。解密的其他配置选项可传递。

$result = $encryptionClient->getObject([ '@MaterialsProvider' => $materialsProvider, '@CipherOptions' => [ // Additional configuration options ], 'Bucket' => $bucket, 'Key' => $key, ]);

注意

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

密码配置

'Cipher' (string)

加密客户端在加密时使用的密码方法。目前只支持 'gcm' 和 'cbc'。

重要

PHP 通过版本 7.1 的更新包含了额外的参数,在使用 OpenSSL 进行 GCM 加密时,这些参数对于加密解密是必要的。因此,将 GCM 与 Aws\S3\Crypto\S3EncryptionClient 配合使用只适用于 PHP 7.1 或更高版本。

'KeySize' (int)

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

'Aad' (string)

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

元数据策略

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

$strategy = new InstructionFileMetadataStrategy( $s3Client, '.instr' ); $result = $encryptionClient->putObject([ '@MaterialsProvider' => $materialsProvider, '@MetadataStrategy' => $strategy, '@CipherOptions' => $cipherOptions, 'Bucket' => $bucket, 'Key' => $key, 'Body' => fopen('file-to-encrypt.txt'), ]);

调用 ::class 也可提供 HeadersMetadataStrategyInstructionFileMetadataStrategy 的类名常量。

$result = $encryptionClient->putObject([ '@MaterialsProvider' => $materialsProvider, '@MetadataStrategy' => HeadersMetadataStrategy::class, '@CipherOptions' => $cipherOptions, 'Bucket' => $bucket, 'Key' => $key, 'Body' => fopen('file-to-encrypt.txt'), ]);

注意

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

分段上传

也可以利用客户端加密执行分段上传。Aws\S3\Crypto\S3EncryptionMultipartUploader 会在上传之前准备用于加密的源流。使用 Aws\S3\MultipartUploaderAws\S3\Crypto\S3EncryptionClient 创建的过程也与此类似。S3EncryptionMultipartUploader 能以与 '@MetadataStrategy' 相同的方式处理 S3EncryptionClient 选项,以及所有可用的 '@CipherOptions' 配置。

$kmsKeyArn = 'arn-to-the-kms-key'; // This materials provider handles generating a cipher key and // initialization vector, as well as encrypting your cipher key via AWS KMS $materialsProvider = new KmsMaterialsProvider( new KmsClient([ 'region' => 'us-east-1', 'version' => 'latest', 'profile' => 'default', ]), $kmsKeyArn ); $bucket = 'the-bucket-name'; $key = 'the-upload-key'; $cipherOptions = [ 'Cipher' => 'gcm' 'KeySize' => 256, // Additional configuration options ]; $multipartUploader = new S3EncryptionMultipartUploader( new S3Client([ 'region' => 'us-east-1', 'version' => 'latest', 'profile' => 'default', ]), fopen('large-file-to-encrypt.txt'), [ '@MaterialsProvider' => $materialsProvider, '@CipherOptions' => $cipherOptions, 'bucket' => 'bucket', 'key' => 'key', ] ); $multipartUploader->upload();

注意

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