Amazon S3 암호화 클라이언트 마이그레이션 - AWS SDK for Java 1.x

다음 버전 AWS SDK for Java (v1) end-of-support 을 발표했습니다. AWS SDK for Java V2로 마이그레이션하실 것을 권장합니다. 마이그레이션 날짜, 추가 세부 정보 및 방법에 대한 자세한 내용은 링크된 공지 사항을 참조하세요.

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

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

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

필수 조건

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

  • Java 8 이상이 애플리케이션 환경에 설치되어 있어야 합니다. 오라클 자바 SE 개발 키트Red Hat OpenJDK 및 JDK와 같은 Amazon Corretto오픈 자바 개발 키트 (OpenJDK) 배포판과 함께 AWS SDK for Java 작동합니다. AdoptOpen

  • Bouncy Castle Crypto 패키지. Bouncy Castle.jar 파일을 애플리케이션 환경의 클래스 경로에 배치하거나 Maven pom.xml 파일에 artifactId bcprov-ext-jdk15on(org.bouncycastle groupID 사용)에 대한 종속성을 추가할 수 있습니다.

마이그레이션 개요

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

  1. 새 형식을 읽도록 기존 클라이언트를 업데이트하세요. AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 애플리케이션을 업데이트하고 애플리케이션을 재배포하세요. 이렇게 하면 애플리케이션의 Amazon S3 클라이언트측 암호화 서비스 클라이언트가 V2 서비스 클라이언트에서 만든 객체를 해독할 수 있습니다. 애플리케이션에서 여러 AWS SDK를 사용하는 경우 각 SDK를 개별적으로 업그레이드해야 합니다.

  2. 암호화 및 복호화 클라이언트를 V2로 마이그레이션하세요. 모든 V1 암호화 클라이언트가 V2 암호화 형식을 읽을 수 있게 되면, V2와 동등한 기능을 사용하도록 애플리케이션 코드의 Amazon S3 클라이언트측 암호화 및 복호화 클라이언트를 업데이트합니다.

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

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

마이그레이션의 첫 번째 단계는 V1 암호화 클라이언트가 AWS SDK for Java의 버전 1.11.837 이상을 사용하도록 업데이트하는 것입니다. (Java API 참조 버전 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 클라이언트를 사용하도록 애플리케이션 코드를 수정할 수 있습니다. 이렇게 하려면 먼저 새 서비스 클라이언트 빌더를 사용하도록 코드를 업데이트하세요. 그런 다음 이름이 바뀐 빌더의 메서드를 사용하여 암호화 자료를 제공하고 필요에 따라 서비스 클라이언트를 추가로 구성하세요.

이 코드 코드 조각은 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();

위 예시에서는 cryptoModeAuthenticatedEncryption로 설정합니다. 이는 V2 암호화 클라이언트가 V1 암호화 클라이언트가 작성한 객체를 읽을 수 있도록 하는 설정입니다. 클라이언트에 V1 클라이언트가 작성한 객체를 읽을 수 있는 기능이 필요하지 않은 경우에는 기본 설정인 StrictAuthenticatedEncryption를 대신 사용하는 것이 좋습니다.

V2 암호화 클라이언트 생성

AmazonS3 v2.EncryptionBuilder () 를 호출하여 V2 암호화 클라이언트를 구성할 수 있습니다. EncryptionClient

기존 V1 암호화 클라이언트를 모두 V2 암호화 클라이언트로 교체할 수 있습니다. V2 암호화 클라이언트는 V1 암호화 클라이언트가 작성한 객체를 항상 읽을 수 있습니다. 단, `를 사용하도록 V2 암호화 클라이언트를 구성하여 읽도록 허용하기만 하면 됩니다. AuthenticatedEncryption `cryptoMode

새 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

참고로 V2 암호화 cryptoMode 클라이언트에서는 EncryptionOnly지원되지 않습니다. 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 암호화 클라이언트를 사용하여 이전에 작성된 객체를 읽으려면 cryptoModeAuthenticatedEncryption로 설정합니다. 다음 코드 코드 조각은 이 설정으로 구성 객체를 생성하는 방법을 보여줍니다.

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

객체의 바이트 범위를 가져오도록 서비스 클라이언트를 구성합니다.

암호화된 S3 객체에서 get 바이트 범위를 지정할 수 있으려면 새 구성 설정 rangeGetMode을 활성화하세요. V2 암호화 클라이언트에서는 이 설정이 기본적으로 비활성화되어 있습니다. 활성화된 경우에도 범위 지정된 get는 클라이언트의 cryptoMode 설정에서 지원하는 알고리즘을 사용하여 암호화된 개체에서만 작동합니다. 자세한 내용은 AWS SDK for Java API 참조의 CryptoRangeGetMode 섹션을 참조하세요.

를 사용하여 V2 암호화 클라이언트를 사용하여 암호화된 Amazon S3 객체의 멀티파트 다운로드를 Amazon S3 TransferManager 수행하려는 경우 먼저 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);