Amazon S3 加密客户端迁移 - Amazon SDK for PHP
迁移概述更新现有客户端以读取新格式将加密和解密客户端迁移到 V2迁移示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

Amazon S3 加密客户端迁移

此主题介绍了如何将应用程序从 Amazon Simple Storage Service (Amazon S3) 加密客户端的版本 1 (V1) 迁移到版本 2 (V2)，并确保应用程序在整个迁移过程中的可用性。

迁移概述

此迁移分为两个阶段：

1. 更新现有客户端以读取新格式。首先，将 Amazon SDK for PHP 的已更新版本部署到应用程序中。这允许现有 V1 加密客户端解密由新的 V2 客户端写入的对象。如果应用程序使用了多个 Amazon SDK，则必须单独升级每个 SDK。

2. 将加密和解密客户端迁移到 V2。一旦所有 V1 加密客户端都能读取新格式，就可以将现有加密和解密客户端迁移到各自的 V2 版本。

更新现有客户端以读取新格式

V2 加密客户端使用旧版本客户端不支持的加密算法。迁移的第一步是将 V1 解密客户端更新到最新 SDK 版本。完成此步骤后，应用程序的 V1 客户端就能够解密由 V2 加密客户端加密的对象。有关 Amazon SDK for PHP 的每个主要版本，请参阅下文的详细信息。

升级 Amazon SDK for PHP 版本 3

版本 3 是 Amazon SDK for PHP 的最新版本。必须使用版本 3.148.0 或更高版本的 aws/aws-sdk-php 包才能完成此迁移。

从命令行安装

对于使用 Composer 来安装的项目，在 Composer 文件中，将 SDK 包更新到 SDK 的 3.148.0 版本，然后运行以下命令。

composer update aws/aws-sdk-php

使用 Phar 或 Zip 文件进行安装

使用以下方法之一。请务必将已更新的 SDK 文件放在代码所需位置，该位置由 require 语句确定。

对于使用 Phar 文件来安装的项目，请下载已更新的文件：aws.phar。

<?php
  require '/path/to/aws.phar';
?>

对于使用 Zip 文件来安装的项目，请下载已更新的文件：。

<?php
  require '/path/to/aws-autoloader.php';
?>

将加密和解密客户端迁移到 V2

更新客户端以读取新的加密格式后，您可以将应用程序更新到 V2 加密和解密客户端。以下步骤展示了如何成功地将代码从 V1 迁移到 V2。

更新到 V2 客户端的要求

1. 必须将 Amazon KMS 加密上下文传递到 S3EncryptionClientV2::putObject 和 S3EncryptionClientV2::putObjectAsync 方法中。Amazon KMS 加密上下文是密钥值对的关联数组，必须将其添加到加密上下文中才能进行 Amazon KMS 密钥加密。如果不需要其他上下文，则可以传递空数组。

2.必须将 @SecurityProfile 传递到 S3EncryptionClientV2 中的 getObject 和 getObjectAsync 方法中。@SecurityProfile 是这些 getObject... 方法的新必填参数。如果设置为 ‘V2’，则只能解密以 V2 兼容格式加密的对象。将此参数设置为 ‘V2_AND_LEGACY’，还允许解密以 V1 兼容格式加密的对象。要支持迁移，请将 @SecurityProfile 设置为 ‘V2_AND_LEGACY’。‘V2’ 仅用于新应用程序开发。

3.（可选）将 @KmsAllowDecryptWithAnyCmk 参数包含在 S3EncryptionClientV2::getObject 和 S3EncryptionClientV2::getObjectAsync* methods. 中。添加了一个名为 @KmsAllowDecryptWithAnyCmk 的新参数。将此参数设置为 true，可在不提供 KMS 密钥的情况下进行解密。默认值为 false。

4. 要使用 V2 客户端进行解密，如果未将 @KmsAllowDecryptWithAnyCmk 参数设置为 true，则对于 “getObject...” 方法调用，必须为 KmsMaterialsProviderV2 构造函数提供 kms-key-id。

迁移示例

示例 1：迁移到 V2 客户端

迁移前 

use Aws\S3\Crypto\S3EncryptionClient;
use Aws\S3\S3Client;

$encryptionClient = new S3EncryptionClient(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

迁移后 

use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;

$encryptionClient = new S3EncryptionClientV2(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);

示例 2：Amazon KMS与一起使用 kms-key-id

注意

这些示例使用在示例 1 中定义的导入和变量。例如，$encryptionClient。

迁移前 

use Aws\Crypto\KmsMaterialsProvider;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProvider(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

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

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

迁移后 

use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

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

$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
$result = $encryptionClient->getObject([
    '@KmsAllowDecryptWithAnyCmk' => true,
    '@SecurityProfile' => 'V2_AND_LEGACY',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);