sync

Author: Lucas McDonald

DynamoDbEncryption/runtimes/python/src/aws_dbesdk_dynamodb/encrypted/table.py

@@ -37,20 +37,21 @@ class EncryptedTable(EncryptedBotoInterface):
     drop-in replacement that transparently handles encryption and decryption of items.
 
     The API matches the standard boto3 DynamoDB table interface:
+
     https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table.html
 
     This class will encrypt/decrypt items for the following operations:
-        * put_item
-        * get_item
-        * query
-        * scan
+        * ``put_item``
+        * ``get_item``
+        * ``query``
+        * ``scan``
+
+    The ``update_item`` operation is not currently supported. Calling this operation will raise ``NotImplementedError``.
 
-    Calling batch_writer() will return a BatchWriter that transparently encrypts batch write requests.
+    Calling ``batch_writer()`` will return a ``BatchWriter`` that transparently encrypts batch write requests.
 
     Any other operations on this class will defer to the underlying boto3 DynamoDB Table's implementation
         and will not be encrypted/decrypted.
-
-    Note: The update_item operation is not currently supported. Calling this operation will raise NotImplementedError.
     """
 
     def __init__(
@@ -60,7 +61,7 @@ def __init__(
         encryption_config: DynamoDbTablesEncryptionConfig,
     ):
         """
-        Create an EncryptedTable object.
+        Create an ``EncryptedTable`` object.
 
         Args:
             table (ServiceResource): Initialized boto3 DynamoDB table
