AWS SDK for .NET V3가 유지 관리 모드로 전환되었습니다.

[AWS SDK for .NET V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html)로 마이그레이션하는 것이 좋습니다. 마이그레이션 방법에 대한 자세한 내용과 정보는 [유지 관리 모드 공지](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/)를 참조하세요.

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

# Amazon S3 암호화 클라이언트 마이그레이션(V2에서 V4로)
S3 암호화 클라이언트 마이그레이션(V2에서 V4로)S3 암호화 클라이언트 V4 마이그레이션

V2에서 V4로 마이그레이션하는 방법에 대한 정보가 추가되었습니다.

**참고**  
V1을 사용하고 V4로 마이그레이션하려면 먼저 V2로 마이그레이션해야 합니다. [Amazon S3 암호화 클라이언트 마이그레이션(V1에서 V2로)](s3-encryption-migration-v1-v2.md)을(를) 참조하세요.

이 주제에서는 Amazon Simple Storage Service(Amazon S3) 암호화 클라이언트 버전 2(V2)에서 버전 4(V4)로 애플리케이션을 마이그레이션하고 마이그레이션 프로세스 전반에 걸쳐 애플리케이션 가용성을 보장하는 방법을 보여줍니다. V4는 콘텐츠 암호화를 위한 키 커밋과 함께 AES-GCM을 사용하고 키 대체 공격에 대한 보안을 강화하기 위한 커밋 정책을 도입합니다.

V4 클라이언트는 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 패키지에서 사용할 수 있습니다.

**중요**  
**주요 변경 사항:** `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` 정책으로 구성된 V4 클라이언트는 V1 또는 V2 클라이언트로 암호화된 객체를 해독할 수 없습니다. 최신 V2 클라이언트만 키 커밋으로 V4-encrypted 복호화할 수 있습니다. `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` 정책으로 이동하기 전에 키 커밋이 활성화된 V4 클라이언트를 사용하여 기존 데이터를 모두 다시 암호화해야 합니다.

## V4 개념 이해


V4는 콘텐츠 암호화를 위한 키 커밋과 함께 AES-GCM을 사용하며 암호화된 데이터의 보호를 강화하는 주요 보안 개념을 도입합니다.

### 약정 정책


커밋 정책은 암호화 및 복호화 작업 중에 암호화 클라이언트가 키 커밋을 처리하는 방법을 제어합니다. V4는 세 가지 커밋 정책을 지원합니다.

`FORBID_ENCRYPT_ALLOW_DECRYPT`  
*암호화:* 커밋 없음  
*복호화:* 커밋되지 않는 객체 허용  
*보안:* 약정을 적용하지 않으며 변조를 허용할 수 있음  
*호환성:* 모든 V2 및 V4 구현은이 정책으로 암호화된 객체를 읽을 수 있습니다.

`REQUIRE_ENCRYPT_ALLOW_DECRYPT`  
*암호화:* 키 커밋 사용  
*복호화:* 커밋하는 객체와 커밋하지 않는 객체 모두 허용  
*보안:* 새 객체가 키 대체 공격으로부터 보호되고 이전 객체는 여전히 읽을 수 있음  
*호환성:* V4만이 정책을 지원합니다.

`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`(V4의 기본값)  
*암호화:* 키 커밋 사용  
*복호화:* 객체만 커밋  
*보안:* 최대 보안을 위한 전체 약정 적용  
*호환성:* V4만이 정책을 지원합니다.

### 키 커밋이 있는 AES GCM


V4는 향상된 보안을 제공하는 콘텐츠 암호화에 대한 키 커밋과 함께 AES-GCM을 사용합니다.
+ *변조 방지:* 암호화된 데이터에 키를 암호화 방식으로 바인딩하여 키 대체 공격으로부터 보호합니다.
+ *버전 호환성:* 키 커밋으로 암호화된 객체는 V4 클라이언트 및 최신 버전에서만 복호화할 수 있습니다.

