Feedback-1 InternalLegacyOverride

Author: imabhichow

DynamoDbEncryption/runtimes/python/src/aws_dbesdk_dynamodb/internaldafny/extern/InternalLegacyOverride.py

@@ -1,8 +1,12 @@
 # Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
 # SPDX-License-Identifier: Apache-2.0
+from _dafny import Seq
+
+import aws_dbesdk_dynamodb.internaldafny.generated.InternalLegacyOverride
 from aws_dbesdk_dynamodb.internaldafny.generated.AwsCryptographyDbEncryptionSdkDynamoDbItemEncryptorTypes import (
     DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig,
     Error_DynamoDbItemEncryptorException,
+    Error_Opaque,
     DecryptItemInput_DecryptItemInput,
     EncryptItemInput_EncryptItemInput,
 )
@@ -14,20 +18,19 @@
 from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb.references import (
     ILegacyDynamoDbEncryptor,
 )
-import smithy_dafny_standard_library.internaldafny.generated.Wrappers as Wrappers
-import _dafny
-
-import aws_dbesdk_dynamodb.internaldafny.generated.InternalLegacyOverride
 from aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor.models import (
     EncryptItemInput,
     EncryptItemOutput,
     DecryptItemOutput,
     DecryptItemInput,
 )
 
-
 try:
     from dynamodb_encryption_sdk.encrypted.client import EncryptedClient
+    from dynamodb_encryption_sdk.encrypted.table import EncryptedTable
+    from dynamodb_encryption_sdk.encrypted.resource import EncryptedResource
+    from dynamodb_encryption_sdk.encrypted.client import EncryptedPaginator
+    from dynamodb_encryption_sdk.encrypted.item import encrypt_dynamodb_item, decrypt_dynamodb_item
     from dynamodb_encryption_sdk.structures import EncryptionContext, AttributeActions
     from dynamodb_encryption_sdk.identifiers import CryptoAction
     from dynamodb_encryption_sdk.encrypted import CryptoConfig
@@ -39,8 +42,14 @@
 
 
 class InternalLegacyOverride(aws_dbesdk_dynamodb.internaldafny.generated.InternalLegacyOverride.InternalLegacyOverride):
+    def __init__(self):
+        super().__init__()
+        self.crypto_config = None
+        self.policy = None
+
     @staticmethod
     def Build(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig):
+        # Check for early return (Postcondition): If there is no legacyOverride there is nothing to do.
         if config.legacyOverride.is_None:
             return InternalLegacyOverride.CreateBuildSuccess(InternalLegacyOverride.CreateInternalLegacyOverrideNone())
 
@@ -51,7 +60,14 @@ def Build(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig):
             return InternalLegacyOverride.CreateBuildFailure(
                 InternalLegacyOverride.CreateError("Could not find aws-dynamodb-encryption-python installation")
             )
-        if not isinstance(legacy_override.encryptor, EncryptedClient):
+
+        # Precondition: The encryptor MUST be one of the supported legacy types
+        if not (
+            isinstance(legacy_override.encryptor, EncryptedClient)
+            or isinstance(legacy_override.encryptor, EncryptedTable)
+            or isinstance(legacy_override.encryptor, EncryptedResource)
+            or isinstance(legacy_override.encryptor, EncryptedPaginator)
+        ):
             return InternalLegacyOverride.CreateBuildFailure(
                 InternalLegacyOverride.CreateError("Legacy encryptor is not supported")
             )
@@ -68,7 +84,6 @@ def Build(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig):
 
         # Create and return the legacy override instance
         legacy_instance = InternalLegacyOverride()
-        legacy_instance.encryptor = legacy_override.encryptor
         legacy_instance.policy = legacy_override.policy
         legacy_instance.crypto_config = CryptoConfig(
             materials_provider=legacy_override.encryptor._materials_provider,
@@ -79,20 +94,16 @@ def Build(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig):
             InternalLegacyOverride.CreateInternalLegacyOverrideSome(legacy_instance)
         )
 
-    def __init__(self):
-        super().__init__()
-        self.encryptor = None
-        self.crypto_config = None
-        self.policy = None
-
     @staticmethod
     def legacyEncryptionContext(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncryptorConfig):
         """Create the legacy encryption context from the config."""
         try:
             # Convert Dafny types to Python strings for the encryption context
