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

# Amazon S3 암호화 클라이언트 마이그레이션(V1에서 V2로)
<a name="s3-encryption-migration-v1-v2"></a>

**참고**  
S3 암호화 클라이언트의 V2를 사용 중이고 V3로 마이그레이션하려는 경우 섹션을 참조하세요[Amazon S3 암호화 클라이언트 마이그레이션(V2에서 V3로)](s3-encryption-migration-v2-v3.md).

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

## 마이그레이션 개요
<a name="migration-overview-v1-v2"></a>

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

1. **새 형식을 읽도록 기존 클라이언트를 업데이트합니다.** 먼저 SDK AWS for Ruby의 업데이트된 버전을 애플리케이션에 배포합니다. 이렇게 하면 기존 V1 암호화 클라이언트에서 새 V2 클라이언트가 작성한 객체를 해독할 수 있습니다. 애플리케이션에서 다중 AWS SDKs 사용하는 경우 각 SDK를 별도로 업그레이드해야 합니다.

2. **암호화 및 복호화 클라이언트를 V2로 마이그레이션합니다.** 모든 V1 암호화 클라이언트가 새 형식을 읽을 수 있게 되면 기존 암호화 및 복호화 클라이언트를 각각의 V2 버전으로 마이그레이션할 수 있습니다.

## 새 형식을 읽기 위한 기존 클라이언트 업데이트
<a name="update-existing-clients-to-read-new-formats-v1-v2"></a>

V2 암호화 클라이언트는 이전 버전의 클라이언트에서 지원하지 않는 암호화 알고리즘을 사용합니다. 마이그레이션의 첫 번째 단계는 V1 복호화 클라이언트를 최신 SDK 릴리스로 업데이트하는 것입니다. 이 단계를 완료하면 애플리케이션의 V1 클라이언트가 V2 암호화 클라이언트로 암호화된 객체를 해독할 수 있습니다. AWS SDK for Ruby의 각 메이저 버전에 대한 세부 정보는 아래를 참조하세요.

### AWS SDK for Ruby 버전 3 업데이트
<a name="update-aws-sdk-for-ruby-version-3-v1-v2"></a>

버전 3은 AWS SDK for Ruby의 최신 버전입니다. 이 마이그레이션을 완료하려면 `aws-sdk-s3`의 버전 1.76.0 이상을 사용해야 합니다.

 **명령줄에서 설치** 

`aws-sdk-s3` gem을 설치하는 프로젝트의 경우 버전 옵션을 사용하여 최소 버전 1.76.0이 설치되어 있는지 확인합니다.

```
gem install aws-sdk-s3 -v '>= 1.76.0'
```

 **Gemfile 사용** 

Gemfile을 사용하여 종속성을 관리하는 프로젝트의 경우 `aws-sdk-s3` gem의 최소 버전을 1.76.0으로 설정합니다. 예제:

```
gem 'aws-sdk-s3', '>= 1.76.0'
```

1. Gemfile을 수정합니다.

1. `bundle update aws-sdk-s3`을 실행합니다. 버전을 확인하려면 `bundle info aws-sdk-s3`을 실행합니다.

