Migrasi ke versi 3.x pustaka enkripsi sisi klien Java untuk DynamoDB - AWS Enkripsi Database SDK

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

Migrasi ke versi 3.x pustaka enkripsi sisi klien Java untuk DynamoDB

Pustaka enkripsi sisi klien kami diubah namanya menjadi SDK Enkripsi AWS Database. Panduan pengembang ini masih memberikan informasi tentang Klien Enkripsi DynamoDB.

Versi 3. x dari pustaka enkripsi sisi klien Java untuk DynamoDB adalah penulisan ulang utama dari 2. basis kode x. Ini mencakup banyak pembaruan, seperti format data terstruktur baru, dukungan multitenancy yang ditingkatkan, perubahan skema yang mulus, dan dukungan enkripsi yang dapat dicari. Topik ini memberikan panduan tentang cara memigrasikan kode Anda ke versi 3. x.

Migrasi dari versi 1.x ke 2.x

Migrasi ke versi 2. x sebelum Anda bermigrasi ke versi 3. x. Versi 2. x mengubah simbol untuk Penyedia Terbaru dari MostRecentProvider keCachingMostRecentProvider. Jika saat ini Anda menggunakan versi 1. x dari pustaka enkripsi sisi klien Java untuk DynamoDB dengan MostRecentProvider simbol, Anda harus memperbarui nama simbol dalam kode Anda ke. CachingMostRecentProvider Untuk informasi selengkapnya, lihat Pembaruan ke Penyedia Terbaru.

Migrasi dari versi 2.x ke 3.x

Prosedur berikut menjelaskan cara memigrasikan kode Anda dari versi 2. x ke versi 3. x dari pustaka enkripsi sisi klien Java untuk DynamoDB.

Langkah 1. Bersiaplah untuk membaca item dalam format baru

Selesaikan langkah-langkah berikut untuk mempersiapkan klien SDK Enkripsi AWS Database Anda untuk membaca item dalam format baru. Setelah Anda menerapkan perubahan berikut, klien Anda akan terus berperilaku dengan cara yang sama seperti di versi 2. x. Klien Anda akan terus membaca dan menulis item dalam versi 2. x format, tetapi perubahan ini mempersiapkan klien untuk membaca item dalam format baru.

Perbarui AWS SDK for Java ke versi 2.x

Versi 3. x dari pustaka enkripsi sisi klien Java untuk DynamoDB memerlukan DynamoDB Enhanced Client. DynamoDB Enhanced Client menggantikan DynamodBMapper yang digunakan dalam versi sebelumnya. Untuk menggunakan klien yang disempurnakan, Anda harus menggunakan AWS SDK for Java 2.x.

Ikuti petunjuk untuk bermigrasi dari versi 1.x ke 2.x. AWS SDK for Java

Untuk informasi lebih lanjut tentang AWS SDK for Java 2.x modul apa yang diperlukan, lihatPrasyarat.

Konfigurasikan klien Anda untuk membaca item yang dienkripsi oleh versi lama