@@ -79,15 +80,16 @@ def put_item(self, **kwargs) -> dict[str, Any]:
         """
         Put a single item to the table. Encrypts the item before writing to DynamoDB.
 
-        The parameters and return value match the boto3 DynamoDB table put_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB table ``put_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/put_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 put_item API parameters.
-                The "Item" field will be encrypted locally before being written to DynamoDB.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 Table ``put_item`` request
+                syntax. The value in ``"Item"`` will be encrypted locally before being written to DynamoDB.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 put_item API response.
+            dict: The response from DynamoDB. This matches the boto3 ``put_item`` response syntax.
 
         """
         return self._table_operation_logic(
@@ -107,15 +109,17 @@ def get_item(self, **kwargs) -> dict[str, Any]:
         """
         Get a single item from the table. Decrypts the item after reading from DynamoDB.
 
-        The parameters and return value match the boto3 DynamoDB table get_item API:
+        The input and output syntaxes match those for the boto3 DynamoDB table ``get_item`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/get_item.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 get_item API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 Table ``get_item`` request
+                syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 get_item API response.
-                The "Item" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 Table ``get_item`` response syntax.
+                The value in ``"Item"`` will be decrypted locally after being read from DynamoDB.
 
         """
         return self._table_operation_logic(
@@ -135,15 +139,17 @@ def query(self, **kwargs) -> dict[str, Any]:
         """
         Query items from the table or index. Decrypts any returned items.
 
-        The parameters and return value match the boto3 DynamoDB table query API:
+        The input and output syntaxes match those for the boto3 DynamoDB table ``query`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/query.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 query API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 Table ``query`` request
+                syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 query API response.
-                The "Items" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 Table ``query`` response syntax.
+                The value in ``"Items"`` will be decrypted locally after being read from DynamoDB.
 
         """
         return self._table_operation_logic(
@@ -163,15 +169,17 @@ def scan(self, **kwargs) -> dict[str, Any]:
         """
         Scan the entire table or index. Decrypts any returned items.
 
-        The parameters and return value match the boto3 DynamoDB table scan API:
+        The input and output syntaxes match those for the boto3 DynamoDB table ``scan`` API:
+
         https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/table/scan.html
 
         Args:
-            **kwargs: Keyword arguments to pass to the operation. These match the boto3 scan API parameters.
+            **kwargs: Keyword arguments to pass to the operation. This matches the boto3 Table ``scan`` request
+                syntax.
 
         Returns:
-            dict: The response from DynamoDB. This matches the boto3 scan API response.
-                The "Items" field will be decrypted locally after being read from DynamoDB.
+            dict: The response from DynamoDB. This matches the boto3 Table ``scan`` response syntax.
+                The value in ``"Items"`` will be decrypted locally after being read from DynamoDB.
 
         """
         return self._table_operation_logic(
@@ -189,7 +197,7 @@ def scan(self, **kwargs) -> dict[str, Any]:
 
     def update_item(self, **kwargs):
         """
-        Not implemented. Raises NotImplementedError.
+        Not implemented. Raises ``NotImplementedError``.
 
         Args:
             **kwargs: Any arguments passed to this method

DynamoDbEncryption/runtimes/python/test/integ/encrypted/test_table.py

@@ -35,6 +35,10 @@ def plaintext_table():
     return table
 
 
+# Creates a matrix of tests for each value in param,
+# with a user-friendly string for test output:
+# encrypted = True -> "encrypted"
+# encrypted = False -> "plaintext"
 @pytest.fixture(params=[True, False], ids=["encrypted", "plaintext"])
 def encrypted(request):
     return request.param
@@ -52,6 +56,10 @@ def table(encrypted):
         return plaintext_table()
 
 
+# Creates a matrix of tests for each value in param,
+# with a user-friendly string for test output:
+# use_complex_item = True -> "complex_item"
+# use_complex_item = False -> "simple_item"
 @pytest.fixture(params=[simple_item_dict, complex_item_dict], ids=["simple_item", "complex_item"])
 def test_item(request):
     return request.param
@@ -135,24 +143,13 @@ def test_GIVEN_items_in_table_WHEN_query_THEN_items_are_decrypted_correctly(tabl
     assert len(query_response["Items"]) == 1
     assert query_response["Items"][0] == put_item_request_dict["Item"]
 
-    # Scans work, but the test items are not found because
-    # DDB only returns the first 1MB of data, and the test items
-    # are not in the first 1MB sometimes. We probably need a new table.
-    # TODO: Add a new table for these tests, enable tests.
-    # # When: Scanning with filter that matches only our test items
-    # scan_response = encrypted_table.scan(**scan_request_dict)
-    # # Then: Scan returns both test items
-    # assert scan_response["ResponseMetadata"]["HTTPStatusCode"] == 200
-    # assert len(scan_response["Items"]) == 2
-    # # Check each test item is found in scan results
-    # found_items = scan_response["Items"]
-    # assert all(any(found_item == item for found_item in found_items) for item in items)
-
 
 @pytest.fixture
 def scan_request(encrypted, test_item):
     if encrypted:
         request = basic_scan_request_dict(test_item)
+        # If the encrypted scan encounters a plaintext item, the scan will fail.
+        # To avoid this, encrypted scans add a filter expression that matches only encrypted items.
         request["FilterExpression"] = request["FilterExpression"] + " AND attribute_exists (#sig)"
         request["ExpressionAttributeNames"] = {}
         request["ExpressionAttributeNames"]["#sig"] = "amzn-ddb-map-sig"

TestVectors/runtimes/python/src/aws_dbesdk_dynamodb_test_vectors/internaldafny/extern/CreateInterceptedDDBTable.py

@@ -12,30 +12,22 @@
 from smithy_dafny_standard_library.internaldafny.generated import Wrappers
 from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb.errors import _smithy_error_to_dafny_error
 from aws_dbesdk_dynamodb_test_vectors.waiting_boto3_ddb_client import WaitingLocalDynamoClient
-from aws_dbesdk_dynamodb.transform import (
-    dict_to_ddb,
-    ddb_to_dict,
-)
-from aws_dbesdk_dynamodb.internal import client_to_resource
-
-from boto3.dynamodb.conditions import Key, Attr, And, Or, Not, Contains
-from boto3.dynamodb.types import TypeDeserializer
 
-# from .....test.resource_formatted_queries import (queries, complex_queries)
+from boto3.dynamodb.conditions import Key, Attr
 
 # When querying, DBESDK DDB TestVectors will pass the Table the query as a string.
 # The Table could accept this string as-is and process it correctly.
 # However, EncryptedTables have extra logic to process boto3 Conditions.
-# I want to test this extra logic as much as possible.
+# This extra logic should be tested as much as possible.
 # This map converts some known query strings to equivalent Conditions.
 # TestVectors will pass the query string (map key) to the Table;
 # the Table's internal logic will look up the query string in this map:
 #  - Entry found: Query with replaced Condition
 #  - Not found: Query with original string. Table accepts strings.
 # This map contains all query strings in the TestVectors' data.json as of commit
 # 4f18689f79243c9a5ab0f3a23108671defddeac4
-# If any query strings are added to TestVectors, they COULD be added here,
-#   but do not need to be added.
+# If any query strings are added to TestVectors, they COULD be added here;
+# if they are not added, the Table will accept the string as-is.
 known_query_string_to_condition_map = {
     # "Basic" queries
     "RecNum = :zero": Key("RecNum").eq(":zero"),
@@ -130,9 +122,9 @@ def get_item(self, **kwargs):
         return client_output
 
     def batch_write_item(self, **kwargs):
-        # There isn't a resource shape for this;
+        # The table doesn't support batch_write_item, but supports batch_writer.
+        # Translate the batch_write_item request to batch_writer requests.
         table_input = self._client_shape_to_resource_shape_converter.batch_write_item_request(kwargs)
-        # table_output = self._table.batch_write_item(**table_input)
         with self._table.batch_writer() as batch_writer:
             for _, items in table_input["RequestItems"].items():
                 for item in items:
@@ -142,7 +134,7 @@ def batch_write_item(self, **kwargs):
                         batch_writer.delete_item(item["DeleteRequest"]["Key"])
                     else:
                         raise ValueError(f"Unknown request type: {item}")
-        # There isn't a shape for the output, but luckily the output can be an empty dict:
+        # An empty dict is valid output:
         # https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/dynamodb/client/batch_write_item.html
         client_output = {}
         return client_output
@@ -158,8 +150,7 @@ def scan(self, **kwargs):
         if "KeyConditionExpression" in table_input:
             if table_input["KeyConditionExpression"] in known_query_string_to_condition_map:
                 # Turn the query into the resource-formatted query
-                query = known_query_string_to_condition_map[table_input["KeyConditionExpression"]]
-                table_input["KeyConditionExpression"] = query
+                table_input["KeyConditionExpression"] = known_query_string_to_condition_map[table_input["KeyConditionExpression"]]
         if "FilterExpression" in table_input:
             if table_input["FilterExpression"] in known_query_string_to_condition_map:
                 # Turn the query into the resource-formatted query
@@ -182,8 +173,7 @@ def query(self, **kwargs):
         if "KeyConditionExpression" in table_input:
             if table_input["KeyConditionExpression"] in known_query_string_to_condition_map:
                 # Turn the query into the resource-formatted query
-                query = known_query_string_to_condition_map[table_input["KeyConditionExpression"]]
-                table_input["KeyConditionExpression"] = query
+                table_input["KeyConditionExpression"] = known_query_string_to_condition_map[table_input["KeyConditionExpression"]]
         if "FilterExpression" in table_input:
             if table_input["FilterExpression"] in known_query_string_to_condition_map:
                 # Turn the query into the resource-formatted query