适用于 PHP 的 AWS SDK 版本 3 中的 Amazon S3 加密客户端迁移

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

迁移概述

此迁移分为两个阶段：

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

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

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

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

升级 适用于 PHP 的 AWS SDK 版本 3

版本 3 是 适用于 PHP 的 AWS SDK 的最新版本。必须使用版本 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. 必须将 AWS KMS 加密上下文传递到 S3EncryptionClientV2::putObject 和 S3EncryptionClientV2::putObjectAsync 方法中。AWS KMS 加密上下文是密钥值对的关联数组，必须将其添加到加密上下文中才能进行 AWS 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：将 AWS KMS 与 kms-key-id 结合使用

迁移前

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