chore(python): feedback

Author: imabhichow

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/README.md

@@ -1,45 +1,51 @@
 # Plaintext to AWS Database Encryption SDK for DynamoDB Migration
 
-This project demonstrates the three steps necessary to migrate to the AWS Database Encryption SDK for DynamoDB
-if you are currently using plaintext data in your DynamoDB tables.
+This project demonstrates the steps necessary
+to migrate to the AWS Database Encryption SDK for DynamoDb
+from a plaintext database.
 
 [Step 0](./plaintext/README.md) demonstrates the starting state for your system.
 
 ## Step 1
 
 In Step 1, you update your system to do the following:
 
-- continue to read items in plaintext format
-- continue to write items in plaintext format
-- prepare to read items in the encrypted format
+- continue to read plaintext items
+- continue to write plaintext items
+- prepare to read encrypted items
 
-When you deploy changes in Step 1, you should not expect any behavior change in your system,
-and your dataset still consists of data written in plaintext format.
+When you deploy changes in Step 1,
+you should not expect any behavior change in your system,
+and your dataset still consists of plaintext data.
 
-You must ensure that the changes in Step 1 make it to all your reads before you proceed to step 2.
+You must ensure that the changes in Step 1 make it to all your readers before you proceed to Step 2.
 
 ## Step 2
 
 In Step 2, you update your system to do the following:
 
-- continue to read items in plaintext format
-- start writing items in the encrypted format
-- continue to read items in the encrypted format
+- continue to read plaintext items
+- start writing encrypted items
+- continue to read encrypted items
 
-When you deploy changes in Step 2, you are introducing an encrypted format to your system,
+When you deploy changes in Step 2,
+you are introducing encrypted items to your system,
 and must make sure that all your readers are updated with the changes from Step 1.
 
-Before you move onto the next step, you will need to re-encrypt all plaintext items in your dataset
-to use the newest format. How you will want to do this, and how long you may want to remain in this Step,
-depends on your system and your desired security properties for old and new items.
+Before you move onto the next step, you will need to encrypt all plaintext items in your dataset.
+Once you have completed this step,
+while new items are being encrypted using the new format and will be authenticated on read,
+your system will still accept reading plaintext, unauthenticated items.
+In order to complete migration to a system where you always authenticate your items,
+you should prioritize moving on to Step 3.
 
 ## Step 3
 
-Once all plaintext items are re-encrypted to use the encrypted format,
-you may update your system to do the following:
+Once all plaintext items are encrypted,
+update your system to do the following:
 
-- continue to write items in the encrypted format
-- continue to read items in the encrypted format
-- do not accept reading items in plaintext format
+- continue to write encrypted items
+- continue to read encrypted items
+- do not accept reading plaintext items
 
 Once you have deployed these changes to your system, you have completed migration.

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/client/common.py

@@ -19,7 +19,7 @@
 )
 
 
-def setup_pure_awsdbe_client(kms_key_id: str, ddb_table_name: str):
+def setup_awsdbe_client_without_plaintext_override(kms_key_id: str, ddb_table_name: str):
     """
     Set up a pure AWS Database Encryption SDK EncryptedClient without plaintext override.
 
@@ -183,6 +183,7 @@ def setup_awsdbe_client_with_plaintext_override(kms_key_id: str, ddb_table_name:
         sort_key_name="sort_key",
         attribute_actions_on_encrypt=attribute_actions_on_encrypt,
         keyring=kms_mrk_multi_keyring,
+        # Provide plaintext_override policy to the config here
         plaintext_override=policy,
         allowed_unsigned_attribute_prefix=unsignAttrPrefix,
         # Specifying an algorithm suite is not required,

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/client/migration_step_3.py

@@ -20,7 +20,7 @@
   - Sort key is named "sort_key" with type (S)
 """
 
-from .common import setup_pure_awsdbe_client
+from .common import setup_awsdbe_client_without_plaintext_override
 
 
 def migration_step_3_with_client(kms_key_id: str, ddb_table_name: str, sort_read_value: int = 3):
