High level helpers

doc/index.rst

@@ -12,6 +12,8 @@ Modules
     dynamodb_encryption_sdk.exceptions
     dynamodb_encryption_sdk.identifiers
     dynamodb_encryption_sdk.structures
+    dynamodb_encryption_sdk.delegated_keys
+    dynamodb_encryption_sdk.delegated_keys.jce
     dynamodb_encryption_sdk.encrypted
     dynamodb_encryption_sdk.encrypted.client
     dynamodb_encryption_sdk.encrypted.item
@@ -21,29 +23,28 @@ Modules
     dynamodb_encryption_sdk.material_providers.aws_kms
     dynamodb_encryption_sdk.material_providers.static
     dynamodb_encryption_sdk.material_providers.wrapped
-    dynamodb_encryption_sdk.material_providers.store
     dynamodb_encryption_sdk.materials
     dynamodb_encryption_sdk.materials.raw
     dynamodb_encryption_sdk.materials.wrapped
     dynamodb_encryption_sdk.internal
-    dynamodb_encryption_sdk.internal.defaults
     dynamodb_encryption_sdk.internal.dynamodb_types
     dynamodb_encryption_sdk.internal.identifiers
     dynamodb_encryption_sdk.internal.str_ops
     dynamodb_encryption_sdk.internal.utils
+    dynamodb_encryption_sdk.internal.validators
     dynamodb_encryption_sdk.internal.crypto
+    dynamodb_encryption_sdk.internal.crypto.authentication
+    dynamodb_encryption_sdk.internal.crypto.encryption
     dynamodb_encryption_sdk.internal.crypto.jce_bridge
     dynamodb_encryption_sdk.internal.crypto.jce_bridge.authentication
     dynamodb_encryption_sdk.internal.crypto.jce_bridge.encryption
     dynamodb_encryption_sdk.internal.crypto.jce_bridge.primitives
-    dynamodb_encryption_sdk.internal.crypto.authentication
-    dynamodb_encryption_sdk.internal.crypto.encryption
     dynamodb_encryption_sdk.internal.formatting
+    dynamodb_encryption_sdk.internal.formatting.material_description
+    dynamodb_encryption_sdk.internal.formatting.transform
     dynamodb_encryption_sdk.internal.formatting.deserialize
     dynamodb_encryption_sdk.internal.formatting.deserialize.attribute
     dynamodb_encryption_sdk.internal.formatting.serialize
     dynamodb_encryption_sdk.internal.formatting.serialize.attribute
-    dynamodb_encryption_sdk.internal.formatting.material_description
-    dynamodb_encryption_sdk.internal.formatting.transform
 
 .. include:: ../CHANGELOG.rst

src/dynamodb_encryption_sdk/internal/defaults.py → examples/src/__init__.py

@@ -10,8 +10,4 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-""""""
-
-ENCODING = 'utf-8'
-LOGGING_NAME = 'dynamodb_encryption_sdk'
-MATERIAL_DESCRIPTION_VERSION = b'\00' * 4
+"""Stub module indicator to make linter configuration simpler."""

examples/src/aws_kms_encrypted_client.py

