Migración de la versión 1.x a la versión 2.x Migración de la versión 2.x a la versión 3.x

Migre a la versión 3.x de la biblioteca de cifrado del cliente de Java para DynamoDB

Se cambió el nombre de nuestra biblioteca de cifrado del lado del cliente por el de SDK de cifrado de AWS bases de datos. En esta guía para desarrolladores, se sigue proporcionando información sobre el cliente de cifrado de DynamoDB.

Versión 3.x de la biblioteca de cifrado del cliente de Java para DynamoDB es una importante reescritura de la base de código 2.x. Incluye numerosas actualizaciones, como un nuevo formato de datos estructurados, una compatibilidad mejorada de multitenencia, cambios de esquema fluidos y compatibilidad con el cifrado para búsquedas. En este tema se proporciona orientación sobre cómo migrar el código a la versión 3.x.

Migración de la versión 1.x a la versión 2.x

Migre a la versión 2.x antes de migrar a la versión 3.x. Versión 2. x cambió el símbolo del proveedor más reciente de MostRecentProvider aCachingMostRecentProvider. Si actualmente usa la versión 1. x de la biblioteca de cifrado del cliente de Java para DynamoDB con el MostRecentProvider símbolo, debe actualizar el nombre del símbolo en el código a. CachingMostRecentProvider Para obtener más información, consulte Actualizaciones del proveedor más reciente.

Migración de la versión 2.x a la versión 3.x

En los siguientes procedimientos se describe cómo migrar el código desde la versión 2.x a la versión 3.x de la biblioteca de cifrado del cliente de Java para DynamoDB.

Paso 1. Prepárese para leer los elementos en el nuevo formato

Complete los siguientes pasos para preparar su cliente del SDK AWS de cifrado de bases de datos para leer los elementos en el nuevo formato. Tras implementar los siguientes cambios, el cliente seguirá comportándose del mismo modo que en la versión 2. x. Su cliente seguirá leyendo y escribiendo los elementos de la versión 2. formato x, pero estos cambios preparan al cliente para leer los elementos en el nuevo formato.

Actualice su versión AWS SDK for Java a la 2.x

Versión 3.x de la biblioteca de cifrado del cliente de Java para DynamoDB requiere el cliente mejorado de DynamoDB. El cliente mejorado de DynamoDB reemplaza al DynamoDBMapper utilizado en versiones anteriores. Para usar el cliente mejorado, debe usar el. AWS SDK for Java 2.x

Siga las instrucciones para migrar de la versión 1.x a la 2.x de AWS SDK for Java.

Para obtener más información sobre los AWS SDK for Java 2.x módulos necesarios, consulteRequisitos previos.

Configure su cliente para que lea los elementos cifrados por las versiones antiguas

Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.

Cree un conjunto de claves.

Los administradores de conjunto de claves y materiales criptográficos sustituyen a los proveedores de materiales criptográficos utilizados en las versiones anteriores de la biblioteca de cifrado del cliente de Java para DynamoDB.

importante
Las claves de encapsulación que especifique al crear un conjunto de claves deben ser las mismas claves de encapsulación que utilizó con su proveedor de materiales criptográficos en la versión 2. x.
Crea un esquema de tabla sobre tu clase anotada.

En este paso se definen las acciones de atributos que se utilizarán cuando comience a escribir elementos en el nuevo formato.

Para obtener instrucciones sobre el uso del nuevo cliente mejorado de DynamoDB, consulte Generar un TableSchema en la Guía para desarrolladores de AWS SDK for Java .

En el siguiente ejemplo, se supone que actualizó la clase anotada a partir de la versión 2.x utilizando las nuevas anotaciones de acciones de atributos. Para obtener más información sobre cómo anotar las acciones de los atributos, consulte Utilice una clase de datos anotada.

nota
Si especifica algún SIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT atributo, los atributos de partición y ordenación también deben serloSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT. Para ver un ejemplo que muestre las anotaciones utilizadas para definirSIGN_AND_INCLUDE_IN_ENCRYPTION_CONTEXT, consulte SimpleClass4.java.
Defina qué atributos se excluyen de la firma.
Configure un mapa explícito de las acciones de los atributos configuradas en su clase modelada de la versión 2.x.

En este paso, se definen las acciones de atributo utilizadas para escribir los elementos en el formato anterior.
Configure el DynamoDBEncryptor que utilizó en la versión 2. x de la biblioteca de cifrado del cliente de Java para DynamoDB.
Configure el comportamiento heredado.
Crear una DynamoDbEncryptionInterceptor.
Cree un nuevo cliente AWS SDK de DynamoDB.
Cree el DynamoDBEnhancedClient y cree una tabla con su clase modelada.

Para obtener más información sobre el cliente mejorado de DynamoDB, consulte crear un cliente mejorado.


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

Mostrar menos

Paso 2. Escriba los elementos en el nuevo formato

Una vez implementados los cambios del paso 1 en todos los lectores, complete los siguientes pasos para configurar su cliente del SDK de cifrado de AWS bases de datos para escribir elementos en el nuevo formato. Tras implementar los siguientes cambios, el cliente seguirá leyendo los elementos en el formato anterior y empezará a escribir y leer los elementos en el nuevo formato.

Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.

Siga configurando el conjunto de claves, el esquema de la tabla, las acciones de los atributos heredados, allowedUnsignedAttributes y DynamoDBEncryptor tal y como hizo en el Paso 1.
Actualice su comportamiento anterior para escribir solo elementos nuevos con el nuevo formato.
Crear una DynamoDbEncryptionInterceptor
Cree un nuevo cliente AWS SDK de DynamoDB.
Cree el DynamoDBEnhancedClient y cree una tabla con su clase modelada.

Para obtener más información sobre el cliente mejorado de DynamoDB, consulte Create an enhanced client.


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

Mostrar menos

Tras implementar los cambios del paso 2, debe volver a cifrar todos los elementos antiguos de la tabla con el nuevo formato para poder continuar con el Paso 3. No hay una única métrica o consulta que puedas ejecutar para cifrar rápidamente los elementos existentes. Utilice el proceso que mejor se adapte a su sistema. Por ejemplo, podría utilizar un proceso asíncrono que escanee lentamente la tabla y reescriba los elementos utilizando las nuevas acciones de atributo y la nueva configuración de cifrado que haya definido.

Paso 3. Lea y escriba únicamente los elementos en el nuevo formato

Tras volver a cifrar todos los elementos de la tabla con el nuevo formato, puede eliminar el comportamiento anterior de la configuración. Siga los pasos que se indican a continuación para configurar el cliente para que solo lea y escriba los elementos en el nuevo formato.

Los siguientes procedimientos proporcionan una descripción general de los pasos que se muestran en el siguiente ejemplo de código.

Continúe configurando el conjunto de claves, el esquema de la tabla y allowedUnsignedAttributes tal como lo hizo en el Paso 1. Elimine las acciones y acciones de los atributos heredados DynamoDBEncryptor de su configuración.
Crear una DynamoDbEncryptionInterceptor.
Cree un nuevo cliente AWS SDK de DynamoDB.
Cree el DynamoDBEnhancedClient y cree una tabla con su clase modelada.

Para obtener más información sobre el cliente mejorado de DynamoDB, consulte Create an enhanced client.


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

Mostrar menos

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Agregar la versión 3.x a una tabla existente

.NET