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

AWS SDK for PHP 버전 3의 Amazon S3 암호화 클라이언트 마이그레이션(V2에서 V3로)

이 주제에서는 Amazon Simple Storage Service(Amazon S3) 암호화 클라이언트 버전 2(V2)에서 버전 3(V3)으로 애플리케이션을 마이그레이션하고 마이그레이션 프로세스 전반에 걸쳐 애플리케이션 가용성을 보장하는 방법을 보여줍니다. 버전 3에는 보안을 강화하고 데이터 키 변조로부터 보호하기 위한 키 커밋 및 커밋 정책이 포함된 AES GCM이 도입되었습니다.

마이그레이션 개요

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

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

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

V3 개념 이해

Amazon S3 암호화 클라이언트 버전 3에는 커밋 정책과 키 커밋 알고리즘이 포함된 AES GCM이라는 두 가지 주요 보안 개선 사항이 도입되었습니다. 이러한 개념을 이해하는 것은 성공적인 마이그레이션에 필수적입니다.

약정 정책

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

키 커밋이 있는 AES GCM

키 커밋이 포함된 AES GCM(ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) 알고리즘은 V3에 도입된 새로운 암호화 알고리즘으로, 데이터 키 변조 공격으로부터 보호합니다.

보안 강화: 데이터 키를 암호화된 콘텐츠에 암호화 방식으로 바인딩하여 데이터 키 변조를 ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY 방지합니다. 이렇게 하면 공격자가 복호화 중에 다른 데이터 키를 대체하지 못하여 의도하지 않은 데이터가 복호화될 수 있습니다.

버전 호환성: 로 암호화된 객체는 V3 및 Amazon S3 암호화 클라이언트의 최신 V2 구현에서만 해독할 ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY 수 있습니다. V1 클라이언트는이 알고리즘으로 암호화된 객체를 해독할 수 없습니다.

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

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

최신 SDK 버전 빌드 및 설치

이 마이그레이션을 완료하려면 V3 암호화 클라이언트 지원이 포함된 aws/aws-sdk-php 패키지의 최신 버전을 사용해야 합니다.

Composer에서 설치

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

composer update aws/aws-sdk-php

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

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

Phar 파일을 사용하여 설치한 프로젝트의 경우 업데이트된 파일을 다운로드하세요. aws.phar

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

Zip 파일을 사용하여 설치한 프로젝트의 경우 업데이트된 파일을 다운로드하세요.

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

애플리케이션 구축, 설치 및 배포

SDK를 업데이트한 후 애플리케이션을 다시 빌드하고 배포하여 모든 구성 요소가 업데이트된 버전을 사용하고 있는지 확인합니다. 이 단계는 V2 클라이언트가 V3 클라이언트로 암호화된 객체를 읽을 수 있도록 하는 데 매우 중요합니다.

조직의 표준 배포 절차에 따라 업데이트된 애플리케이션을 롤아웃합니다. 암호화 및 복호화 클라이언트를 V3로 마이그레이션하기 전에 애플리케이션의 모든 인스턴스가 업데이트되었는지 확인합니다.

배포 후 애플리케이션이 여전히 기존 객체를 복호화할 수 있고 정상 작업 중에 오류가 발생하지 않는지 확인합니다. 이렇게 하면 SDK 업데이트가 성공했으며 애플리케이션이 다음 마이그레이션 단계를 수행할 준비가 되었음을 확인할 수 있습니다.

암호화 및 복호화 클라이언트를 V3로 마이그레이션

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

V3 암호화 클라이언트 사용

V3는 S3EncryptionClientV3 클래스 및를 도입KmsMaterialsProviderV3하여 V2에 상응하는 클래스를 대체합니다. V3의 주요 차이점은 다음과 같습니다.

예: KMS 암호화를 사용하여 V2에서 V3로 마이그레이션

마이그레이션 전(V2)

use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

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

$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',
   '@CommitmentPolicy' => 'FORBID_ENCRYPT_ALLOW_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

마이그레이션 중(이전 버전과의 호환성을 갖춘 V3)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   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,
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

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

마이그레이션 후(키 커밋이 포함된 V3)

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;
 
// Create V3 encryption client
$encryptionClient = new S3EncryptionClientV3(
   new S3Client([
      'profile' => 'default',
      'region' => 'us-east-1',
      'version' => 'latest',
   ])
);

// Create encryption materials
$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProviderV3(
   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,
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@KmsEncryptionContext' => ['context-key' => 'context-value'],
   'Bucket' => $bucket,
   'Key' => $key,
   'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

$result = $encryptionClient->getObject([
   '@SecurityProfile' => 'V3',
   // Use the commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
   // This encrypts with key commitment and does not decrypt V2 objects
   '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
   '@MaterialsProvider' => $materialsProvider,
   '@CipherOptions' => $cipherOptions,
   'Bucket' => $bucket,
   'Key' => $key,
]);

V3의 주요 차이점:

추가 예제

다음 예제에서는 마이그레이션 프로세스를 관리하고 암호화 동작을 제어하는 데 도움이 되는 V3에서 사용할 수 있는 추가 구성 옵션을 보여줍니다.

레거시 지원 사용

마이그레이션 중에 Amazon S3 암호화 클라이언트의 V1 또는 V2로 암호화된 객체를 복호화해야 할 수 있습니다. @SecurityProfile 파라미터는 V3 클라이언트가 복호화할 수 있는 암호화 버전을 제어합니다.

이 구성을 사용해야 하는 경우: 애플리케이션이 V1 또는 V2 클라이언트로 암호화된 객체를 읽어야 하는 경우 'V3_AND_LEGACY' 보안 프로필을 사용합니다. 이는 버킷에 이전 암호화된 객체와 새 암호화된 객체가 혼합되어 있는 마이그레이션 기간 동안 흔히 발생합니다.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

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

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

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

// Decrypt objects encrypted with V1, V2, or V3
$result = $encryptionClient->getObject([
    '@SecurityProfile' => 'V3_AND_LEGACY',
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_ALLOW_DECRYPT',
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);

@SecurityProfile 파라미터는 다음 값 중 하나를 받습니다.

스토리지 방법 구성

Amazon S3 암호화 클라이언트는 객체의 메타데이터 헤더 또는 별도의 명령 파일에 두 가지 방식으로 암호화 메타데이터를 저장할 수 있습니다. @MetadataStrategy 파라미터는 사용되는 스토리지 방법을 제어합니다.

이 구성을 사용하는 경우: 원본 객체 메타데이터를 보존'INSTRUCTION_FILE'해야 하거나 메타데이터 크기 제약이 있는 객체로 작업할 때 사용합니다. 암호화 메타데이터를 객체와 함께 저장할 수 있는 더 간단한 배포에는 'METADATA' (기본값)를 사용합니다.

use Aws\S3\Crypto\S3EncryptionClientV3;
use Aws\S3\S3Client;
use Aws\Crypto\KmsMaterialsProviderV3;
use Aws\Kms\KmsClient;

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

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

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

// Store encryption metadata in a separate instruction file
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'INSTRUCTION_FILE',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

// Store encryption metadata in object headers (default)
$encryptionClient->putObject([
    '@MaterialsProvider' => $materialsProvider,
    '@CipherOptions' => $cipherOptions,
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => 'METADATA',
    '@KmsEncryptionContext' => ['context-key' => 'context-value'],
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

@MetadataStrategy 파라미터는 다음 값 중 하나를 받습니다.