-            table_name = _dafny.string_of(config.logicalTableName)
-            partition_key_name = _dafny.string_of(config.partitionKeyName)
-            sort_key_name = _dafny.string_of(config.sortKeyName.value) if config.sortKeyName.is_Some else None
+            table_name = InternalLegacyOverride.ToNative(config.logicalTableName)
+            partition_key_name = InternalLegacyOverride.ToNative(config.partitionKeyName)
+            sort_key_name = (
+                InternalLegacyOverride.ToNative(config.sortKeyName.value) if config.sortKeyName.is_Some else None
+            )
 
             # Create the legacy encryption context with the extracted values
             encryption_context = EncryptionContext(
@@ -102,22 +113,22 @@ def legacyEncryptionContext(config: DynamoDbItemEncryptorConfig_DynamoDbItemEncr
             )
 
             return InternalLegacyOverride.CreateBuildSuccess(encryption_context)
-        except Exception as e:
-            # Return a failure with the error message if any exception occurs
-            return InternalLegacyOverride.CreateBuildFailure(InternalLegacyOverride.CreateError(str(e)))
+        except Exception as ex:
+            return InternalLegacyOverride.CreateBuildFailure(Error_Opaque(ex))
 
     @staticmethod
     def legacyActions(attribute_actions_on_encrypt):
         """Create the legacy attribute actions from the config."""
         try:
             # Create a new AttributeActions with default ENCRYPT_AND_SIGN
+            # Default Action to take if no specific action is defined in ``attribute_actions``
+            # https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/DDBEC-legacy-concepts.html#legacy-attribute-actions
             legacy_actions = AttributeActions(default_action=CryptoAction.ENCRYPT_AND_SIGN)
 
             # Map the action from the config to legacy actions
             attribute_actions = {}
             for key, action in attribute_actions_on_encrypt.items:
-                # Convert the string key to Python string
-                key_str = _dafny.string_of(key)
+                key_str = InternalLegacyOverride.ToNative(key)
 
                 # Map the action type to the appropriate CryptoAction
                 if action == CryptoAction_ENCRYPT__AND__SIGN():
@@ -134,8 +145,8 @@ def legacyActions(attribute_actions_on_encrypt):
             # Update the attribute_actions dictionary
             legacy_actions.attribute_actions = attribute_actions
             return InternalLegacyOverride.CreateBuildSuccess(legacy_actions)
-        except Exception as e:
-            return InternalLegacyOverride.CreateBuildFailure(InternalLegacyOverride.CreateError(str(e)))
+        except Exception as ex:
+            return InternalLegacyOverride.CreateBuildFailure(Error_Opaque(ex))
 
     def EncryptItem(self, input: EncryptItemInput_EncryptItemInput):
         """Encrypt an item using the legacy DynamoDB encryptor.
@@ -147,9 +158,9 @@ def EncryptItem(self, input: EncryptItemInput_EncryptItemInput):
             Result containing the encrypted item or an error
         """
         try:
-            # Check policy
+            # Precondition: Policy MUST allow the caller to encrypt.
             if not self.policy.is_FORCE__LEGACY__ENCRYPT__ALLOW__LEGACY__DECRYPT:
-                return Wrappers.Result_Failure(
+                return self.CreateEncryptItemFailure(
                     InternalLegacyOverride.CreateError("Legacy policy does not support encrypt")
                 )
 
@@ -158,24 +169,23 @@ def EncryptItem(self, input: EncryptItemInput_EncryptItemInput):
                 input
             )
 
-            # Use the encryptor to encrypt the item using the instance attributes
-            encrypted_item = self.encryptor._encrypt_item(
+            # Encrypt the item using the instance attributes
+            encrypted_item = encrypt_dynamodb_item(
                 item=native_input.plaintext_item,
                 crypto_config=self.crypto_config.with_item(native_input.plaintext_item),
             )
 
             # Return the encrypted item
-            # The legacy encryption client returns items in the format that Dafny expects,
+            # The legacy encryption method returns items in the format that Dafny expects,
             # so no additional conversion is needed here
             native_output = EncryptItemOutput(encrypted_item=encrypted_item, parsed_header=None)
             dafny_output = aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor.smithy_to_dafny.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor_EncryptItemOutput(
                 native_output
             )
-            return Wrappers.Result_Success(dafny_output)
+            return self.CreateEncryptItemSuccess(dafny_output)
 
-        except Exception as e:
-            # Return an appropriate error result with the exception details
-            return Wrappers.Result_Failure(InternalLegacyOverride.CreateError(f"Error during encryption: {str(e)}"))
+        except Exception as ex:
+            return self.CreateEncryptItemFailure(InternalLegacyOverride.CreateError(Error_Opaque(ex)))
 
     def DecryptItem(self, input: DecryptItemInput_DecryptItemInput):
         """Decrypt an item using the legacy DynamoDB encryptor.
@@ -187,12 +197,17 @@ def DecryptItem(self, input: DecryptItemInput_DecryptItemInput):
             Result containing the decrypted item or an error
         """
         try:
-            # Check policy
+            # Precondition: Policy MUST allow the caller to decrypt.
+            # = specification/dynamodb-encryption-client/decrypt-item.md#behavior
+            ## If a [Legacy Policy](./ddb-table-encryption-config.md#legacy-policy) of
+            ## `FORBID_LEGACY_ENCRYPT_FORBID_LEGACY_DECRYPT` is configured,
+            ## and the input item [is an item written in the legacy format](#determining-legacy-items),
+            ## this operation MUST fail.
             if not (
                 self.policy.is_FORCE__LEGACY__ENCRYPT__ALLOW__LEGACY__DECRYPT
                 or self.policy.is_FORBID__LEGACY__ENCRYPT__ALLOW__LEGACY__DECRYPT
             ):
-                return Wrappers.Result_Failure(
+                return self.CreateDecryptItemFailure(
                     InternalLegacyOverride.CreateError("Legacy policy does not support decrypt")
                 )
 
@@ -202,8 +217,8 @@ def DecryptItem(self, input: DecryptItemInput_DecryptItemInput):
                     input
                 )
             )
-            # Use the encryptor to decrypt the item using the instance attributes
-            decrypted_item = self.encryptor._decrypt_item(
+            # Decrypt the item using the instance attributes
+            decrypted_item = decrypt_dynamodb_item(
                 item=native_input.encrypted_item,
                 crypto_config=self.crypto_config.with_item(native_input.encrypted_item),
             )
@@ -212,10 +227,9 @@ def DecryptItem(self, input: DecryptItemInput_DecryptItemInput):
             dafny_output = aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor.smithy_to_dafny.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor_DecryptItemOutput(
                 native_output
             )
-            return Wrappers.Result_Success(dafny_output)
-        except Exception as e:
-            # Return an appropriate error result with the exception details
-            return Wrappers.Result_Failure(InternalLegacyOverride.CreateError(f"Error during decryption: {str(e)}"))
+            return self.CreateDecryptItemSuccess(dafny_output)
+        except Exception as ex:
+            return self.CreateDecryptItemFailure(InternalLegacyOverride.CreateError(Error_Opaque(ex)))
 
     def IsLegacyInput(self, input: DecryptItemInput_DecryptItemInput):
         """
@@ -227,35 +241,36 @@ def IsLegacyInput(self, input: DecryptItemInput_DecryptItemInput):
         Returns:
             Boolean indicating if the input is from a legacy client
         """
-        try:
-            if not _HAS_LEGACY_DDBEC:
-                return False
+        if not input.is_DecryptItemInput:
+            return False
 
-            if not input.is_DecryptItemInput:
-                return False
-
-            # Get the Native DecryptItemInput
-            native_input: DecryptItemInput = (
-                aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor.dafny_to_smithy.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor_DecryptItemInput(
-                    input
-                )
-            )
-            # = specification/dynamodb-encryption-client/decrypt-item.md#determining-legacy-items
-            ## An item MUST be determined to be encrypted under the legacy format if it contains
-            ## attributes for the material description and the signature.
-            return (
-                "*amzn-ddb-map-desc*" in native_input.encrypted_item
-                and "*amzn-ddb-map-sig*" in native_input.encrypted_item
+        # Get the Native DecryptItemInput
+        native_input: DecryptItemInput = (
+            aws_dbesdk_dynamodb.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor.dafny_to_smithy.aws_cryptography_dbencryptionsdk_dynamodb_itemencryptor_DecryptItemInput(
+                input
             )
+        )
+        # = specification/dynamodb-encryption-client/decrypt-item.md#determining-legacy-items
+        ## An item MUST be determined to be encrypted under the legacy format if it contains
+        ## attributes for the material description and the signature.
+        return (
+            "*amzn-ddb-map-desc*" in native_input.encrypted_item and "*amzn-ddb-map-sig*" in native_input.encrypted_item
+        )
 
-        except Exception as e:
-            # If we encounter any error during detection, default to not using legacy
-            return Wrappers.Result_Failure(InternalLegacyOverride.CreateError(f"Error in IsLegacyInput: {e}"))
+    @staticmethod
+    def ToNative(dafny_input):
+        return b"".join(ord(c).to_bytes(2, "big") for c in dafny_input).decode("utf-16-be")
+
+    @staticmethod
+    def ToDafny(native_input):
+        return Seq(
+            "".join([chr(int.from_bytes(pair, "big")) for pair in zip(*[iter(native_input.encode("utf-16-be"))] * 2)])
+        )
 
     @staticmethod
     def CreateError(message):
         """Create an Error with the given message."""
-        return Error_DynamoDbItemEncryptorException(message)
+        return Error_DynamoDbItemEncryptorException(InternalLegacyOverride.ToDafny(message))
 
 
 aws_dbesdk_dynamodb.internaldafny.generated.InternalLegacyOverride.InternalLegacyOverride = InternalLegacyOverride

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

@@ -1,69 +1,45 @@
-# Migration Examples: Legacy DynamoDB Encryption Client to AWS Database Encryption SDK
+# DyanmoDb Encryption Client to AWS Database Encryption SDK for DynamoDb Migration
 
-These examples demonstrate a complete migration path from the legacy AWS DynamoDB Encryption Client Python library to the new AWS Database Encryption SDK for DynamoDB.
+This projects demonstrates the three Steps necessary to migration to the AWS Database Encryption SDK for DynamoDb
+if you are currently using the DynamoDb Encryption Client.
 
-## Overview
+[Step 0](./ddbec/README.md) demonstrates the starting state for your system.
 
-The migration process is demonstrated through a series of example steps that show how to gradually transition from the legacy client to the new SDK while maintaining compatibility with previously encrypted data.
+## Step 1
 
-## Migration Steps
+In Step 1, you update your system to do the following:
 
-### Step 0: Legacy DynamoDB Encryption Client
+- continue to read items in the old format
+- continue to write items in the old format
+- prepare to read items in the new format
 
-[migration_step_0.py](./ddbec/migration_step_0.py) demonstrates using the legacy DynamoDB Encryption Client to encrypt and decrypt items. This represents the starting point for migration.
+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 the old format.
 
-Key concepts:
+You must ensure that the changes in Step 1 make it to all your reads before you proceed to step 2.
 
-- Setting up the legacy client with an AWS KMS cryptographic materials provider
-- Defining attribute actions for encryption/signing
-- Storing and retrieving encrypted items
+## Step 2
 
-### Step 1: AWS Database Encryption SDK with Legacy Override
+In Step 2, you update your system to do the following:
 
-[migration_step_1.py](./awsdbe/migration_step_1.py) demonstrates how to start using the AWS Database Encryption SDK with a pre-existing table used with the DynamoDB Encryption Client.
+- continue to read items in the old format
+- start writing items in the new format
+- continue to read items in the new format
 
-Key concepts:
+When you deploy changes in Step 2, you are introducing a new encryption format to your system,
+and must make sure that all your readers are updated with the changes from Step 1.
 
-- Configure AWS DBESDK to read items encrypted in the legacy format
-- Continue to encrypt items in the legacy format (FORCE_LEGACY_ENCRYPT_ALLOW_DECRYPT policy)
-- Read items encrypted in the new format
-- Deploy this step to all readers before moving to step 2
+Before you move onto the next step, you will need to re-encrypt all old 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.
 
-### Step 2: Full Migration to AWS Database Encryption SDK
+## Step 3
 
-[migration_step_2.py](./awsdbe/migration_step_2.py) demonstrates the next step in the migration process, using both the pure AWS DBESDK client and the legacy-override client side by side.
+Once all old items are re-encrypted to use the new format,
+you may update your system to do the following:
 
-Key concepts:
+- continue to write items in the new format
+- continue to read items in the new format
+- do not accept reading items in the old format
 
-- Create a pure AWS DBESDK client for new data
-- Keep using legacy-override client when needed for legacy data
-- Re-encrypt legacy data with the new client
-- Demonstrate that the legacy-override client can read both formats
-
-### Step 3: Complete Migration - Using Only AWS DBESDK
-
-[migration_step_3.py](./awsdbe/migration_step_3.py) demonstrates the final state of the migration, where all data has been re-encrypted using the new format.
-
-Key concepts:
-
-- Use only the pure AWS DBESDK client (no more legacy override)
-- Verify all previously re-encrypted data is readable
-- Add new data using the pure client
-
-## Prerequisites
-
-Before running these examples:
-
-1. Replace `common.KMS_KEY_ID` with a valid AWS KMS key ID or alias
-2. Ensure you have AWS credentials configured with permissions for:
-   - DynamoDB (CreateTable, PutItem, GetItem, etc.)
-   - KMS (GenerateDataKey, Decrypt)
-3. Have both libraries installed:
-   - Legacy library: `pip install dynamodb-encryption-sdk`
-   - New SDK: `pip install aws-dbesdk-dynamodb`
-
-## Important Notes
-
-- These examples create a real DynamoDB table and perform actual AWS KMS operations, which may incur AWS charges
-- By default, the examples leave the created table intact when they finish - uncomment the table deletion code in the example scripts if you want to clean up resources
-- These examples are focused on demonstrating a migration path and are not production-ready code
+Once you have deployed these changes to your system, you have completed migration.