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 암호화 클라이언트 마이그레이션
이 주제에서는 애플리케이션을 Amazon Simple Storage Service () 암호화 클라이언트 버전 1(V1 Amazon S3)에서 버전 2(V2)로 마이그레이션하고 마이그레이션 프로세스 전반에 걸쳐 애플리케이션 가용성을 보장하는 방법을 보여줍니다.
## 사전 조건
Amazon S3 클라이언트 측 암호화에는 다음이 필요합니다.
+ Java 8 이상이 애플리케이션 환경에 설치되어 있어야 합니다. 는 [Oracle Java SE 개발 키트](https://www.oracle.com/java/technologies/javase-downloads.html) 및 [Amazon Corretto](https://aws.amazon.com/corretto/), Red Hat OpenJDK, [AdoptOpenJDK](https://adoptopenjdk.net/)와 같은 Open Java 개발 키트(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 파일을 애플리케이션 환경의 클래스 경로에 배치하거나 Maven `pom.xml` 파일에 artifactId `bcprov-ext-jdk15on`(`org.bouncycastle` groupID 사용)에 대한 종속성을 추가할 수 있습니다.
## 마이그레이션 개요
이 마이그레이션은 다음 두 단계로 진행됩니다.
1. **새 형식을 읽도록 기존 클라이언트를 업데이트하세요.** 버전 1.11.837 이상을 사용하도록 애플리케이션을 업데이트 AWS SDK for Java 하고 애플리케이션을 재배포합니다. 이렇게 하면 애플리케이션의 Amazon S3 클라이언트 측 암호화 서비스 클라이언트가 V2 서비스 클라이언트에서 생성한 객체를 해독할 수 있습니다. 애플리케이션에서 다중 AWS SDKs 사용하는 경우 각 SDK를 별도로 업데이트해야 합니다.
1. **암호화 및 복호화 클라이언트를 V2로 마이그레이션합니다.** 모든 V1 암호화 클라이언트가 V2 암호화 형식을 읽을 수 있게 되면 애플리케이션 코드에서 Amazon S3 클라이언트 측 암호화 및 복호화 클라이언트를 업데이트하여 해당 V2 암호화 형식을 사용합니다.
## 새 형식을 읽도록 기존 클라이언트를 업데이트하세요
V2 암호화 클라이언트는 이전 버전의가 지원하지 AWS SDK for Java 않는 암호화 알고리즘을 사용합니다.
마이그레이션의 첫 번째 단계는 V1 암호화 클라이언트가 AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 업데이트하는 것입니다. ([Java API 참조 버전 1.x](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc)에서 찾을 수 있는 최신 릴리스 버전으로 업데이트하는 것이 좋습니다.) 이렇게 하려면 프로젝트 구성의 종속성을 업데이트합니다. 프로젝트 구성이 업데이트된 후 프로젝트를 다시 빌드하고 다시 배포하세요.
이 단계를 완료하면 애플리케이션의 V1 암호화 클라이언트가 V2 암호화 클라이언트가 작성한 객체를 읽을 수 있습니다.
### 프로젝트 구성의 종속성을 업데이트하세요.
AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 프로젝트 구성 파일(예: pom.xml 또는 build.gradle)을 수정하세요. 그런 다음 프로젝트를 다시 빌드하고 다시 배포하세요.
새 애플리케이션 코드를 배포하기 전에 이 단계를 완료하면 마이그레이션 프로세스 중에 플릿 전체에서 암호화 및 암호 해독 작업을 일관되게 유지할 수 있습니다.
#### Maven 사용 사례
pom.xml 파일의 코드 조각:
```
com.amazonaws
aws-java-sdk-bom
1.11.837
pom
import
```
#### Gradle 사용 사례
build.gradle 파일의 코드 조각:
```
dependencies {
implementation platform('com.amazonaws:aws-java-sdk-bom:1.11.837')
implementation 'com.amazonaws:aws-java-sdk-s3'
}
```
## 암호화 및 복호화 클라이언트를 V2로 마이그레이션
프로젝트가 최신 SDK 버전으로 업데이트되면 V2 클라이언트를 사용하도록 애플리케이션 코드를 수정할 수 있습니다. 이렇게 하려면 먼저 새 서비스 클라이언트 빌더를 사용하도록 코드를 업데이트하세요. 그런 다음 이름이 바뀐 빌더의 메서드를 사용하여 암호화 자료를 제공하고 필요에 따라 서비스 클라이언트를 추가로 구성하세요.
이러한 코드 조각은에서 클라이언트 측 암호화를 사용하는 방법을 보여주고 V1 AWS SDK for Java및 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`로 설정합니다. 이는 V2 암호화 클라이언트가 V1 암호화 클라이언트가 작성한 객체를 읽을 수 있도록 하는 설정입니다. 클라이언트에 V1 클라이언트가 작성한 객체를 읽을 수 있는 기능이 필요하지 않은 경우에는 기본 설정인 `StrictAuthenticatedEncryption`를 대신 사용하는 것이 좋습니다.
### V2 암호화 클라이언트 생성
V2 암호화 클라이언트는 *AmazonS3EncryptionClientV2.encryptionBuilder()*를 호출하여 구성할 수 있습니다.
기존 V1 암호화 클라이언트를 모두 V2 암호화 클라이언트로 교체할 수 있습니다. V2 암호화 클라이언트가 `AuthenticatedEncryption``cryptoMode`을 사용하도록 구성하는 한 V2 암호화 클라이언트는 항상 V1 암호화 클라이언트가 작성한 모든 객체를 읽을 수 있습니다.
새 V2 암호화 클라이언트를 만드는 것은 V1 암호화 클라이언트를 만드는 방법과 매우 비슷합니다. 그러나 몇 가지 차이점이 있습니다.
+ `CryptoConfiguration` 객체 대신 `CryptoConfigurationV2` 객체를 사용하여 클라이언트를 구성합니다. 이 파라미터는 필수 사항입니다.
+ V2 암호화 클라이언트의 기본 `cryptoMode` 설정은 `StrictAuthenticatedEncryption`입니다. V1 암호화 클라이언트의 경우 `EncryptionOnly`입니다.
+ 암호화 클라이언트 빌더의 메서드 *withEncryptionMaterials()*는 *withEncryptionMaterialsProvider()*로 이름이 변경되었습니다. 이는 단순히 인수 유형을 더 정확하게 반영하기 위한 외관상의 변경일 뿐입니다. 서비스 클라이언트를 구성할 때 새 메서드를 사용해야 합니다.
**참고**
AES-GCM으로 해독할 때는 해독된 데이터를 사용하기 전에 전체 객체를 끝까지 읽습니다. 이는 객체가 암호화된 이후 수정되지 않았는지 확인하기 위한 것입니다.
### 암호화 자료 제공업체 사용
V1 암호화 클라이언트에서는 이미 사용하고 있는 동일한 암호화 자료 제공자 및 암호화 자료 객체를 계속 사용할 수 있습니다. 이러한 클래스는 암호화 클라이언트가 데이터를 보호하는 데 사용하는 키를 제공하는 역할을 합니다. V2 및 V1 암호화 클라이언트 모두와 호환하여 사용할 수 있습니다.
### V2 암호화 클라이언트 구성
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);
```
## 추가 예제
다음 예제는 V1에서 V2로의 마이그레이션과 관련된 특정 사용 사례를 해결하는 방법을 보여줍니다.
### V1 암호화 클라이언트가 생성한 객체를 읽도록 서비스 클라이언트를 구성합니다.
V1 암호화 클라이언트를 사용하여 이전에 작성된 객체를 읽으려면 `cryptoMode`를 `AuthenticatedEncryption`로 설정합니다. 다음 코드 코드 조각은 이 설정으로 구성 객체를 생성하는 방법을 보여줍니다.
```
CryptoConfigurationV2 cryptoConfiguration = new CryptoConfigurationV2()
.withCryptoMode(CryptoMode.AuthenticatedEncryption);
```
### 객체의 바이트 범위를 가져오도록 서비스 클라이언트를 구성합니다.
암호화된 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);
```