############################################
Amazon DynamoDB Encryption Client for Python
############################################
.. image:: https://img.shields.io/pypi/v/dynamodb-encryption-sdk.svg
:target: https://pypi.python.org/pypi/dynamodb-encryption-sdk
:alt: Latest Version
.. image:: https://img.shields.io/pypi/pyversions/dynamodb-encryption-sdk.svg
:target: https://pypi.org/project/dynamodb-encryption-sdk
:alt: Supported Python Versions
.. image:: https://img.shields.io/badge/code_style-black-000000.svg
:target: https://github.com/ambv/black
:alt: Code style: black
.. image:: https://readthedocs.org/projects/aws-dynamodb-encryption-python/badge/?version=latest
:target: http://aws-dynamodb-encryption-python.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/aws/aws-dynamodb-encryption-python/workflows/tests/badge.svg
:target: https://github.com/aws/aws-dynamodb-encryption-python/actions?query=workflow%3Atests
:alt: tests
.. image:: https://github.com/aws/aws-dynamodb-encryption-python/workflows/static%20analysis/badge.svg
:target: https://github.com/aws/aws-dynamodb-encryption-python/actions?query=workflow%3A%22static+analysis%22
:alt: static analysis
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`_.
`Security issue notifications`_
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.
.. code::
$ 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.
.. code-block:: python
>>> 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.
.. code-block:: python
>>> 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
.. _Amazon DynamoDB Encryption Client: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/legacy-dynamodb-encryption-client.html
.. _Amazon DynamoDB: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html
.. _primary documents: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/legacy-dynamodb-encryption-client.html
.. _Concepts Guide: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/DDBEC-legacy-concepts.html
.. _Amazon DynamoDB Encryption Client for Java: https://github.com/aws/aws-dynamodb-encryption-java/
.. _Amazon DynamoDB Encryption Client for Python: https://github.com/aws/aws-dynamodb-encryption-python/
.. _DynamoDB Stream: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html
.. _Read the Docs: http://aws-dynamodb-encryption-python.readthedocs.io/en/latest/
.. _GitHub: https://github.com/aws/aws-dynamodb-encryption-python/
.. _cryptography: https://cryptography.io/en/latest/
.. _cryptography installation guide: https://cryptography.io/en/latest/installation.html
.. _boto3: https://boto3.readthedocs.io/en/latest/
.. _EncryptedClient: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html
.. _EncryptedResource: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html
.. _EncryptedTable: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html
.. _CryptoConfig: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html
.. _decrypt_dynamodb_item: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/item.html#dynamodb_encryption_sdk.encrypted.item.decrypt_dynamodb_item
.. _transformation functions: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/transform.html
.. _Security issue notifications: https://github.com/aws/aws-dynamodb-encryption-python/blob/master/CONTRIBUTING.md
.. _Support Policy: https://github.com/aws/aws-dynamodb-encryption-python/blob/master/SUPPORT_POLICY.rst
Raw data
{
"_id": null,
"home_page": "https://github.com/aws/aws-dynamodb-encryption-python",
"name": "dynamodb-encryption-sdk",
"maintainer": "Amazon Web Services",
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "dynamodb-encryption-sdk aws kms encryption dynamodb",
"author": "Amazon Web Services",
"author_email": "aws-cryptools@amazon.com",
"download_url": "https://files.pythonhosted.org/packages/b8/e5/bce50d507ce1458c1d598b63dec8ed6bcd5f572d47fee5bc5be4c761dc6f/dynamodb-encryption-sdk-3.3.0.tar.gz",
"platform": null,
"description": "############################################\nAmazon DynamoDB Encryption Client for Python\n############################################\n\n.. image:: https://img.shields.io/pypi/v/dynamodb-encryption-sdk.svg\n :target: https://pypi.python.org/pypi/dynamodb-encryption-sdk\n :alt: Latest Version\n\n.. image:: https://img.shields.io/pypi/pyversions/dynamodb-encryption-sdk.svg\n :target: https://pypi.org/project/dynamodb-encryption-sdk\n :alt: Supported Python Versions\n\n.. image:: https://img.shields.io/badge/code_style-black-000000.svg\n :target: https://github.com/ambv/black\n :alt: Code style: black\n\n.. image:: https://readthedocs.org/projects/aws-dynamodb-encryption-python/badge/?version=latest\n :target: http://aws-dynamodb-encryption-python.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://github.com/aws/aws-dynamodb-encryption-python/workflows/tests/badge.svg\n :target: https://github.com/aws/aws-dynamodb-encryption-python/actions?query=workflow%3Atests\n :alt: tests\n\n.. image:: https://github.com/aws/aws-dynamodb-encryption-python/workflows/static%20analysis/badge.svg\n :target: https://github.com/aws/aws-dynamodb-encryption-python/actions?query=workflow%3A%22static+analysis%22\n :alt: static analysis\n\nThe `Amazon DynamoDB Encryption Client for Python`_ provides client-side encryption of `Amazon\nDynamoDB`_ items to help you to protect your table data before you send it to DynamoDB. It\nprovides an implementation of the `Amazon DynamoDB Encryption Client`_ that is fully compatible\nwith the `Amazon DynamoDB Encryption Client for Java`_.\n\nYou can find the latest Python documentation at `Read the Docs`_ and you can find the latest\nfull documents in our `primary documents`_.\n\nYou can find our source on `GitHub`_.\n\n`Security issue notifications`_\n\nSee `Support Policy`_ for details on the current support status of all major versions of this library.\n\n***************\nGetting Started\n***************\n\nRequired Prerequisites\n======================\n\n* Python 3.8+\n\n\nInstallation\n============\n\n.. note::\n\n If you have not already installed `cryptography`_, you might need to install additional\n prerequisites as detailed in the `cryptography installation guide`_ for your operating\n system.\n\n .. code::\n\n $ pip install dynamodb-encryption-sdk\n\nConcepts\n========\n\nFor a detailed description of the concepts that are important to understand when using this\nclient, please review our `Concepts Guide`_.\n\n\n*****\nUsage\n*****\n\nHelper Clients\n==============\n\nWe provide helper clients that look and feel like the low level client (`EncryptedClient`_),\nservice resource (`EncryptedResource`_), and table resource (`EncryptedTable`_) available\nfrom the `boto3`_ library. For most uses, once configured, these clients can be used exactly\nas you would a standard client from `boto3`_, and your items will be transparently encrypted\non write and decrypted on read.\n\nWhat can't I do with the helper clients?\n----------------------------------------\n\nFor most uses, the helper clients (once configured) can be used as drop-in replacements for\nthe `boto3`_ clients. However, there are a couple cases where this is not the case.\n\nUpdate Item\n^^^^^^^^^^^\n\nBecause we can't know that a partial update you might be making to an item covers all\nof the signed attributes in your item, we do not allow ``update_item`` on the helper clients.\n\nThis is because if you update only some of the signed attributes, then next time you try\nto read that item the signature validation will fail.\n\nAttribute Filtering\n^^^^^^^^^^^^^^^^^^^\n\nBecause we can't know what attributes in an item are signed, the helper clients do not allow\nany attribute filtering.\n\nFor ``get_item``, ``batch_get_item``, and ``scan``, this includes the use of ``AttributesToGet``\nand ``ProjectionExpression``.\n\nFor ``scan``, this also includes the use of ``Select`` values ``SPECIFIC_ATTRIBUTES`` and\n``ALL_PROJECTED_ATTRIBUTES``.\n\nThis is because if you do not retrieve all signed attributes, the signature validation will\nfail.\n\nItem Encryptor\n==============\n\nThe helper clients provide a familiar interface but the actual item encryption and decryption\nis handled by a low-level item encryptor. You usually will not need to interact with these\nlow-level functions, but for certain advanced use cases it can be useful.\n\nIf you do choose to use the item encryptor functions directly, you will need to provide a\n`CryptoConfig`_ for each call.\n\n.. code-block:: python\n\n >>> from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item, encrypt_python_item\n >>> plaintext_item = {\n ... 'some': 'data',\n ... 'more': 5\n ... }\n >>> encrypted_item = encrypt_python_item(\n ... item=plaintext_item,\n ... crypto_config=my_crypto_config\n ... )\n >>> decrypted_item = decrypt_python_item(\n ... item=encrypted_item,\n ... crypto_config=my_crypto_config\n ... )\n\n\nWhen should I use the item encryptor?\n-------------------------------------\n\nOne example of a use case where you might want to use the item encryptor directly is when\nprocessing items in a `DynamoDB Stream`_. Since you receive the items data directly, and\nin DynamoDB JSON format, you can use the `decrypt_dynamodb_item`_ function to decrypt the\nitem in the stream. We also provide helper `transformation functions`_\n\nAdvanced Use\n============\n\nBy default, the helper clients use your attribute actions and cryptographic materials provider\nto build the `CryptoConfig`_ that is provided to the item encryptor. For some advanced use\ncases, you might want to provide a custom `CryptoConfig`_ for specific operations.\n\nAll data plane operations (get item, put item, etc) on helper clients accept a ``crypto_config``\nparameter in addition to all of the parameters that the underlying `boto3`_ client accepts.\n\nIf this parameter is supplied, that `CryptoConfig`_ will be used for that operation instead\nof the one that the client would normally construct for you.\n\n.. code-block:: python\n\n >>> from dynamodb_encryption_sdk.encrypted.table import EncryptedTable\n >>> encrypted_table = EncryptedTable(\n ... table=table,\n ... materials_provider=my_crypto_materials_provider\n ... )\n >>> encrypted_table.put_item(\n ... Item=my_standard_item\n ... ) # this uses the crypto config built by the helper\n >>> encrypted_table.put_item(\n ... Item=my_special_item,\n ... crypto_config=my_special_crypto_config\n ... ) # this uses my_special_crypto_config\n\n\n.. _Amazon DynamoDB Encryption Client: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/legacy-dynamodb-encryption-client.html\n.. _Amazon DynamoDB: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html\n.. _primary documents: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/legacy-dynamodb-encryption-client.html\n.. _Concepts Guide: https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/DDBEC-legacy-concepts.html\n.. _Amazon DynamoDB Encryption Client for Java: https://github.com/aws/aws-dynamodb-encryption-java/\n.. _Amazon DynamoDB Encryption Client for Python: https://github.com/aws/aws-dynamodb-encryption-python/\n.. _DynamoDB Stream: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html\n.. _Read the Docs: http://aws-dynamodb-encryption-python.readthedocs.io/en/latest/\n.. _GitHub: https://github.com/aws/aws-dynamodb-encryption-python/\n.. _cryptography: https://cryptography.io/en/latest/\n.. _cryptography installation guide: https://cryptography.io/en/latest/installation.html\n.. _boto3: https://boto3.readthedocs.io/en/latest/\n.. _EncryptedClient: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/client.html\n.. _EncryptedResource: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/resource.html\n.. _EncryptedTable: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/table.html\n.. _CryptoConfig: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/config.html\n.. _decrypt_dynamodb_item: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/encrypted/item.html#dynamodb_encryption_sdk.encrypted.item.decrypt_dynamodb_item\n.. _transformation functions: https://aws-dynamodb-encryption-python.readthedocs.io/en/latest/lib/tools/transform.html\n.. _Security issue notifications: https://github.com/aws/aws-dynamodb-encryption-python/blob/master/CONTRIBUTING.md\n.. _Support Policy: https://github.com/aws/aws-dynamodb-encryption-python/blob/master/SUPPORT_POLICY.rst\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "DynamoDB Encryption Client for Python",
"version": "3.3.0",
"project_urls": {
"Homepage": "https://github.com/aws/aws-dynamodb-encryption-python"
},
"split_keywords": [
"dynamodb-encryption-sdk",
"aws",
"kms",
"encryption",
"dynamodb"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "807e3d98f608460a75ff7ed8f5f045d666e2087b29cdee94d0bdf7e6b2006266",
"md5": "c32bc94e0bd7ccb1e2db9ec586fc6303",
"sha256": "3519820927ff431c85f1a09cf67481169c4dc68bc5d9032518e61a769379af9c"
},
"downloads": -1,
"filename": "dynamodb_encryption_sdk-3.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c32bc94e0bd7ccb1e2db9ec586fc6303",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 103802,
"upload_time": "2024-08-07T22:16:39",
"upload_time_iso_8601": "2024-08-07T22:16:39.958826Z",
"url": "https://files.pythonhosted.org/packages/80/7e/3d98f608460a75ff7ed8f5f045d666e2087b29cdee94d0bdf7e6b2006266/dynamodb_encryption_sdk-3.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b8e5bce50d507ce1458c1d598b63dec8ed6bcd5f572d47fee5bc5be4c761dc6f",
"md5": "bf55a7d360769ffc4272a67cd06eb590",
"sha256": "242183b146cd04b40e2c91aa9d2da02b6797c389a7d7c618d6db84563e8c55ce"
},
"downloads": -1,
"filename": "dynamodb-encryption-sdk-3.3.0.tar.gz",
"has_sig": false,
"md5_digest": "bf55a7d360769ffc4272a67cd06eb590",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 190099,
"upload_time": "2024-08-07T22:16:42",
"upload_time_iso_8601": "2024-08-07T22:16:42.298968Z",
"url": "https://files.pythonhosted.org/packages/b8/e5/bce50d507ce1458c1d598b63dec8ed6bcd5f572d47fee5bc5be4c761dc6f/dynamodb-encryption-sdk-3.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-07 22:16:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aws",
"github_project": "aws-dynamodb-encryption-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "boto3",
"specs": [
[
">=",
"1.10.0"
]
]
},
{
"name": "cryptography",
"specs": [
[
">=",
"3.4.6"
]
]
},
{
"name": "attrs",
"specs": [
[
">=",
"17.4.0"
]
]
}
],
"tox": true,
"lcname": "dynamodb-encryption-sdk"
}
JSON
