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

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

**참고**  
Amazon S3 암호화 클라이언트 버전 2(V2)를 사용하고 버전 3(V3)으로 마이그레이션하려는 경우 섹션을 참조하세요[AWS SDK for PHP 버전 3의 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. **새 형식을 읽도록 기존 클라이언트를 업데이트하세요.** 먼저, AWS SDK for PHP 의 업데이트된 버전을 애플리케이션에 배포합니다. 이렇게 하면 기존 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 PHP의 각 주요 버전에 대한 세부 정보는 아래를 참조하세요.

### AWS SDK for PHP 버전 3 업그레이드
<a name="upgrading-aws-sdk-for-php-version-3-v1-v2"></a>

버전 3은 AWS SDK for PHP의 최신 버전이 아닙니다. 이 마이그레이션을 완료하려면 패키지 버전 3.148.0 이상을 사용해야 합니다. `aws/aws-sdk-php` 

 **명령줄에서 설치** 

Composer를 사용하여 설치한 프로젝트의 경우 Composer 파일에서 SDK 패키지를 SDK 버전 3.148.0으로 업데이트한 후 다음 명령을 실행합니다.

```
composer update aws/aws-sdk-php
```

 **Phar 또는 ZIP 파일을 사용하여 설치** 

다음 방법 중 하나를 사용합니다. 업데이트된 SDK 파일은 require 문에 의해 결정되는 코드에서 요구하는 위치에 배치해야 합니다.

Phar 파일을 사용하여 설치한 프로젝트의 경우 업데이트된 파일을 다운로드하세요. [`aws.phar`](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar) 

```
<?php
  require '/path/to/aws.phar';
?>
```

Zip 파일을 사용하여 설치한 프로젝트의 경우 업데이트된 파일을 다운로드하세요. [``](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip) 

```
<?php
  require '/path/to/aws-autoloader.php';
?>
```

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

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

### V2 클라이언트로 업데이트하기 위한 요구 사항
<a name="requirements-for-updating-to-v2-clients-v1-v2"></a>

1. AWS KMS 암호화 컨텍스트는 `S3EncryptionClientV2::putObject` 및 `S3EncryptionClientV2::putObjectAsync` 메서드로 전달되어야 합니다. AWS KMS 암호화 컨텍스트는 키-값 페어의 결합 배열로, AWS KMS 키 암호화를 위해 암호화 컨텍스트에 추가해야 합니다. 추가 컨텍스트가 필요하지 않은 경우 빈 배열을 전달할 수 있습니다.

2. `@SecurityProfile`은 `S3EncryptionClientV2`의 `getObject` 및 `getObjectAsync` 메서드에 전달되어야 합니다. `@SecurityProfile`은 `getObject...` 메서드의 새로운 필수 파라미터입니다. `'V2'`로 설정하면 V2 호환 형식으로 암호화된 객체만 해독할 수 있습니다. 이 파라미터를 `'V2_AND_LEGACY'`로 설정하면 V1 호환 형식으로 암호화된 객체도 해독할 수 있습니다. 마이그레이션을 지원하려면 `@SecurityProfile`을 `'V2_AND_LEGACY'`로 설정합니다. 새 애플리케이션 개발에만 `'V2'`를 사용하세요.

3. (선택 사항) `S3EncryptionClientV2::getObject`에 `@KmsAllowDecryptWithAnyCmk` 파라미터를 포함시키고 `@KmsAllowDecryptWithAnyCmk` 호출에 `S3EncryptionClientV2::getObjectAsync* methods.` 새 파라미터가 추가되었습니다. KMS 키를 제공하지 않고도 암호 해독이 가능하도록 이 파라미터를 `true`에 설정합니다. 기본값은 `false`입니다.

4. V2 클라이언트를 사용한 암호 해독의 경우 `@KmsAllowDecryptWithAnyCmk` 파라미터가 `"getObject..."` 메서드 호출에 대해 `true`에 설정되지 않은 경우 `KmsMaterialsProviderV2` 생성자에 `kms-key-id`를 제공해야 합니다.

## 마이그레이션 예제
<a name="migration-examples-v1-v2"></a>

### 예 1: V2 클라이언트로 마이그레이션
<a name="example-1-migrating-to-v2-clients-v1-v2"></a>

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

```
use Aws\S3\Crypto\S3EncryptionClient;
use Aws\S3\S3Client;

$encryptionClient = new S3EncryptionClient(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);
```

 **마이그레이션 후** 

```
use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;

$encryptionClient = new S3EncryptionClientV2(
    new S3Client([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ])
);
```

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

**참고**  
이 예제에서는 예제 1에 정의된 가져오기와 변수를 사용합니다. 예를 들어 `$encryptionClient`입니다.

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

```
use Aws\Crypto\KmsMaterialsProvider;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProvider(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);
```

 **마이그레이션 후** 

```
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV2(
    new KmsClient([
        'profile' => 'default',
        'region' => 'us-east-1',
        'version' => 'latest',
    ]),
    $kmsKeyId
);

$bucket = 'the-bucket-name';
$key = 'the-file-name';
$cipherOptions = [
    'Cipher' => 'gcm',
    'KeySize' => 256,
];

$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);
$result = $encryptionClient->getObject([
    '@KmsAllowDecryptWithAnyCmk' => true,
    '@SecurityProfile' => 'V2_AND_LEGACY',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);
```