diff --git a/README.rst b/README.rst index 75bba7fe..7655ba0e 100644 --- a/README.rst +++ b/README.rst @@ -1,3 +1,168 @@ -##################################### -DynamoDB Encryption Client for Python -##################################### +############################################ +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`_. + +*************** +Getting Started +*************** + +Required Prerequisites +====================== + +* Python 2.7 or 3.4+ + +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/dynamodb-encryption-client/latest/devguide/ +.. _Amazon DynamoDB: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html +.. _primary documents: https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/ +.. _Concepts Guide: https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/concepts.html +.. _Amazon DynamoDB Encryption Client for Java: https://github.com/awslabs/aws-dynamodb-encryption-java/ +.. _Amazon DynamoDB Encryption Client for Python: https://github.com/awslabs/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/awslabs/aws-dynamodb-encryption-python/ +.. _cryptography: https://cryptography.io/en/latest/ +.. _cryptography installation guide: https://cryptography.io/en/latest/installation/ +.. _boto3: https://boto3.readthedocs.io/en/latest/ +.. _EncryptedClient: lib/encrypted/client.html +.. _EncryptedResource: lib/encrypted/resource.html +.. _EncryptedTable: lib/encrypted/table.html +.. _CryptoConfig: lib/encrypted/config.html +.. _decrypt_dynamodb_item: lib/encrypted/item.html#dynamodb_encryption_sdk.encrypted.item.decrypt_dynamodb_item +.. _transformation functions: lib/tools/transform.html diff --git a/doc/index.rst b/doc/index.rst index c5264765..56a9dbb6 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,7 +1,3 @@ -##################################### -DynamoDB Encryption Client for Python -##################################### - .. include:: ../README.rst *** diff --git a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.client.rst b/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.client.rst deleted file mode 100644 index 9b0578f2..00000000 --- a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.client.rst +++ /dev/null @@ -1,23 +0,0 @@ -dynamodb\_encryption\_sdk.encrypted.client -========================================== - -.. automodule:: dynamodb_encryption_sdk.encrypted.client - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - EncryptedClient - EncryptedPaginator - - - - - - \ No newline at end of file diff --git a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.resource.rst b/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.resource.rst deleted file mode 100644 index ea60f601..00000000 --- a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.resource.rst +++ /dev/null @@ -1,23 +0,0 @@ -dynamodb\_encryption\_sdk.encrypted.resource -============================================ - -.. automodule:: dynamodb_encryption_sdk.encrypted.resource - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - EncryptedResource - EncryptedTablesCollectionManager - - - - - - \ No newline at end of file diff --git a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.table.rst b/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.table.rst deleted file mode 100644 index 45f1c661..00000000 --- a/doc/lib/encrypted/dynamodb_encryption_sdk.encrypted.table.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.encrypted.table -========================================= - -.. automodule:: dynamodb_encryption_sdk.encrypted.table - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - EncryptedTable - - - - - - \ No newline at end of file diff --git a/doc/lib/encrypted/index.rst b/doc/lib/encrypted/index.rst deleted file mode 100644 index 8ab685f8..00000000 --- a/doc/lib/encrypted/index.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. toctree:: - - helpers - item diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.aws_kms.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.aws_kms.rst deleted file mode 100644 index 37114662..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.aws_kms.rst +++ /dev/null @@ -1,25 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.aws\_kms -====================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.aws_kms - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - AwsKmsCryptographicMaterialsProvider - EncryptionContextKeys - HkdfInfo - KeyInfo - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.most_recent.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.most_recent.rst deleted file mode 100644 index bef8de30..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.most_recent.rst +++ /dev/null @@ -1,24 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.most\_recent -========================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.most_recent - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - BasicCache - MostRecentProvider - TtlActions - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.rst deleted file mode 100644 index 71a73946..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers -============================================= - -.. automodule:: dynamodb_encryption_sdk.material_providers - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - CryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.static.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.static.rst deleted file mode 100644 index 8647e934..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.static.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.static -==================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.static - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - StaticCryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.meta.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.meta.rst deleted file mode 100644 index 591a9f75..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.meta.rst +++ /dev/null @@ -1,24 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.store.meta -======================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.store.meta - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - MetaStore - MetaStoreAttributeNames - MetaStoreValues - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.rst deleted file mode 100644 index e50a3b87..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.store.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.store -=================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.store - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - ProviderStore - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.wrapped.rst b/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.wrapped.rst deleted file mode 100644 index b79a28d1..00000000 --- a/doc/lib/materials_providers/TEST/dynamodb_encryption_sdk.material_providers.wrapped.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.wrapped -===================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.wrapped - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - WrappedCryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.aws_kms.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.aws_kms.rst deleted file mode 100644 index 37114662..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.aws_kms.rst +++ /dev/null @@ -1,25 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.aws\_kms -====================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.aws_kms - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - AwsKmsCryptographicMaterialsProvider - EncryptionContextKeys - HkdfInfo - KeyInfo - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.most_recent.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.most_recent.rst deleted file mode 100644 index bef8de30..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.most_recent.rst +++ /dev/null @@ -1,24 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.most\_recent -========================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.most_recent - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - BasicCache - MostRecentProvider - TtlActions - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.rst deleted file mode 100644 index 71a73946..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers -============================================= - -.. automodule:: dynamodb_encryption_sdk.material_providers - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - CryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.static.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.static.rst deleted file mode 100644 index 8647e934..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.static.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.static -==================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.static - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - StaticCryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.meta.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.meta.rst deleted file mode 100644 index 591a9f75..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.meta.rst +++ /dev/null @@ -1,24 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.store.meta -======================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.store.meta - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - MetaStore - MetaStoreAttributeNames - MetaStoreValues - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.rst deleted file mode 100644 index e50a3b87..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.store.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.store -=================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.store - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - ProviderStore - - - - - - \ No newline at end of file diff --git a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.wrapped.rst b/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.wrapped.rst deleted file mode 100644 index b79a28d1..00000000 --- a/doc/lib/materials_providers/dynamodb_encryption_sdk.material_providers.wrapped.rst +++ /dev/null @@ -1,22 +0,0 @@ -dynamodb\_encryption\_sdk.material\_providers.wrapped -===================================================== - -.. automodule:: dynamodb_encryption_sdk.material_providers.wrapped - - - - - - - - .. rubric:: Classes - - .. autosummary:: - - WrappedCryptographicMaterialsProvider - - - - - - \ No newline at end of file diff --git a/src/dynamodb_encryption_sdk/encrypted/item.py b/src/dynamodb_encryption_sdk/encrypted/item.py index ffb8d67c..23d8a050 100644 --- a/src/dynamodb_encryption_sdk/encrypted/item.py +++ b/src/dynamodb_encryption_sdk/encrypted/item.py @@ -37,6 +37,16 @@ def encrypt_dynamodb_item(item, crypto_config): # type: (dynamodb_types.ITEM, CryptoConfig) -> dynamodb_types.ITEM """Encrypt a DynamoDB item. + >>> from dynamodb_encryption_sdk.encrypted.item import encrypt_dynamodb_item + >>> plaintext_item = { + ... 'some': {'S': 'data'}, + ... 'more': {'N': '5'} + ... } + >>> encrypted_item = encrypt_dynamodb_item( + ... item=plaintext_item, + ... crypto_config=my_crypto_config + ... ) + .. note:: This handles DynamoDB-formatted items and is for use with the boto3 DynamoDB client. @@ -112,6 +122,16 @@ def encrypt_python_item(item, crypto_config): # type: (dynamodb_types.ITEM, CryptoConfig) -> dynamodb_types.ITEM """Encrypt a dictionary for DynamoDB. + >>> from dynamodb_encryption_sdk.encrypted.item import encrypt_python_item + >>> plaintext_item = { + ... 'some': 'data', + ... 'more': 5 + ... } + >>> encrypted_item = encrypt_python_item( + ... item=plaintext_item, + ... crypto_config=my_crypto_config + ... ) + .. note:: This handles human-friendly dictionaries and is for use with the boto3 DynamoDB service or table resource. @@ -130,6 +150,16 @@ def decrypt_dynamodb_item(item, crypto_config): # type: (dynamodb_types.ITEM, CryptoConfig) -> dynamodb_types.ITEM """Decrypt a DynamoDB item. + >>> from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item + >>> encrypted_item = { + ... 'some': {'B': b'ENCRYPTED_DATA'}, + ... 'more': {'B': b'ENCRYPTED_DATA'} + ... } + >>> decrypted_item = decrypt_python_item( + ... item=encrypted_item, + ... crypto_config=my_crypto_config + ... ) + .. note:: This handles DynamoDB-formatted items and is for use with the boto3 DynamoDB client. @@ -204,6 +234,16 @@ def decrypt_python_item(item, crypto_config): # type: (dynamodb_types.ITEM, CryptoConfig) -> dynamodb_types.ITEM """Decrypt a dictionary for DynamoDB. + >>> from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item + >>> encrypted_item = { + ... 'some': Binary(b'ENCRYPTED_DATA'), + ... 'more': Binary(b'ENCRYPTED_DATA') + ... } + >>> decrypted_item = decrypt_python_item( + ... item=encrypted_item, + ... crypto_config=my_crypto_config + ... ) + .. note:: This handles human-friendly dictionaries and is for use with the boto3 DynamoDB service or table resource.