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

第 3 版中的 Amazon S3 用戶端加密 適用於 PHP 的 AWS SDK

使用用戶端加密時，會直接在您的環境中將資料加密和解密。這表示此資料在傳輸至 Amazon S3 之前會先加密，而且您不需要依賴外部服務來為您處理加密。對於新的實作，我們建議在 S3EncryptionClientV3和 S3EncryptionMultipartUploaderV3 以及已棄用 S3EncryptionClientV2S3EncryptionMultipartUploaderV2和 上使用 S3EncryptionClient和 S3EncryptionMultipartUploader。建議仍然使用已棄用版本的舊實作嘗試遷移。 會S3EncryptionClientV3維持對使用舊版 加密資料的解密支援S3EncryptionClient。

適用於 PHP 的 AWS SDK 實作信封加密，並使用 OpenSSL 進行加密和解密。這項實作功能可與符合其功能支援的其他開發套件互通，也相容於軟體開發套件採用 promise 的非同步工作流程。

遷移指南

對於嘗試從已棄用用戶端遷移到新用戶端的人員，這裡有從 v1 遷移到 v2 的遷移指南，https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-encryption-migration-v1-v2-section.html以及從 v2 遷移到 v3 的遷移指南。

設定

若要開始使用用戶端加密，您需要下列項目：

在執行任何範例程式碼之前，請先設定您的 AWS 登入資料。請參閱第 3 適用於 PHP 的 AWS SDK 版的登入資料。

加密

在 中上傳加密的物件S3EncryptionClientV3，除了標準參數之外，還需要四個額外的PutObject參數：

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

 // Let's construct our S3EncryptionClient using an S3Client
 $encryptionClient = new S3EncryptionClientV3(
     new S3Client([
         'profile' => 'default',
         'region' => 'us-east-1',
         'version' => 'latest',
     ])
 );

 $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,
     // Additional configuration options
 ];

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

解密

除了標準參數之外，下載和解密物件還有五個額外的GetObject參數，其中兩個是必要的。用戶端會為您偵測基本密碼選項。

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

密碼組態

中繼資料策略

您也可以選擇針對實作 Aws\Crypto\MetadataStrategyInterface 的類別，來提供其執行個體。這個簡單的界面可儲存和載入 Aws\Crypto\MetadataEnvelope，其中包含您的信封加密資料。開發套件提供了實作此項目的兩個類別：Aws\S3\Crypto\HeadersMetadataStrategy 與 Aws\S3\Crypto\InstructionFileMetadataStrategy。預設會使用 HeadersMetadataStrategy。

$strategy = new InstructionFileMetadataStrategy(
    $s3Client
);

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

$result = $encryptionClient->getObject([
    '@KmsAllowDecryptWithAnyCmk' => false,
    '@MaterialsProvider' => $materialsProvider,
    '@SecurityProfile' => 'V3',
    '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
    '@MetadataStrategy' => $strategy,
    '@CipherOptions' => $cipherOptions,
    'Bucket' => $bucket,
    'Key' => $key,
]);

您也可透過呼叫 HeadersMetadataStrategy::classInstructionFileMetadataStrategy，來提供 和 的類別名稱常數。

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

分段上傳

您也可以使用用戶端加密來進行分段上傳。會在上傳之前Aws\S3\Crypto\S3EncryptionMultipartUploaderV3準備來源串流以進行加密。建立的方法類似於使用 Aws\S3\MultipartUploader 和 Aws\S3\Crypto\S3EncryptionClientV3 時的經驗。S3EncryptionMultipartUploaderV3 可以處理與 '@MetadataStrategy' 相同的 S3EncryptionClientV3 選項，以及所有可用的 '@CipherOptions' 組態。

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

$bucket = 'the-bucket-name';
$key = 'the-upload-key';
$cipherOptions = [
    'Cipher' => 'gcm'
    'KeySize' => 256,
    // Additional configuration options
];

$multipartUploader = new S3EncryptionMultipartUploaderV3(
    new S3Client([
        'region' => 'us-east-1',
        'version' => 'latest',
        'profile' => 'default',
    ]),
    fopen('large-file-to-encrypt.txt', 'r'),
    [
        '@MaterialsProvider' => $materialsProvider,
        '@CipherOptions' => $cipherOptions,
        '@CommitmentPolicy' => 'REQUIRE_ENCRYPT_REQUIRE_DECRYPT',
        'bucket' => $bucket,
        'key' => $key,
    ]
);
$multipartUploader->upload();