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

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

使用客户端加密，数据可在您的环境中直接加密和解密。这就意味着，数据在传输到 Amazon S3 之前已加密，您无需使用外部服务来处理加密。对于新的实现，我们建议使用 S3EncryptionClientV2 和 S3EncryptionMultipartUploaderV2 来替代已弃用的 S3EncryptionClient 和 S3EncryptionMultipartUploader。建议仍在使用已弃用版本的旧实现尝试迁移。S3EncryptionClientV2 继续支持对使用旧版 S3EncryptionClient 加密的数据进行解密。

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

迁移指南

对于尝试从已弃用客户端迁移到新客户端的用户，可以在此处找到迁移指南。

设置

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

运行任何示例代码之前，请配置您的 AWS 凭证。请参阅 AWS SDK for PHP 版本 3 的凭证。

加密

在 S3EncryptionClientV2 中上传加密对象，除标准 PutObject 参数之外，还需要三个额外参数：

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

解密

下载和解密对象时，除了标准 GetObject 参数外，还有四个额外参数，其中两个是必需的。客户端将为您检测基本的密码选项。

$result = $encryptionClient->getObject([
    '@KmsAllowDecryptWithAnyCmk' => true,
    '@SecurityProfile' => 'V2_AND_LEGACY',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);

密码配置

元数据策略

您还可以选择提供实施 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,
]);

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

$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();