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

# 第 3 版中的 Amazon S3 加密用戶端遷移 (V1 到 V2) 適用於 PHP 的 AWS SDK
<a name="s3-encryption-migration-v1-v2"></a>

**注意**  
如果您使用 Amazon S3 加密用戶端的第 2 版 (V2)，並且想要遷移到第 3 版 (V3)，請參閱 [第 3 版中的 Amazon S3 加密用戶端遷移 (V2 到 V3) 適用於 PHP 的 AWS SDK](s3-encryption-migration-v2-v3.md)。

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

## 遷移概觀
<a name="migration-overview-v1-v2"></a>

此遷移分為兩個階段：

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

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

## 更新現有用戶端以讀取新格式
<a name="update-existing-clients-to-read-new-formats-v1-v2"></a>

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

### 升級第 3 適用於 PHP 的 AWS SDK 版
<a name="upgrading-aws-sdk-for-php-version-3-v1-v2"></a>

第 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 檔案放在程式碼所需的位置，此位置由 要求陳述式決定。

對於使用 Phar 檔案安裝的專案，請下載更新的 檔案：[`aws.phar`](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar)。

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

對於使用 Zip 檔案安裝的專案，請下載更新的 檔案：[``](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip)。

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

## 將加密和解密用戶端遷移至 V2
<a name="migrate-encryption-and-decryption-clients-to-v2-v1-v2"></a>

將用戶端更新為讀取新的加密格式後，您可以將應用程式更新為 V2 加密和解密用戶端。下列步驟說明如何成功將程式碼從 V1 遷移至 V2。

### 更新至 V2 用戶端的需求
<a name="requirements-for-updating-to-v2-clients-v1-v2"></a>

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` 提供給建構函數。

## 遷移範例
<a name="migration-examples-v1-v2"></a>

### 範例 1：遷移至 V2 用戶端
<a name="example-1-migrating-to-v2-clients-v1-v2"></a>

 **預遷移** 

```
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
<a name="example-2-using-kms-with-kms-key-id-v1-v2"></a>

**注意**  
這些範例使用範例 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,
]);
```