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

Amazon S3 加密用戶端遷移

本主題說明如何將應用程式從 Amazon Simple Storage Service (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。

升級第 3 AWS SDK for PHP 版

第 3 版是 的最新版本 AWS 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 檔案放置在程式碼所需的位置，這由需要的陳述式決定。

對於使用 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-compatible格式加密的物件。將此參數設定為 ‘V2_AND_LEGACY’ 也允許解密以 V1-compatible格式加密的物件。若要支援遷移，請將 @SecurityProfile設定為 ‘V2_AND_LEGACY’。‘V2’ 僅用於新的應用程式開發。

3. （選用） 在 中包含 @KmsAllowDecryptWithAnyCmk 參數S3EncryptionClientV2::getObjectAsync* methods.，S3EncryptionClientV2::getObject並已新增名為 的新參數@KmsAllowDecryptWithAnyCmk。將此參數設定為true啟用解密，而不提供 KMS 金鑰。預設值為 false。

4. 對於使用 V2 用戶端進行解密，如果“getObject...”方法呼叫的 @KmsAllowDecryptWithAnyCmk 參數未設為 true ，kms-key-id則必須將 KmsMaterialsProviderV2 提供給建構器。

遷移範例

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