hierarchical_keyring_example

Author: imabhichow

Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example/__init__.py

@@ -0,0 +1,3 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Stub to allow relative imports of examples from tests."""

…/keyring/hierarchical_keyring_example.py …cal_keyring_example/encryption_config.pyExamples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example.py renamed to Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example/encryption_config.py Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example.py renamed to Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example/encryption_config.py

@@ -1,49 +1,10 @@
 # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
 """
-Example demonstrating DynamoDb Encryption using a Hierarchical Keyring.
+Configuration module for hierarchical keyring encryption setup.
 
-This example sets up DynamoDb Encryption for the AWS SDK client
-using the Hierarchical Keyring, which establishes a key hierarchy
-where "branch" keys are persisted in DynamoDb.
-These branch keys are used to protect your data keys,
-and these branch keys are themselves protected by a root KMS Key.
-
-Establishing a key hierarchy like this has two benefits:
-
-First, by caching the branch key material, and only calling back
-to KMS to re-establish authentication regularly according to your configured TTL,
-you limit how often you need to call back to KMS to protect your data.
-This is a performance/security tradeoff, where your authentication, audit, and
-logging from KMS is no longer one-to-one with every encrypt or decrypt call.
-However, the benefit is that you no longer have to make a
-network call to KMS for every encrypt or decrypt.
-
-Second, this key hierarchy makes it easy to hold multi-tenant data
-that is isolated per branch key in a single DynamoDb table.
-You can create a branch key for each tenant in your table,
-and encrypt all that tenant's data under that distinct branch key.
-On decrypt, you can either statically configure a single branch key
-to ensure you are restricting decryption to a single tenant,
-or you can implement an interface that lets you map the primary key on your items
-to the branch key that should be responsible for decrypting that data.
-
-This example then demonstrates configuring a Hierarchical Keyring
-with a Branch Key ID Supplier to encrypt and decrypt data for
-two separate tenants.
-
-Running this example requires access to the DDB Table whose name
-is provided in CLI arguments.
-This table must be configured with the following
-primary key configuration:
-  - Partition key is named "partition_key" with type (S)
-  - Sort key is named "sort_key" with type (S)
-
-This example also requires using a KMS Key whose ARN
-is provided in CLI arguments. You need the following access
-on this key:
-  - GenerateDataKeyWithoutPlaintext
-  - Decrypt
+This module provides the common encryption configuration used by both
+EncryptedClient and EncryptedTable examples.
 """
 
 import boto3
@@ -57,7 +18,6 @@
     CreateAwsKmsHierarchicalKeyringInput,
     DefaultCache,
 )
-from aws_dbesdk_dynamodb.encrypted.client import EncryptedClient
 from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb.client import DynamoDbEncryption
 from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb.config import (
     DynamoDbEncryptionConfig,
@@ -71,26 +31,27 @@
     CryptoAction,
 )
 
-from .example_branch_key_id_supplier import ExampleBranchKeyIdSupplier
+from ..example_branch_key_id_supplier import ExampleBranchKeyIdSupplier
 
 
-def hierarchical_keyring_get_item_put_item(
+def create_encryption_config(
     ddb_table_name: str,
     tenant1_branch_key_id: str,
     tenant2_branch_key_id: str,
     keystore_table_name: str,
     logical_keystore_name: str,
     kms_key_id: str,
-):
+) -> DynamoDbTablesEncryptionConfig:
     """
-    Demonstrate using a hierarchical keyring with multiple tenants.
+    Create the encryption configuration for DynamoDB encryption.
 
     :param ddb_table_name: The name of the DynamoDB table
     :param tenant1_branch_key_id: Branch key ID for tenant 1
     :param tenant2_branch_key_id: Branch key ID for tenant 2
     :param keystore_table_name: The name of the KeyStore DynamoDB table
     :param logical_keystore_name: The logical name for this keystore
     :param kms_key_id: The ARN of the KMS key to use
