Esegui la migrazione alla versione 3.x della libreria di crittografia lato client Java per DynamoDB

La nostra libreria di crittografia lato client è stata rinominata AWS Database Encryption SDK. Questa guida per sviluppatori fornisce ancora informazioni sul DynamoDB Encryption Client.

Versione 3. x della libreria di crittografia lato client Java per DynamoDB è una riscrittura importante della 2. x codice base. Include molti aggiornamenti, come un nuovo formato di dati strutturati, un supporto multitenancy migliorato, modifiche dello schema senza interruzioni e supporto per la crittografia ricercabile. Questo argomento fornisce indicazioni su come migrare il codice alla versione 3. x.

Migrazione dalla versione 1.x alla 2.x

Migrare alla versione 2. x prima di migrare alla versione 3. x. Versione 2. x ha cambiato il simbolo del provider più recente da MostRecentProvider aCachingMostRecentProvider. Se attualmente utilizzi la versione 1. x della libreria di crittografia lato client Java per DynamoDB con il MostRecentProvider simbolo, è necessario aggiornare il nome del simbolo nel codice su. CachingMostRecentProvider Per ulteriori informazioni, consulta Updates to the Most Recent Provider.

Migrazione dalla versione 2.x alla 3.x

Le seguenti procedure descrivono come migrare il codice dalla versione 2. x alla versione 3. x della libreria di crittografia lato client Java per DynamoDB.

Fase 1: Preparati a leggere gli articoli nel nuovo formato

Completa i seguenti passaggi per preparare il client AWS Database Encryption SDK alla lettura degli elementi nel nuovo formato. Dopo aver implementato le seguenti modifiche, il client continuerà a comportarsi nello stesso modo in cui si comportava nella versione 2. x. Il tuo client continuerà a leggere e scrivere elementi nella versione 2. formato x, ma queste modifiche preparano il client a leggere gli elementi nel nuovo formato.

Aggiorna il tuo AWS SDK for Java alla versione 2.x

Versione 3. x della libreria di crittografia lato client Java per DynamoDB richiede DynamoDB Enhanced Client. Il DynamoDB Enhanced Client sostituisce il DynamodBMapper utilizzato nelle versioni precedenti. Per utilizzare il client avanzato, è necessario utilizzare il. AWS SDK for Java 2.x

Segui le istruzioni per la migrazione dalla versione 1.x alla 2.x di. AWS SDK for Java

Per ulteriori informazioni sui AWS SDK for Java 2.x moduli richiesti, vedere. Prerequisiti

Configura il tuo client per leggere gli elementi crittografati dalle versioni precedenti

Le seguenti procedure forniscono una panoramica dei passaggi illustrati nell'esempio di codice riportato di seguito.

1. Crea un portachiavi.

   I portachiavi e i gestori di materiali crittografici sostituiscono i fornitori di materiali crittografici utilizzati nelle versioni precedenti della libreria di crittografia lato client Java per DynamoDB.

   Importante

   Le chiavi di wrapping specificate durante la creazione di un portachiavi devono essere le stesse chiavi di wrapping utilizzate con il fornitore di materiali crittografici nella versione 2. x.

2. Crea uno schema tabellare sulla tua classe annotata.

   Questo passaggio definisce le azioni degli attributi che verranno utilizzate quando inizierai a scrivere elementi nel nuovo formato.

   Per indicazioni sull'uso del nuovo DynamoDB Enhanced Client, consulta Generate a nella AWS SDK for Java Developer TableSchema Guide.

   L'esempio seguente presuppone che tu abbia aggiornato la tua classe annotata dalla versione 2. x utilizzando le nuove annotazioni sulle azioni degli attributi. Per ulteriori indicazioni sull'annotazione delle azioni relative agli attributi, vedere. Utilizza una classe di dati annotata

   Nota

   Se si specificano degli SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT attributi, devono esserlo anche gli attributi di partizione e ordinamento. SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT Per un esempio che mostra le annotazioni utilizzate per definireSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, vedete SimpleClass 4.java.

3. Definire quali attributi sono esclusi dalla firma.

4. Configura una mappa esplicita delle azioni degli attributi configurate nella classe modellata della versione 2.x.

   Questo passaggio definisce le azioni degli attributi utilizzate per scrivere gli elementi nel vecchio formato.

5. Configura quello DynamoDBEncryptor che hai usato nella versione 2. x della libreria di crittografia lato client Java per DynamoDB.

6. Configura il comportamento precedente.

7. Creare un DynamoDbEncryptionInterceptor.

8. Crea un nuovo client AWS SDK DynamoDB.

9. Crea DynamoDBEnhancedClient e crea una tabella con la tua classe modellata.

   Per ulteriori informazioni sul DynamoDB Enhanced Client, consulta creare un client avanzato.

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

Mostra piùMostra meno

Fase 2: Scrivi gli elementi nel nuovo formato

Dopo aver distribuito le modifiche dal Passaggio 1 a tutti i lettori, completa i passaggi seguenti per configurare il client AWS Database Encryption SDK per scrivere elementi nel nuovo formato. Dopo aver implementato le seguenti modifiche, il client continuerà a leggere gli elementi nel vecchio formato e inizierà a scrivere e leggere gli elementi nel nuovo formato.

Le seguenti procedure forniscono una panoramica dei passaggi illustrati nell'esempio di codice riportato di seguito.

1. Continua a configurare il portachiavi, lo schema della tabellaallowedUnsignedAttributes, le azioni degli attributi legacy e DynamoDBEncryptor come hai fatto nel passaggio 1.

2. Aggiorna il tuo comportamento precedente per scrivere solo nuovi elementi utilizzando il nuovo formato.

3. Creazione di una destinazione DynamoDbEncryptionInterceptor

4. Crea un nuovo client AWS SDK DynamoDB.

5. Crea DynamoDBEnhancedClient e crea una tabella con la tua classe modellata.

   Per ulteriori informazioni sul DynamoDB Enhanced Client, consulta creare un client avanzato.

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

Mostra piùMostra meno

Dopo aver implementato le modifiche della Fase 2, è necessario crittografare nuovamente tutti i vecchi elementi della tabella con il nuovo formato prima di poter continuare con la Fase 3. Non è possibile eseguire alcuna metrica o query per crittografare rapidamente gli elementi esistenti. Utilizzate il processo più adatto al vostro sistema. Ad esempio, è possibile utilizzare un processo asincrono che scansiona lentamente la tabella e quindi riscrive gli elementi utilizzando le nuove azioni degli attributi e la configurazione di crittografia definite.

Fase 3. Leggi e scrivi solo elementi nel nuovo formato

Dopo aver ricrittografato tutti gli elementi della tabella con il nuovo formato, puoi rimuovere il comportamento precedente dalla tua configurazione. Completa i seguenti passaggi per configurare il client in modo che legga e scriva solo elementi nel nuovo formato.

Le seguenti procedure forniscono una panoramica dei passaggi illustrati nell'esempio di codice riportato di seguito.

1. Continua a configurare il portachiavi, lo schema della tabella e allowedUnsignedAttributes come hai fatto nel passaggio 1. Rimuovi le azioni degli attributi precedenti DynamoDBEncryptor dalla tua configurazione.

2. Creare un DynamoDbEncryptionInterceptor.

3. Crea un nuovo client AWS SDK DynamoDB.

4. Crea DynamoDBEnhancedClient e crea una tabella con la tua classe modellata.

   Per ulteriori informazioni sul DynamoDB Enhanced Client, consulta creare un client avanzato.

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

Mostra piùMostra meno