AWS DynamoDB Encryption Client (Internal Dependency)

Common errors

• ModuleNotFoundError: No module named 'aws_dynamodb_encryption_sdk'

  cause Attempting to import from the public DynamoDB Encryption SDK module (`aws_dynamodb_encryption_sdk`) after only installing its internal dependency (`aws-cryptography-internal-dynamodb`).
  fix Install the full AWS SDK for DynamoDB Encryption: `pip install aws-sdk-dynamodb-encryption`.

• AttributeError: module 'aws_cryptography_internal_dynamodb' has no attribute 'EncryptedTable'

  cause Mistakenly attempting to use `aws-cryptography-internal-dynamodb` as if it were the public-facing DynamoDB Encryption SDK and trying to access its classes.
  fix All public interfaces for DynamoDB client-side encryption are provided by `aws-sdk-dynamodb-encryption`. Install that library and import classes like `EncryptedTable` from `aws_dynamodb_encryption_sdk`.

Warnings

• breaking This package (`aws-cryptography-internal-dynamodb`) is an internal dependency of the AWS SDK for DynamoDB Encryption. It is not designed for direct consumption, and its internal components are subject to breaking changes without notice or adherence to semantic versioning for public APIs.
  Fix: Always install and interact with the public-facing SDK: `aws-sdk-dynamodb-encryption`. This SDK manages its dependencies, including this package, and provides a stable, documented API.
• gotcha Installing `aws-cryptography-internal-dynamodb` alone does NOT provide the AWS DynamoDB Encryption Client SDK. You will not find the main `aws_dynamodb_encryption_sdk` module or its public classes after installing only this dependency.
  Fix: To use client-side encryption for DynamoDB, you MUST install the full AWS SDK for DynamoDB Encryption: `pip install aws-sdk-dynamodb-encryption`.
• gotcha Trying to import directly from `aws_cryptography_internal_dynamodb` will likely result in `ModuleNotFoundError` for intended classes or `AttributeError` for methods, as it exposes no public interfaces designed for direct user interaction.
  Fix: All public interfaces (e.g., `EncryptedTable`, `KMSKeyring`) are provided by `aws_dynamodb_encryption_sdk`. Import from that module instead.

Install

• pip install aws-cryptography-internal-dynamodb Installation of the internal dependency
• pip install aws-sdk-dynamodb-encryption Recommended: Install the public-facing SDK

Imports

• EncryptedTable

  from aws_dynamodb_encryption_sdk.encrypted.table import EncryptedTable

  This symbol is from the parent library, `aws-sdk-dynamodb-encryption`, which depends on this internal package. Do not attempt to import from `aws-cryptography-internal-dynamodb` directly, as it does not expose public interfaces.
• DynamoDbEncryptionConfig

  from aws_dynamodb_encryption_sdk.identifiers import DynamoDbEncryptionConfig

  Similar to `EncryptedTable`, this is part of the public API provided by the `aws-sdk-dynamodb-encryption` library, not this internal dependency.

Quickstart

This quickstart demonstrates the typical usage pattern for the AWS DynamoDB Encryption Client. Note that the imports and `EncryptedTable` class are provided by the *parent* library, `aws-sdk-dynamodb-encryption`, not `aws-cryptography-internal-dynamodb` directly. Ensure you have the `aws-sdk-dynamodb-encryption` package installed and configured with appropriate AWS credentials and a KMS key ARN. The example shows putting and getting an item, with client-side encryption and decryption handled automatically.

import os
import boto3
from aws_dynamodb_encryption_sdk.encrypted.table import EncryptedTable
from aws_encryption_sdk.key_providers.kms import KMSKeyring

# NOTE: This quickstart demonstrates usage of the PARENT library: `aws-sdk-dynamodb-encryption`.
# This internal package (`aws-cryptography-internal-dynamodb`) is NOT for direct use.
# Ensure you have installed the public-facing SDK: `pip install aws-sdk-dynamodb-encryption`

# Configuration
TABLE_NAME = os.environ.get('DYNAMODB_TABLE_NAME', 'my-encrypted-table')
KMS_KEY_ARN = os.environ.get('KMS_KEY_ARN', 'arn:aws:kms:us-west-2:123456789012:key/your-kms-key-id')
REGION = os.environ.get('AWS_REGION', 'us-west-2')

# Initialize boto3 DynamoDB client
dynamodb_client = boto3.client('dynamodb', region_name=REGION)

# Create a KMS Keyring
keyring = KMSKeyring(key_ids=[KMS_KEY_ARN])

# Create an EncryptedTable instance for your DynamoDB table
# The master key provider is used to encrypt/decrypt data on the client side
encrypted_table = EncryptedTable(
    table=boto3.resource('dynamodb', region_name=REGION).Table(TABLE_NAME),
    keyring=keyring
)

# Example: Put an item into the encrypted table
item_id = 'item123'
item_data = {'id': item_id, 'data': 'sensitive_info', 'cleartext_attribute': 'visible_data'}
print(f"Putting item: {item_data}")
encrypted_table.put_item(Item=item_data)

# Example: Get an item from the encrypted table
retrieved_item = encrypted_table.get_item(Key={'id': item_id})['Item']
print(f"Retrieved item: {retrieved_item}")

# Verify decryption (sensitive_info should be visible)
assert retrieved_item['data'] == 'sensitive_info'
print("Item successfully encrypted and decrypted.")