AWS SDK for Java 1.x は 2025 年 12 月 31 日にend-of-supportしました。新しい機能、可用性の向上、セキュリティ更新のために、[AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) に移行することをお勧めします。

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

# Amazon S3 暗号化クライアントの移行
<a name="s3-encryption-migration"></a>

このトピックでは、 Amazon Simple Storage Service () 暗号化クライアントのバージョン 1 (V1 Amazon S3) からバージョン 2 (V2) にアプリケーションを移行し、移行プロセス全体でアプリケーションの可用性を確保する方法について説明します。

## 前提条件
<a name="s3-cse-prereq"></a>

 Amazon S3 クライアント側の暗号化には、以下が必要です。
+ Java 8 以降がアプリケーション環境にインストールされていること。は、[Oracle Java SE Development Kit ](https://www.oracle.com/java/technologies/javase-downloads.html)と、、Red Hat OpenJDK[Amazon Corretto](https://aws.amazon.com/corretto/)、[AdoptOpenJDK](https://adoptopenjdk.net/) などの Open Java Development Kit (OpenJDK) のディストリビューションで AWS SDK for Java 動作します。 [ OpenJDK](https://developers.redhat.com/products/openjdk)
+ [Bouncy Castle Crypto パッケージ](https://www.bouncycastle.org/download/bouncy-castle-java/)。Bouncy Castle .jar ファイルをアプリケーション環境のクラスパスに配置するか、artifactId `bcprov-ext-jdk15on` (`org.bouncycastle` の groupId を使用) における依存関係を Maven `pom.xml` ファイルに追加できます。

## 移行の概要
<a name="s3-cse-overview"></a>

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

1.  **新しいフォーマットを読み取るために既存のクライアントを更新します。**バージョン 1.11.837 以降の を使用するようにアプリケーションを更新 AWS SDK for Java し、アプリケーションを再デプロイします。これにより、アプリケーションの Amazon S3 クライアント側の暗号化サービスクライアントは、V2 サービスクライアントによって作成されたオブジェクトを復号できます。アプリケーションで AWS SDKs、各 SDK を個別に更新する必要があります。

1.  **暗号化および復号クライアントを V2 に移行します。**すべての V1 暗号化クライアントが V2 暗号化形式を読み取れるようになったら、アプリケーションコードの Amazon S3 クライアント側の暗号化クライアントと復号クライアントを更新して V2 に相当するものを使用します。

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

V2 暗号化クライアントは、 の古いバージョンではサポート AWS SDK for Java されていない暗号化アルゴリズムを使用します。

移行の最初のステップは、 AWS SDK for Javaのバージョン 1.11.837 以降を使用するように V1 暗号化クライアントを更新することです。([Java API リファレンスバージョン 1.x](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc) にある最新リリースバージョンに更新することをお勧めします。) これを実行するには、プロジェクト設定の依存関係を更新します。プロジェクト設定が更新されたら、プロジェクトを再構築して再デプロイします。

これらの手順を完了すると、アプリケーションの V1 暗号化クライアントは、V2 暗号化クライアントによって書き込まれたオブジェクトを読み取ることができるようになります。

### プロジェクト設定の依存関係を更新する
<a name="update-the-dependency-in-your-project-configuration"></a>

プロジェクト設定ファイル (pom.xml や build.gradle など) を変更して、 AWS SDK for Javaのバージョン 1.11.837 以降を使用します。その後、プロジェクトを再構築して再デプロイします。

新しいアプリケーションコードをデプロイする前にこのステップを完了すると、移行プロセス中にフリート全体で暗号化と復号の操作の一貫性を保つことができます。

#### Maven を使用した例
<a name="example-using-maven"></a>

pom.xml ファイルからのスニペット:

```
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.amazonaws</groupId>
      <artifactId>aws-java-sdk-bom</artifactId>
      <version>1.11.837</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
```

#### Gradle を使用した例
<a name="example-using-gradle"></a>

build.gradle ファイルからのスニペット:

```
dependencies {
  implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
  implementation 'com.amazonaws:aws-java-sdk-s3'
}
```

## 暗号化および復号クライアントを V2 に移行する
<a name="s3-cse-update-code"></a>

プロジェクトが最新の SDK バージョンで更新されたら、V2 クライアントを使用するようにアプリケーションコードを変更できます。これを実行するには、新しいサービスクライアントビルダーを使用するように、最初にコードを更新します。その後、名前が変更されたビルダーのメソッドを使用して暗号化マテリアルを提供し、必要に応じてサービスクライアントをさらに設定します。

これらのコードスニペットは、 でクライアント側の暗号化を使用する方法を示し AWS SDK for Java、V1 暗号化クライアントと V2 暗号化クライアントの比較を提供します。

 **V1** 

```
// minimal configuration in V1; default CryptoMode.EncryptionOnly.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3Encryption encryptionClient = AmazonS3EncryptionClient.encryptionBuilder()
             .withEncryptionMaterials(encryptionMaterialsProvider)
             .build();
```

 **V2** 

```
// minimal configuration in V2; default CryptoMode.StrictAuthenticatedEncryption.
EncryptionMaterialsProvider encryptionMaterialsProvider = ...
AmazonS3EncryptionV2 encryptionClient = AmazonS3EncryptionClientV2.encryptionBuilder()
             .withEncryptionMaterialsProvider(encryptionMaterialsProvider)
             .withCryptoConfiguration(new CryptoConfigurationV2()
                           // The following setting allows the client to read V1 encrypted objects
                           .withCryptoMode(CryptoMode.AuthenticatedEncryption)
             )
             .build();
```

上記の例では、`cryptoMode` を `AuthenticatedEncryption` に設定しています。これは、V1 暗号化クライアントによって書き込まれたオブジェクトを V2 暗号化クライアントが読み取ることを許可する設定です。クライアントが V1 クライアントによって書き込まれたオブジェクトを読み取る機能を必要としない場合は、代わりにデフォルト設定の `StrictAuthenticatedEncryption` を使用することをお勧めします。

### V2 暗号化クライアントをコンストラクトする
<a name="construct-a-v2-encryption-client"></a>

V2 暗号化クライアントは、 *AmazonS3EncryptionClientV2.encryptionBuilder()* を呼び出すことで構築できます。

既存のすべての V1 暗号化クライアントを V2 暗号化クライアントに置き換えることができます。V2 暗号化クライアントは、`AuthenticatedEncryption``cryptoMode` を使用するように V2 暗号化クライアントを設定することを通じて許可されている限り、V1 暗号化クライアントによって書き込まれたすべてのオブジェクトを常に読み取ることができます。

新しい V2 暗号化クライアントの作成は、V1 暗号化クライアントの作成方法と非常によく似ています。ただし、いくつか違いがあります。
+ `CryptoConfiguration` オブジェクトの代わりに、`CryptoConfigurationV2` オブジェクトを使用してクライアントを設定します。このパラメータは必須です。
+ V2 暗号化クライアントのデフォルトの `cryptoMode` 設定は `StrictAuthenticatedEncryption` です。V1 暗号化クライアントの場合は `EncryptionOnly` です。
+ 暗号化クライアントビルダーのメソッドである *withEncryptionMaterials()* の名前は、*withEncryptionMaterialsProvider()* に変更されました。これは、単に引数の型をより正確に反映するための外観上の変更です。サービスクライアントを設定する際には、新しいメソッドを使用する必要があります。

**注記**  
AES-GCM で復号する場合は、復号されたデータの使用を開始する前に、オブジェクト全体を最後まで読み取ります。これは、オブジェクトが暗号化されてから変更されていないことを確認するためものステップです。

### 暗号化マテリアルプロバイダーを使用する
<a name="use-encryption-materials-providers"></a>

V1 暗号化クライアントで既に使用しているものと同じ暗号化マテリアルプロバイダーおよび暗号化マテリアルオブジェクトを引き続き使用できます。これらのクラスは、暗号化クライアントがデータを保護するために使用するキーを提供する役割を果たします。これらは、V2 および V1 暗号化クライアントの両方と互換的に使用できます。

### V2 暗号化クライアントを設定する
<a name="configure-the-v2-encryption-client"></a>

V2 暗号化クライアントは `CryptoConfigurationV2` オブジェクトで設定されます。このオブジェクトは、デフォルトのコンストラクターを呼び出し、必要に応じてデフォルトからプロパティを変更することで構築できます。

`CryptoConfigurationV2` のデフォルト値は次のとおりです。
+  `cryptoMode` = `CryptoMode.StrictAuthenticatedEncryption` 
+  `storageMode` = `CryptoStorageMode.ObjectMetadata` 
+  `secureRandom` = `SecureRandom` のインスタンス 
+  `rangeGetMode` = `CryptoRangeGetMode.DISABLED` 
+  `unsafeUndecryptableObjectPassthrough` = `false` 

*EncryptionOnly* は V2 暗号化クライアントでサポートされている `cryptoMode` ではないことに注意してください。V2 暗号化クライアントは、常に認証された暗号化を使用してコンテンツを暗号化し、V2 `KeyWrap` オブジェクトを使用してコンテンツ暗号化キー (CEK) を保護します。

次の例は、V1 で暗号設定を指定する方法と、*CryptoConfigurationV2* オブジェクトをインスタンス化して V2 暗号化クライアントビルダーに渡す方法を示しています。

 **V1** 

```
CryptoConfiguration cryptoConfiguration = new CryptoConfiguration()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);
```

 **V2** 

```
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.StrictAuthenticatedEncryption);
```

## その他の例
<a name="additional-examples"></a>

次の例は、V1 から V2 への移行に関連する特定のユースケースに対処する方法を示しています。

### V1 暗号化クライアントによって作成されたオブジェクトを読み取るようにサービスクライアントを設定する
<a name="configure-a-service-client-to-read-objects-created-by-the-v1-encryption-client"></a>

以前に V1 暗号化クライアントを使用して作成されたオブジェクトを読み取るには、`cryptoMode` を `AuthenticatedEncryption` に設定します。次のコードスニペットは、この設定で設定オブジェクトを構築する方法を示しています。

```
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
        .withCryptoMode(CryptoMode.AuthenticatedEncryption);
```

### オブジェクトのバイト範囲を取得するようにサービスクライアントを設定する
<a name="configure-a-service-client-to-get-byte-ranges-of-objects"></a>

暗号化された S3 オブジェクトからバイト範囲を `get` できるようにするには、新しい設定 `rangeGetMode` を有効にします。この設定は、V2 暗号化クライアントではデフォルトで無効になっています。有効になっている場合でも、範囲設定された `get` は、クライアントの `cryptoMode` 設定でサポートされているアルゴリズムを使用して暗号化されたオブジェクトでのみ機能することに注意してください。詳細については、 AWS SDK for Java API リファレンスの[CryptoRangeGetMode](https://docs.aws.amazon.com/sdk-for-java/v1/reference/com/amazonaws/services/s3/model/CryptoRangeGetMode.html)」を参照してください。

 Amazon S3 TransferManager を使用して V2 暗号化クライアントを使用して暗号化された Amazon S3 オブジェクトのマルチパートダウンロードを実行する場合は、まず V2 暗号化クライアントで `rangeGetMode`設定を有効にする必要があります。

次のコードスニペットは、範囲設定された `get` を実行するために V2 クライアントを設定する方法を示しています。

```
// Allows range gets using AES/CTR, for V2 encrypted objects only
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withRangeGetMode(CryptoRangeGetMode.ALL);

// Allows range gets using AES/CTR and AES/CBC, for V1 and V2 objects
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
       .withCryptoMode(CryptoMode.AuthenticatedEncryption)
       .withRangeGetMode(CryptoRangeGetMode.ALL);
```