Prosedur berikut memberikan gambaran tentang langkah-langkah yang ditunjukkan dalam contoh kode di bawah ini.

  1. Buat keyring.

    Keyrings dan manajer bahan kriptografi menggantikan penyedia bahan kriptografi yang digunakan dalam versi sebelumnya dari pustaka enkripsi sisi klien Java untuk DynamoDB.

    penting

    Kunci pembungkus yang Anda tentukan saat membuat keyring harus berupa kunci pembungkus yang sama yang Anda gunakan dengan penyedia bahan kriptografi Anda di versi 2. x.

  2. Buat skema tabel di atas kelas beranotasi Anda.

    Langkah ini mendefinisikan tindakan atribut yang akan digunakan ketika Anda mulai menulis item dalam format baru.

    Untuk panduan tentang penggunaan DynamoDB Enhanced Client baru, lihat Menghasilkan TableSchema a di AWS SDK for Java Panduan Pengembang.

    Contoh berikut mengasumsikan Anda memperbarui kelas beranotasi Anda dari versi 2. x menggunakan anotasi tindakan atribut baru. Untuk panduan selengkapnya tentang anotasi tindakan atribut Anda, lihat. Gunakan kelas data beranotasi

    catatan

    Jika Anda menentukan SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT atribut apa pun, maka atribut partisi dan sortir juga harusSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Untuk contoh yang menunjukkan anotasi yang digunakan untuk mendefinisikanSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, lihat SimpleClass4.java.

  3. Tentukan atribut mana yang dikecualikan dari tanda tangan.

  4. Konfigurasikan peta eksplisit tindakan atribut yang dikonfigurasi di kelas model versi 2.x Anda.

    Langkah ini mendefinisikan tindakan atribut yang digunakan untuk menulis item dalam format lama.

  5. Konfigurasikan yang DynamoDBEncryptor Anda gunakan di versi 2. x dari pustaka enkripsi sisi klien Java untuk DynamoDB.

  6. Konfigurasikan perilaku lama.

  7. Buat aDynamoDbEncryptionInterceptor.

  8. Buat klien AWS SDK DynamoDB baru.

  9. Buat DynamoDBEnhancedClient dan buat tabel dengan kelas model Anda.

    Untuk informasi selengkapnya tentang DynamoDB Enhanced Client, lihat membuat klien yang disempurnakan.

public class MigrationExampleStep1 { public static void MigrationStep1(String kmsKeyId, String ddbTableName, int sortReadValue) { // 1. Create a Keyring. // This example creates an AWS KMS Keyring that specifies the // same kmsKeyId previously used in the version 2.x configuration. // It uses the 'CreateMrkMultiKeyring' method to create the // keyring, so that the keyring can correctly handle both single // region and Multi-Region KMS Keys. // Note that this example uses the AWS SDK for Java v2 KMS client. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder() .generator(kmsKeyId) .build(); final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput); // 2. Create a Table Schema over your annotated class. // For guidance on using the new attribute actions // annotations, see SimpleClass.java in the // aws-database-encryption-sdk-dynamodb GitHub repository. // All primary key attributes must be signed but not encrypted // and by default all non-primary key attributes // are encrypted and signed (ENCRYPT_AND_SIGN). // If you want a particular non-primary key attribute to be signed but // not encrypted, use the 'DynamoDbEncryptionSignOnly' annotation. // If you want a particular attribute to be neither signed nor encrypted // (DO_NOTHING), use the 'DynamoDbEncryptionDoNothing' annotation. final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class); // 3. Define which attributes the client should expect to be excluded // from the signature when reading items. // This value represents all unsigned attributes across the entire // dataset. final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3"); // 4. Configure an explicit map of the attribute actions configured // in your version 2.x modeled class. final Map<String, CryptoAction> legacyActions = new HashMap<>(); legacyActions.put("partition_key", CryptoAction.SIGN_ONLY); legacyActions.put("sort_key", CryptoAction.SIGN_ONLY); legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN); legacyActions.put("attribute2", CryptoAction.SIGN_ONLY); legacyActions.put("attribute3", CryptoAction.DO_NOTHING); // 5. Configure the DynamoDBEncryptor that you used in version 2.x. final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient(); final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId); final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp); // 6. Configure the legacy behavior. // Input the DynamoDBEncryptor and attribute actions created in // the previous steps. For Legacy Policy, use // 'FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy continues to read // and write items using the old format, but will be able to read // items written in the new format as soon as they appear. final LegacyOverride legacyOverride = LegacyOverride .builder() .encryptor(oldEncryptor) .policy(LegacyPolicy.FORCE_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT) .attributeActionsOnEncrypt(legacyActions) .build(); // 7. Create a DynamoDbEncryptionInterceptor with the above configuration. final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>(); tableConfigs.put(ddbTableName, DynamoDbEnhancedTableEncryptionConfig.builder() .logicalTableName(ddbTableName) .keyring(kmsKeyring) .allowedUnsignedAttributes(allowedUnsignedAttributes) .schemaOnEncrypt(tableSchema) .legacyOverride(legacyOverride) .build()); final DynamoDbEncryptionInterceptor interceptor = DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor( CreateDynamoDbEncryptionInterceptorInput.builder() .tableEncryptionConfigs(tableConfigs) .build() ); // 8. Create a new AWS SDK DynamoDb client using the // interceptor from Step 7. final DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration( ClientOverrideConfiguration.builder() .addExecutionInterceptor(interceptor) .build()) .build(); // 9. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb client // created in Step 8, and create a table with your modeled class. final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema); } }

Langkah 2. Tulis item dalam format baru

Setelah Anda menerapkan perubahan dari Langkah 1 ke semua pembaca, selesaikan langkah-langkah berikut untuk mengonfigurasi klien SDK Enkripsi AWS Database Anda untuk menulis item dalam format baru. Setelah Anda menerapkan perubahan berikut, klien Anda akan melanjutkan membaca item dalam format lama dan mulai menulis dan membaca item dalam format baru.

Prosedur berikut memberikan gambaran tentang langkah-langkah yang ditunjukkan dalam contoh kode di bawah ini.