### AWS SDK for Ruby 버전 2 업그레이드
<a name="upgdate-aws-sdk-for-ruby-version-2-v1-v2"></a>

 AWS SDK for Ruby 버전 2는 2021년 11월 21일에 [유지 관리 모드로](https://aws.amazon.com/blogs/developer/deprecation-schedule-for-aws-sdk-for-ruby-v2/) 전환됩니다. 이 마이그레이션을 완료하려면 aws-sdk gem의 버전 2.11.562 이상을 사용해야 합니다.

 **명령줄에서 설치** 

`aws-sdk` gem을 설치하는 프로젝트의 경우 명령줄에서 버전 옵션을 사용하여 최소 버전 2.11.562가 설치되어 있는지 확인합니다.

```
gem install aws-sdk -v '>= 2.11.562'
```

 **Gemfile 사용** 

Gemfile을 사용하여 종속성을 관리하는 프로젝트의 경우 `aws-sdk` gem의 최소 버전을 2.11.562로 설정합니다. 예제:

```
gem 'aws-sdk', '>= 2.11.562'
```

1. Gemfile을 수정합니다. Gemfile.lock 파일이 있는 경우 해당 파일을 삭제하거나 업데이트합니다.

1. `bundle update aws-sdk`을 실행합니다. 버전을 확인하려면 `bundle info aws-sdk`을 실행합니다.

## 암호화 및 복호화 클라이언트를 V2로 마이그레이션
<a name="migrate-encryption-and-decryption-clients-to-v2-v1-v2"></a>

새 암호화 형식을 읽도록 클라이언트를 업데이트한 후 애플리케이션을 V2 암호화 및 복호화 클라이언트로 업데이트할 수 있습니다. 다음 단계는 V1에서 V2로 코드를 성공적으로 마이그레이션하는 방법을 보여줍니다.

V2 암호화 클라이언트를 사용하도록 코드를 업데이트하기 전에 이전 단계를 따르고 `aws-sdk-s3` gem 버전 2.11.562 이상을 사용하고 있는지 확인합니다.

**참고**  
AES-GCM으로 해독할 때는 해독된 데이터를 사용하기 전에 전체 객체를 끝까지 읽습니다. 이는 암호화되었던 객체이므로 객체가 수정되지 않았는지 확인하기 위함입니다.

### V2 암호화 클라이언트 구성
<a name="configuring-v2-encryption-clients-v1-v2"></a>

*EncryptionV2::Client*에는 추가 구성이 필요합니다. 자세한 구성 정보는 [EncryptionV2::Client 설명서](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/EncryptionV2/Client.html#initialize-instance_method) 또는 이 주제의 뒷부분에 제공된 예제를 참조하세요.

1. **키 랩 방법 및 콘텐츠 암호화 알고리즘은 클라이언트 구성 시 지정해야 합니다.** 새 `EncryptionV2::Client`를 만들 때는 `key_wrap_schema` 및 `content_encryption_schema`에 대한 값을 제공해야 합니다.

 `key_wrap_schema` -를 사용하는 경우 AWS KMS로 설정해야 합니다`:kms_context`. 대칭(AES) 키를 사용하는 경우 이 값을 `:aes_gcm`으로 설정해야 합니다. 비대칭(RSA) 키를 사용하는 경우 이 값을 `:rsa_oaep_sha1`으로 설정해야 합니다.

 `content_encryption_schema` - 이 값은 *:aes\_gcm\_no\_padding*으로 설정해야 합니다.

2. **security\_profile은 클라이언트 구성 시 지정해야 합니다.** 새 `EncryptionV2::Client`를 만들 때는 `security_profile`에 대한 값을 제공해야 합니다. *security\_profile* 파라미터는 이전 V1 `Encryption::Client`를 사용하여 작성된 객체를 읽기 위한 지원을 결정합니다. *:v2* 및 *:v2\_and\_legacy*라는 두 값이 있습니다. 마이그레이션을 지원하려면 `security_profile`을 *:v2\_and\_legacy*로 설정합니다. *:v2*는 새 애플리케이션 개발에만 사용하세요.

3. **AWS KMS key ID는 기본적으로 적용됩니다.** V1,에서 클라이언트`Encryption::Client`를 생성하는 데 `kms_key_id` 사용된가에 제공되지 않았습니다 AWS KMS `Decrypt call`.는 메타데이터에서이 정보를 가져와 대칭 사이퍼텍스트 BLOB에 추가할 AWS KMS 수 있습니다. V2, E`ncryptionV2::Client`에서는 *kms\_key\_id*가 AWS KMS Decrypt 호출로 전달되고 객체를 암호화하는 데 사용된 키와 일치하지 않으면 호출이 실패합니다. 이전에 코드가 특정 `kms_key_id`를 설정하지 않았다면 클라이언트 생성 시 `kms_key_id: :kms_allow_decrypt_with_any_cmk`를 설정하거나 `get_object` 호출 시 `kms_allow_decrypt_with_any_cmk: true`를 설정합니다.

### 예: 대칭(AES) 키 사용
<a name="example-using-a-symmetric-aes-key-v1-v2"></a>

 **사전 마이그레이션** 

```
client = Aws::S3::Encryption::Client.new(encryption_key: aes_key)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)
```

 **마이그레이션 후** 

```
client = Aws::S3::EncryptionV2::Client.new(
  encryption_key: rsa_key,
  key_wrap_schema: :rsa_oaep_sha1, # the key_wrap_schema must be rsa_oaep_sha1 for asymmetric keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
 )
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key) # No changes
```

### 예: kms\_key\_id AWS KMS 와 함께 사용
<a name="example-using-aws-kms-with-kms-key-id-v1-v2"></a>

 **사전 마이그레이션** 

```
client = Aws::S3::Encryption::Client.new(kms_key_id: kms_key_id)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)
```

 **마이그레이션 후** 

```
client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key) # No change
```

### 예: kms\_key\_id AWS KMS 없이 사용
<a name="example-using-aws-kms-without-kms-key-id-v1-v2"></a>

 **사전 마이그레이션** 

```
client = Aws::S3::Encryption::Client.new(kms_key_id: kms_key_id)
client.put_object(bucket: bucket, key: key, body: secret_data)
resp = client.get_object(bucket: bucket, key: key)
```

 **마이그레이션 후** 

```
client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: kms_key_id,
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
client.put_object(bucket: bucket, key: key, body: secret_data)  # No changes
resp = client.get_object(bucket: bucket, key: key, kms_allow_decrypt_with_any_cmk: true) # To allow decrypting with any cmk
```

 **마이그레이션 후 대안** 

S2 암호화 클라이언트를 사용하여 객체를 읽고 해독만 하는 경우(작성 및 암호화하지 않음) 이 코드를 사용합니다.

```
client = Aws::S3::EncryptionV2::Client.new(
  kms_key_id: :kms_allow_decrypt_with_any_cmk, # set kms_key_id to allow all get_object requests to use any cmk
  key_wrap_schema: :kms_context, # the key_wrap_schema must be kms_context for KMS keys
  content_encryption_schema: :aes_gcm_no_padding,
  security_profile: :v2_and_legacy # to allow reading/decrypting objects encrypted by the V1 encryption client
)
resp = client.get_object(bucket: bucket, key: key) # No change
```