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 (V1 ke V2) di AWS SDK untuk PHP Versi 3
<a name="s3-encryption-migration-v1-v2"></a>

**catatan**  
Jika Anda menggunakan Versi 2 (V2) dari klien enkripsi Amazon S3 dan ingin bermigrasi ke Versi 3 (V3), lihat[Migrasi Klien Enkripsi Amazon S3 (V2 ke V3) di AWS SDK untuk PHP Versi 3](s3-encryption-migration-v2-v3.md).

Topik ini menunjukkan cara memigrasi aplikasi Anda dari versi 1 (V1) klien enkripsi Amazon Simple Storage Service (Amazon S3) ke Versi 2 (V2), dan memastikan ketersediaan aplikasi selama proses migrasi.

## Ikhtisar migrasi
<a name="migration-overview-v1-v2"></a>

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 V1 yang ada untuk mendekripsi objek yang ditulis oleh klien V2 baru. Jika aplikasi Anda menggunakan beberapa AWS SDK, Anda harus memutakhirkan setiap SDK secara terpisah.

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

## Perbarui klien yang ada untuk membaca format baru
<a name="update-existing-clients-to-read-new-formats-v1-v2"></a>

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

### Meningkatkan AWS SDK untuk PHP Versi 3
<a name="upgrading-aws-sdk-for-php-version-3-v1-v2"></a>

Versi 3 adalah versi terbaru dari AWS SDK untuk PHP. Untuk menyelesaikan migrasi ini, Anda harus menggunakan paket versi 3.148.0 atau yang lebih baru. `aws/aws-sdk-php`

 **Menginstal dari Baris Perintah ** 

Untuk proyek yang diinstal menggunakan Composer, di file Composer, perbarui paket SDK ke versi 3.148.0 dari 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`](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.phar).

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

Untuk proyek yang diinstal menggunakan file Zip, unduh file yang diperbarui: [``](https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip).

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

## Migrasikan klien enkripsi dan dekripsi ke V2
<a name="migrate-encryption-and-decryption-clients-to-v2-v1-v2"></a>

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

### Persyaratan untuk Memperbarui ke Klien V2
<a name="requirements-for-updating-to-v2-clients-v1-v2"></a>

1. Kon AWS KMS teks enkripsi harus diteruskan ke `S3EncryptionClientV2::putObjectAsync` metode `S3EncryptionClientV2::putObject` dan. AWS KMS konteks enkripsi adalah array asosiatif pasangan kunci-nilai, yang harus Anda tambahkan ke konteks enkripsi untuk enkripsi kunci. AWS KMS Jika tidak ada konteks tambahan yang diperlukan, Anda dapat meneruskan array kosong.

2. `@SecurityProfile`harus diteruskan ke `getObjectAsync` metode `getObject` dan di`S3EncryptionClientV2`. `@SecurityProfile`adalah parameter wajib baru dari `getObject...` metode. Jika disetel ke`'V2'`, hanya objek yang dienkripsi dalam V2-compatible format yang dapat didekripsi. Mengatur parameter ini untuk `'V2_AND_LEGACY'` juga memungkinkan objek yang dienkripsi dalam V1-compatible format untuk didekripsi. Untuk mendukung migrasi, setel `@SecurityProfile` ke`'V2_AND_LEGACY'`. Gunakan `'V2'` hanya untuk pengembangan aplikasi baru.

3. (opsional) Ser `@KmsAllowDecryptWithAnyCmk` takan parameter di `S3EncryptionClientV2::getObject` dan Parameter `S3EncryptionClientV2::getObjectAsync* methods.` baru telah ditambahkan dipanggil`@KmsAllowDecryptWithAnyCmk`. Mengatur parameter ini untuk `true` mengaktifkan dekripsi tanpa memberikan kunci KMS. Nilai default-nya adalah `false`.

4. Untuk dekripsi dengan klien V2, jika `@KmsAllowDecryptWithAnyCmk` parameter tidak disetel `true` untuk panggilan `"getObject..."` metode, a `kms-key-id` harus diberikan ke `KmsMaterialsProviderV2` konstruktor.

## Contoh migrasi
<a name="migration-examples-v1-v2"></a>

### Contoh 1: Bermigrasi ke klien V2
<a name="example-1-migrating-to-v2-clients-v1-v2"></a>

 **Pre-migration** 

```
use Aws\S3\Crypto\S3EncryptionClient;
use Aws\S3\S3Client;

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

 **Post-migration** 

```
use Aws\S3\Crypto\S3EncryptionClientV2;
use Aws\S3\S3Client;

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

### Contoh 2: Menggunakan AWS KMS dengan kms-key-id
<a name="example-2-using-kms-with-kms-key-id-v1-v2"></a>

**catatan**  
Contoh-contoh ini menggunakan impor dan variabel yang didefinisikan dalam Contoh 1. Misalnya, `$encryptionClient`.

 **Pre-migration** 

```
use Aws\Crypto\KmsMaterialsProvider;
use Aws\Kms\KmsClient;

$kmsKeyId = 'kms-key-id';
$materialsProvider = new KmsMaterialsProvider(
    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,
    'Bucket' => $bucket,
    'Key' => $key,
    'Body' => fopen('file-to-encrypt.txt', 'r'),
]);

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

 **Post-migration** 

```
use Aws\Crypto\KmsMaterialsProviderV2;
use Aws\Kms\KmsClient;

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