@@ -0,0 +1,183 @@
+# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+# http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+"""Example showing use of AWS KMS CMP with EncryptedClient."""
+import boto3
+from dynamodb_encryption_sdk.encrypted.client import EncryptedClient
+from dynamodb_encryption_sdk.identifiers import CryptoAction
+from dynamodb_encryption_sdk.material_providers.aws_kms import AwsKmsCryptographicMaterialsProvider
+from dynamodb_encryption_sdk.structures import AttributeActions
+
+
+def encrypt_item(table_name, aws_cmk_id):
+    """Demonstrate use of EncryptedClient to transparently encrypt an item."""
+    index_key = {
+        'partition_attribute': {'S': 'is this'},
+        'sort_attribute': {'N': '55'}
+    }
+    plaintext_item = {
+        'example': {'S': 'data'},
+        'some numbers': {'N': '99'},
+        'and some binary': {'B': b'\x00\x01\x02'},
+        'leave me': {'S': 'alone'}  # We want to ignore this attribute
+    }
+    # Collect all of the attributes that will be encrypted (used later).
+    encrypted_attributes = set(plaintext_item.keys())
+    encrypted_attributes.remove('leave me')
+    # Collect all of the attributes that will not be encrypted (used later).
+    unencrypted_attributes = set(index_key.keys())
+    unencrypted_attributes.add('leave me')
+    # Add the index pairs to the item.
+    plaintext_item.update(index_key)
+
+    # Create a normal client.
+    client = boto3.client('dynamodb')
+    # Create a crypto materials provider using the specified AWS KMS key.
+    aws_kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=aws_cmk_id)
+    # Create attribute actions that tells the encrypted client to encrypt all attributes except one.
+    actions = AttributeActions(
+        default_action=CryptoAction.ENCRYPT_AND_SIGN,
+        attribute_actions={
+            'leave me': CryptoAction.DO_NOTHING
+        }
+    )
+    # Use these objects to create an encrypted client.
+    encrypted_table = EncryptedClient(
+        client=client,
+        materials_provider=aws_kms_cmp,
+        attribute_actions=actions
+    )
+
+    # Put the item to the table, using the encrypted client to transparently encrypt it.
+    encrypted_table.put_item(TableName=table_name, Item=plaintext_item)
+
+    # Get the encrypted item using the standard client.
+    encrypted_item = client.get_item(TableName=table_name, Key=index_key)['Item']
+
+    # Get the item using the encrypted client, transparently decyrpting it.
+    decrypted_item = encrypted_table.get_item(TableName=table_name, Key=index_key)['Item']
+
+    # Verify that all of the attributes are different in the encrypted item
+    for name in encrypted_attributes:
+        assert encrypted_item[name] != plaintext_item[name]
+        assert decrypted_item[name] == plaintext_item[name]
+
+    # Verify that all of the attributes that should not be encrypted were not.
+    for name in unencrypted_attributes:
+        assert decrypted_item[name] == encrypted_item[name] == plaintext_item[name]
+
+    # Clean up the item
+    encrypted_table.delete_item(TableName=table_name, Key=index_key)
+
+
+def encrypt_batch_items(table_name, aws_cmk_id):
+    """Demonstrate use of EncryptedClient to transparently encrypt multiple items in a batch request."""
+    index_keys = [
+        {
+            'partition_attribute': {'S': 'is this'},
+            'sort_attribute': {'N': '55'}
+        },
+        {
+            'partition_attribute': {'S': 'is this'},
+            'sort_attribute': {'N': '56'}
+        },
+        {
+            'partition_attribute': {'S': 'is this'},
+            'sort_attribute': {'N': '57'}
+        },
+        {
+            'partition_attribute': {'S': 'another'},
+            'sort_attribute': {'N': '55'}
+        }
+    ]
+    plaintext_additional_attributes = {
+        'example': {'S': 'data'},
+        'some numbers': {'N': '99'},
+        'and some binary': {'B': b'\x00\x01\x02'},
+        'leave me': {'S': 'alone'}  # We want to ignore this attribute
+    }
+    plaintext_items = []
+    for key in index_keys:
+        _attributes = key.copy()
+        _attributes.update(plaintext_additional_attributes)
+        plaintext_items.append(_attributes)
+
+    # Collect all of the attributes that will be encrypted (used later).
+    encrypted_attributes = set(plaintext_additional_attributes.keys())
+    encrypted_attributes.remove('leave me')
+    # Collect all of the attributes that will not be encrypted (used later).
+    unencrypted_attributes = set(index_keys[0].keys())
+    unencrypted_attributes.add('leave me')
+
+    # Create a normal client.
+    client = boto3.client('dynamodb')
+    # Create a crypto materials provider using the specified AWS KMS key.
+    aws_kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=aws_cmk_id)
+    # Create attribute actions that tells the encrypted client to encrypt all attributes except one.
+    actions = AttributeActions(
+        default_action=CryptoAction.ENCRYPT_AND_SIGN,
+        attribute_actions={
+            'leave me': CryptoAction.DO_NOTHING
+        }
+    )
+    # Use these objects to create an encrypted client.
+    encrypted_client = EncryptedClient(
+        client=client,
+        materials_provider=aws_kms_cmp,
+        attribute_actions=actions
+    )
+
+    # Put the items to the table, using the encrypted client to transparently encrypt them.
+    encrypted_client.batch_write_item(RequestItems={
+        table_name: [{'PutRequest': {'Item': item}} for item in plaintext_items]
+    })
+
+    # Get the encrypted item using the standard client.
+    encrypted_items = client.batch_get_item(
+        RequestItems={table_name: {'Keys': index_keys}}
+    )['Responses'][table_name]
+
+    # Get the item using the encrypted client, transparently decyrpting it.
+    decrypted_items = encrypted_client.batch_get_item(
+        RequestItems={table_name: {'Keys': index_keys}}
+    )['Responses'][table_name]
+
+    def _select_index_from_item(item):
+        """Find the index keys that match this item."""
+        for index in index_keys:
+            if all([item[key] == value for key, value in index.items()]):
+                return index
+
+    def _select_item_from_index(index, all_items):
+        """Find the item that matches these index keys."""
+        for item in all_items:
+            if all([item[key] == value for key, value in index.items()]):
+                return item
+
+    for encrypted_item in encrypted_items:
+        key = _select_index_from_item(encrypted_item)
+        plaintext_item = _select_item_from_index(key, plaintext_items)
+        decrypted_item = _select_item_from_index(key, decrypted_items)
+
+        # Verify that all of the attributes are different in the encrypted item
+        for name in encrypted_attributes:
+            assert encrypted_item[name] != plaintext_item[name]
+            assert decrypted_item[name] == plaintext_item[name]
+
+        # Verify that all of the attributes that should not be encrypted were not.
+        for name in unencrypted_attributes:
+            assert decrypted_item[name] == encrypted_item[name] == plaintext_item[name]
+
+    # Clean up the item
+    encrypted_client.batch_write_item(RequestItems={
+        table_name: [{'DeleteRequest': {'Key': key}} for key in index_keys]
+    })

