翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# AWS SDK for PHP バージョン 3 での Amazon S3 暗号化クライアント移行 (V2 から V3)
<a name="s3-encryption-migration-v2-v3"></a>

**注記**  
Amazon S3 暗号化クライアントのバージョン 1 (V1) を使用している場合は、まずバージョン 2 (V2) に移行してから、バージョン 3 (V3) に移行する必要があります。「[AWS SDK for PHP バージョン 3 での Amazon S3 暗号化クライアント移行 (V1 から V2)](s3-encryption-migration-v1-v2.md)」を参照してください。

このトピックでは、Amazon Simple Storage Service (Amazon S3) 暗号化クライアントのバージョン 2 (V2) からバージョン 3 (V3) にアプリケーションを移行し、移行プロセス全体でアプリケーションの可用性を確保する方法について説明します。バージョン 3 では、セキュリティを強化し、データキーの改ざんから保護するために、キーコミットメントとコミットメントポリシーを含む AES GCM が導入されています。

## 移行の概要
<a name="s3-encryption-migration-v2-v3-overview"></a>

この移行は 2 つのフェーズから構成されます。

1. **新しいフォーマットを読み取るために既存のクライアントを更新します。**まず、更新されたバージョンの AWS SDK for PHP をアプリケーションにデプロイします。これにより、既存の V2 暗号化クライアントは、新しい V3 クライアントによって書き込まれたオブジェクトを復号できます。アプリケーションで AWS SDKs、各 SDK を個別にアップグレードする必要があります。

2. **暗号化クライアントと復号クライアントを V3 に移行します。**すべての V2 暗号化クライアントが新しい形式を読み取れるようになったら、既存の暗号化クライアントと復号クライアントをそれぞれの V3 バージョンに移行できます。

## V3 の概念について
<a name="s3-encryption-migration-v2-v3-concepts"></a>

Amazon S3 暗号化クライアントのバージョン 3 では、コミットメントポリシーとキーコミットメントアルゴリズムを使用した AES GCM という 2 つの主要なセキュリティ機能強化が導入されています。これらの概念を理解することは、移行を成功させるために不可欠です。

### コミットメントポリシー
<a name="s3-encryption-migration-v2-v3-concepts-commitment-policy"></a>

コミットメントポリシーは、暗号化および復号オペレーション中に暗号化クライアントがキーコミットメントを処理する方法を制御します。バージョン 3 には 3 つのポリシーオプションがあります。

`FORBID_ENCRYPT_ALLOW_DECRYPT`  
**暗号化動作:** キーコミットメントなしでオブジェクトを暗号化します。  
**復号動作:** キーコミットメントの有無にかかわらず暗号化されたオブジェクトの復号を許可します。  
**セキュリティへの影響:** このポリシーは、新しく暗号化されたオブジェクトにキーコミットメントを適用しません。これにより、データキーの改ざんが許可される可能性があります。このポリシーは、V2 クライアントとの互換性を維持する必要がある最初の移行フェーズでのみ使用します。  
**バージョンの互換性:** このポリシーで暗号化されたオブジェクトは、すべての V2 および V3 実装で読み取ることができます。

`REQUIRE_ENCRYPT_ALLOW_DECRYPT`  
**暗号化動作:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムを使用して、キーコミットメントを持つオブジェクトを暗号化します。  
**復号動作:** キーコミットメントの有無にかかわらず暗号化されたオブジェクトの復号を許可します。  
**セキュリティへの影響:** このポリシーは、既存のオブジェクトを読み取る機能を維持しながら、新しく暗号化されたオブジェクトのセキュリティを強化します。これは、ほとんどの移行シナリオで推奨されるポリシーです。  
**バージョンの互換性:** このポリシーで暗号化されたオブジェクトは、V3 および最新の V2 実装でのみ読み取ることができます。  
**移行に関する考慮事項:** このポリシーを使用する前に、暗号化されたオブジェクトを読み取る必要があるすべてのクライアントが V3 または最新の V2 にアップグレードされていることを確認してください。

`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`  
**暗号化動作:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムを使用して、キーコミットメントでオブジェクトを暗号化します。  
**復号動作:** キーコミットメントで暗号化されたオブジェクトの復号のみを許可します。キーコミットメントなしで暗号化されたオブジェクトは復号に失敗します。  
**セキュリティへの影響:** このポリシーは、暗号化と復号の両方にキーコミットメントを適用することで、最高レベルのセキュリティを提供します。このポリシーは、すべてのオブジェクトがキーコミットメントを使用するように移行された後にのみ使用します。  
**バージョンの互換性:** このポリシーを使用できるのは V3 実装のみです。このポリシーを使用して V1 または V2 で暗号化されたオブジェクトを復号しようとすると失敗します。  
**移行に関する考慮事項:** このポリシーは、完全な移行を完了し、すべての既存のオブジェクトをキーコミットメントで再暗号化した後にのみ使用してください。