  1. Lanjutkan mengonfigurasi keyring, skema tabel, tindakan atribut lamaallowedUnsignedAttributes, dan DynamoDBEncryptor seperti yang Anda lakukan di Langkah 1.

  2. Perbarui perilaku lama Anda untuk hanya menulis item baru menggunakan format baru.

  3. Membuat tujuan

  4. Buat klien AWS SDK DynamoDB baru.

  5. Buat DynamoDBEnhancedClient dan buat tabel dengan kelas model Anda.

    Untuk informasi selengkapnya tentang DynamoDB Enhanced Client, lihat membuat klien yang disempurnakan.

public class MigrationExampleStep2 { public static void MigrationStep2(String kmsKeyId, String ddbTableName, int sortReadValue) { // 1. Continue to configure your keyring, table schema, legacy // attribute actions, allowedUnsignedAttributes, and // DynamoDBEncryptor as you did in Step 1. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder() .generator(kmsKeyId) .build(); final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput); final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class); final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3"); final Map<String, CryptoAction> legacyActions = new HashMap<>(); legacyActions.put("partition_key", CryptoAction.SIGN_ONLY); legacyActions.put("sort_key", CryptoAction.SIGN_ONLY); legacyActions.put("attribute1", CryptoAction.ENCRYPT_AND_SIGN); legacyActions.put("attribute2", CryptoAction.SIGN_ONLY); legacyActions.put("attribute3", CryptoAction.DO_NOTHING); final AWSKMS kmsClient = AWSKMSClientBuilder.defaultClient(); final DirectKmsMaterialProvider cmp = new DirectKmsMaterialProvider(kmsClient, kmsKeyId); final DynamoDBEncryptor oldEncryptor = DynamoDBEncryptor.getInstance(cmp); // 2. Update your legacy behavior to only write new items using the new // format. // For Legacy Policy, use 'FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT'. This policy // continues to read items in both formats, but will only write items // using the new format. final LegacyOverride legacyOverride = LegacyOverride .builder() .encryptor(oldEncryptor) .policy(LegacyPolicy.FORBID_LEGACY_ENCRYPT_ALLOW_LEGACY_DECRYPT) .attributeActionsOnEncrypt(legacyActions) .build(); // 3. Create a DynamoDbEncryptionInterceptor with the above configuration. final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>(); tableConfigs.put(ddbTableName, DynamoDbEnhancedTableEncryptionConfig.builder() .logicalTableName(ddbTableName) .keyring(kmsKeyring) .allowedUnsignedAttributes(allowedUnsignedAttributes) .schemaOnEncrypt(tableSchema) .legacyOverride(legacyOverride) .build()); final DynamoDbEncryptionInterceptor interceptor = DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor( CreateDynamoDbEncryptionInterceptorInput.builder() .tableEncryptionConfigs(tableConfigs) .build() ); // 4. Create a new AWS SDK DynamoDb client using the // interceptor from Step 3. final DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration( ClientOverrideConfiguration.builder() .addExecutionInterceptor(interceptor) .build()) .build(); // 5. Create the DynamoDbEnhancedClient using the AWS SDK DynamoDb Client created // in Step 4, and create a table with your modeled class. final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema); } }

Setelah menerapkan perubahan Langkah 2, Anda harus mengenkripsi ulang semua item lama di tabel Anda dengan format baru sebelum Anda dapat melanjutkan ke Langkah 3. Tidak ada metrik atau kueri tunggal yang dapat Anda jalankan untuk mengenkripsi item yang ada dengan cepat. Gunakan proses yang paling masuk akal untuk sistem Anda. Misalnya, Anda dapat menggunakan proses asinkron yang memindai tabel secara perlahan dan menulis ulang item menggunakan tindakan atribut baru dan konfigurasi enkripsi yang Anda tentukan.

Langkah 3. Hanya membaca dan menulis item dalam format baru

Setelah mengenkripsi ulang semua item dalam tabel Anda dengan format baru, Anda dapat menghapus perilaku lama dari konfigurasi Anda. Selesaikan langkah-langkah berikut untuk mengonfigurasi klien Anda agar hanya membaca dan menulis item dalam format baru.

Prosedur berikut memberikan gambaran tentang langkah-langkah yang ditunjukkan dalam contoh kode di bawah ini.