+    :return: The DynamoDB tables encryption configuration
     """
     # Initial KeyStore Setup: This example requires that you have already
     # created your KeyStore, and have populated it with two new branch keys.
@@ -190,40 +151,4 @@ def hierarchical_keyring_get_item_put_item(
     )
 
     table_configs = {ddb_table_name: table_config}
-    tables_config = DynamoDbTablesEncryptionConfig(table_encryption_configs=table_configs)
-
-    # 7. Create the EncryptedClient
-    ddb_client = boto3.client("dynamodb")
-    encrypted_ddb_client = EncryptedClient(client=ddb_client, encryption_config=tables_config)
-
-    # 8. Put an item into our table using the above client.
-    #    Before the item gets sent to DynamoDb, it will be encrypted
-    #    client-side, according to our configuration.
-    #    Because the item we are writing uses "tenantId1" as our partition value,
-    #    based on the code we wrote in the ExampleBranchKeySupplier,
-    #    `tenant1_branch_key_id` will be used to encrypt this item.
-    item = {
-        "partition_key": {"S": "tenant1Id"},
-        "sort_key": {"N": "0"},
-        "tenant_sensitive_data": {"S": "encrypt and sign me!"},
-    }
-
-    put_response = encrypted_ddb_client.put_item(TableName=ddb_table_name, Item=item)
-
-    # Demonstrate that PutItem succeeded
-    assert put_response["ResponseMetadata"]["HTTPStatusCode"] == 200
-
-    # 9. Get the item back from our table using the same client.
-    #    The client will decrypt the item client-side, and return
-    #    back the original item.
-    #    Because the returned item's partition value is "tenantId1",
-    #    based on the code we wrote in the ExampleBranchKeySupplier,
-    #    `tenant1_branch_key_id` will be used to decrypt this item.
-    key_to_get = {"partition_key": {"S": "tenant1Id"}, "sort_key": {"N": "0"}}
-
-    get_response = encrypted_ddb_client.get_item(TableName=ddb_table_name, Key=key_to_get)
-
-    # Demonstrate that GetItem succeeded and returned the decrypted item
-    assert get_response["ResponseMetadata"]["HTTPStatusCode"] == 200
-    returned_item = get_response["Item"]
-    assert returned_item["tenant_sensitive_data"]["S"] == "encrypt and sign me!"
+    return DynamoDbTablesEncryptionConfig(table_encryption_configs=table_configs)

Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example/with_encrypted_client.py

@@ -0,0 +1,95 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Example demonstrating DynamoDb Encryption using a Hierarchical Keyring with EncryptedClient.
+
+This example sets up DynamoDb Encryption for the AWS SDK client
+using the Hierarchical Keyring, which establishes a key hierarchy
+where "branch" keys are persisted in DynamoDb.
+These branch keys are used to protect your data keys,
+and these branch keys are themselves protected by a root KMS Key.
+
+Running this example requires access to the DDB Table whose name
+is provided in CLI arguments.
+This table must be configured with the following
+primary key configuration:
+  - Partition key is named "partition_key" with type (S)
+  - Sort key is named "sort_key" with type (S)
+
+This example also requires using a KMS Key whose ARN
+is provided in CLI arguments. You need the following access
+on this key:
+  - GenerateDataKeyWithoutPlaintext
+  - Decrypt
+"""
+
+import boto3
+from aws_dbesdk_dynamodb.encrypted.client import EncryptedClient
+
+from .encryption_config import create_encryption_config
+
+
+def hierarchical_keyring_client_example(
+    ddb_table_name: str,
+    tenant1_branch_key_id: str,
+    tenant2_branch_key_id: str,
+    keystore_table_name: str,
+    logical_keystore_name: str,
+    kms_key_id: str,
+):
+    """
+    Demonstrate using a hierarchical keyring with multiple tenants using EncryptedClient.
+
+    :param ddb_table_name: The name of the DynamoDB table
+    :param tenant1_branch_key_id: Branch key ID for tenant 1
+    :param tenant2_branch_key_id: Branch key ID for tenant 2
+    :param keystore_table_name: The name of the KeyStore DynamoDB table
+    :param logical_keystore_name: The logical name for this keystore
+    :param kms_key_id: The ARN of the KMS key to use
+    """
+    # 1. Create the DynamoDb Encryption configuration for the table we will be writing to.
+    #    See encryption_config.py in this directory for detailed steps on the encryption configuration.
+    tables_config = create_encryption_config(
+        ddb_table_name=ddb_table_name,
+        tenant1_branch_key_id=tenant1_branch_key_id,
+        tenant2_branch_key_id=tenant2_branch_key_id,
+        keystore_table_name=keystore_table_name,
+        logical_keystore_name=logical_keystore_name,
+        kms_key_id=kms_key_id,
+    )
+
+    # 2. Create the EncryptedClient
+    ddb_client = boto3.client("dynamodb")
+    encrypted_ddb_client = EncryptedClient(client=ddb_client, encryption_config=tables_config)
+
+    # 3. Put an item into our table using the above client.
+    #    Before the item gets sent to DynamoDb, it will be encrypted
+    #    client-side, according to our configuration.
+    #    Because the item we are writing uses "tenantId1" as our partition value,
+    #    based on the code we wrote in the ExampleBranchKeySupplier,
+    #    `tenant1_branch_key_id` will be used to encrypt this item.
+    item = {
+        "partition_key": {"S": "tenant1Id"},
+        "sort_key": {"N": "0"},
+        "tenant_sensitive_data": {"S": "encrypt and sign me!"},
+    }
+
+    put_response = encrypted_ddb_client.put_item(TableName=ddb_table_name, Item=item)
+
+    # Demonstrate that PutItem succeeded
+    assert put_response["ResponseMetadata"]["HTTPStatusCode"] == 200
+
+    # 4. Get the item back from our table using the same client.
+    #    The client will decrypt the item client-side, and return
+    #    back the original item.
+    #    Because the returned item's partition value is "tenantId1",
+    #    based on the code we wrote in the ExampleBranchKeySupplier,
+    #    `tenant1_branch_key_id` will be used to decrypt this item.
+    key_to_get = {"partition_key": {"S": "tenant1Id"}, "sort_key": {"N": "0"}}
+
+    get_response = encrypted_ddb_client.get_item(TableName=ddb_table_name, Key=key_to_get)
+
+    # Demonstrate that GetItem succeeded and returned the decrypted item
+    assert get_response["ResponseMetadata"]["HTTPStatusCode"] == 200
+    returned_item = get_response["Item"]
+    assert returned_item["tenant_sensitive_data"]["S"] == "encrypt and sign me!"