### キーコミットメントを持つ AES GCM
<a name="s3-encryption-migration-v2-v3-concepts-aes-gcm-kc"></a>

AES GCM with Key Commitment (`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`) アルゴリズムは、V3 で導入された新しい暗号化アルゴリズムであり、データキーの改ざん攻撃に対する保護を提供します。

**セキュリティの強化:** データキーを暗号化されたコンテンツに暗号化バインドすることで、データキーの改ざん`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`を防止します。これにより、攻撃者が復号中に別のデータキーを置き換えるのを防ぎ、意図しないデータの復号につながる可能性があります。

**バージョンの互換性: **で暗号化されたオブジェクトは、V3 および Amazon S3 暗号化クライアントの最新の V2 実装でのみ復号`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`できます。V1 クライアントは、このアルゴリズムで暗号化されたオブジェクトを復号できません。

**重要**  
**アップグレード要件:** で暗号化を有効にする前に `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` (REQUIRE\_ENCRYPT\_ALLOW\_DECRYPT または REQUIRE\_ENCRYPT\_REQUIRE\_DECRYPT ポリシーを使用）、暗号化されたオブジェクトを読み取る必要があるすべてのクライアントが V3 にアップグレードされていることを確認する必要があります。すべてのリーダーをアップグレードしないと、キーコミットメントで暗号化されたオブジェクトの復号に失敗します。

## 新しいフォーマットを読み取るために既存のクライアントを更新する
<a name="s3-encryption-migration-v2-v3-update-clients"></a>

V3 暗号化クライアントは、古いバージョンのクライアントがサポートしていない暗号化アルゴリズムとキーコミットメント機能を使用します。移行の最初のステップは、V2 復号クライアントを最新の SDK リリースに更新することです。このステップを完了すると、アプリケーションの V2 クライアントは V3 暗号化クライアントによって暗号化されたオブジェクトを復号できるようになります。のインストール方法の詳細については、以下を参照してください AWS SDK for PHP。

### 最新の SDK バージョンの構築とインストール
<a name="s3-encryption-migration-v2-v3-update-clients-sdk"></a>

この移行を完了するには、V3 暗号化クライアントのサポートを含む最新バージョンの `aws/aws-sdk-php` パッケージを使用する必要があります。

 **Composer からの のインストール** 

Composer を使用してインストールされたプロジェクトの場合、Composer ファイルで SDK パッケージを最新バージョンの SDK に更新し、次のコマンドを実行します。

```
composer update aws/aws-sdk-php
```

 **Phar または Zip ファイルを使用したインストール** 

次のいずれかの方法を使用します。更新された SDK ファイルは、必ず require ステートメントによって決定されるコードで求められる場所に配置してください。

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';
?>
```

### アプリケーションの構築、インストール、デプロイ
<a name="s3-encryption-migration-v2-v3-update-clients-deploy"></a>

SDK を更新したら、アプリケーションを再構築して再デプロイし、すべてのコンポーネントが更新されたバージョンを使用していることを確認します。このステップは、V2 クライアントが V3 クライアントによって暗号化されたオブジェクトを読み取れるようにするために重要です。

組織の標準デプロイ手順に従って、更新されたアプリケーションをロールアウトします。暗号化クライアントと復号クライアントを V3 に移行する前に、アプリケーションのすべてのインスタンスが更新されていることを確認してください。

デプロイ後、アプリケーションが引き続き既存のオブジェクトを復号でき、通常のオペレーション中にエラーが発生しないことを確認します。これにより、SDK の更新が成功し、アプリケーションが移行の次のフェーズの準備が整ったことを確認します。

## 暗号化クライアントと復号クライアントを V3 に移行する
<a name="s3-encryption-migration-v2-v3-migrate"></a>

クライアントを更新して新しい暗号化形式を読み取ると、アプリケーションを V3 暗号化および復号クライアントに更新できます。次の例は、コードを V2 から V3 に正常に移行する方法を示しています。

### V3 暗号化クライアントの使用
<a name="s3-encryption-migration-v2-v3-using-v3-clients"></a>

V3 は `S3EncryptionClientV3` クラス と を導入`KmsMaterialsProviderV3`し、V2 に相当するものを置き換えます。V3 の主な違いは次のとおりです。
+ V3 は `KmsMaterialsProviderV3` (V2 と同じ) を使用しますが、`GetObject`呼び出しでオブジェクトを復号するときに暗号化コンテキストを検証します。
+ V3 では、暗号化と復号の動作を制御するコミットメントポリシーが導入されています。

 **例: KMS 暗号化を使用した V2 から V3 への移行** 

 *移行前 (V2)* 

```
use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

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

$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',
   '@CommitmentPolicy' => 'FORBID_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);
```

 *移行中 (下位互換性がある V3)* 

```
use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   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,
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

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

 *移行後 (キーコミットメント付き V3)* 

```
use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;
 
// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   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,
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3',
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);
```

V3 の主な違い:
+ `KmsMaterialsProviderV2` の代わりに `KmsMaterialsProviderV3` を使用する
+ `@KmsEncryptionContext` パラメータは引き続き `putObject`オペレーションに必要です
+ `@KmsEncryptionContext` パラメータは `getObject`オペレーションではオプションであり、指定された暗号化コンテキストが オブジェクト内の暗号化コンテキストと一致することを確認します。
+ `@SecurityProfile` パラメータは、復号できる暗号化バージョンを制御します。移行中の V1 および V2 暗号化オブジェクトの読み取りをサポートする`'V3_AND_LEGACY'`には、 に設定します。
+ `@CommitmentPolicy` パラメータは、このオペレーションのコミットメントポリシーを制御します。移行中の非コミットメント暗号化オブジェクトの読み取りをサポートする`'FORBID_ENCRYPT_ALLOW_DECRYPT'`には、 に設定します。

## その他の例
<a name="s3-encryption-migration-v2-v3-examples"></a>

次の例は、移行プロセスを管理し、暗号化動作を制御するのに役立つ V3 で利用可能な追加の設定オプションを示しています。

### レガシー サポートの有効化
<a name="s3-encryption-migration-v2-v3-examples-legacy"></a>

移行中に、Amazon S3 暗号化クライアントの V1 または V2 で暗号化されたオブジェクトを復号する必要がある場合があります。`@SecurityProfile` パラメータは、V3 クライアントが復号できる暗号化バージョンを制御します。

**この設定を使用する場合:** アプリケーションが V1 または V2 クライアントによって暗号化されたオブジェクトを読み取る必要がある場合は、`'V3_AND_LEGACY'`セキュリティプロファイルを使用します。これは、移行期間中にバケットに古い暗号化オブジェクトと新しい暗号化オブジェクトが混在している場合によく発生します。

```
use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

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

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

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

// Decrypt objects encrypted with V1, V2, or V3
$result = $encryptionClient->getObject([
    '@SecurityProfile' => 'V3_AND_LEGACY',
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);
```

`@SecurityProfile` パラメータには、次の値を指定できます。
+ `'V3'` (デフォルト): キーコミットメントを使用して V3 で暗号化されたオブジェクトのみを復号する
+ `'V3_AND_LEGACY'`: V1、V2、または V3 で暗号化されたオブジェクトを復号する

**重要**  
移行を完了し、V3 ですべてのオブジェクトを再暗号化したら、 `@SecurityProfile`パラメータを削除するか`'V3'`、 に設定してセキュリティを最大化する必要があります。

### ストレージ方法の設定
<a name="s3-encryption-migration-v2-v3-examples-storage"></a>

Amazon S3 暗号化クライアントは、オブジェクトのメタデータヘッダーまたは別の命令ファイルという 2 つの方法で暗号化メタデータを保存できます。`@MetadataStrategy` パラメータは、使用するストレージ方法を制御します。

**この設定を使用するタイミング:** 元のオブジェクトメタデータを保持する必要がある場合、またはメタデータサイズの制約があるオブジェクトを操作する場合に使用します。 `'INSTRUCTION_FILE'`オブジェクトと一緒に暗号化メタデータを保存できるシンプルなデプロイには、 `'METADATA'` (デフォルト) を使用します。

```
use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

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

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

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

// Store encryption metadata in a separate instruction file
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'INSTRUCTION_FILE',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

// Store encryption metadata in object headers (default)
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'METADATA',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
```

`@MetadataStrategy` パラメータには、次の値を指定できます。
+ `'METADATA'` (デフォルト): オブジェクトのメタデータヘッダーに暗号化メタデータを保存する
+ `'INSTRUCTION_FILE'`: 暗号化メタデータをサフィックス付きの別の命令ファイルに保存する `.instruction`

**注記**  
を使用する場合`'INSTRUCTION_FILE'`、AES GCM with Key Commitment アルゴリズムは、データキーの改ざんに対する追加の保護を提供します。`'METADATA'` ストレージを使用するオブジェクトは、この追加の保護の恩恵を受けません。