Skip to content

Commit ca81758

Browse files
mattsb42-awsmattsb42-aws
committed
add full readme
1 parent f214259 commit ca81758

File tree

1 file changed

+167
-3
lines changed

1 file changed

+167
-3
lines changed

‎README.rst

Lines changed: 167 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,167 @@
1-
#####################################
2-
DynamoDB Encryption Client for Python
3-
#####################################
1+
############################################
2+
Amazon DynamoDB Encryption Client for Python
3+
############################################
4+
5+
The `Amazon DynamoDB Encryption Client for Python`_ provides client-side encryption of DynamoDB
6+
items to help you to protect your table data before you send it to Amazon DynamoDB. It provides
7+
an implementation of the `Amazon DynamoDB Encryption Client`_ that is fully compatible with the
8+
`Amazon DynamoDB Encryption Client for Java`_.
9+
10+
You can find the latest Python documentation at `Read the Docs`_ and you can find the latest
11+
full documents in our `primary documents`_.
12+
13+
You can find our source on `GitHub`_.
14+
15+
***************
16+
Getting Started
17+
***************
18+
19+
Required Prerequisites
20+
======================
21+
22+
* Python 2.7 or 3.4+
23+
24+
Installation
25+
============
26+
27+
.. note::
28+
29+
If you have not already installed `cryptography`_, you might need to install additional
30+
prerequisites as detailed in the `cryptography installation guide`_ for your operating
31+
system.
32+
33+
.. code::
34+
35+
$ pip install dynamodb-encryption-sdk
36+
37+
Concepts
38+
========
39+
40+
For a detailed description of the concepts that are important to understand when using this
41+
client, please review our `Concepts Guide`_.
42+
43+
44+
*****
45+
Usage
46+
*****
47+
48+
Helper Clients
49+
==============
50+
51+
We provide helper clients that look and feel like the low level client (`EncryptedClient`_),
52+
service resource (`EncryptedResource`_), and table resource (`EncryptedTable`_) available
53+
from the `boto3`_ library. For most uses, once configured, these clients can be used exactly
54+
as you would a standard client from `boto3`_, and your items will be transparently encrypted
55+
on write and decrypted on read.
56+
57+
What can I not do with the helper clients?
58+
------------------------------------------
59+
60+
For most uses, the helper clients (once configured) can be used as drop-in replacements for
61+
the `boto3`_ clients. However, there are a couple cases where this is not the case.
62+
63+
Update Item
64+
^^^^^^^^^^^
65+
66+
Because we cannot know that a partial update you might be making to an item covers all
67+
of the signed attributes in your item, we do not allow ``update_item`` on the helper clients.
68+
69+
The reason for this is because if you update only some of the signed attributes, then next
70+
time you try to read that item the signature validation will fail.
71+
72+
Attribute Filtering
73+
^^^^^^^^^^^^^^^^^^^
74+
75+
Because we cannot know what attributes in an item are signed, the helper clients do not allow
76+
any attribute filtering.
77+
78+
For ``get_item``, ``batch_get_item``, and ``scan``, this includes the use of ``AttributesToGet``
79+
and ``ProjectionExpression``.
80+
81+
For ``scan``, this also includes the use of ``Select`` values ``SPECIFIC_ATTRIBUTES`` and
82+
``ALL_PROJECTED_ATTRIBUTES``.
83+
84+
The reason for this is because if you do not retrieve all signed attributes, the signature
85+
validation will fail.
86+
87+
Item Encryptor
88+
==============
89+
90+
The helper clients provide a familiar interface but the actual item encryption and decryption
91+
is handled by a low-level item encryptor. You usually will not need to interact with these
92+
low-level functions, but for certain advanced use cases it can be useful.
93+
94+
If you do choose to use the item encryptor functions directly, you will need to provide a
95+
`CryptoConfig`_ for each call.
96+
97+
.. code-block:: python
98+
99+
>>> from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item, encrypt_python_item
100+
>>> plaintext_item = {
101+
... 'some': 'data',
102+
... 'more': 5
103+
... }
104+
>>> encrypted_item = encrypt_python_item(
105+
... item=plaintext_item,
106+
... crypto_config=my_crypto_config
107+
... )
108+
>>> decrypted_item = decrypt_python_item(
109+
... item=encrypted_item,
110+
... crypto_config=my_crypto_config
111+
... )
112+
113+
114+
When should I use the item encryptor?
115+
-------------------------------------
116+
117+
One example of a use case where you might want to use the item encryptor directly is when
118+
processing items in a `DynamoDB Stream`_. Since you receive the items data directly, and
119+
in DynamoDB JSON format, you can use the `decrypt_dynamodb_item`_ function to decrypt the
120+
item in the stream. We also provide helper `transformation functions`_
121+
122+
Advanced Use
123+
============
124+
125+
By default, the helper clients use your attribute actions and cryptographic materials provider
126+
to build the `CryptoConfig`_ that is provided to the item encryptor. For some advanced use
127+
cases, you might want to provide a custom `CryptoConfig`_ for specific operations.
128+
129+
All data plane operations (get item, put item, etc) on helper clients accept a ``crypto_config``
130+
parameter in addition to all of the parameters that the underlying `boto3`_ client accepts.
131+
132+
If this parameter is supplied, that `CryptoConfig`_ will be used for that operation instead
133+
of the one that the client would normally construct for you.
134+
135+
.. code-block:: python
136+
137+
>>> from dynamodb_encryption_sdk.encrypted.table import EncryptedTable
138+
>>> encrypted_table = EncryptedTable(
139+
... table=table,
140+
... materials_provider=my_crypto_materials_provider
141+
... )
142+
>>> encrypted_table.put_item(
143+
... Item=my_standard_item
144+
... ) # this uses the crypto config built by the helper
145+
>>> encrypted_table.put_item(
146+
... Item=my_special_item,
147+
... crypto_config=my_special_crypto_config
148+
... ) # this uses my_special_crypto_config
149+
150+
151+
.. _Amazon DynamoDB Encryption Client: https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/
152+
.. _primary documents: https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/
153+
.. _Concepts Guide: https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/concepts.html
154+
.. _Amazon DynamoDB Encryption Client for Java: https://github.com/awslabs/aws-dynamodb-encryption-java/
155+
.. _Amazon DynamoDB Encryption Client for Python: https://github.com/awslabs/aws-dynamodb-encryption-python/
156+
.. _DynamoDB Stream: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html
157+
.. _Read the Docs: http://aws-dynamodb-encryption-python.readthedocs.io/en/latest/
158+
.. _GitHub: https://github.com/awslabs/aws-dynamodb-encryption-python/
159+
.. _cryptography: https://cryptography.io/en/latest/
160+
.. _cryptography installation guide: https://cryptography.io/en/latest/installation/
161+
.. _boto3: https://boto3.readthedocs.io/en/latest/
162+
.. _EncryptedClient: lib/encrypted/client.html
163+
.. _EncryptedResource: lib/encrypted/resource.html
164+
.. _EncryptedTable: lib/encrypted/table.html
165+
.. _CryptoConfig: lib/encrypted/config.html
166+
.. _decrypt_dynamodb_item: lib/encrypted/item.html#dynamodb_encryption_sdk.encrypted.item.decrypt_dynamodb_item
167+
.. _transformation functions: lib/tools/transform.html

0 commit comments

Comments
 (0)