Migrer vers la version 3.x de la bibliothèque de chiffrement côté client Java pour DynamoDB

Notre bibliothèque de chiffrement côté client a été renommée SDK de chiffrement de AWS base de données. Ce guide du développeur fournit toujours des informations sur le client de chiffrement DynamoDB.

Version 3. x de la bibliothèque de chiffrement côté client Java pour DynamoDB est une réécriture majeure du 2. base de code x. Il inclut de nombreuses mises à jour, telles qu'un nouveau format de données structuré, une prise en charge améliorée de la mutualisation, des modifications de schéma fluides et la prise en charge du chiffrement consultable. Cette rubrique fournit des conseils sur la façon de migrer votre code vers la version 3. x.

Migration de la version 1.x vers la version 2.x

Migrez vers la version 2. x avant de migrer vers la version 3. x. Version 2. x a changé le symbole du fournisseur le plus récent de MostRecentProvider àCachingMostRecentProvider. Si vous utilisez actuellement la version 1. x de la bibliothèque de chiffrement côté client Java pour DynamoDB avec le MostRecentProvider symbole, vous devez mettre à jour le nom du symbole dans votre code en. CachingMostRecentProvider Pour plus d'informations, voir Mises à jour du fournisseur le plus récent.

Migration de la version 2.x vers la version 3.x

Les procédures suivantes décrivent comment migrer votre code depuis la version 2. x vers la version 3. x de la bibliothèque de chiffrement côté client Java pour DynamoDB.

Étape 1. Préparez-vous à lire les éléments dans le nouveau format

Procédez comme suit pour préparer votre client AWS Database Encryption SDK à lire les éléments dans le nouveau format. Après avoir déployé les modifications suivantes, votre client continuera à se comporter de la même manière que dans la version 2. x. Votre client continuera à lire et à écrire des éléments dans la version 2. format x, mais ces modifications préparent le client à lire les éléments dans le nouveau format.

Mettez à jour votre AWS SDK for Java version 2.x

Version 3. x de la bibliothèque de chiffrement côté client Java pour DynamoDB nécessite le client DynamoDB amélioré. Le DynamoDB Enhanced Client remplace le DynamoDBMapper utilisé dans les versions précédentes. Pour utiliser le client amélioré, vous devez utiliser le AWS SDK for Java 2.x.

Suivez les instructions de migration de la version 1.x vers la version 2.x du. AWS SDK for Java

Pour plus d'informations sur les AWS SDK for Java 2.x modules requis, consultezPrérequis.

Configurez votre client pour lire les éléments chiffrés par les anciennes versions

Les procédures suivantes fournissent une vue d'ensemble des étapes illustrées dans l'exemple de code ci-dessous.

1. Créez un porte-clés.

   Les porte-clés et les gestionnaires de matériel cryptographique remplacent les fournisseurs de matériel cryptographique utilisés dans les versions précédentes de la bibliothèque de chiffrement côté client Java pour DynamoDB.

   Important

   Les clés d'encapsulation que vous spécifiez lors de la création d'un jeu de clés doivent être les mêmes que celles que vous avez utilisées avec votre fournisseur de matériel cryptographique dans la version 2. x.

2. Créez un schéma de table au-dessus de votre classe annotée.

   Cette étape définit les actions d'attribut qui seront utilisées lorsque vous commencerez à écrire des éléments dans le nouveau format.

   Pour obtenir des conseils sur l'utilisation du nouveau client DynamoDB amélioré, reportez-vous à la section Generate TableSchema a du guide du développeur.AWS SDK for Java

   L'exemple suivant suppose que vous avez mis à jour votre classe annotée à partir de la version 2. x en utilisant les nouvelles annotations d'actions d'attribut. Pour plus d'informations sur l'annotation des actions de vos attributs, consultezUtiliser une classe de données annotée.

   Note

   Si vous spécifiez des SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT attributs, les attributs de partition et de tri doivent également l'êtreSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Pour un exemple illustrant les annotations utilisées pour définirSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, consultez SimpleClass4.java.

3. Définissez les attributs exclus de la signature.

4. Configurez une carte explicite des actions d'attributs configurées dans votre classe modélisée de la version 2.x.

   Cette étape définit les actions d'attribut utilisées pour écrire des éléments dans l'ancien format.

5. Configurez le DynamoDBEncryptor que vous avez utilisé dans la version 2. x de la bibliothèque de chiffrement côté client Java pour DynamoDB.

6. Configurez le comportement existant.

7. Créez un DynamoDbEncryptionInterceptor.

8. Créez un nouveau client AWS DynamoDB SDK.

9. Créez le DynamoDBEnhancedClient et créez un tableau avec votre classe modélisée.

   Pour plus d'informations sur le client DynamoDB amélioré, voir créer un client amélioré.

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);
    }
}

Afficher plusAfficher moins

Étape 2. Écrire des éléments dans le nouveau format

Après avoir déployé les modifications apportées à l'étape 1 sur tous les lecteurs, effectuez les étapes suivantes pour configurer votre client AWS Database Encryption SDK afin d'écrire des éléments dans le nouveau format. Après avoir déployé les modifications suivantes, votre client continuera à lire les éléments dans l'ancien format et commencera à écrire et à lire des éléments dans le nouveau format.

Les procédures suivantes fournissent une vue d'ensemble des étapes illustrées dans l'exemple de code ci-dessous.

1. Continuez à configurer votre trousseau de clés, votre schéma de table, vos anciennes actions attributairesallowedUnsignedAttributes, DynamoDBEncryptor comme vous l'avez fait à l'étape 1.

2. Mettez à jour votre ancien comportement pour n'écrire que les nouveaux éléments en utilisant le nouveau format.

3. Création d'un DynamoDbEncryptionInterceptor

4. Créez un nouveau client AWS DynamoDB SDK.

5. Créez le DynamoDBEnhancedClient et créez un tableau avec votre classe modélisée.

   Pour plus d'informations sur le client DynamoDB amélioré, voir créer un client amélioré.

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);
    }
}

Afficher plusAfficher moins

Après avoir déployé les modifications de l'étape 2, vous devez rechiffrer tous les anciens éléments de votre tableau avec le nouveau format avant de passer à l'étape 3. Il n'existe pas de métrique ou de requête unique que vous puissiez exécuter pour chiffrer rapidement vos éléments existants. Utilisez le processus le mieux adapté à votre système. Par exemple, vous pouvez utiliser un processus asynchrone qui analyse lentement la table et réécrit les éléments à l'aide des nouvelles actions attributaires et de la nouvelle configuration de chiffrement que vous avez définies.

Étape 3. Lisez et écrivez uniquement les éléments dans le nouveau format

Après avoir rechiffré tous les éléments de votre tableau avec le nouveau format, vous pouvez supprimer le comportement existant de votre configuration. Procédez comme suit pour configurer votre client de manière à ce qu'il lise et écrive uniquement les éléments dans le nouveau format.

Les procédures suivantes fournissent une vue d'ensemble des étapes illustrées dans l'exemple de code ci-dessous.

1. Continuez à configurer votre trousseau de clés, votre schéma de table, allowedUnsignedAttributes comme vous l'avez fait à l'étape 1. Supprimez les anciennes actions attributaires et DynamoDBEncryptor supprimez-les de votre configuration.

2. Créez un DynamoDbEncryptionInterceptor.

3. Créez un nouveau client AWS DynamoDB SDK.

4. Créez le DynamoDBEnhancedClient et créez un tableau avec votre classe modélisée.

   Pour plus d'informations sur le client DynamoDB amélioré, voir créer un client amélioré.

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);
    }
}

Afficher plusAfficher moins