Examples/runtimes/python/DynamoDBEncryption/src/keyring/hierarchical_keyring_example/with_encrypted_table.py

@@ -0,0 +1,98 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+Example demonstrating DynamoDb Encryption using a Hierarchical Keyring with EncryptedTable.
+
+This example sets up DynamoDb Encryption for the AWS SDK table
+using the Hierarchical Keyring, which establishes a key hierarchy
+where "branch" keys are persisted in DynamoDb.
+These branch keys are used to protect your data keys,
+and these branch keys are themselves protected by a root KMS Key.
+
+Running this example requires access to the DDB Table whose name
+is provided in CLI arguments.
+This table must be configured with the following
+primary key configuration:
+  - Partition key is named "partition_key" with type (S)
+  - Sort key is named "sort_key" with type (S)
+
+This example also requires using a KMS Key whose ARN
+is provided in CLI arguments. You need the following access
+on this key:
+  - GenerateDataKeyWithoutPlaintext
+  - Decrypt
+"""
+
+import boto3
+from aws_dbesdk_dynamodb.encrypted.table import EncryptedTable
+
+from .encryption_config import create_encryption_config
+
+
+def hierarchical_keyring_table_example(
+    ddb_table_name: str,
+    tenant1_branch_key_id: str,
+    tenant2_branch_key_id: str,
+    keystore_table_name: str,
+    logical_keystore_name: str,
+    kms_key_id: str,
+):
+    """
+    Demonstrate using a hierarchical keyring with multiple tenants using EncryptedTable.
+
+    :param ddb_table_name: The name of the DynamoDB table
+    :param tenant1_branch_key_id: Branch key ID for tenant 1
+    :param tenant2_branch_key_id: Branch key ID for tenant 2
+    :param keystore_table_name: The name of the KeyStore DynamoDB table
+    :param logical_keystore_name: The logical name for this keystore
+    :param kms_key_id: The ARN of the KMS key to use
+    """
+    # 1. Create the DynamoDb Encryption configuration for the table we will be writing to.
+    #    See encryption_config.py in this directory for detailed steps on how this is done.
+    tables_config = create_encryption_config(
+        ddb_table_name=ddb_table_name,
+        tenant1_branch_key_id=tenant1_branch_key_id,
+        tenant2_branch_key_id=tenant2_branch_key_id,
+        keystore_table_name=keystore_table_name,
+        logical_keystore_name=logical_keystore_name,
+        kms_key_id=kms_key_id,
+    )
+
+    # 2. Create the EncryptedTable
+    ddb_table = boto3.resource("dynamodb").Table(ddb_table_name)
+    encrypted_table = EncryptedTable(
+        table=ddb_table,
+        encryption_config=tables_config,
+    )
+
+    # 3. Put an item into our table using the above table.
+    #    Before the item gets sent to DynamoDb, it will be encrypted
+    #    client-side, according to our configuration.
+    #    Because the item we are writing uses "tenantId1" as our partition value,
+    #    based on the code we wrote in the ExampleBranchKeySupplier,
+    #    `tenant1_branch_key_id` will be used to encrypt this item.
+    item = {
+        "partition_key": "tenant1Id",
+        "sort_key": 0,
+        "tenant_sensitive_data": "encrypt and sign me!",
+    }
+
+    put_response = encrypted_table.put_item(Item=item)
+
+    # Demonstrate that PutItem succeeded
+    assert put_response["ResponseMetadata"]["HTTPStatusCode"] == 200
+
+    # 4. Get the item back from our table using the same table.
+    #    The table will decrypt the item client-side, and return
+    #    back the original item.
+    #    Because the returned item's partition value is "tenantId1",
+    #    based on the code we wrote in the ExampleBranchKeySupplier,
+    #    `tenant1_branch_key_id` will be used to decrypt this item.
+    key_to_get = {"partition_key": "tenant1Id", "sort_key": 0}
+
+    get_response = encrypted_table.get_item(Key=key_to_get)
+
+    # Demonstrate that GetItem succeeded and returned the decrypted item
+    assert get_response["ResponseMetadata"]["HTTPStatusCode"] == 200
+    returned_item = get_response["Item"]
+    assert returned_item["tenant_sensitive_data"] == "encrypt and sign me!"

Examples/runtimes/python/DynamoDBEncryption/test/keyring/hierarchical_keyring_example/__init__.py

@@ -0,0 +1,3 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Stub to allow relative imports of examples from tests."""

