AWS SDK for .NET V3 telah memasuki mode pemeliharaan.

Kami menyarankan Anda bermigrasi ke [AWS SDK for .NET V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html). Untuk detail dan informasi tambahan tentang cara bermigrasi, silakan lihat [pengumuman mode pemeliharaan](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/) kami.

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 V4)
Migrasi Klien Enkripsi S3 (V2 ke V4)Migrasi V4 Klien Enkripsi S3

Menambahkan informasi tentang migrasi dari V2 ke V4.

**catatan**  
Jika Anda menggunakan V1 dan ingin bermigrasi ke V4, Anda harus terlebih dahulu bermigrasi ke V2. Lihat [Migrasi Klien Enkripsi Amazon S3 (V1 ke V2)](s3-encryption-migration-v1-v2.md).

Topik ini menunjukkan cara memigrasikan aplikasi Anda dari klien enkripsi Amazon Simple Storage Service (Amazon S3) ke Versi 2 (V4) Amazon Simple Storage Service (Amazon S3) ke Versi 4 (V4), dan memastikan ketersediaan aplikasi selama proses migrasi. V4 menggunakan AES-GCM dengan komitmen utama untuk enkripsi konten dan memperkenalkan Kebijakan Komitmen untuk meningkatkan keamanan terhadap serangan substitusi kunci.

Klien V4 tersedia dalam paket [ NuGet Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption).

**penting**  
**Melanggar Perubahan:** Klien V4 yang dikonfigurasi dengan `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` kebijakan tidak dapat mendekripsi objek yang dienkripsi dengan klien V1 atau V2. Hanya klien V2 terbaru yang dapat mendekripsi objek terenkripsi V4 dengan komitmen utama. Sebelum beralih ke `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` kebijakan, Anda harus mengenkripsi ulang semua data yang ada menggunakan klien V4 dengan komitmen utama diaktifkan.

## Memahami Konsep V4


V4 menggunakan AES-GCM dengan komitmen utama untuk enkripsi konten dan memperkenalkan konsep keamanan utama yang meningkatkan perlindungan data terenkripsi Anda:

### Kebijakan Komitmen


Kebijakan Komitmen mengontrol cara klien enkripsi menangani komitmen utama selama operasi enkripsi dan dekripsi. V4 mendukung tiga kebijakan komitmen:

`FORBID_ENCRYPT_ALLOW_DECRYPT`  
*Enkripsi:* Tanpa komitmen  
*Dekripsi:* Memungkinkan objek yang tidak berkomitmen  
*Keamanan:* Tidak menegakkan komitmen dan memungkinkan gangguan  
*Kompatibilitas:* Semua implementasi V2 dan V4 dapat membaca objek yang dienkripsi dengan kebijakan ini

`REQUIRE_ENCRYPT_ALLOW_DECRYPT`  
*Enkripsi:* Dengan komitmen utama  
*Dekripsi:* Memungkinkan objek yang melakukan dan tidak berkomitmen  
*Keamanan:* Objek baru dilindungi dari serangan substitusi kunci, objek lama masih dapat dibaca  
*Kompatibilitas:* Hanya V4 yang mendukung kebijakan ini

`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`(Default untuk V4)  
*Enkripsi:* Dengan komitmen utama  
*Dekripsi:* Hanya melakukan objek  
*Keamanan:* Penegakan komitmen penuh untuk keamanan maksimum  
*Kompatibilitas:* Hanya V4 yang mendukung kebijakan ini

### AES GCM dengan Komitmen Utama


V4 menggunakan AES-GCM dengan komitmen utama untuk enkripsi konten, yang memberikan keamanan yang ditingkatkan:
+ *Perlindungan Perusakan:* Ini melindungi terhadap serangan substitusi kunci dengan mengikat kunci ke data terenkripsi secara kriptografis.
+ *Kompatibilitas Versi:* Objek yang dienkripsi dengan komitmen utama hanya dapat didekripsi oleh klien V4 dan versi yang lebih baru.

**Awas**  
Sebelum mengaktifkan enkripsi komitmen utama dalam produksi, pastikan bahwa semua aplikasi yang perlu mendekripsi objek Anda telah ditingkatkan ke V4 atau yang lebih baru karena klien V2 tidak digunakan lagi.

## Perbarui Klien yang Ada untuk Membaca Format V4


Klien enkripsi V4 menggunakan algoritma enkripsi yang tidak didukung oleh versi klien yang lebih lama. Langkah pertama dalam migrasi adalah memperbarui klien V2 Anda sehingga mereka dapat membaca format V4 baru.

### Perbarui Dependensi NuGet Package


Perbarui aplikasi Anda untuk menggunakan versi terbaru dari paket [ NuGet Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) yang mencakup dukungan V4. Lakukan langkah-langkah berikut pada setiap aplikasi Anda:

1. Perbarui ke paket [Amazon.Extensions.S3.Encryption](https://www.nuget.org/packages/Amazon.Extensions.S3.Encryption) terbaru. **Jika proyek Anda bergantung langsung pada **AWSSDK.S3** atau. AWSSDK KeyManagementService**paket, Anda harus memperbarui dependensi tersebut atau menghapusnya sehingga versi yang diperbarui akan ditarik dengan paket baru ini.

1. Pastikan `using` pernyataan Anda mereferensikan namespace yang benar:

   ```
   using Amazon.Extensions.S3.Encryption;
   using Amazon.Extensions.S3.Encryption.Primitives;
   ```

1. Membangun kembali dan menerapkan kembali aplikasi Anda.

Klien V2 Anda yang ada akan terus bekerja dengan paket yang diperbarui dan akan dapat mendekripsi objek yang dienkripsi oleh klien V4 (tergantung pada kebijakan komitmen yang digunakan).

### Membangun dan Menyebarkan Aplikasi


Setelah memperbarui dependensi NuGet paket Anda:

1. Bangun aplikasi Anda untuk memastikan semua dependensi diselesaikan dengan benar.

1. Uji aplikasi Anda di lingkungan pengembangan untuk memverifikasi bahwa fungsionalitas yang ada terus berfungsi.

1. Terapkan aplikasi yang diperbarui ke lingkungan produksi Anda.

Pembaruan ini memungkinkan klien V2 Anda yang ada untuk mendekripsi objek yang akan dienkripsi oleh klien V4, memastikan kompatibilitas selama proses migrasi.

## Migrasi ke Klien V4


Setelah memperbarui klien Anda yang ada untuk membaca format enkripsi baru, Anda dapat melanjutkan untuk memperbarui aplikasi Anda dengan aman untuk menggunakan enkripsi V4 dan klien dekripsi. Klien V4 memberikan keamanan yang ditingkatkan melalui komitmen utama sambil mempertahankan kompatibilitas dengan objek terenkripsi yang ada.

### Proses Migrasi 4 Langkah


Migrasi dari V2 ke V4 mengikuti proses 4 langkah terstruktur untuk memastikan kompatibilitas dan keamanan. Setiap langkah mewakili konfigurasi spesifik yang harus diterapkan di semua aplikasi Anda sebelum melanjutkan ke langkah berikutnya.

1. **Langkah 0: Klien V2 (Titik Awal)** - Implementasi V2 Anda yang ada

1. **Langkah 1: V4 dengan Kompatibilitas V2** - Migrasi ke klien V4 sambil mempertahankan perilaku enkripsi yang kompatibel dengan V2

1. **Langkah 2: V4 dengan Key Commitment Writes** - Mulai mengenkripsi dengan komitmen utama sambil memungkinkan dekripsi objek warisan

1. **Langkah 3: V4 dengan Penegakan Penuh** - Memerlukan komitmen utama untuk enkripsi dan dekripsi

### Langkah 0: Klien V2 (Titik Awal)


Ini mewakili konfigurasi klien V2 Anda yang ada. Langkah ini menunjukkan status awal sebelum migrasi.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 0: V2 Client - Starting configuration
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV2(kmsKeyId, KmsType.KmsContext, encryptionContext);

#pragma warning disable 0618
var configuration = new AmazonS3CryptoConfigurationV2(SecurityProfile.V2);
#pragma warning enable 0618

var encryptionClient = new AmazonS3EncryptionClientV2(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

### Langkah 1: V4 dengan Kompatibilitas V2


Migrasi ke klien V4 sambil mempertahankan perilaku identik ke V2. Langkah ini menggunakan `FORBID_ENCRYPT_ALLOW_DECRYPT` kebijakan untuk mengenkripsi tanpa komitmen dan memungkinkan dekripsi semua objek.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 1: V4 Client with V2 compatibility
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcm);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**Perilaku:** Mengenkripsi tanpa komitmen, dapat mendekripsi objek yang berkomitmen dan tidak berkomitmen. Identik dengan perilaku V2.

### Langkah 2: V4 dengan Key Commitment Writes


Mulai enkripsi dengan komitmen utama sambil mempertahankan kompatibilitas mundur untuk dekripsi. Langkah ini menggunakan `REQUIRE_ENCRYPT_ALLOW_DECRYPT` kebijakan.

**Awas**  
Sebelum menerapkan Langkah 2, pastikan semua pembaca telah diperbarui ke Langkah 1 atau yang lebih baru untuk menangani enkripsi komitmen utama.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 2: V4 Client with key commitment writes
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**Perilaku:** Mengenkripsi dengan komitmen, dapat mendekripsi objek yang berkomitmen dan tidak berkomitmen. Objek baru dilindungi dari serangan substitusi kunci.

### Langkah 3: V4 dengan Penegakan Penuh


Memerlukan komitmen utama untuk enkripsi dan dekripsi. Langkah ini menggunakan `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` kebijakan untuk keamanan maksimum.

**Awas**  
Sebelum menerapkan Langkah 3, pastikan semua objek di sistem Anda telah dienkripsi ulang dengan komitmen utama (Langkah 2). Langkah ini akan gagal mendekripsi objek yang dienkripsi tanpa komitmen.

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;
using Amazon.S3.Model;

// Step 3: V4 Client with full key commitment enforcement
var encryptionContext = new Dictionary<string, string>();
var encryptionMaterial = new EncryptionMaterialsV4(kmsKeyId, KmsType.KmsContext, encryptionContext);

var configuration = new AmazonS3CryptoConfigurationV4(
    SecurityProfile.V4, 
    CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT, 
    ContentEncryptionAlgorithm.AesGcmWithCommitment);

var encryptionClient = new AmazonS3EncryptionClientV4(configuration, encryptionMaterial);

// Use the client for PutObject and GetObject operations
await encryptionClient.PutObjectAsync(new PutObjectRequest
{
    BucketName = bucket,
    Key = objectKey,
    ContentBody = content
});
```

**Perilaku:** Mengenkripsi dengan komitmen, hanya mendekripsi objek yang dienkripsi dengan komitmen. Keamanan maksimum terhadap serangan substitusi kunci.

## Contoh Konfigurasi Tambahan


Bagian ini memberikan contoh tambahan untuk mengonfigurasi klien V4 dengan opsi berbeda selama migrasi.

### Mengaktifkan Legacy Support


Untuk mengaktifkan klien V4 membaca objek yang dienkripsi oleh klien V1 dan V2, konfigurasikan klien dengan kebijakan komitmen yang memungkinkan dekripsi lama:

```
using Amazon.Extensions.S3.Encryption;
using Amazon.Extensions.S3.Encryption.Primitives;

// Configure V4 client to read V1/V2 objects
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};

// This configuration allows:
// - Encryption: With commitment (secure)
// - Decryption: Both V2 (non-committing) and V4 (committing) objects
```

Gunakan konfigurasi ini selama migrasi saat Anda perlu mendekripsi objek yang dienkripsi oleh klien lama sambil memastikan objek baru dienkripsi dengan keamanan yang ditingkatkan.

### Mengkonfigurasi Metode Penyimpanan


V4 mendukung dua metode penyimpanan untuk metadata enkripsi. Pilih metode yang paling sesuai dengan kasus penggunaan Anda:

**Metadata Objek (Default)**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.ObjectMetadata
};
// Encryption metadata is stored in S3 object metadata
```

**File Instruksi**

```
var configuration = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT)
{
    StorageMode = CryptoStorageMode.InstructionFile
};
// Encryption metadata is stored in a separate S3 object (instruction file)
```

Gunakan `InstructionFile` saat Anda perlu mempertahankan metadata objek untuk tujuan lain atau saat bekerja dengan objek yang memiliki batasan ukuran metadata.

### Mengkonfigurasi Kebijakan Komitmen


Pilih kebijakan komitmen yang sesuai berdasarkan persyaratan keamanan dan fase migrasi Anda:

**Fase Migrasi (Kompatibilitas V2)**

```
// For migration: encrypt without commitment, allow all decryption
var migrationConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.FORBID_ENCRYPT_ALLOW_DECRYPT);
```

**Fase Transisi (Direkomendasikan)**

```
// For transition: encrypt with commitment, allow legacy decryption
var transitionConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_ALLOW_DECRYPT);
```

**Fase Keamanan Penuh**

```
// For maximum security: require commitment for both encryption and decryption
var secureConfig = new AmazonS3CryptoConfigurationV4(CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT);
```

Mulailah dengan `FORBID_ENCRYPT_ALLOW_DECRYPT` selama migrasi awal, pindah ke `REQUIRE_ENCRYPT_ALLOW_DECRYPT` untuk fase transisi, dan akhirnya gunakan `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` ketika semua klien telah ditingkatkan dan semua objek telah dienkripsi ulang dengan komitmen.