Amazon DynamoDB Encryption Client for Python
The Amazon DynamoDB Encryption Client for Python provides client-side encryption of Amazon DynamoDB items to help you to protect your table data before you send it to DynamoDB. It provides an implementation of the Amazon DynamoDB Encryption Client that is fully compatible with the Amazon DynamoDB Encryption Client for Java.
You can find the latest Python documentation at Read the Docs and you can find the latest full documents in our primary documents.
You can find our source on GitHub.
See Support Policy for details on the current support status of all major versions of this library.
Getting Started
Required Prerequisites
Python 3.8+
Installation
Note
If you have not already installed cryptography, you might need to install additional prerequisites as detailed in the cryptography installation guide for your operating system.
$ pip install dynamodb-encryption-sdk
Concepts
For a detailed description of the concepts that are important to understand when using this client, please review our Concepts Guide.
Usage
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.
What can’t I do with the helper clients?
For most uses, the helper clients (once configured) can be used as drop-in replacements for the boto3 clients. However, there are a couple cases where this is not the case.
Update Item
Because we can’t know that a partial update you might be making to an item covers all
of the signed attributes in your item, we do not allow update_item
on the helper clients.
This is because if you update only some of the signed attributes, then next time you try to read that item the signature validation will fail.
Attribute Filtering
Because we can’t know what attributes in an item are signed, the helper clients do not allow any attribute filtering.
For get_item
, batch_get_item
, and scan
, this includes the use of AttributesToGet
and ProjectionExpression
.
For scan
, this also includes the use of Select
values SPECIFIC_ATTRIBUTES
and
ALL_PROJECTED_ATTRIBUTES
.
This is because if you do not retrieve all signed attributes, the signature validation will fail.
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
... )
When should I use the item encryptor?
One example of a use case where you might want to use the item encryptor directly is when processing items in a DynamoDB Stream. Since you receive the items data directly, and in DynamoDB JSON format, you can use the decrypt_dynamodb_item function to decrypt the item in the stream. We also provide helper transformation functions
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
API
Changelog
3.3.0 – 2024-08-05
Deprecation
The AWS DynamoDB Encryption Client for Python no longer supports Python 3.7 as of version 3.3 - Only Python 3.8+ is supported.
We no longer support OpenSSL 1.0.1 or 1.0.2, as per cryptography documentation.
Feature
Warn on Deprecated Python 3.7 usage
Add Python 3.11 to CI
Add Python 3.12 to CI
Maintenance
Update requirements for boto3 (>=1.10.0) and cryptography (>=3.4.6)
3.2.0 – 2021-12-19
Deprecation
The AWS DynamoDB Encryption Client for Python no longer supports Python 3.6 as of version 3.2; only Python 3.7+ is supported.
Feature
Warn on Deprecated Python 3.6 usage
3.1.0 – 2021-11-10
Deprecation
The AWS DynamoDB Encryption Client for Python no longer supports Python 3.5 as of version 3.1; only Python 3.6+ is supported. Customers using Python 3.5 can still use the 2.x line of the AWS DynamoDB Encryption Client for Python, which will continue to receive security updates, in accordance with our Support Policy.
Feature
Warn on Deprecated Python usage #368
Add Python 3.10 to CI
Remove Python 3.5 from testing
3.0.0 – 2021-07-15
Deprecation
The AWS DynamoDB Encryption Client for Python no longer supports Python 2 or Python 3.4 as of major version 3.x; only Python 3.5+ is supported. Customers using Python 2 or Python 3.4 can still use the 2.x line of the DynamoDB Encryption Client, which will continue to receive security updates for the next 12 months, in accordance with our Support Policy.
2.1.0 – 2021-07-15
Deprecation Announcement
The AWS DynamoDB Encryption Client for Python is discontinuing support for Python 2. Future major versions of this library will drop support for Python 2 and begin to adopt changes that are known to break Python 2.
Support for Python 3.4 will be removed at the same time. Moving forward, we will support Python 3.5+.
Security updates will still be available for the DynamoDB Encryption Client 2.x line for the next 12 months, in accordance with our Support Policy.
2.0.0 – 2021-02-04
Breaking Changes
Removes MostRecentProvider. MostRecentProvider is replaced by CachingMostRecentProvider as of 1.3.0.
1.3.0 – 2021-02-04
Adds the CachingMostRecentProvider and deprecates MostRecentProvider.
Time-based key reauthorization logic in MostRecentProvider did not reauthorize the use of the key after key usage permissions were changed at the key provider (for example AWS Key Management Service). This created the potential for keys to be used in the DynamoDB Encryption Client after permissions to do so were revoked.
CachingMostRecentProvider replaces MostRecentProvider and provides a cache entry TTL to reauthorize the key with the key provider.
MostRecentProvider is now deprecated, and is removed in 2.0.0. See https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/most-recent-provider.html#mrp-versions for more details.
1.2.0 – 2019-10-10
Bugfixes
Fix
AwsKmsCryptographicMaterialsProvider
regional clients override bug #124 NOTE: It is possible that this is a breaking change for you, depending on how you are re-using any custom botocore sessions that you provide to AwsKmsCryptographicMaterialsProvider.Remove
attributes
attribute fromEncryptionContext
str
andrepr
values. #127
1.1.1 – 2019-08-29
Bugfixes
Fix
EncryptedPaginator
to successfully decrypt when usingAwsKmsCryptographicMaterialsProvider
#118
1.1.0 – 2019-03-13
Features
- Batch write operations via the high-level helper clients now return plaintext items in
UnprocessedItems
.
- Batch write operations via the high-level helper clients now return plaintext items in
1.0.7 – 2018-01-16
Bugfixes
Fix
MostRecentProvider
cache reuse bug. #105
1.0.6 – 2018-01-15
Bugfixes
Fix
MostRecentProvider
bug in providing invalid cached results. #102
1.0.5 – 2018-08-01
Move the
aws-dynamodb-encryption-python
repository fromawslabs
toaws
.
1.0.4 – 2018-05-22
Bugfixes
1.0.3 – 2018-05-03
Bugfixes
Finish fixing
MANIFEST.in
.
1.0.2 – 2018-05-03
Bugfixes
Fill out
MANIFEST.in
to correctly include necessary files in source build.
1.0.1 – 2018-05-02
Add version convenience import to base namespace.
1.0.0 – 2018-05-02
Initial public release