The AWS SDK for Java 1.x는 2024년 7월 31일부터 유지 관리 모드로 전환되었으며 2025년 12월 31일에 end-of-support에 도달할 예정입니다. 새로운 기능, 가용성 개선 사항 및 보안 업데이트를 AWS SDK for Java 2.x 계속 받으려면 로 마이그레이션하는 것이 좋습니다.

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

Amazon S3 암호화 클라이언트 마이그레이션

이 주제에서는 애플리케이션을 Amazon Simple Storage Service () 암호화 클라이언트의 버전 1(V1 Amazon S3)에서 버전 2(V2)로 마이그레이션하고 마이그레이션 프로세스 전반에 걸쳐 애플리케이션 가용성을 보장하는 방법을 보여줍니다.

사전 조건

Amazon S3 클라이언트 측 암호화에는 다음이 필요합니다.

마이그레이션 개요

이 마이그레이션은 다음 두 단계로 진행됩니다.

새 형식을 읽도록 기존 클라이언트를 업데이트하세요

V2 암호화 클라이언트는 이전 버전의가 지원하지 AWS SDK for Java 않는 암호화 알고리즘을 사용합니다.

마이그레이션의 첫 번째 단계는 V1 암호화 클라이언트가 AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 업데이트하는 것입니다. (Java API Reference 버전 1.x에서 찾을 수 있는 최신 릴리스 버전으로 업데이트하는 것이 좋습니다.) 이렇게 하려면 프로젝트 구성의 종속성을 업데이트합니다. 프로젝트 구성이 업데이트된 후 프로젝트를 다시 빌드하고 다시 배포하세요.

이 단계를 완료하면 애플리케이션의 V1 암호화 클라이언트가 V2 암호화 클라이언트가 작성한 객체를 읽을 수 있습니다.

프로젝트 구성의 종속성을 업데이트하세요.

AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 프로젝트 구성 파일(예: pom.xml 또는 build.gradle)을 수정하세요. 그런 다음 프로젝트를 다시 빌드하고 다시 배포하세요.

새 애플리케이션 코드를 배포하기 전에 이 단계를 완료하면 마이그레이션 프로세스 중에 플릿 전체에서 암호화 및 암호 해독 작업을 일관되게 유지할 수 있습니다.

Maven 사용 사례

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 사용 사례

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 암호화 클라이언트를 만드는 방법과 매우 비슷합니다. 그러나 몇 가지 차이점이 있습니다.

암호화 자료 제공업체 사용

V1 암호화 클라이언트에서는 이미 사용하고 있는 동일한 암호화 자료 제공자 및 암호화 자료 객체를 계속 사용할 수 있습니다. 이러한 클래스는 암호화 클라이언트가 데이터를 보호하는 데 사용하는 키를 제공하는 역할을 합니다. V2 및 V1 암호화 클라이언트 모두와 호환하여 사용할 수 있습니다.

V2 암호화 클라이언트 구성

V2 암호화 클라이언트는 CryptoConfigurationV2 객체로 구성됩니다. 이 객체는 기본 생성자를 호출한 다음 필요에 따라 기본값에서 해당 속성을 수정하여 생성할 수 있습니다.

CryptoConfigurationV2의 기본값은 다음과 같습니다.

EncryptionOnly는 V2 암호화 클라이언트cryptoMode에서 지원되지 않습니다. V2 암호화 클라이언트는 항상 인증된 암호화를 사용하여 콘텐츠를 암호화하고 V2 KeyWrap 객체를 사용하여 콘텐츠 암호화 키(CEKs)를 보호합니다.

다음 예제에서는 V1에서 암호화 구성을 지정하는 방법과 V2 암호화 클라이언트 빌더에 전달할 CryptoConfigurationVV2V2 객체를 인스턴스화하는 방법을 보여줍니다.

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를 참조하세요.

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);