Examples/runtimes/python/DynamoDBEncryption/test/keyring/hierarchical_keyring_example/test_with_encrypted_client.py

@@ -0,0 +1,46 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Test hierarchical keyring with abstraction EncryptedClient example."""
+import time
+
+import pytest
+
+from ....src.create_keystore_key_example import keystore_create_key
+from ....src.keyring.hierarchical_keyring_example.with_encrypted_client import (
+    hierarchical_keyring_client_example,
+)
+from ...cleanup import delete_branch_key
+from ...test_utils import (
+    TEST_DDB_TABLE_NAME,
+    TEST_KEYSTORE_KMS_KEY_ID,
+    TEST_KEYSTORE_NAME,
+    TEST_LOGICAL_KEYSTORE_NAME,
+)
+
+pytestmark = [pytest.mark.examples]
+
+
+def test_hierarchical_keyring_client_example():
+    """Test hierarchical keyring abstracted client example."""
+    # Create new branch keys for test
+    key_id1 = keystore_create_key(TEST_KEYSTORE_NAME, TEST_LOGICAL_KEYSTORE_NAME, TEST_KEYSTORE_KMS_KEY_ID)
+    key_id2 = keystore_create_key(TEST_KEYSTORE_NAME, TEST_LOGICAL_KEYSTORE_NAME, TEST_KEYSTORE_KMS_KEY_ID)
+
+    try:
+        # Key creation is eventually consistent, so wait 5 seconds to decrease the likelihood
+        # our test fails due to eventual consistency issues.
+        time.sleep(5)
+
+        # Run the client example
+        hierarchical_keyring_client_example(
+            TEST_DDB_TABLE_NAME,
+            key_id1,
+            key_id2,
+            TEST_KEYSTORE_NAME,
+            TEST_LOGICAL_KEYSTORE_NAME,
+            TEST_KEYSTORE_KMS_KEY_ID,
+        )
+    finally:
+        # Cleanup Branch Keys
+        delete_branch_key(key_id1, TEST_KEYSTORE_NAME, None)
+        delete_branch_key(key_id2, TEST_KEYSTORE_NAME, None)