chore: Add an example illustrating MRKs (#169)

Author: farleyb-amazon

examples/README.md

@@ -0,0 +1,54 @@
+#########################################
+AWS DynamoDB Encryption Client Examples
+#########################################
+
+This section features examples that show you
+how to use the AWS DynamoDB Encryption Client.
+We demonstrate how to use the encryption and decryption APIs
+and how to set up some common configuration patterns.
+
+APIs
+====
+
+The AWS DynamoDB Encryption Client provides four high-level APIs: `EncryptedClient`, `EncryptedItem`,
+`EncryptedResource`, and `EncryptedTable`.
+
+You can find examples that demonstrate these APIs
+in the `examples/src/dynamodb_encryption_sdk_examples <./src/dynamodb_encryption_sdk_examples>`_ directory.
+Each of these examples uses AWS KMS as the materials provider.
+
+* `How to use the EncryptedClient API <./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_client.py>`_
+* `How to use the EncryptedItem API <./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_item.py>`_
+* `How to use the EncryptedResource API <./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_resource.py>`_
+* `How to use the EncryptedTable API <./src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_table.py>`_
+
+Material Providers
+==================
+
+To use the encryption and decryption APIs, you need to describe how you want the library to protect your data keys.
+You can do this by configuring material providers. AWS KMS is the most common material provider used with the AWS DynamoDB Encryption
+SDK, and each of the API examples above uses AWS KMS. This section describes the other providers that come bundled
+with this library.
+
+* `How to use the CachingMostRecentProvider <./src/dynamodb_encryption_sdk_examples/most_recent_provider_encrypted_table.py>`_
+* `How to use raw symmetric wrapping keys <./src/dynamodb_encryption_sdk_examples/wrapped_symmetric_encrypted_table.py>`_
+* `How to use raw asymmetric wrapping keys <./src/dynamodb_encryption_sdk_examples/wrapped_rsa_encrypted_table.py>`_
+
+For more details on the different type of material providers, see `How to choose a cryptographic materials provider <https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/crypto-materials-providers.html>`_.
+
+Running the examples
+====================
+
+In order to run these examples, these things must be configured:
+
+#. Ensure that AWS credentials are available in one of the `automatically discoverable credential locations`_.
+#. The ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_KEY_ID`` environment variable
+   must be set to a valid `AWS KMS CMK ARN`_ that can be used by the available credentials.
+#. The ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID`` and ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID_2`` environment variables
+   must be set to two related AWS KMS Multi-Region key ids in different regions.
+#. The ``DDB_ENCRYPTION_CLIENT_TEST_TABLE_NAME`` environment variable must be set to a valid
+   DynamoDB table name, in the default region, to which the discoverable credentials have
+   read, write, and describe permissions.
+
+.. _automatically discoverable credential locations: http://boto3.readthedocs.io/en/latest/guide/configuration.html
+.. _AWS KMS CMK ARN: http://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html

examples/README.rst

@@ -54,7 +54,7 @@ def encrypt_item(table_name, aws_cmk_id):
     # 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.
+    # Get the item using the encrypted client, transparently decrypting it.
     decrypted_item = encrypted_client.get_item(TableName=table_name, Key=index_key)["Item"]
 
     # Verify that all of the attributes are different in the encrypted item

examples/src/dynamodb_encryption_sdk_examples/aws_kms_encrypted_client.py

@@ -0,0 +1,78 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Example showing use of AWS KMS CMP with a DynamoDB Global table and an AWS Multi-Region Key."""
+
+import time
+
+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
+
+SECOND_REGION = "eu-west-1"
+
+
+def encrypt_item(table_name, cmk_mrk_arn_first_region, cmk_mrk_arn_second_region):
+    """Demonstrate use of Multi-Region Keys with DynamoDB Encryption Client.
+
+    This example encrypts an item with a Multi-Region Key in one region and decrypts it in another region. It
+    assumes that you have a Dynamo DB Global table in two regions, as well as a KMS
+    Multi-Region Key replicated to these regions.
+    """
+    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 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}
+    )
+
+    # Create a DDB client and KMS crypto materials provider in the first region using the specified AWS KMS key.
+    split_arn = cmk_mrk_arn_first_region.split(":")
+    encryption_region = split_arn[3]
+    ddb_client = boto3.client("dynamodb", region_name=encryption_region)
+    encryption_cmp = AwsKmsCryptographicMaterialsProvider(key_id=cmk_mrk_arn_first_region)
+    # Use these objects to create an encrypted client.
+    encryption_client = EncryptedClient(client=ddb_client, materials_provider=encryption_cmp, attribute_actions=actions)
+
+    # Put the item to the table, using the encrypted client to transparently encrypt it.
+    encryption_client.put_item(TableName=table_name, Item=plaintext_item)
+
+    # Create a DDB client and KMS crypto materials provider in the second region
+    split_arn = cmk_mrk_arn_second_region.split(":")
+    decryption_region = split_arn[3]
+    decryption_cmp = AwsKmsCryptographicMaterialsProvider(key_id=cmk_mrk_arn_second_region)
+    ddb_client = boto3.client("dynamodb", region_name=decryption_region)
+    # Use these objects to create an encrypted client.
+    decryption_client = EncryptedClient(client=ddb_client, materials_provider=decryption_cmp, attribute_actions=actions)
+
+    # DDB Global Table replication takes some time. Sleep for a moment to give the item a chance to replicate to the
+    # second region
+    time.sleep(1)
+
+    # Get the item from the second region, transparently decrypting it. This allows you to avoid a cross-region KMS
+    # call to the first region if your application is running in the second region
+    decrypted_item = decryption_client.get_item(TableName=table_name, Key=index_key)["Item"]
+
+    # Verify that the decryption successfully retrieved the original plaintext
+    for name in encrypted_attributes:
+        assert plaintext_item[name] == decrypted_item[name]
+
+    # Clean up the item
+    encryption_client.delete_item(TableName=table_name, Key=index_key)

examples/src/dynamodb_encryption_sdk_examples/aws_kms_multi_region_key.py

@@ -5,4 +5,4 @@
 os.environ["AWS_ENCRYPTION_SDK_EXAMPLES_TESTING"] = "yes"
 sys.path.extend([os.sep.join([os.path.dirname(__file__), "..", "..", "test", "integration"])])
 
-from integration_test_utils import cmk_arn, ddb_table_name  # noqa pylint: disable=unused-import
+from integration_test_utils import cmk_arn, cmk_mrk_arn, ddb_table_name, second_cmk_mrk_arn  # noqa pylint: disable=unused-import

examples/test/examples_test_utils.py

@@ -17,9 +17,10 @@
     aws_kms_encrypted_item,
     aws_kms_encrypted_resource,
     aws_kms_encrypted_table,
+    aws_kms_multi_region_key,
 )
 
-from .examples_test_utils import cmk_arn, ddb_table_name  # noqa pylint: disable=unused-import
+from .examples_test_utils import cmk_arn, cmk_mrk_arn, ddb_table_name, second_cmk_mrk_arn  # noqa pylint: disable=unused-import
 
 pytestmark = [pytest.mark.examples]
 
@@ -42,3 +43,7 @@ def test_aws_kms_encrypted_item(ddb_table_name, cmk_arn):
 
 def test_aws_kms_encrypted_resource(ddb_table_name, cmk_arn):
     aws_kms_encrypted_resource.encrypt_batch_items(ddb_table_name, cmk_arn)
+
+
+def test_aws_kms_mrk_client(ddb_table_name, cmk_mrk_arn, second_cmk_mrk_arn):
+    aws_kms_multi_region_key.encrypt_item(ddb_table_name, cmk_mrk_arn, second_cmk_mrk_arn)

examples/test/test_aws_kms_encrypted_examples.py

@@ -11,6 +11,9 @@ commands = python -m pytest --basetemp={envtmpdir} -l {posargs}
 passenv =
     # Identifies AWS KMS key id to use in integration tests
     AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_KEY_ID \
+    # Identifes AWS KMS Multi-Region key ids to use in examples \
+    AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID \
+    AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID_2 \
     # DynamoDB Table to use in integration tests
     DDB_ENCRYPTION_CLIENT_TEST_TABLE_NAME \
     # Pass through AWS credentials

examples/tox.ini

@@ -8,6 +8,8 @@ In order to run these integration tests successfully, these things which must be
    `automatically discoverable credential locations`_.
 #. The ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_KEY_ID`` environment variable
    must be set to a valid `AWS KMS CMK ARN`_ that can be used by the available credentials.
+#. The ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID`` and ``AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID_2`` environment variables
+   must be set to two related AWS KMS Multi-Region key ids in different regions.
 #. The ``DDB_ENCRYPTION_CLIENT_TEST_TABLE_NAME`` environment variable must be set to a valid
    DynamoDB table name, in the default region, to which the discoverable credentials have
    read, write, and describe permissions.

test/README.rst

@@ -27,16 +27,18 @@
         raise
 
 AWS_KMS_KEY_ID = "AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_KEY_ID"
+AWS_KMS_MRK_KEY_ID = "AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID"
+AWS_KMS_MRK_KEY_ID_2 = "AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID_2"
 DDB_TABLE_NAME = "DDB_ENCRYPTION_CLIENT_TEST_TABLE_NAME"
 
 
-def cmk_arn_value():
+def cmk_arn_value(env_variable=AWS_KMS_KEY_ID):
     """Retrieve the target CMK ARN from environment variable."""
-    arn = os.environ.get(AWS_KMS_KEY_ID, None)
+    arn = os.environ.get(env_variable, None)
     if arn is None:
         raise ValueError(
             'Environment variable "{}" must be set to a valid KMS CMK ARN for integration tests to run'.format(
-                AWS_KMS_KEY_ID
+                env_variable
             )
         )
     if arn.startswith("arn:") and ":alias/" not in arn:
@@ -47,7 +49,19 @@ def cmk_arn_value():
 @pytest.fixture
 def cmk_arn():
     """As of Pytest 4.0.0, fixtures cannot be called directly."""
-    return cmk_arn_value()
+    return cmk_arn_value(AWS_KMS_KEY_ID)
+
+
+@pytest.fixture
+def cmk_mrk_arn():
+    """As of Pytest 4.0.0, fixtures cannot be called directly."""
+    return cmk_arn_value(AWS_KMS_MRK_KEY_ID)
+
+
+@pytest.fixture
+def second_cmk_mrk_arn():
+    """As of Pytest 4.0.0, fixtures cannot be called directly."""
+    return cmk_arn_value(AWS_KMS_MRK_KEY_ID_2)
 
 
 def _build_kms_cmp(require_attributes):

test/integration/integration_test_utils.py

@@ -46,6 +46,9 @@ commands = pytest --basetemp={envtmpdir} -l {posargs}
 passenv =
     # Identifies AWS KMS key id to use in integration tests
     AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_KEY_ID \
+    # Identifies AWS KMS MRK key ids to use in integration tests
+    AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID \
+    AWS_ENCRYPTION_SDK_PYTHON_INTEGRATION_TEST_AWS_KMS_MRK_KEY_ID_2 \
     # DynamoDB Table to use in integration tests
     DDB_ENCRYPTION_CLIENT_TEST_TABLE_NAME \
     # Pass through AWS credentials
@@ -251,7 +254,7 @@ commands =
         # Ignore D103 docstring requirements for tests
         --ignore F811,D103 \
         # Our path munging confuses isort, so disable flake8-isort checks on that file
-        --per-file-ignores="examples/test/examples_test_utils.py:I003,I004" \
+        --per-file-ignores="examples/test/examples_test_utils.py:I003,I004,I005,examples/test/test_aws_kms_encrypted_examples.py:I005" \
         examples/test/
 
 [testenv:pylint]