Using the DynamoDB Encryption Client for Python

This topic explains some of the features of the DynamoDB Encryption Client for Python that might not be found in other programming language implementations. These features are designed to make it easier to use the DynamoDB Encryption Client in the most secure way. Unless you have an unusual use case, we recommend that you use them.

For details about programming with the DynamoDB Encryption Client, see the Python examples in this guide, the examples in the aws-dynamodb-encryption-python repository on GitHub, and the Python documentation for the DynamoDB Encryption Client.

Client helper classes

The DynamoDB Encryption Client for Python includes several client helper classes that mirror the Boto 3 classes for DynamoDB. These helper classes are designed to make it easier to add encryption and signing to your existing DynamoDB application and avoid the most common problems, as follows:

You can use the client helper classes instead of interacting directly with the lower-level item encryptor. Use these classes unless you need to set advanced options in the item encryptor.

The client helper classes include:

To use the client helper classes, the caller must have permission to call the DynamoDB DescribeTable operation on the target table.

TableInfo class

The TableInfo class is a helper class that represents a DynamoDB table, complete with fields for its primary key and secondary indexes. It helps you to get accurate, real-time information about the table.

If you use a client helper class, it creates and uses a TableInfo object for you. Otherwise, you can create one explicitly. For an example, see Use the item encryptor.

When you call the refresh_indexed_attributes method on a TableInfo object, it populates the property values of the object by calling the DynamoDB DescribeTable operation. Querying the table is much more reliable than hard-coding index names. The TableInfo class also includes an encryption_context_values property that provides the required values for the DynamoDB encryption context.

To use the refresh_indexed_attributes method, the caller must have permission to call the DynamoDB DescribeTable operation on the target table.

Attribute actions in Python

Attribute actions tell the item encryptor which actions to perform on each attribute of the item. To specify attribute actions in Python, create an AttributeActions object with a default action and any exceptions for particular attributes. The valid values are defined in the CryptoAction enumerated type.

DO_NOTHING = 0
SIGN_ONLY = 1
ENCRYPT_AND_SIGN = 2

For example, this AttributeActions object establishes ENCRYPT_AND_SIGN as the default for all attributes, and specifies exceptions for the ISBN and PublicationYear attributes.

actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
    attribute_actions={
        'ISBN': CryptoAction.DO_NOTHING,
        'PublicationYear': CryptoAction.SIGN_ONLY
    }
)

If you use a client helper class, you don't need to specify an attribute action for the primary key attributes. The client helper classes prevent you from encrypting your primary key.

If you do not use a client helper class and the default action is ENCRYPT_AND_SIGN, you must specify an action for the primary key. The recommended action for primary keys is SIGN_ONLY. To make this easy, use the set_index_keys method, which uses SIGN_ONLY for primary keys, or DO_NOTHING, when that is the default action.

actions = AttributeActions(
    default_action=CryptoAction.ENCRYPT_AND_SIGN,
)
actions.set_index_keys(*table_info.protected_index_keys())