Required Prerequisites

• Python 3.8+

Installation

Concepts

For a detailed description of the concepts that are important to understand when using this client, please review our Concepts Guide.

Helper Clients

We provide helper clients that look and feel like the low level client (EncryptedClient), service resource (EncryptedResource), and table resource (EncryptedTable) available from the boto3 library. For most uses, once configured, these clients can be used exactly as you would a standard client from boto3, and your items will be transparently encrypted on write and decrypted on read.

Item Encryptor

The helper clients provide a familiar interface but the actual item encryption and decryption is handled by a low-level item encryptor. You usually will not need to interact with these low-level functions, but for certain advanced use cases it can be useful.

If you do choose to use the item encryptor functions directly, you will need to provide a CryptoConfig for each call.

>>> from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item, encrypt_python_item
>>> plaintext_item = {
...     'some': 'data',
...     'more': 5
... }
>>> encrypted_item = encrypt_python_item(
...     item=plaintext_item,
...     crypto_config=my_crypto_config
... )
>>> decrypted_item = decrypt_python_item(
...     item=encrypted_item,
...     crypto_config=my_crypto_config
... )

Advanced Use

By default, the helper clients use your attribute actions and cryptographic materials provider to build the CryptoConfig that is provided to the item encryptor. For some advanced use cases, you might want to provide a custom CryptoConfig for specific operations.

All data plane operations (get item, put item, etc) on helper clients accept a crypto_config parameter in addition to all of the parameters that the underlying boto3 client accepts.

If this parameter is supplied, that CryptoConfig will be used for that operation instead of the one that the client would normally construct for you.

>>> from dynamodb_encryption_sdk.encrypted.table import EncryptedTable
>>> encrypted_table = EncryptedTable(
...     table=table,
...     materials_provider=my_crypto_materials_provider
... )
>>> encrypted_table.put_item(
...     Item=my_standard_item
... )  # this uses the crypto config built by the helper
>>> encrypted_table.put_item(
...     Item=my_special_item,
...     crypto_config=my_special_crypto_config
... )  # this uses my_special_crypto_config