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

# Amazon S3 暗号化クライアントの移行 (V2 から V3)
<a name="s3-encryption-migration-v2-v3"></a>

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

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

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

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

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

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

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

Amazon S3 暗号化クライアントのバージョン 3 では、データキーの改ざんに対する保護を強化する新しいセキュリティ機能が導入されています。これらの概念を理解することは、移行を成功させるために不可欠です。

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

コミットメントポリシーは、暗号化および復号オペレーション中に暗号化クライアントがキーコミットメントを処理する方法を制御します。V3 には、さまざまな移行シナリオとセキュリティ要件をサポートする 3 つのポリシーオプションが用意されています。

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

**`REQUIRE_ENCRYPT_ALLOW_DECRYPT` (デフォルト)**  
**暗号化動作:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムを使用して、キーコミットメントでオブジェクトを暗号化します。  
**復号動作:** キーコミットメントで暗号化されたオブジェクトと、キーコミットメントなしで暗号化されたオブジェクトの両方の復号を許可します。  
**セキュリティへの影響:** このポリシーは、古いオブジェクトを読み取るための下位互換性を維持しながら、新しく暗号化されたオブジェクトに対して強力なセキュリティを提供します。これは、ほとんどの移行シナリオで推奨されるポリシーです。  
**バージョンの互換性:** このポリシーで暗号化されたオブジェクトは、V3 および最新の V2 実装でのみ読み取ることができます。V2 クライアントはこれらのオブジェクトを復号できません。ただし、このポリシーを使用する V3 クライアントは、V2 クライアントによって暗号化されたオブジェクトを復号できます。

**`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`**  
**暗号化動作:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムを使用して、キーコミットメントでオブジェクトを暗号化します。  
**復号動作:** キーコミットメントで暗号化されたオブジェクトの復号のみを許可します。キーコミットメントなしで暗号化されたオブジェクトを拒否します。  
**セキュリティへの影響:** このポリシーは、すべてのオペレーションに主要なコミットメントを適用することで、最高レベルのセキュリティを提供します。このポリシーは、すべてのオブジェクトがキーコミットメントで再暗号化され、レガシー V1 または V2 で暗号化されたオブジェクトを読み取る必要がなくなった後にのみ使用します。  
**バージョンの互換性:** このポリシーで暗号化されたオブジェクトは、V3 および最新の V2 実装でのみ読み取ることができます。さらに、このポリシーを使用するクライアントは、V1 または V2 クライアントによって暗号化されたオブジェクトを復号できません。

**移行に関する考慮事項:** 移行中に V2 クライアント`FORBID_ENCRYPT_ALLOW_DECRYPT`が新しいオブジェクトを読み取る必要がある場合は、 から開始し、すべてのクライアントが V3 にアップグレード`REQUIRE_ENCRYPT_ALLOW_DECRYPT`されたら に移動します。最後に、すべてのレガシーオブジェクトが再暗号化された後に`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`のみ考慮してください。

### ALG\_AES\_256\_GCM\_HKDF\_SHA512\_COMMIT\_KEY アルゴリズム
<a name="s3-encryption-migration-v2-v3-aes-gcm-kc"></a>

`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` アルゴリズムは、命令ファイルに保存されている暗号化されたデータキーのセキュリティを強化する V3 で導入された新しい暗号化アルゴリズムです。

**命令ファイルの影響:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムは、暗号化されたデータキーを含む暗号化メタデータを保存する個別の S3 オブジェクトである命令ファイルにのみ影響します。暗号化メタデータをオブジェクトメタデータに保存するオブジェクト (デフォルトのストレージ方法) は、このアルゴリズムの変更の影響を受けません。

**改ざんに対する保護:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムは、暗号化されたデータキーを暗号化コンテキストに暗号化バインドすることで、データキーの改ざんから保護します。これにより、攻撃者が命令ファイル内の別の暗号化されたデータキーを置き換えるのを防ぎ、意図しないキーによる復号につながる可能性があります。

**バージョンの互換性: **`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムで暗号化されたオブジェクトは、V3 実装と V3 復号サポートを含む SDK の最新の V3 V2 移行バージョンでのみ復号できます。

**警告**  
**重要:** ( `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`コミットメントポリシーを使用して) `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムによる暗号化を有効にする前に、これらのオブジェクトを読み取るすべてのクライアントが V3 または V3 復号をサポートするV3 V2 移行バージョンにアップグレードされていることを確認する必要があります。すべてのリーダーを最初にアップグレードしないと、新しく暗号化されたオブジェクトの復号に失敗します。

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

