chore(python): examples for keyrings

Author: imabhichow

Examples/runtimes/java/DynamoDbEncryption/src/main/java/software/amazon/cryptography/examples/keyring/SharedCacheAcrossHierarchicalKeyringsExample.java

@@ -180,7 +180,7 @@ public static void SharedCacheAcrossHierarchicalKeyringsGetItemPutItem(
     final IKeyring hierarchicalKeyring1 =
       matProv.CreateAwsKmsHierarchicalKeyring(keyringInput1);
 
-    // 4. Configure which attributes are encrypted and/or signed when writing new items.
+    // 5. Configure which attributes are encrypted and/or signed when writing new items.
     //    For each attribute that may exist on the items we plan to write to our DynamoDbTable,
     //    we must explicitly configure how they should be treated during item encryption:
     //      - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature
@@ -194,14 +194,14 @@ public static void SharedCacheAcrossHierarchicalKeyringsGetItemPutItem(
       CryptoAction.ENCRYPT_AND_SIGN
     );
 
-    // 5. Get the DDB Client for Hierarchical Keyring 1.
+    // 6. Get the DDB Client for Hierarchical Keyring 1.
     final DynamoDbClient ddbClient1 = GetDdbClient(
       ddbTableName,
       hierarchicalKeyring1,
       attributeActionsOnEncrypt
     );
 
-    // 6. Encrypt Decrypt roundtrip with ddbClient1
+    // 7. Encrypt Decrypt roundtrip with ddbClient1
     PutGetItems(ddbTableName, ddbClient1);
 
     // Through the above encrypt and decrypt roundtrip, the cache will be populated and
@@ -210,7 +210,7 @@ public static void SharedCacheAcrossHierarchicalKeyringsGetItemPutItem(
     // - Same Logical Key Store Name of the Key Store for the Hierarchical Keyring
     // - Same Branch Key ID
 
-    // 7. Configure your KeyStore resource keystore2.
+    // 8. Configure your KeyStore resource keystore2.
     //       This SHOULD be the same configuration that you used
     //       to initially create and populate your physical KeyStore.
     //    Note that keyStoreTableName is the physical Key Store,
@@ -243,13 +243,13 @@ public static void SharedCacheAcrossHierarchicalKeyringsGetItemPutItem(
       )
       .build();
 
-    // 8. Create the Hierarchical Keyring HK2 with Key Store instance K2, the shared Cache
+    // 9. Create the Hierarchical Keyring HK2 with Key Store instance K2, the shared Cache
     //    and the same partitionId and BranchKeyId used in HK1 because we want to share cache entries
     //    (and experience cache HITS).
 
-    // Please make sure that you read the guidance on how to set Partition ID, Logical Key Store Name and
-    // Branch Key ID at the top of this example before creating Hierarchical Keyrings with a Shared Cache.
-    // partitionId for this example is a random UUID
+    Please make sure that you read the guidance on how to set Partition ID, Logical Key Store Name and
+    Branch Key ID at the top of this example before creating Hierarchical Keyrings with a Shared Cache.
+    partitionId for this example is a random UUID
     final CreateAwsKmsHierarchicalKeyringInput keyringInput2 =
       CreateAwsKmsHierarchicalKeyringInput
         .builder()
@@ -262,14 +262,14 @@ public static void SharedCacheAcrossHierarchicalKeyringsGetItemPutItem(
     final IKeyring hierarchicalKeyring2 =
       matProv.CreateAwsKmsHierarchicalKeyring(keyringInput2);
 
-    // 9. Get the DDB Client for Hierarchical Keyring 2.
+    // 10. Get the DDB Client for Hierarchical Keyring 2.
     final DynamoDbClient ddbClient2 = GetDdbClient(
       ddbTableName,
       hierarchicalKeyring2,
       attributeActionsOnEncrypt
     );
 
-    // 10. Encrypt Decrypt roundtrip with ddbClient2
+    // 11. Encrypt Decrypt roundtrip with ddbClient2
     PutGetItems(ddbTableName, ddbClient2);
   }
 
@@ -352,12 +352,12 @@ public static void PutGetItems(
     String ddbTableName,
     DynamoDbClient ddbClient
   ) {
-    // Put an item into our table using the given ddb client.
-    // Before the item gets sent to DynamoDb, it will be encrypted
-    // client-side, according to our configuration.
-    // This example creates a Hierarchical Keyring for a single BranchKeyId. You can, however, use a
-    // BranchKeyIdSupplier as per your use-case. See the HierarchicalKeyringsExample.java for more
-    // information.
+    Put an item into our table using the given ddb client.
+    Before the item gets sent to DynamoDb, it will be encrypted
+    client-side, according to our configuration.
+    This example creates a Hierarchical Keyring for a single BranchKeyId. You can, however, use a
+    BranchKeyIdSupplier as per your use-case. See the HierarchicalKeyringsExample.java for more
+    information.
     final HashMap<String, AttributeValue> item = new HashMap<>();
     item.put("partition_key", AttributeValue.builder().s("id").build());
     item.put("sort_key", AttributeValue.builder().n("0").build());
@@ -377,12 +377,12 @@ public static void PutGetItems(
     // Demonstrate that PutItem succeeded
     assert 200 == putResponse.sdkHttpResponse().statusCode();
 
-    // 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.
-    // This example creates a Hierarchical Keyring for a single BranchKeyId. You can, however, use a
-    // BranchKeyIdSupplier as per your use-case. See the HierarchicalKeyringsExample.java for more
-    // information.
+    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.
+    This example creates a Hierarchical Keyring for a single BranchKeyId. You can, however, use a
+    BranchKeyIdSupplier as per your use-case. See the HierarchicalKeyringsExample.java for more
+    information.
     final HashMap<String, AttributeValue> keyToGet = new HashMap<>();
     keyToGet.put("partition_key", AttributeValue.builder().s("id").build());
     keyToGet.put("sort_key", AttributeValue.builder().n("0").build());

Examples/runtimes/python/DynamoDBEncryption/src/create_keystore_table_example.py

@@ -0,0 +1,62 @@
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""
+The Hierarchical Keyring Example and Searchable Encryption Examples
+rely on the existence of a DDB-backed key store with pre-existing
+branch key material or beacon key material.
+
+This example demonstrates configuring a KeyStore and then
+using a helper method to create the DDB table that will be
+used to persist branch keys and beacons keys for this KeyStore.
+
+This table creation should occur within your control plane. This
+only needs to occur once. While not demonstrated in this example,
+you should additionally use the `VersionKey` API on the KeyStore
+to periodically rotate your branch key material.
+"""
+
+import boto3
+from aws_cryptographic_material_providers.keystore.client import KeyStore
+from aws_cryptographic_material_providers.keystore.config import KeyStoreConfig
+from aws_cryptographic_material_providers.keystore.models import (
+    CreateKeyStoreInput,
+    KMSConfigurationKmsKeyArn,
+)
+
+
+def keystore_create_table(
+    keystore_table_name: str,
+    logical_keystore_name: str,
+    kms_key_arn: str
+):
+    """Create KeyStore Table Example.
+
+    :param keystore_table_name: The name of the DynamoDB table to create
+    :param logical_keystore_name: The logical name for this keystore
+    :param kms_key_arn: The ARN of the KMS key to use for protecting branch keys
+    """
+    # 1. Configure your KeyStore resource.
+    #    `ddb_table_name` is the name you want for the DDB table that
+    #    will back your keystore.
+    #    `kms_key_arn` is the KMS Key that will protect your branch keys and beacon keys
+    #    when they are stored in your DDB table.
+    keystore = KeyStore(
+        config=KeyStoreConfig(
+            ddb_client=boto3.client('dynamodb'),
+            ddb_table_name=keystore_table_name,
+            logical_key_store_name=logical_keystore_name,
+            kms_client=boto3.client('kms'),
+            kms_configuration=KMSConfigurationKmsKeyArn(kms_key_arn),
+        )
+    )
+
+    # 2. Create the DynamoDb table that will store the branch keys and beacon keys.
+    #    This checks if the correct table already exists at `ddb_table_name`
+    #    by using the DescribeTable API. If no table exists,
+    #    it will create one. If a table exists, it will verify
+    #    the table's configuration and will error if the configuration is incorrect.
+    keystore.create_key_store(input=CreateKeyStoreInput())
+    # It may take a couple of minutes for the table to become ACTIVE,
+    # at which point it is ready to store branch and beacon keys.
+    # See the Create KeyStore Key Example for how to populate
+    # this table.

Examples/runtimes/python/DynamoDBEncryption/src/item_encryptor/encrypt_decrypt_example.py

@@ -45,7 +45,7 @@
 )
 
 
-def encrypt_decrypt_example(kms_key_id: str, ddb_table_name: str) -> None:
+def encrypt_decrypt_example(kms_key_id: str, ddb_table_name: str):
     """Encrypt and decrypt an item with an ItemEncryptor."""
     # 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data.
     #    For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use.

Examples/runtimes/python/DynamoDBEncryption/src/keyring/__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."""