本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

Amazon S3 加密客戶端遷移

本主題說明如何將應用程式從 Amazon 簡單儲存服務 (Amazon S3) 加密用戶端的版本 1 (V1) 遷移到第 2 版 (V2)，並確保應用程式在整個遷移過程中可用性。

移轉概觀

此遷移分兩個階段進行：

1. 更新現有用戶端以讀取新格式。首先，將更新版本的部署 AWS SDK for PHP 到您的應用程式。這可讓現有 V1 加密用戶端解密由新 V2 用戶端寫入的物件。如果您的應用程式使用多個應用程式 AWS SDKs，您必須SDK分別升級每

2. 將加密和解密用戶端移轉至 V2。一旦所有 V1 加密用戶端都可以讀取新格式，您就可以將現有的加密和解密用戶端遷移至各自的 V2 版本。

更新現有用戶端以讀取新格式

V2 加密用戶端使用舊版用戶端不支援的加密演算法。移轉的第一個步驟是將 V1 解密用戶端更新至最新SDK版本。完成此步驟之後，您的應用程式的 V1 用戶端將能夠解密由 V2 加密用戶端加密的物件。請參閱以下每個主要版本的詳細資訊 AWS SDK for PHP。

升級 AWS SDK for PHP 版本 3

版本 3 是最新版本的 AWS SDK for PHP. 若要完成此移轉，您必須使用套件的 3.148.0 版或更新版本aws/aws-sdk-php。

從命令列安裝

對於使用 Composer 安裝的專案，請在 Composer 檔案中，將SDK套件更新至的 3.148.0 版，SDK然後執行下列命令。

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必須傳入中的getObject和getObjectAsync方法S3EncryptionClientV2。 @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 客戶端進行解密，如果“getObject...”方法調用未將@KmsAllowDecryptWithAnyCmk參數設置true為，則kms-key-id必須向KmsMaterialsProviderV2構造函數提供 a。

移轉範例

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