まず、既存のクライアントを最新の SDK リリースに更新する必要があります。このステップを完了すると、アプリケーションの V2 クライアントは、アプリケーションのコードベースを更新することなく、V3 暗号化クライアントによって暗号化されたオブジェクトを復号できます。

### の最新バージョンをビルドしてインストールする AWS SDK for C\+\+
<a name="s3-encryption-migration-v2-v3-build-install-sdk"></a>

 **ソースから SDK を利用するアプリケーション** 

ソース AWS SDK for C\+\+ から を構築してインストールする場合は、GitHub の から SDK ソースをダウンロードまたはクローン[`aws/aws-sdk-cpp`](https://github.com/aws/aws-sdk-cpp)します。その後、通常のビルドおよびインストール手順を繰り返します。

1.11.x より前のバージョン AWS SDK for C\+\+ からアップグレードする場合は、各メジャーバージョンで導入された重大な変更について、この [CHANGELOG](https://github.com/aws/aws-sdk-cpp/blob/main/CHANGELOG.md) を参照してください。をビルドおよびインストールする方法の詳細については AWS SDK for C\+\+、「」を参照してください[ソースコード AWS SDK for C\+\+ から を取得する](sdk-from-source.md)。

 **Vcpkg から SDK を利用するアプリケーション** 

アプリケーションで [Vcpkg](https://github.com/microsoft/vcpkg) を使用して SDK の更新を追跡している場合は、既存の Vcpkg アップグレード方法を使用して SDK を最新バージョンにアップグレードするだけです。バージョンがリリースされてからパッケージマネージャーで使用可能になるまでに遅延があることに注意してください。最新バージョンは[ソースからインストール](sdk-from-source.md)することで常に使用できます。

次のコマンドを実行してパッケージ `aws-sdk-cpp` をアップグレードできます。

```
vcpkg upgrade aws-sdk-cpp
```

次に、パッケージ `aws-sdk-cpp` のバージョンを確認します。

```
vcpkg list aws-sdk-cpp
```

V3-encryptedオブジェクトの復号をサポートするには、バージョンが 1.11.x 以上である必要があります。

で Vcpkg を使用する方法の詳細については AWS SDK for C\+\+、「」を参照してください[パッケージマネージャー AWS SDK for C\+\+ から を取得する](sdk-from-pm.md)。

### アプリケーションのビルド、インストール、デプロイする
<a name="s3-encryption-migration-v2-v3-build-deploy-apps"></a>

アプリケーションが と静的にリンクされている場合 AWS SDK for C\+\+、アプリケーションにコードの変更は必要ありませんが、最新の SDK の変更を使用するためにアプリケーションを再度構築する必要があります。動的リンクの場合、このステップは不要です。

アプリケーションの依存関係バージョンをアップグレードし、アプリケーションの機能を確認したら、フリートへのアプリケーションのデプロイに進みます。アプリケーションのデプロイが完了したら、次のフェーズに進み、アプリケーションを移行して V3 暗号化クライアントと復号クライアントを使用できます。

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

次の手順は、Amazon S3 暗号化クライアントの V2 から V3 にコードを正常に移行する方法を示しています。 Amazon S3 コードの変更が必要なため、静的または動的にリンクしているかどうかにかかわらず、アプリケーションを再構築する必要があります AWS SDK for C\+\+。

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

V3 は `S3EncryptionClientV3` クラス と を導入`CryptoConfigurationV3`し、V2 に相当するものを置き換えます。V3 の主な違いは次のとおりです。
+ V3 は `KMSWithContextEncryptionMaterials` (V2 と同じ) を使用しますが、 で明示的な設定が必要です`CryptoConfigurationV3`。
+ すべての`PutObject`オペレーションには暗号化コンテキストマップが必要です (空にすることもできます）。
+ V3 では、暗号化と復号の動作を制御するコミットメントポリシーが導入されています。
+ デフォルトでは、V3 は `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`アルゴリズムを使用してキーコミットメントで暗号化します。
+ レガシーアルゴリズム復号設定 API は から `config.SetSecurityProfile(SecurityProfile::V2_AND_LEGACY);`に変更されます`config.AllowLegacy();`。

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

 *移行前 (V2)* 

```
// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);

// Create V2 crypto configuration
CryptoConfigurationV2 cryptoConfig(materials);

// Create V2 encryption client
S3EncryptionClientV2 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```

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

```
// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);

// Set commitment policy to maintain compatibility with V2 encrypted objects
// This allows V3 clients to decrypt objects encrypted by the V2 client
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```

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

```
// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);

// Use the default commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
// This encrypts with key commitment and does not decrypt V2 objects
// cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object with encryption context
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);

auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```

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

このセクションでは、さまざまな移行シナリオと要件をサポートするために V3 暗号化クライアントオプションを設定するための追加の例を示します。

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

V3 クライアントは、 `REQUIRE_ENCRYPT_ALLOW_DECRYPT`または `FORBID_ENCRYPT_ALLOW_DECRYPT` コミットメントポリシーを使用する場合にのみ、V2 クライアントによって暗号化されたオブジェクトを復号できます。ただし、V1 クライアントによって暗号化されたオブジェクトを復号する必要がある場合は、 `AllowLegacy()`メソッドを使用してレガシーサポートを明示的に有効にする必要があります。

**レガシーサポートを使用するタイミング:**
+ S3 暗号化クライアントの V1 を使用して暗号化されたオブジェクトが S3 にあります。
+ これらの V1-encryptedオブジェクトは、移行プロセス中に V3 クライアントで読み取る必要があります。
+ `REQUIRE_ENCRYPT_ALLOW_DECRYPT` または `FORBID_ENCRYPT_ALLOW_DECRYPT`コミットメントポリシーを使用しています。

**警告**  
レガシーサポートは、移行中に一時的にのみ有効にする必要があります。すべての V1 オブジェクトが V2 または V3 で再暗号化されたら、レガシーサポートを無効にしてセキュリティを最大化します。

**例: レガシーサポートの有効化**

```
// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);

// Enable legacy support to read V1 encrypted objects
cryptoConfig.AllowLegacy();

// Set commitment policy (default is REQUIRE_ENCRYPT_REQUIRE_DECRYPT but we need to allow decryption)
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);

// Create V3 encryption client with legacy support enabled
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Now you can decrypt objects encrypted by V1, V2, and V3 clients
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(LEGACY_OBJECT_KEY);

Aws::Map<Aws::String, Aws::String> encryptionContext;
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```

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

S3 暗号化クライアントは、暗号化メタデータをオブジェクトメタデータ (デフォルト) として、または別の命令ファイルとして 2 つの方法で保存できます。ストレージメソッドは、 の `SetStorageMethod()`メソッドを使用して設定できます`CryptoConfigurationV3`。

**ストレージメソッドのオプション:**

**`METADATA` (デフォルト)**  
暗号化メタデータは、オブジェクトのメタデータヘッダーに保存されます。これは、すべての暗号化情報がオブジェクト自体に保存されるため、最も一般的で便利な方法です。  
**使用するタイミング:** ほとんどのシナリオでこの方法を使用します。暗号化メタデータはオブジェクトとともに移動するため、オブジェクト管理が簡素化されます。

**`INSTRUCTION_FILE`**  
暗号化メタデータは、サフィックス が付いた別の S3 オブジェクト (命令ファイル) に保存されます`.instruction`。  
**使用するタイミング:** オブジェクトメタデータのサイズが懸念される場合、または暗号化されたオブジェクトから暗号化メタデータを分離する必要がある場合は、このメソッドを使用します。命令ファイルを使用するには、2 つの S3 オブジェクト (暗号化されたオブジェクトとその命令ファイル) を 1 つではなく管理する必要があることに注意してください。

**例: ストレージ方法の設定**

```
// Create encryption materials
auto materials = Aws::MakeShared<KMSWithContextEncryptionMaterials>("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);

// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);

// Option 1: Use metadata storage (default, can be omitted)
cryptoConfig.SetStorageMethod(StorageMethod::METADATA);

// Option 2: Use instruction file storage
cryptoConfig.SetStorageMethod(StorageMethod::INSTRUCTION_FILE);

// Create V3 encryption client with the configured storage method
S3EncryptionClientV3 encryptionClient(cryptoConfig);

// Put object - encryption metadata will be stored according to the configured method
Aws::Map<Aws::String, Aws::String> encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");

PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...

auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);

// If using INSTRUCTION_FILE, a separate object with key "OBJECT_KEY.instruction" will be created
```

**注記**  
`INSTRUCTION_FILE` ストレージメソッドを使用する場合、暗号化されたオブジェクトを削除しても、命令ファイルは自動的に削除されないことに注意してください。両方のオブジェクトを個別に管理する必要があります。