**주의**  
프로덕션 환경에서 키 커밋 암호화를 활성화하기 전에 V2 클라이언트가 더 이상 사용되지 않으므로 객체를 복호화해야 하는 모든 애플리케이션이 V4 이상으로 업그레이드되었는지 확인합니다.

## V4 형식을 읽도록 기존 클라이언트 업데이트


V4 암호화 클라이언트는 이전 버전의 클라이언트가 지원하지 않는 암호화 알고리즘을 사용합니다. 마이그레이션의 첫 번째 단계는 새 V4 형식을 읽을 수 있도록 V2 클라이언트를 업데이트하는 것입니다. V4 

### NuGet 패키지 종속성 업데이트


V4 지원이 포함된 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) NuGet 패키지의 최신 버전을 사용하도록 애플리케이션을 업데이트합니다. 각 애플리케이션에서 다음 단계를 수행합니다.

1. 최신 [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) 패키지로 업데이트합니다. 프로젝트가 **AWSSDK.S3** 또는 **AWSSDK.KeyManagementService** 패키지에 직접 의존하는 경우 이러한 종속성을 업데이트하거나 제거하여 업데이트된 버전을 이 새 패키지와 함께 가져오도록 해야 합니다.

1. `using` 문이 올바른 네임스페이스를 참조하는지 확인합니다.

   ```
   using Amazon.Extensions.S3.Encryption;
   using Amazon.Extensions.S3.Encryption.Primitives;
   ```

1. 애플리케이션을 다시 빌드하고 다시 배포합니다.

기존 V2 클라이언트는 업데이트된 패키지로 계속 작동하며 V4 클라이언트로 암호화된 객체를 해독할 수 있습니다(사용된 커밋 정책에 따라 다름).

### 애플리케이션 빌드 및 배포


NuGet 패키지 종속성을 업데이트한 후:

1. 애플리케이션을 구축하여 모든 종속성이 올바르게 해결되도록 합니다.

1. 개발 환경에서 애플리케이션을 테스트하여 기존 기능이 계속 작동하는지 확인합니다.

1. 업데이트된 애플리케이션을 프로덕션 환경에 배포합니다.

이 업데이트를 통해 기존 V2 클라이언트는 V4 클라이언트가 암호화할 객체를 복호화하여 마이그레이션 프로세스 중에 호환성을 보장할 수 있습니다.

## V4 클라이언트로 마이그레이션


기존 클라이언트를 업데이트하여 새 암호화 형식을 읽은 후 V4 암호화 및 복호화 클라이언트를 사용하도록 애플리케이션을 안전하게 업데이트할 수 있습니다. V4 클라이언트는 기존의 암호화된 객체와의 호환성을 유지하면서 키 커밋을 통해 향상된 보안을 제공합니다.

### 4-Step 마이그레이션 프로세스


V2에서 V4로의 마이그레이션은 호환성과 보안을 보장하기 위해 구조화된 4단계 프로세스를 따릅니다. 각 단계는 다음 단계로 진행하기 전에 모든 애플리케이션에 배포해야 하는 특정 구성을 나타냅니다.

1. **0단계: V2 클라이언트(시작점)** - 기존 V2 구현

1. **1단계: V4 있는 V4 V2 ** V2-compatible 암호화 동작을 유지하면서 V4 클라이언트로 마이그레이션

1. **2단계: 키 커밋 쓰기가 포함된 V4 ** - 레거시 객체의 복호화를 허용하면서 키 커밋으로 암호화 시작

1. **3단계: 전체 적용이 포함된 V4 ** - 암호화 및 복호화 모두에 키 커밋 필요

### 0단계: V2 클라이언트(시작점)


이는 기존 V2 클라이언트 구성을 나타냅니다. 이 단계에서는 마이그레이션 전 시작 상태를 보여줍니다.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 0: V2 Client - Starting configuration
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext);

#pragma warning disable 0618
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
#pragma warning enable 0618

var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

### 1단계: V2 호환성이 있는 V4 V2


