Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Migrasi Klien Enkripsi Amazon S3 (V2 ke V3) di AWS SDK untuk PHP Versi 3

Topik ini menunjukkan cara memigrasi aplikasi Anda dari versi 2 (V2) klien enkripsi Amazon Simple Storage Service (Amazon S3) ke Versi 3 (V3), dan memastikan ketersediaan aplikasi selama proses migrasi. Versi 3 memperkenalkan AES GCM dengan Kebijakan Komitmen dan Komitmen Utama untuk meningkatkan keamanan dan melindungi terhadap gangguan kunci data.

Ikhtisar migrasi

Migrasi ini terjadi dalam dua fase:

1. Perbarui klien yang ada untuk membaca format baru. Pertama, terapkan versi terbaru AWS SDK untuk PHP ke aplikasi Anda. Hal ini memungkinkan klien enkripsi V2 yang ada untuk mendekripsi objek yang ditulis oleh klien V3 baru. Jika aplikasi Anda menggunakan beberapa AWS SDK, Anda harus memutakhirkan setiap SDK secara terpisah.

2. Migrasikan klien enkripsi dan dekripsi ke V3. Setelah semua klien enkripsi V2 Anda dapat membaca format baru, Anda dapat memigrasikan klien enkripsi dan dekripsi yang ada ke versi V3 masing-masing.

Memahami konsep V3

Versi 3 dari klien enkripsi Amazon S3 memperkenalkan dua peningkatan keamanan utama: Kebijakan Komitmen dan algoritma AES GCM dengan Komitmen Utama. Memahami konsep-konsep ini sangat penting untuk migrasi yang sukses.

Kebijakan Komitmen

Kebijakan Komitmen mengontrol bagaimana klien enkripsi menangani komitmen kunci selama operasi enkripsi dan dekripsi. Versi 3 menyediakan tiga opsi kebijakan:

AES GCM dengan Komitmen Utama

Algoritma AES GCM dengan Key Commitment (ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY) adalah algoritma enkripsi baru yang diperkenalkan di V3 yang memberikan perlindungan terhadap serangan perusakan kunci data.

Peningkatan keamanan: ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY melindungi terhadap gangguan kunci data dengan mengikat kunci data secara kriptografis ke konten terenkripsi. Ini mencegah penyerang mengganti kunci data yang berbeda selama dekripsi, yang dapat menyebabkan dekripsi data yang tidak diinginkan.

Kompatibilitas versi: Objek yang dienkripsi hanya ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY dapat didekripsi oleh V3 dan implementasi V2 terbaru dari klien enkripsi Amazon S3. Klien V1 tidak dapat mendekripsi objek yang dienkripsi dengan algoritma ini.

Perbarui klien yang ada untuk membaca format baru

Klien enkripsi V3 menggunakan algoritma enkripsi dan fitur komitmen utama yang tidak didukung oleh versi klien yang lebih lama. Langkah pertama dalam migrasi adalah memperbarui klien dekripsi V2 Anda ke rilis SDK terbaru. Setelah menyelesaikan langkah ini, klien V2 aplikasi Anda akan dapat mendekripsi objek yang dienkripsi oleh klien enkripsi V3. Lihat detail di bawah ini untuk setiap metode instalasi AWS SDK untuk PHP.

Membangun dan menginstal versi SDK terbaru

Untuk menyelesaikan migrasi ini, Anda harus menggunakan versi terbaru dari aws/aws-sdk-php paket yang menyertakan dukungan klien enkripsi V3.

Menginstal dari Komposer

Untuk proyek yang diinstal menggunakan Composer, di file Composer, perbarui paket SDK ke versi terbaru SDK dan kemudian jalankan perintah berikut.

composer update aws/aws-sdk-php

Menginstal Menggunakan File Phar atau Zip

Gunakan salah satu metode berikut. Pastikan untuk menempatkan file SDK yang diperbarui di lokasi yang diperlukan oleh kode Anda, yang ditentukan oleh pernyataan require.

Untuk proyek yang diinstal menggunakan file Phar, unduh file yang diperbarui: aws.phar.

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

Untuk proyek yang diinstal menggunakan file Zip, unduh file yang diperbarui: .

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

Membangun, menginstal, dan menyebarkan aplikasi

Setelah memperbarui SDK, buat ulang dan gunakan kembali aplikasi Anda untuk memastikan semua komponen menggunakan versi yang diperbarui. Langkah ini sangat penting untuk memastikan bahwa klien V2 Anda dapat membaca objek yang dienkripsi oleh klien V3.

Ikuti prosedur penerapan standar organisasi Anda untuk meluncurkan aplikasi yang diperbarui. Pastikan semua instance aplikasi Anda diperbarui sebelum melanjutkan untuk memigrasikan klien enkripsi dan dekripsi Anda ke V3.

Setelah penerapan, verifikasi bahwa aplikasi Anda masih dapat mendekripsi objek yang ada dan tidak ada kesalahan yang terjadi selama operasi normal. Ini mengonfirmasi bahwa pembaruan SDK berhasil dan aplikasi Anda siap untuk fase migrasi berikutnya.

Migrasikan klien Enkripsi dan Dekripsi ke V3

Setelah memperbarui klien Anda untuk membaca format enkripsi baru, Anda dapat memperbarui aplikasi Anda ke klien enkripsi dan dekripsi V3. Contoh berikut menunjukkan cara berhasil memigrasikan kode Anda dari V2 ke V3.

Menggunakan Klien Enkripsi V3

V3 memperkenalkan S3EncryptionClientV3 kelas dan KmsMaterialsProviderV3 untuk menggantikan setara V2. Perbedaan utama dalam V3 adalah:

Contoh: Migrasi dari V2 ke V3 dengan Enkripsi KMS

Pre-migration (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,
]);

Selama migrasi (V3 dengan kompatibilitas mundur)

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,
]);

Post-migration (V3 dengan komitmen utama)

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,
]);

Perbedaan utama dalam V3:

Contoh tambahan

Contoh berikut menunjukkan opsi konfigurasi tambahan yang tersedia di V3 yang dapat membantu Anda mengelola proses migrasi dan mengontrol perilaku enkripsi.

Mengaktifkan dukungan lama

Selama migrasi, Anda mungkin perlu mendekripsi objek yang dienkripsi dengan V1 atau V2 dari klien enkripsi Amazon S3. @SecurityProfileParameter mengontrol versi enkripsi mana yang dapat didekripsi klien V3 Anda.

Kapan menggunakan konfigurasi ini: Gunakan profil 'V3_AND_LEGACY' keamanan saat aplikasi Anda perlu membaca objek yang dienkripsi oleh klien V1 atau V2. Hal ini biasa terjadi selama periode migrasi ketika Anda memiliki campuran objek terenkripsi lama dan baru di bucket Anda.

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,
]);

@SecurityProfileParameter menerima nilai-nilai berikut:

Mengkonfigurasi metode penyimpanan

Klien enkripsi Amazon S3 dapat menyimpan metadata enkripsi dengan dua cara: di header metadata objek atau dalam file instruksi terpisah. @MetadataStrategyParameter mengontrol metode penyimpanan yang digunakan.

Kapan menggunakan konfigurasi ini: Gunakan 'INSTRUCTION_FILE' saat Anda perlu mempertahankan metadata objek asli atau saat bekerja dengan objek yang memiliki batasan ukuran metadata. Gunakan 'METADATA' (default) untuk penerapan yang lebih sederhana di mana metadata enkripsi dapat disimpan di samping objek.

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'),
]);

@MetadataStrategyParameter menerima nilai-nilai berikut: