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)
**catatan**
Jika Anda menggunakan V1 dari klien enkripsi Amazon S3, Anda harus terlebih dahulu bermigrasi ke V2 sebelum bermigrasi ke V3. Lihat [Migrasi Klien Enkripsi Amazon S3 (V1 ke V2)](s3-encryption-migration-v1-v2.md).
Topik ini menunjukkan cara memigrasikan aplikasi Anda dari Versi 2 (V2) ke Versi 3 (V3) klien enkripsi Amazon Simple Storage Service (Amazon S3) dan memastikan ketersediaan aplikasi selama proses migrasi. V3 memperkenalkan `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` algoritma dan Kebijakan Komitmen untuk meningkatkan keamanan dengan melindungi terhadap gangguan kunci data dalam File Instruksi.
## Ikhtisar Migrasi
Migrasi ini terjadi dalam dua fase:
1. **Perbarui klien yang ada untuk membaca format baru.** Pertama, gunakan versi terbaru dari aplikasi AWS SDK untuk C\+\+ Anda. Ini memungkinkan klien enkripsi V2 yang ada untuk mendekripsi objek yang ditulis oleh klien V3 baru. Jika aplikasi Anda menggunakan beberapa AWS SDKs, Anda harus memutakhirkan setiap SDK secara terpisah.
2. **Migrasikan enkripsi dan dekripsi klien 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 fitur keamanan baru yang meningkatkan perlindungan terhadap gangguan kunci data. Memahami konsep-konsep ini sangat penting untuk migrasi yang sukses.
### Kebijakan Komitmen
Kebijakan Komitmen mengontrol bagaimana klien enkripsi menangani komitmen utama selama operasi enkripsi dan dekripsi. V3 menyediakan tiga opsi kebijakan untuk mendukung skenario migrasi dan persyaratan keamanan yang berbeda:
**`FORBID_ENCRYPT_ALLOW_DECRYPT`**
**Perilaku enkripsi:** Mengenkripsi objek tanpa komitmen utama, menggunakan algoritma yang sama dengan V2.
**Perilaku dekripsi:** Memungkinkan dekripsi objek yang dienkripsi dengan dan tanpa komitmen utama.
**Implikasi keamanan:** Kebijakan ini tidak menegakkan komitmen utama dan memungkinkan perusakan kunci data terenkripsi dalam File Instruksi. Gunakan kebijakan ini hanya selama fase migrasi awal ketika Anda memerlukan klien V2 untuk membaca objek yang baru dienkripsi.
**Kompatibilitas versi:** Objek yang dienkripsi dengan kebijakan ini dapat dibaca oleh semua implementasi V2 dan V3.
**`REQUIRE_ENCRYPT_ALLOW_DECRYPT`(Default)**
**Perilaku enkripsi:** Mengenkripsi objek dengan komitmen utama menggunakan algoritme. `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`
**Perilaku dekripsi:** Memungkinkan dekripsi kedua objek yang dienkripsi dengan komitmen utama dan objek yang dienkripsi tanpa komitmen utama.
**Implikasi keamanan:** Kebijakan ini memberikan keamanan yang kuat untuk objek yang baru dienkripsi sambil mempertahankan kompatibilitas mundur untuk membaca objek lama. Ini adalah kebijakan yang direkomendasikan untuk sebagian besar skenario migrasi.
**Kompatibilitas versi:** Objek yang dienkripsi dengan kebijakan ini hanya dapat dibaca oleh V3 dan implementasi V2 terbaru. Klien V2 tidak dapat mendekripsi objek ini. Namun, klien V3 yang menggunakan kebijakan ini masih dapat mendekripsi objek yang dienkripsi oleh klien V2.
**`REQUIRE_ENCRYPT_REQUIRE_DECRYPT`**
**Perilaku enkripsi:** Mengenkripsi objek dengan komitmen utama menggunakan algoritme. `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`
**Perilaku dekripsi:** Hanya memungkinkan dekripsi objek yang dienkripsi dengan komitmen utama. Menolak objek yang dienkripsi tanpa komitmen utama.
**Implikasi keamanan:** Kebijakan ini memberikan tingkat keamanan tertinggi dengan menegakkan komitmen utama untuk semua operasi. Gunakan kebijakan ini hanya setelah semua objek dienkripsi ulang dengan komitmen utama dan Anda tidak perlu lagi membaca objek terenkripsi V1 atau V2 lama.
**Kompatibilitas versi:** Objek yang dienkripsi dengan kebijakan ini hanya dapat dibaca oleh V3 dan implementasi V2 terbaru. Selain itu, klien yang menggunakan kebijakan ini tidak dapat mendekripsi objek yang dienkripsi oleh klien V1 atau V2.
**Pertimbangan migrasi:** Selama migrasi, mulailah dengan `FORBID_ENCRYPT_ALLOW_DECRYPT` jika Anda memerlukan klien V2 untuk membaca objek baru, lalu pindah ke `REQUIRE_ENCRYPT_ALLOW_DECRYPT` setelah semua klien ditingkatkan ke V3. Akhirnya, pertimbangkan `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` hanya setelah semua objek warisan telah dienkripsi ulang.
### ALG\_AES\_256\_GCM\_HKDF\_ SHA512 \_COMMIT\_KEY Algoritma
`ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`Algoritma ini adalah algoritma enkripsi baru yang diperkenalkan di V3 yang memberikan keamanan yang ditingkatkan untuk kunci data terenkripsi yang disimpan dalam File Instruksi.
**Dampak File Instruksi:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` Algoritma hanya memengaruhi File Instruksi, yang merupakan objek S3 terpisah yang menyimpan metadata enkripsi termasuk kunci data terenkripsi. Objek yang menyimpan metadata enkripsi dalam metadata objek (metode penyimpanan default) tidak terpengaruh oleh perubahan algoritma ini.
**Perlindungan terhadap gangguan:** `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` Algoritma melindungi terhadap gangguan kunci data dengan mengikat kunci data terenkripsi secara kriptografis ke konteks enkripsi. Ini mencegah penyerang mengganti kunci data terenkripsi yang berbeda dalam File Instruksi, yang berpotensi menyebabkan dekripsi dengan kunci yang tidak diinginkan.
**Kompatibilitas versi:** Objek yang dienkripsi dengan `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` algoritme hanya dapat didekripsi oleh implementasi V3 dan versi transisi V2 terbaru dari SDK yang menyertakan dukungan dekripsi V3.
**Awas**
**Penting:** Sebelum mengaktifkan enkripsi dengan `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY` algoritme (dengan menggunakan `REQUIRE_ENCRYPT_ALLOW_DECRYPT` atau kebijakan `REQUIRE_ENCRYPT_REQUIRE_DECRYPT` komitmen), Anda harus memastikan bahwa semua klien yang akan membaca objek ini telah ditingkatkan ke V3 atau versi transisi V2 terbaru yang mendukung dekripsi V3. Kegagalan untuk memutakhirkan semua pembaca terlebih dahulu akan mengakibatkan kegagalan dekripsi untuk objek yang baru dienkripsi.
## Perbarui Klien yang Ada untuk Membaca Format Baru
Anda harus terlebih dahulu memperbarui klien yang sudah ada ke rilis SDK terbaru. Setelah menyelesaikan langkah ini, klien V2 aplikasi Anda akan dapat mendekripsi objek yang dienkripsi oleh klien enkripsi V3 tanpa memperbarui basis kode aplikasi Anda.
### Membangun dan Menginstal Versi Terbaru dari AWS SDK untuk C\+\+
**Aplikasi Mengkonsumsi SDK dari Sumber**
Jika Anda membuat dan menginstal AWS SDK untuk C\+\+ from source, unduh atau kloning sumber SDK dari [`aws/aws-sdk-cpp`](https://github.com/aws/aws-sdk-cpp)on. GitHub Kemudian ulangi langkah build dan install normal Anda.
Jika Anda memutakhirkan AWS SDK untuk C\+\+ dari versi lebih awal dari 1.11.x, lihat [CHANGELOG](https://github.com/aws/aws-sdk-cpp/blob/main/CHANGELOG.md) ini untuk memecahkan perubahan yang diperkenalkan di setiap versi utama. Untuk informasi selengkapnya tentang cara membuat dan menginstal AWS SDK untuk C\+\+, lihat[Mendapatkan AWS SDK untuk C\+\+ dari kode sumber](sdk-from-source.md).
**Aplikasi Mengkonsumsi SDK dari Vcpkg**
Jika aplikasi Anda menggunakan [Vcpkg](https://github.com/microsoft/vcpkg) untuk melacak pembaruan SDK, cukup gunakan metode pemutakhiran Vcpkg yang ada untuk memutakhirkan SDK ke versi terbaru. Perlu diingat, ada penundaan antara kapan versi dirilis dan kapan tersedia melalui manajer paket. Versi terbaru selalu tersedia melalui [instalasi dari sumber](sdk-from-source.md).
Anda dapat menjalankan perintah berikut untuk meng-upgrade paket`aws-sdk-cpp`:
```
vcpkg upgrade aws-sdk-cpp
```
Dan verifikasi versi paket`aws-sdk-cpp`:
```
vcpkg list aws-sdk-cpp
```
Versi harus setidaknya 1.11.x untuk mendukung dekripsi objek yang dienkripsi V3.
Untuk informasi lebih lanjut tentang menggunakan Vcpkg dengan, lihat. AWS SDK untuk C\+\+[Mendapatkan AWS SDK untuk C\+\+ dari manajer paket](sdk-from-pm.md)
### Membangun, Menginstal, dan Menyebarkan Aplikasi Anda
Jika aplikasi Anda terhubung secara statis terhadap AWS SDK untuk C\+\+, perubahan kode tidak diperlukan dalam aplikasi Anda, tetapi Anda harus membangun aplikasi Anda lagi untuk menggunakan perubahan SDK terbaru. Langkah ini tidak diperlukan untuk penautan dinamis.
Setelah memutakhirkan versi dependensi aplikasi Anda dan memverifikasi fungsionalitas aplikasi, lanjutkan untuk menerapkan aplikasi Anda ke armada Anda. Setelah penerapan aplikasi selesai, Anda dapat melanjutkan ke fase berikutnya untuk memigrasikan aplikasi Anda untuk menggunakan enkripsi V3 dan klien dekripsi.
## Migrasi Klien Enkripsi dan Dekripsi ke V3
Langkah-langkah berikut menunjukkan kepada Anda cara berhasil memigrasikan kode Anda dari V2 ke V3 dari klien enkripsi Amazon S3. Karena perubahan kode diperlukan, Anda perlu membangun kembali aplikasi Anda terlepas dari apakah itu secara statis atau dinamis menautkan ke aplikasi. AWS SDK untuk C\+\+
### Menggunakan Klien Enkripsi V3
V3 memperkenalkan `S3EncryptionClientV3` kelas dan `CryptoConfigurationV3` untuk menggantikan setara V2. Perbedaan utama dalam V3 adalah:
+ V3 menggunakan `KMSWithContextEncryptionMaterials` (sama dengan V2) tetapi membutuhkan konfigurasi eksplisit di. `CryptoConfigurationV3`
+ Semua `PutObject` operasi memerlukan peta konteks enkripsi (bisa kosong).
+ V3 memperkenalkan Kebijakan Komitmen untuk mengontrol perilaku enkripsi dan dekripsi.
+ Secara default, V3 mengenkripsi dengan komitmen utama menggunakan algoritma. `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY`
+ API konfigurasi dekripsi algoritma lama berubah dari ke. `config.SetSecurityProfile(SecurityProfile::V2_AND_LEGACY);` `config.AllowLegacy();`
**Contoh: Migrasi dari V2 ke V3 dengan Enkripsi KMS**
*Pra-migrasi (V2)*
```
// Create encryption materials
auto materials = Aws::MakeShared("s3EncryptionV2", CUSTOMER_MASTER_KEY_ID);
// Create V2 crypto configuration
CryptoConfigurationV2 cryptoConfig(materials);
// Create V2 encryption client
S3EncryptionClientV2 encryptionClient(cryptoConfig);
// Put object with encryption context
Aws::Map encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");
PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...
auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);
// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```
*Selama migrasi (V3 dengan kompatibilitas mundur)*
```
// Create encryption materials
auto materials = Aws::MakeShared("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);
// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);
// Set commitment policy to maintain compatibility with V2 encrypted objects
// This allows V3 clients to decrypt objects encrypted by the V2 client
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);
// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);
// Put object with encryption context
Aws::Map encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");
PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...
auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);
// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```
*Pasca-migrasi (V3 dengan komitmen utama)*
```
// Create encryption materials
auto materials = Aws::MakeShared("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);
// Create V3 crypto configuration with materials
CryptoConfigurationV3 cryptoConfig(materials);
// Use the default commitment policy (REQUIRE_ENCRYPT_REQUIRE_DECRYPT)
// This encrypts with key commitment and does not decrypt V2 objects
// cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);
// Create V3 encryption client
S3EncryptionClientV3 encryptionClient(cryptoConfig);
// Put object with encryption context
Aws::Map encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
encryptionContext.emplace("version", "1.11.0");
PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...
auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);
// Get object with encryption context
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(OBJECT_KEY);
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```
## Contoh Tambahan
Bagian ini memberikan contoh tambahan untuk mengonfigurasi opsi klien enkripsi V3 untuk mendukung berbagai skenario dan persyaratan migrasi.
### Mengaktifkan Legacy Support
Klien V3 dapat mendekripsi objek yang dienkripsi oleh klien V2 hanya ketika menggunakan kebijakan atau komitmen. `REQUIRE_ENCRYPT_ALLOW_DECRYPT` `FORBID_ENCRYPT_ALLOW_DECRYPT` Namun, jika Anda perlu mendekripsi objek yang dienkripsi oleh klien V1, Anda harus secara eksplisit mengaktifkan dukungan lama menggunakan metode ini. `AllowLegacy()`
**Kapan menggunakan dukungan lama:**
+ Anda memiliki objek di S3 yang dienkripsi menggunakan V1 dari Klien Enkripsi S3.
+ Anda perlu membaca objek terenkripsi V1 ini dengan klien V3 Anda selama proses migrasi.
+ Anda menggunakan kebijakan `REQUIRE_ENCRYPT_ALLOW_DECRYPT` atau `FORBID_ENCRYPT_ALLOW_DECRYPT` komitmen.
**Awas**
Dukungan lama seharusnya hanya diaktifkan sementara selama migrasi. Setelah semua objek V1 dienkripsi ulang dengan V2 atau V3, nonaktifkan dukungan lama untuk memastikan keamanan maksimum.
**Contoh: Mengaktifkan Legacy Support**
```
// Create encryption materials
auto materials = Aws::MakeShared("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);
// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);
// Enable legacy support to read V1 encrypted objects
cryptoConfig.AllowLegacy();
// Set commitment policy (default is REQUIRE_ENCRYPT_REQUIRE_DECRYPT but we need to allow decryption)
cryptoConfig.SetCommitmentPolicy(CommitmentPolicy::REQUIRE_ENCRYPT_ALLOW_DECRYPT);
// Create V3 encryption client with legacy support enabled
S3EncryptionClientV3 encryptionClient(cryptoConfig);
// Now you can decrypt objects encrypted by V1, V2, and V3 clients
GetObjectRequest getObjectRequest;
getObjectRequest.SetBucket(BUCKET_NAME);
getObjectRequest.SetKey(LEGACY_OBJECT_KEY);
Aws::Map encryptionContext;
auto getOutcome = encryptionClient.GetObject(getObjectRequest, encryptionContext);
```
### Mengkonfigurasi Metode Penyimpanan
Klien Enkripsi S3 dapat menyimpan metadata enkripsi dalam dua cara: sebagai metadata objek (default) atau dalam File Instruksi terpisah. Anda dapat mengonfigurasi metode penyimpanan menggunakan `SetStorageMethod()` metode aktif`CryptoConfigurationV3`.
**Opsi metode penyimpanan:**
**`METADATA`(Default)**
Metadata enkripsi disimpan di header metadata objek. Ini adalah metode yang paling umum dan nyaman karena semua informasi enkripsi disimpan dengan objek itu sendiri.
**Kapan menggunakan:** Gunakan metode ini untuk sebagian besar skenario. Ini menyederhanakan manajemen objek karena metadata enkripsi berjalan dengan objek.
**`INSTRUCTION_FILE`**
Metadata enkripsi disimpan dalam objek S3 terpisah (File Instruksi) dengan akhiran. `.instruction`
**Kapan menggunakan: Gunakan** metode ini ketika ukuran metadata objek menjadi perhatian atau ketika Anda perlu memisahkan metadata enkripsi dari objek terenkripsi. Perhatikan bahwa menggunakan File Instruksi memerlukan pengelolaan dua objek S3 (objek terenkripsi dan file instruksinya), bukan satu.
**Contoh: Mengkonfigurasi Metode Penyimpanan**
```
// Create encryption materials
auto materials = Aws::MakeShared("s3EncryptionV3", CUSTOMER_MASTER_KEY_ID);
// Create V3 crypto configuration
CryptoConfigurationV3 cryptoConfig(materials);
// Option 1: Use metadata storage (default, can be omitted)
cryptoConfig.SetStorageMethod(StorageMethod::METADATA);
// Option 2: Use instruction file storage
cryptoConfig.SetStorageMethod(StorageMethod::INSTRUCTION_FILE);
// Create V3 encryption client with the configured storage method
S3EncryptionClientV3 encryptionClient(cryptoConfig);
// Put object - encryption metadata will be stored according to the configured method
Aws::Map encryptionContext;
encryptionContext.emplace("client", "aws-sdk-cpp");
PutObjectRequest putObjectRequest;
putObjectRequest.SetBucket(BUCKET_NAME);
putObjectRequest.SetKey(OBJECT_KEY);
// Set object body...
auto putOutcome = encryptionClient.PutObject(putObjectRequest, encryptionContext);
// If using INSTRUCTION_FILE, a separate object with key "OBJECT_KEY.instruction" will be created
```
**catatan**
Saat menggunakan metode `INSTRUCTION_FILE` penyimpanan, ingatlah bahwa menghapus objek terenkripsi tidak secara otomatis menghapus file instruksi. Anda harus mengelola kedua objek secara terpisah.