V2와 동일한 동작을 유지하면서 V4 클라이언트로 마이그레이션합니다. V2 이 단계에서는 `FORBID_ENCRYPT_ALLOW_DECRYPT` 정책을 사용하여 커밋 없이 암호화하고 모든 객체의 복호화를 허용합니다.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 1: V4 Client with V2 compatibility
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcm);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**동작:** 커밋 없는 암호화는 커밋 객체와 커밋되지 않은 객체를 모두 복호화할 수 있습니다. V2 동작과 동일합니다.

### 2단계: 키 커밋 쓰기가 포함된 V4


복호화를 위한 이전 버전과의 호환성을 유지하면서 키 커밋으로 암호화를 시작합니다. 이 단계에서는 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 정책을 사용합니다.

**주의**  
2단계를 배포하기 전에 키 커밋 암호화를 처리하기 위해 모든 리더가 1단계 이상으로 업데이트되었는지 확인합니다.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 2: V4 Client with key commitment writes
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**동작:** 커밋을 사용하여 암호화하며 커밋 객체와 커밋하지 않는 객체를 모두 복호화할 수 있습니다. 새 객체는 키 대체 공격으로부터 보호됩니다.

### 3단계: 전체 적용이 포함된 V4


암호화와 복호화 모두에 키 커밋이 필요합니다. 이 단계에서는 `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` 정책을 사용하여 보안을 극대화합니다.

**주의**  
3단계를 배포하기 전에 시스템의 모든 객체가 키 커밋으로 다시 암호화되었는지 확인합니다(2단계). 이 단계는 커밋 없이 암호화된 객체를 복호화하지 못합니다.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 3: V4 Client with full key commitment enforcement
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**동작:** 커밋으로 암호화하고 커밋으로 암호화된 객체만 복호화합니다. 키 대체 공격에 대한 최대 보안.

## 추가 구성 예제


이 섹션에서는 마이그레이션 중에 다양한 옵션으로 V4 클라이언트를 구성하는 추가 예제를 제공합니다.

### 레거시 지원 활성화


V4 클라이언트가 V1 및 V2 클라이언트로 암호화된 객체를 읽을 수 있도록 하려면 레거시 복호화를 허용하는 커밋 정책으로 클라이언트를 구성합니다.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

// Configure V4 client to read V1/V2 objects
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};

// This configuration allows:
// - Encryption: With commitment (secure)
// - Decryption: Both V2 (non-committing) and V4 (committing) objects
```

이전 클라이언트가 암호화한 객체를 복호화해야 하는 경우 마이그레이션 중에이 구성을 사용하고 새 객체를 향상된 보안으로 암호화합니다.

### 스토리지 방법 구성


V4는 암호화 메타데이터에 대해 두 가지 스토리지 방법을 지원합니다. 사용 사례에 가장 적합한 방법을 선택합니다.

**객체 메타데이터(기본값)**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata
```

**지침 파일**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.InstructionFile
};
// Encryption metadata is stored in a separate S3 object (instruction file)
```

다른 목적으로 객체 메타데이터를 보존`InstructionFile`해야 하거나 메타데이터 크기 제한이 있는 객체로 작업할 때 사용합니다.

### 커밋 정책 구성


보안 요구 사항 및 마이그레이션 단계에 따라 적절한 약정 정책을 선택합니다.

**마이그레이션 단계(V2 호환성)**

```
// For migration: encrypt without commitment, allow all decryption
var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT);
```

**전환 단계(권장)**

```
// For transition: encrypt with commitment, allow legacy decryption
var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);
```

**전체 보안 단계**

```
// For maximum security: require commitment for both encryption and decryption
var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
```

초기 마이그레이션 `FORBID_ENCRYPT_ALLOW_DECRYPT` 중에 로 시작하고 전환 단계를 `REQUIRE_ENCRYPT_ALLOW_DECRYPT` 위해 로 이동한 다음, 마지막으로 모든 클라이언트가 업그레이드되고 모든 객체가 커밋으로 다시 암호화되었을 `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` 때를 사용합니다.