@@ -33,7 +33,7 @@ def migration_step_3_with_client(kms_key_id: str, ddb_table_name: str, sort_read
     """
     # 1. Create the EncryptedClient.
     #    Do not configure any plaintext override.
-    encrypted_client = setup_pure_awsdbe_client(kms_key_id, ddb_table_name)
+    encrypted_client = setup_awsdbe_client_without_plaintext_override(kms_key_id, ddb_table_name)
 
     # 2. Put an item into your table using the Encrypted Client.
     #    This item will be encrypted using the DB Encryption SDK, using the

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/paginator/migration_step_3.py

@@ -19,7 +19,7 @@
   - Sort key is named "sort_key" with type (N)
 """
 
-from ..client.common import setup_pure_awsdbe_client
+from ..client.common import setup_awsdbe_client_without_plaintext_override
 
 
 def migration_step_3_with_paginator(kms_key_id: str, ddb_table_name: str, sort_read_value: int = 3):
@@ -33,7 +33,9 @@ def migration_step_3_with_paginator(kms_key_id: str, ddb_table_name: str, sort_r
     # 1. Create an EncryptedClient without plaintext override.
     #    Without a plaintext override, both reads and writes will use the AWS Database Encryption SDK,
     #    meaning that we can only read items that have been encrypted and we will always encrypt items on write.
-    encrypted_client = setup_pure_awsdbe_client(kms_key_id=kms_key_id, ddb_table_name=ddb_table_name)
+    encrypted_client = setup_awsdbe_client_without_plaintext_override(
+        kms_key_id=kms_key_id, ddb_table_name=ddb_table_name
+    )
 
     # 2. Put an example item into our DynamoDb table using the Encrypted Client.
     #    This item will be encrypted using the DB Encryption SDK, using the

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/resource/common.py

@@ -19,7 +19,7 @@
 )
 
 
-def setup_pure_awsdbe_resource(kms_key_id: str, ddb_table_name: str):
+def setup_awsdbe_resource_without_plaintext_override(kms_key_id: str, ddb_table_name: str):
     """
     Set up a pure AWS Database Encryption SDK EncryptedResource without plaintext override.
 
@@ -187,6 +187,7 @@ def setup_awsdbe_resource_with_plaintext_override(kms_key_id: str, ddb_table_nam
         sort_key_name="sort_key",
         attribute_actions_on_encrypt=attribute_actions_on_encrypt,
         keyring=kms_mrk_multi_keyring,
+        # Provide plaintext_override policy to the config here
         plaintext_override=policy,
         allowed_unsigned_attribute_prefix=unsignAttrPrefix,
         # Specifying an algorithm suite is not required,

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/resource/migration_step_3.py

@@ -20,7 +20,7 @@
   - Sort key is named "sort_key" with type (N)
 """
 
-from .common import setup_pure_awsdbe_resource
+from .common import setup_awsdbe_resource_without_plaintext_override
 
 
 def migration_step_3_with_resource(kms_key_id: str, ddb_table_name: str, sort_read_value: int = 3):
@@ -33,7 +33,7 @@ def migration_step_3_with_resource(kms_key_id: str, ddb_table_name: str, sort_re
     """
     # 1. Create the EncryptedResource.
     #    Do not configure any plaintext override.
-    encrypted_resource = setup_pure_awsdbe_resource(kms_key_id, ddb_table_name)
+    encrypted_resource = setup_awsdbe_resource_without_plaintext_override(kms_key_id, ddb_table_name)
 
     # 2. Write a batch of items to the table using the Encrypted Resource.
     #    These items will be encrypted using the DB Encryption SDK, using the

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/table/common.py

@@ -19,7 +19,7 @@
 )
 
 
-def setup_pure_awsdbe_table(kms_key_id: str, ddb_table_name: str):
+def setup_awsdbe_table_without_plaintext_override(kms_key_id: str, ddb_table_name: str):
     """
     Set up a pure AWS Database Encryption SDK EncryptedTable without plaintext override.
 
@@ -188,6 +188,7 @@ def setup_awsdbe_table_with_plaintext_override(kms_key_id: str, ddb_table_name:
         sort_key_name="sort_key",
         attribute_actions_on_encrypt=attribute_actions_on_encrypt,
         keyring=kms_mrk_multi_keyring,
+        # Provide plaintext_override policy to the config here
         plaintext_override=policy,
         allowed_unsigned_attribute_prefix=unsignAttrPrefix,
         # Specifying an algorithm suite is not required,

Examples/runtimes/python/Migration/plaintext_to_awsdbe/src/awsdbe/table/migration_step_3.py

@@ -20,7 +20,7 @@
   - Sort key is named "sort_key" with type (N)
 """
 
-from .common import setup_pure_awsdbe_table
+from .common import setup_awsdbe_table_without_plaintext_override
 
 
 def migration_step_3_with_table(kms_key_id: str, ddb_table_name: str, sort_read_value: int = 3):
@@ -33,7 +33,7 @@ def migration_step_3_with_table(kms_key_id: str, ddb_table_name: str, sort_read_
     """
     # 1. Create the EncryptedTable.
     #    Do not configure any plaintext override.
-    encrypted_table = setup_pure_awsdbe_table(kms_key_id, ddb_table_name)
+    encrypted_table = setup_awsdbe_table_without_plaintext_override(kms_key_id, ddb_table_name)
 
     # 2. Put an item into your table using the Encrypted Table.
     #    This item will be encrypted using the DB Encryption SDK, using the

Examples/runtimes/python/Migration/plaintext_to_awsdbe/test/awsdbe/paginator/test_migration_step_3.py

@@ -7,11 +7,16 @@
 Step 3 can only read encrypted items and will fail with plaintext items.
 """
 import pytest
+from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_transforms.errors import (
+    DynamoDbItemEncryptor,
+)
 
 from ....src.awsdbe.paginator import (
+    migration_step_1,
     migration_step_2,
     migration_step_3,
 )
+from ....src.plaintext.paginator import migration_step_0
 from ...test_utils import TEST_DDB_TABLE_NAME, TEST_KMS_KEY_ID
 
 pytestmark = [pytest.mark.examples]
@@ -20,14 +25,36 @@
 def test_migration_step_3_with_paginator():
     """Test migration step 3 compatibility with encrypted data formats only."""
     # Successfully executes Step 3
-    migration_step_3.migration_step_3_with_paginator(kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME)
+    migration_step_3.migration_step_3_with_paginator(
+        kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=3
+    )
 
-    # Given: Step 2 has succeeded (writing encrypted data)
-    migration_step_2.migration_step_2_with_paginator(kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME)
-    # When: Execute Step 3
-    # Then: Success (i.e. can read values in encrypted format)
-    migration_step_3.migration_step_3_with_paginator(kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME)
+    # Given: Step 0 has succeeded
+    migration_step_0.migration_step_0_with_paginator(ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=0)
+    # When: Execute Step 3 with sort_read_value=0
+    # Then: throws DynamoDbItemEncryptor Exception (i.e. cannot read values in plaintext format)
+    with pytest.raises(DynamoDbItemEncryptor):
+        migration_step_3.migration_step_3_with_paginator(
+            kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=0
+        )
 
-    # Note: Step 3 cannot read plaintext items (those written by Step 0 or Step 1)
-    # If attempted, it would throw an error because those items don't have the
-    # necessary encryption material
+    # Given: Step 1 has succeeded
+    migration_step_1.migration_step_1_with_paginator(
+        kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=1
+    )
+    # When: Execute Step 3 with sort_read_value=1
+    # Then: throws DynamoDbItemEncryptor Exception (i.e. cannot read values in plaintext format)
+    with pytest.raises(DynamoDbItemEncryptor):
+        migration_step_3.migration_step_3_with_paginator(
+            kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=1
+        )
+
+    # Given: Step 2 has succeeded
+    migration_step_2.migration_step_2_with_paginator(
+        kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=2
+    )
+    # When: Execute Step 3 with sort_read_value=2
+    # Then: Success (i.e. can read values in encrypted format)
+    migration_step_3.migration_step_3_with_paginator(
+        kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=2
+    )

Examples/runtimes/python/Migration/plaintext_to_awsdbe/test/awsdbe/resource/test_migration_step_3.py

@@ -7,11 +7,16 @@
 Step 3 can only read encrypted items and will fail with plaintext items.
 """
 import pytest
+from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_transforms.errors import (
+    DynamoDbItemEncryptor,
+)
 
 from ....src.awsdbe.resource import (
+    migration_step_1,
     migration_step_2,
     migration_step_3,
 )
+from ....src.plaintext.resource import migration_step_0
 from ...test_utils import TEST_DDB_TABLE_NAME, TEST_KMS_KEY_ID
 
 pytestmark = [pytest.mark.examples]
@@ -24,7 +29,27 @@ def test_migration_step_3_with_resource():
         kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=3
     )
 
-    # Given: Step 2 has succeeded (writing encrypted data)
+    # Given: Step 0 has succeeded
+    migration_step_0.migration_step_0_with_resource(ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=0)
+    # When: Execute Step 3 with sort_read_value=0
+    # Then: throws DynamoDbItemEncryptor Exception (i.e. cannot read values in plaintext format)
+    with pytest.raises(DynamoDbItemEncryptor):
+        migration_step_3.migration_step_3_with_resource(
+            kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=0
+        )
+
+    # Given: Step 1 has succeeded
+    migration_step_1.migration_step_1_with_resource(
+        kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=1
+    )
+    # When: Execute Step 3 with sort_read_value=1
+    # Then: throws DynamoDbItemEncryptor Exception (i.e. cannot read values in plaintext format)
+    with pytest.raises(DynamoDbItemEncryptor):
+        migration_step_3.migration_step_3_with_resource(
+            kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=1
+        )
+
+    # Given: Step 2 has succeeded
     migration_step_2.migration_step_2_with_resource(
         kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=2
     )
@@ -33,7 +58,3 @@ def test_migration_step_3_with_resource():
     migration_step_3.migration_step_3_with_resource(
         kms_key_id=TEST_KMS_KEY_ID, ddb_table_name=TEST_DDB_TABLE_NAME, sort_read_value=2
     )
-
-    # Note: Step 3 cannot read plaintext items (those written by Step 0 or Step 1)
-    # If attempted, it would throw an error because those items don't have the
-    # necessary encryption material