翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS SDK for PHP バージョン 3 での Amazon S3 暗号化クライアント移行 (V2 から V3)

このトピックでは、Amazon Simple Storage Service (Amazon S3) 暗号化クライアントのバージョン 2 (V2) からバージョン 3 (V3) にアプリケーションを移行し、移行プロセス全体でアプリケーションの可用性を確保する方法について説明します。バージョン 3 では、セキュリティを強化し、データキーの改ざんから保護するために、キーコミットメントとコミットメントポリシーを含む AES GCM が導入されています。

移行の概要

この移行は 2 つのフェーズから構成されます。

1. 新しいフォーマットを読み取るために既存のクライアントを更新します。まず、更新されたバージョンの AWS SDK for PHP をアプリケーションにデプロイします。これにより、既存の V2 暗号化クライアントは、新しい V3 クライアントによって書き込まれたオブジェクトを復号できます。アプリケーションで AWS SDKs、各 SDK を個別にアップグレードする必要があります。

2. 暗号化クライアントと復号クライアントを V3 に移行します。すべての V2 暗号化クライアントが新しい形式を読み取れるようになったら、既存の暗号化クライアントと復号クライアントをそれぞれの V3 バージョンに移行できます。

V3 の概念について

Amazon S3 暗号化クライアントのバージョン 3 では、コミットメントポリシーとキーコミットメントアルゴリズムを使用した AES GCM の 2 つの主要なセキュリティ機能強化が導入されています。これらの概念を理解することは、移行を成功させるために不可欠です。

コミットメントポリシー

コミットメントポリシーは、暗号化および復号オペレーション中に暗号化クライアントがキーコミットメントを処理する方法を制御します。バージョン 3 には 3 つのポリシーオプションがあります。

AES GCM とキーコミットメント

AES GCM with Key Commitment (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 暗号化クライアントは、オブジェクトのメタデータヘッダーまたは別の命令ファイルという 2 つの方法で暗号化メタデータを保存できます。@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 パラメータには、次の値を指定できます。