  1. Lanjutkan mengkonfigurasi keyring Anda, skema tabel, dan allowedUnsignedAttributes seperti yang Anda lakukan di Langkah 1. Hapus tindakan atribut lama dan DynamoDBEncryptor dari konfigurasi Anda.

  2. Buat aDynamoDbEncryptionInterceptor.

  3. Buat klien AWS SDK DynamoDB baru.

  4. Buat DynamoDBEnhancedClient dan buat tabel dengan kelas model Anda.

    Untuk informasi selengkapnya tentang DynamoDB Enhanced Client, lihat membuat klien yang disempurnakan.

public class MigrationExampleStep3 { public static void MigrationStep3(String kmsKeyId, String ddbTableName, int sortReadValue) { // 1. Continue to configure your keyring, table schema, // and allowedUnsignedAttributes as you did in Step 1. // Do not include the configurations for the DynamoDBEncryptor or // the legacy attribute actions. final MaterialProviders matProv = MaterialProviders.builder() .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) .build(); final CreateAwsKmsMrkMultiKeyringInput keyringInput = CreateAwsKmsMrkMultiKeyringInput.builder() .generator(kmsKeyId) .build(); final IKeyring kmsKeyring = matProv.CreateAwsKmsMrkMultiKeyring(keyringInput); final TableSchema<SimpleClass> schemaOnEncrypt = TableSchema.fromBean(SimpleClass.class); final List<String> allowedUnsignedAttributes = Arrays.asList("attribute3"); // 3. Create a DynamoDbEncryptionInterceptor with the above configuration. // Do not configure any legacy behavior. final Map<String, DynamoDbEnhancedTableEncryptionConfig> tableConfigs = new HashMap<>(); tableConfigs.put(ddbTableName, DynamoDbEnhancedTableEncryptionConfig.builder() .logicalTableName(ddbTableName) .keyring(kmsKeyring) .allowedUnsignedAttributes(allowedUnsignedAttributes) .schemaOnEncrypt(tableSchema) .build()); final DynamoDbEncryptionInterceptor interceptor = DynamoDbEnhancedClientEncryption.CreateDynamoDbEncryptionInterceptor( CreateDynamoDbEncryptionInterceptorInput.builder() .tableEncryptionConfigs(tableConfigs) .build() ); // 4. Create a new AWS SDK DynamoDb client using the // interceptor from Step 3. final DynamoDbClient ddb = DynamoDbClient.builder() .overrideConfiguration( ClientOverrideConfiguration.builder() .addExecutionInterceptor(interceptor) .build()) .build(); // 5. Create the DynamoDbEnhancedClient using the AWS SDK Client // created in Step 4, and create a table with your modeled class. final DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder() .dynamoDbClient(ddb) .build(); final DynamoDbTable<SimpleClass> table = enhancedClient.table(ddbTableName, tableSchema); } }