examples/src/aws_kms_encrypted_item.py

@@ -0,0 +1,101 @@
+# Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+# http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file is
+# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
+# ANY KIND, either express or implied. See the License for the specific
+# language governing permissions and limitations under the License.
+"""Example showing use of AWS KMS CMP with item encryption functions directly."""
+import boto3
+from boto3.dynamodb.types import Binary
+from dynamodb_encryption_sdk.encrypted import CryptoConfig
+from dynamodb_encryption_sdk.encrypted.item import decrypt_python_item, encrypt_python_item
+from dynamodb_encryption_sdk.identifiers import CryptoAction
+from dynamodb_encryption_sdk.material_providers.aws_kms import AwsKmsCryptographicMaterialsProvider
+from dynamodb_encryption_sdk.structures import AttributeActions, EncryptionContext, TableInfo
+from dynamodb_encryption_sdk.transform import dict_to_ddb
+
+
+def encrypt_item(table_name, aws_cmk_id):
+    """Demonstrate use of EncryptedTable to transparently encrypt an item."""
+    index_key = {
+        'partition_attribute': 'is this',
+        'sort_attribute': 55
+    }
+    plaintext_item = {
+        'example': 'data',
+        'some numbers': 99,
+        'and some binary': Binary(b'\x00\x01\x02'),
+        'leave me': 'alone'  # We want to ignore this attribute
+    }
+    # Collect all of the attributes that will be encrypted (used later).
+    encrypted_attributes = set(plaintext_item.keys())
+    encrypted_attributes.remove('leave me')
+    # Collect all of the attributes that will not be encrypted (used later).
+    unencrypted_attributes = set(index_key.keys())
+    unencrypted_attributes.add('leave me')
+    # Add the index pairs to the item.
+    plaintext_item.update(index_key)
+
+    # Create a normal table resource.
+    table = boto3.resource('dynamodb').Table(table_name)
+
+    # Use the TableInfo helper to collect information about the indexes.
+    table_info = TableInfo(name=table_name)
+    table_info.refresh_indexed_attributes(table.meta.client)
+
+    # Create a crypto materials provider using the specified AWS KMS key.
+    aws_kms_cmp = AwsKmsCryptographicMaterialsProvider(key_id=aws_cmk_id)
+
+    encryption_context = EncryptionContext(
+        table_name=table_name,
+        partition_key_name=table_info.primary_index.partition,
+        sort_key_name=table_info.primary_index.sort,
+        # The only attributes that are used by the AWS KMS cryptographic materials providers
+        # are the primary index attributes.
+        # These attributes need to be in the form of a DynamoDB JSON structure, so first
+        # convert the standard dictionary.
+        attributes=dict_to_ddb(index_key)
+    )
+
+    # Create attribute actions that tells the encrypted table to encrypt all attributes
+    # except the primary index attributes and the one identified attribute to ignore.
+    actions = AttributeActions(
+        default_action=CryptoAction.ENCRYPT_AND_SIGN,
+        attribute_actions={
+            name: CryptoAction.DO_NOTHING
+            for name in set(['leave me']).union(table_info.protected_index_keys())
+        }
+    )
+
+    # Build the crypto config to use for this item.
+    # When using the higher-level helpers, this is handled for you.
+    crypto_config = CryptoConfig(
+        materials_provider=aws_kms_cmp,
+        encryption_context=encryption_context,
+        attribute_actions=actions
+    )
+
+    # Encrypt the plaintext item directly
+    encrypted_item = encrypt_python_item(plaintext_item, crypto_config)
+
+    # You could now put the encrypted item to DynamoDB just as you would any other item.
+    # table.put_item(Item=encrypted_item)
+    # We will skip this for the purposes of this example.
+
+    # Decrypt the encrypted item directly
+    decrypted_item = decrypt_python_item(encrypted_item, crypto_config)
+
+    # Verify that all of the attributes are different in the encrypted item
+    for name in encrypted_attributes:
+        assert encrypted_item[name] != plaintext_item[name]
+        assert decrypted_item[name] == plaintext_item[name]
+
+    # Verify that all of the attributes that should not be encrypted were not.
+    for name in unencrypted_attributes:
+        assert decrypted_item[name] == encrypted_item[name] == plaintext_item[name]