本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

第 3 版中的 Amazon S3 加密用戶端遷移 (V2 到 V3) 適用於 PHP 的 AWS SDK

本主題說明如何將應用程式從 Amazon Simple Storage Service (Amazon S3) 加密用戶端的第 2 版 (V2) 遷移到第 3 版 (V3)，並確保在整個遷移過程中的應用程式可用性。第 3 版推出具有金鑰承諾和承諾政策的 AES GCM，以增強安全性並防止資料金鑰竄改。

遷移概觀

此遷移分為兩個階段：

1. 更新現有用戶端以讀取新格式。首先，將更新的 適用於 PHP 的 AWS SDK 版本部署到您的應用程式。這可讓現有的 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以防止資料金鑰遭到竄改。這可防止攻擊者在解密期間替換不同的資料金鑰，這可能會導致意外資料解密。

版本相容性：使用 加密的物件ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY只能由 V3 加密用戶端的 V3 和最新的 V2 實作解密。 Amazon S3 V1 用戶端無法解密使用此演算法加密的物件。

更新現有用戶端以讀取新格式

V3 加密用戶端使用舊版用戶端不支援的加密演算法和金鑰承諾功能。遷移的第一步是將 V2 解密用戶端更新為最新的 SDK 版本。完成此步驟後，應用程式的 V2 用戶端將能夠解密由 V3 加密用戶端加密的物件。請參閱以下有關 的每個安裝方法的詳細資訊 適用於 PHP 的 AWS SDK。

建置和安裝最新的 SDK 版本

若要完成此遷移，您必須使用包含 V3 加密用戶端支援的最新版本 aws/aws-sdk-php套件。

從 Composer 安裝

對於使用 Composer 安裝的專案，請在 Composer 檔案中，將 SDK 套件更新為最新版本的 SDK，然後執行下列命令。

composer update aws/aws-sdk-php

使用 Phar 或 Zip 檔案安裝

使用下列其中一種方法。請務必將更新的 SDK 檔案放在程式碼所需的位置，此位置由 要求陳述式決定。

對於使用 Phar 檔案安裝的專案，請下載更新的 檔案：aws.phar。

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

對於使用 Zip 檔案安裝的專案，請下載更新的 檔案：。

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

建置、安裝和部署應用程式

更新軟體開發套件後，請重建並重新部署您的應用程式，以確保所有元件都使用更新版本。此步驟對於確保您的 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 參數接受下列值：