기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# Amazon S3 암호화 클라이언트 마이그레이션(V1에서 V2로)
**참고**
Amazon S3 암호화 클라이언트의 V2를 사용 중이고 V3로 마이그레이션하려는 경우 섹션을 참조하세요[Amazon S3 암호화 클라이언트 마이그레이션(V2에서 V3로)](s3-encryption-migration-v2-v3.md).
이 주제는 애플리케이션을 Amazon Simple Storage Service(Amazon S3) 암호화 클라이언트 버전 1(V1)에서 버전 2(V2)로 마이그레이션하고 마이그레이션 프로세스 전반에 걸쳐 애플리케이션 가용성을 보장하는 방법을 설명합니다.
## 마이그레이션 개요
이 마이그레이션은 다음 두 단계로 진행됩니다.
1. **새 형식을 읽도록 기존 클라이언트를 업데이트하세요.** 먼저, AWS SDK for C\+\+ 의 업데이트된 버전을 애플리케이션에 배포합니다. 이렇게 하면 기존 V1 암호화 클라이언트가 새 V2 클라이언트가 작성한 객체를 해독할 수 있습니다. 애플리케이션에서 다중 AWS SDKs 사용하는 경우 각 SDK를 별도로 업그레이드해야 합니다.
2. **암호화 및 복호화 클라이언트를 V2로 마이그레이션합니다.** 모든 V1 암호화 클라이언트가 새 형식을 읽을 수 있게 되면 기존 암호화 및 복호화 클라이언트를 각각의 V2 버전으로 마이그레이션할 수 있습니다.
## 새 형식을 읽기 위한 기존 클라이언트 업데이트
먼저 기존 클라이언트를 최신 SDK 릴리스로 업데이트해야 합니다. 이 단계를 완료한 후 애플리케이션의 V1 클라이언트는 애플리케이션의 코드 기반을 업데이트하지 않고도 V2 암호화 클라이언트로 암호화된 객체를 복호화할 수 있습니다.
### 의 최신 버전 빌드 및 설치 AWS SDK for C\+\+
**소스에서 SDK를 사용하는 애플리케이션**
소스 AWS SDK for C\+\+ 에서를 빌드하고 설치하는 경우 GitHub의 [`aws/aws-sdk-cpp`](https://github.com/aws/aws-sdk-cpp)에서 SDK 소스를 다운로드하거나 복제합니다. 그런 다음 일반 빌드 및 설치 단계를 반복합니다.
1.8.x 이전 버전 AWS SDK for C\+\+ 에서 업그레이드하는 경우 각 메이저 버전에 도입된 주요 변경 사항은이 [변경 로그](https://github.com/aws/aws-sdk-cpp/blob/master/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
```
버전은 1.8.24 이상이어야 합니다.
에서 Vcpkg을 사용하는 방법에 대한 자세한 내용은 섹션을 AWS SDK for C\+\+참조하세요[패키지 관리자 AWS SDK for C\+\+ 에서 가져오기](sdk-from-pm.md).
### 애플리케이션 빌드, 설치 및 배포
애플리케이션이에 정적으로 연결되어 있는 경우 애플리케이션에서 AWS SDK for C\+\+코드 변경이 필요하지 않지만 최신 SDK 변경 사항을 사용하려면 애플리케이션을 다시 빌드해야 합니다. 동적 연결의 경우에는 이 단계가 필요하지 않습니다.
애플리케이션의 종속성 버전을 업그레이드하고 애플리케이션 기능을 확인한 후 플릿에 애플리케이션 배포를 진행합니다. 애플리케이션 배포가 완료되면 V2 암호화 및 복호화 클라이언트를 사용하도록 애플리케이션을 마이그레이션하는 다음 단계로 진행할 수 있습니다.
## 암호화 및 복호화 클라이언트를 V2로 마이그레이션
다음 단계는 Amazon S3 암호화 클라이언트를 V1에서 V2로 코드를 성공적으로 마이그레이션하는 방법을 보여줍니다. 코드 변경이 필요하므로에 대한 정적 또는 동적 연결 여부에 관계없이 애플리케이션을 다시 빌드해야 합니다 AWS SDK for C\+\+.
### 새 암호화 자료 사용
V2 Amazon S3 암호화 클라이언트와 V2 암호화 구성에서는 다음 암호화 자료가 더 이상 사용되지 않습니다.
+ `SimpleEncryptionMaterials`
+ `KMSEncryptionMaterials`
다음 보안 암호화 자료로 대체되었습니다.
+ `SimpleEncryptionMaterialsWithGCMAAD`
+ `KMSWithContextEncryptionMaterials`
V2 S3 암호화 클라이언트를 구성하려면 다음과 같은 코드 변경이 필요합니다.
+
**S3 암호화 클라이언트를 생성할 때 `KMSEncryptionMaterials`를 사용하는 경우:**
+ V2 S3 암호화 클라이언트를 생성할 때 `KMSEncryptionMaterials`를 `KMSWithContextEncryptionMaterials`로 바꾸고 V2 암호화 구성에 이를 지정합니다.
+ V2 Amazon S3 암호화 클라이언트를 사용하여 객체를 배치할 때는 CEK 암호화를 위한 KMS 컨텍스트로 문자열-문자열 컨텍스트 맵을 명시적으로 제공해야 합니다. 이 맵은 비어 있을 수도 있습니다.
+
**S3 암호화 클라이언트를 생성할 때 `SimpleEncryptionMaterials`를 사용하는 경우:**
+ V2 Amazon S3 암호화 클라이언트를 생성할 때 `SimpleEncryptionMaterials`를 `SimpleEncryptionMaterialsWithGCMAAD`로 바꾸고 V2 암호화 구성에 이를 지정합니다.
+ V2 Amazon S3 암호화 클라이언트를 사용하여 객체를 배치할 때는 빈 문자열-문자열 컨텍스트 맵을 명시적으로 제공해야 합니다. 그렇지 않으면 SDK에서 오류를 반환합니다.
**예: KMS/KMSWithContext 키 래핑 알고리즘 사용**
*마이그레이션 전(KMS 키 래핑)*
```
auto materials = Aws::MakeShared("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest);
```
*마이그레이션 후(KMSWithContext 키 래핑)*
```
auto materials = Aws::MakeShared("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
Aws::Map kmsContextMap;
kmsContextMap.emplace("client", "aws-sdk-cpp");
kmsContextMap.emplace("version", "1.8.0");
encryptionClient.PutObject(putObjectRequest, kmsContextMap /* could be empty as well */);
```
**예: AES/AES-GCM 키 래핑 알고리즘 사용**
*마이그레이션 전(AES 키 래핑)*
```
auto materials = Aws::MakeShared("s3Encryption", HashingUtils::Base64Decode(AES_MASTER_KEY_BASE64));
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest);
```
*마이그레이션 후(AES-GCM 키 래핑)*
```
auto materials = Aws::MakeShared("s3EncryptionV2", HashingUtils::Base64Decode(AES_MASTER_KEY_BASE64));
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the putObjectRequest object.
encryptionClient.PutObject(putObjectRequest, {} /* must be an empty map */);
```
## 추가 예제
다음 예제는 V1에서 V2로의 마이그레이션과 관련된 특정 사용 사례를 해결하는 방법을 보여줍니다.
### 레거시 Amazon S3 암호화 클라이언트로 암호화된 객체 복호화
기본적으로 V2 Amazon S3 암호화 클라이언트를 사용하여 더 이상 사용되지 않는 키 래핑 알고리즘 또는 더 이상 사용되지 않는 콘텐츠 암호화 스키마로 암호화된 객체를 해독할 수 없습니다.
다음 키 래핑 알고리즘은 더 이상 사용되지 않습니다.
+ `KMS`
+ `AES_KEY_WRAP`
다음 콘텐츠 암호화 스키마는 더 이상 사용되지 않습니다.
+ `CBC`
+ `CTR`
에서 레거시 Amazon S3 암호화 클라이언트 AWS SDK for C\+\+ 를 사용하여 객체를 암호화하는 경우 다음과 같은 경우 더 이상 사용되지 않는 메서드를 사용할 수 있습니다.
+ `SimpleEncryptionMaterials` 또는 `KMSEncryptionMaterials`를 사용한 경우.
+ 암호화 구성에서 `ENCRYPTION_ONLY`로 `Crypto Mode`를 사용한 경우
더 이상 사용되지 않는 키 래핑 알고리즘이나 더 이상 사용되지 않는 콘텐츠 암호화 스키마로 암호화된 객체를 V2 Amazon S3 암호화 클라이언트를 사용하여 복호화하려면 V2 암호화 구성에서 `SecurityProfile`의 기본값을 `V2`에서 `V2_AND_LEGACY`로 재정의해야 합니다.
**예제**
*사전 마이그레이션*
```
auto materials = Aws::MakeShared("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);
```
*마이그레이션 후*
```
auto materials = Aws::MakeShared("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
cryptoConfig.SetSecurityProfile(SecurityProfile::V2_AND_LEGACY);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);
```
### 범위 지정으로 객체 복호화
레거시 Amazon S3 암호화 클라이언트를 사용하면 S3 객체를 복호화할 때 수신할 바이트 범위를 지정할 수 있습니다. V2 Amazon S3 암호화 클라이언트에서 이 기능은 기본적으로 `DISABLED`입니다. 따라서 V2 암호화 구성에서 `RangeGetMode`의 기본값을 `DISABLED`에서 `ALL`로 재정의해야 합니다.
**예제**
*사전 마이그레이션*
```
auto materials = Aws::MakeShared("s3Encryption", CUSTOMER_MASTER_KEY_ID);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
getObjectRequest.WithRange("bytes=38-75");
encryptionClient.GetObject(getObjectRequest);
```
*마이그레이션 후*
```
auto materials = Aws::MakeShared("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
CryptoConfigurationV2 cryptoConfig(materials);
cryptoConfig.SetUnAuthenticatedRangeGet(RangeGetMode::ALL);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
getObjectRequest.WithRange("bytes=38-75");
encryptionClient.GetObject(getObjectRequest);
```
### CMK를 사용하여 객체 복호화
`KMSWithContextEncryptionMaterials`로 암호화된 객체를 복호화할 때 V2 Amazon S3 암호화 클라이언트는 빈 마스터 키를 제공하여 KMS에서 적절한 CMK를 찾도록 할 수 있습니다. 이 기능은 기본적으로 `DISABLED`입니다. KMS 암호화 자료에 대해 `SetKMSDecryptWithAnyCMK(true)`를 직접적으로 호출하여 명시적으로 구성해야 합니다.
**예제**
*사전 마이그레이션*
```
auto materials = Aws::MakeShared("s3Encryption", ""/* provide an empty KMS Master Key*/);
CryptoConfiguration cryptoConfig;
S3EncryptionClient encryptionClient(materials, cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);
```
*마이그레이션 후*
```
auto materials = Aws::MakeShared("s3EncryptionV2", ""/* provide an empty KMS Master Key*/);
materials.SetKMSDecryptWithAnyCMK(true);
CryptoConfigurationV2 cryptoConfig(materials);
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Code snippet here to setup the getObjectRequest object.
encryptionClient.GetObject(getObjectRequest);
```
이러한 모든 마이그레이션 시나리오에 대한 전체 코드는 Github의 [Amazon S3 암호화 예제](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/s3encryption)를 참조하세요.