移轉至適用於 DynamoDB 的 Java 用戶端加密程式庫 3.x 版 - AWS 資料庫加密 SDK
從 1.x 版移轉至 2.x 版從 2.x 版移轉至 3.x 版

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

移轉至適用於 DynamoDB 的 Java 用戶端加密程式庫 3.x 版

我們的用戶端加密程式庫已重新命名為 AWS 資料庫加密 SDK。本開發人員指南仍提供 DynamoDB 加密用戶端的相關資訊。

版本 3. 適用於 DynamoDB 的 Java 用戶端加密程式庫的 x 是 2 的主要重新寫入。 x 代碼庫。它包含許多更新，例如新的結構化資料格式、改進的多租戶支援、順暢的結構描述變更，以及可搜尋的加密支援。本主題提供如何將程式碼移轉至第 3 版的指引。 x.

從 1.x 版移轉至 2.x 版

移轉至版本 2。 x，然後再移轉至版本 3。 x. 版本 2. x 將「最近提供者」的符號從變更MostRecentProvider為CachingMostRecentProvider。如果您目前使用版本 1。 具有MostRecentProvider符號的 DynamoDB 的 Java 用戶端加密程式庫的 x，您必須將程式碼中的符號名稱更新為。CachingMostRecentProvider如需詳細資訊，請參閱最新提供者的更新。

從 2.x 版移轉至 3.x 版

下列程序說明如何從版本 2 移轉程式碼。 x 轉換為版本 3。 適用於 Java 用戶端加密程式 DynamoDB x 個。

步驟 1. 準備閱讀新格式的項目

完成下列步驟，準備您的 AWS 資料庫加密 SDK 用戶端以讀取新格式的項目。部署下列變更之後，用戶端將繼續以與第 2 版相同的方式運作。 x. 您的客戶端將繼續讀取和寫入第 2 版中的項目。 x 格式，但這些變更會讓用戶端以新格式讀取項目做好準備。

AWS SDK for Java 將您的更新到 2.x 版

版本 3. DynamoDB 的 Java 用戶端加密程式庫的 x 個需要使用 DynamoDB 增強型用戶端。DynamoDB 增強型用戶端會取代舊版中使用的 DynamoDBMapper。若要使用增強型用戶端，您必須使用 AWS SDK for Java 2.x.

請遵循從 1.x 版移轉至 2.x 版的指示。 AWS SDK for Java

如需需要哪些 AWS SDK for Java 2.x 模組的詳細資訊，請參閱必要條件。

設定您的用戶端讀取由舊版加密的項目

下列程序提供以下程式碼範例中所示步驟的概觀。

  1. 建立鑰匙圈。

    金鑰圈和加密材料管理員會取代舊版 DynamoDB Java 用戶端加密程式庫中使用的加密材料提供者。

    重要

    您在建立金鑰圈時指定的包裝金鑰必須與您在第 2 版中搭配加密材料提供者使用的包裝金鑰相同。 x.

  2. 在您的註釋類上創建一個表格模式。

    此步驟定義開始以新格式撰寫項目時將使用的屬性動作。

    如需使用新 DynamoDB 增強型用戶端的指引，請參閱AWS SDK for Java 開發人員指南TableSchema中的產生 a。

    下列範例假設您已從版本 2 更新已註解的類別。 x 使用新的屬性動作註釋。如需註解屬性動作的詳細指引，請參閱。使用帶註釋的數據類

    注意

    如果您指定任何SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT屬性，則分割區和排序屬性也必須是SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT。如需顯示用於定義之註釋的範例SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT，請參閱 SimpleClass4.java。

  3. 定義要從簽章中排除的屬性。

  4. 配置在 2.x 版模型化類別中配置的屬性動作的明確對映。

    此步驟會定義用來以舊格式寫入項目的屬性動作。

  5. 配置DynamoDBEncryptor您在版本 2 中使用的。 適用於 Java 用戶端加密程式 DynamoDB x 個。

  6. 設定舊版行為。

  7. 建立 DynamoDbEncryptionInterceptor。

  8. 建立新的 Dynam AWS oDB 戶端。

  9. 使用您的模型化類創建DynamoDBEnhancedClient並創建一個表。

    如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。

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);
    }
}
顯示較多顯示較少

步驟 2. 以新格式寫入項目

將步驟 1 的變更部署到所有讀取器之後，請完成下列步驟，將資 AWS 料庫加密 SDK 用戶端設定為以新格式寫入項目。部署下列變更之後，用戶端會繼續讀取舊格式的項目，並開始以新格式撰寫和讀取項目。

下列程序提供以下程式碼範例中所示步驟的概觀。

  1. 繼續設定金鑰圈、資料表結構描述、舊屬性動作allowedUnsignedAttributes，以及您在步驟 1 中DynamoDBEncryptor所做的一樣。

  2. 將舊版行為更新為僅使用新格式寫入新項目。

  3. 建立DynamoDbEncryptionInterceptor

  4. 建立新的 Dynam AWS oDB 戶端。

  5. 使用您的模型化類創建DynamoDBEnhancedClient並創建一個表。

    如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。

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);
    }
}
顯示較多顯示較少

部署步驟 2 變更之後，您必須使用新格式重新加密資料表中的所有舊項目，才能繼續執行步驟 3。您無法執行單一指標或查詢來快速加密現有項目。使用對您的系統最有意義的過程。例如，您可以使用非同步程序來緩慢掃描表格，並使用您定義的新屬性動作和加密配置重寫項目。

步驟 3。只讀取和寫入新格式的項目

使用新格式重新加密表格中的所有項目之後，您可以從組態中移除舊版行為。完成下列步驟，將用戶端設定為只讀取和寫入新格式的項目。

下列程序提供以下程式碼範例中所示步驟的概觀。

  1. 繼續設定金鑰圈、資料表結構描述，以allowedUnsignedAttributes及在步驟 1 中所做的一樣。移除舊有屬性動作，並DynamoDBEncryptor從您的組態中移除。

  2. 建立 DynamoDbEncryptionInterceptor。

  3. 建立新的 Dynam AWS oDB 戶端。

  4. 使用您的模型化類創建DynamoDBEnhancedClient並創建一個表。

    如需 DynamoDB 增強型用戶端的詳細資訊，請參閱建立增強型用戶端。

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);
    }
}
顯示較多顯示較少