|
| 1 | +# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. |
| 2 | +# SPDX-License-Identifier: Apache-2.0 |
| 3 | +"""Example for using the EncryptedTablesCollectionManager provided by EncryptedResource |
| 4 | +
|
| 5 | +Running this example requires access to the DDB Tables whose names |
| 6 | +are provided in the function arguments. |
| 7 | +These tables must be configured with the following primary key configuration: |
| 8 | +- Partition key is named "partition_key" with type (S) |
| 9 | +- Sort key is named "sort_key" with type (N) |
| 10 | +""" |
| 11 | + |
| 12 | +import boto3 |
| 13 | +from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders |
| 14 | +from aws_cryptographic_material_providers.mpl.config import MaterialProvidersConfig |
| 15 | +from aws_cryptographic_material_providers.mpl.models import ( |
| 16 | + CreateAwsKmsMrkMultiKeyringInput, |
| 17 | + DBEAlgorithmSuiteId, |
| 18 | +) |
| 19 | +from aws_cryptographic_material_providers.mpl.references import IKeyring |
| 20 | +from aws_dbesdk_dynamodb.encrypted.resource import ( |
| 21 | + EncryptedResource, |
| 22 | + EncryptedTablesCollectionManager, |
| 23 | +) |
| 24 | +from aws_dbesdk_dynamodb.structures.dynamodb import ( |
| 25 | + DynamoDbTableEncryptionConfig, |
| 26 | + DynamoDbTablesEncryptionConfig, |
| 27 | +) |
| 28 | +from aws_dbesdk_dynamodb.structures.structured_encryption import ( |
| 29 | + CryptoAction, |
| 30 | +) |
| 31 | + |
| 32 | +def encrypted_tables_collection_manager_example( |
| 33 | + kms_key_id: str, |
| 34 | + dynamodb_table_names: list[str], |
| 35 | +): |
| 36 | + """Use an EncryptedTablesCollectionManager to write and read to multiple tables.""" |
| 37 | + # 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data. |
| 38 | + # For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use. |
| 39 | + # We will use the `CreateMrkMultiKeyring` method to create this keyring, |
| 40 | + # as it will correctly handle both single region and Multi-Region KMS Keys. |
| 41 | + mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders(config=MaterialProvidersConfig()) |
| 42 | + kms_mrk_multi_keyring_input: CreateAwsKmsMrkMultiKeyringInput = CreateAwsKmsMrkMultiKeyringInput( |
| 43 | + generator=kms_key_id, |
| 44 | + ) |
| 45 | + kms_mrk_multi_keyring: IKeyring = mat_prov.create_aws_kms_mrk_multi_keyring(input=kms_mrk_multi_keyring_input) |
| 46 | + |
| 47 | + # 2. Configure which attributes are encrypted and/or signed when writing new items. |
| 48 | + # For each attribute that may exist on the items we plan to write to our DynamoDbTable, |
| 49 | + # we must explicitly configure how they should be treated during item encryption: |
| 50 | + # - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature |
| 51 | + # - SIGN_ONLY: The attribute not encrypted, but is still included in the signature |
| 52 | + # - DO_NOTHING: The attribute is not encrypted and not included in the signature |
| 53 | + attribute_actions_on_encrypt = { |
| 54 | + "partition_key": CryptoAction.SIGN_ONLY, |
| 55 | + "sort_key": CryptoAction.SIGN_ONLY, |
| 56 | + "attribute1": CryptoAction.ENCRYPT_AND_SIGN, |
| 57 | + "attribute2": CryptoAction.SIGN_ONLY, |
| 58 | + ":attribute3": CryptoAction.DO_NOTHING, |
| 59 | + } |
| 60 | + |
| 61 | + # 3. Configure which attributes we expect to be included in the signature |
| 62 | + # when reading items. There are two options for configuring this: |
| 63 | + # |
| 64 | + # - (Recommended) Configure `allowedUnsignedAttributesPrefix`: |
| 65 | + # When defining your DynamoDb schema and deciding on attribute names, |
| 66 | + # choose a distinguishing prefix (such as ":") for all attributes that |
| 67 | + # you do not want to include in the signature. |
| 68 | + # This has two main benefits: |
| 69 | + # - It is easier to reason about the security and authenticity of data within your item |
| 70 | + # when all unauthenticated data is easily distinguishable by their attribute name. |
| 71 | + # - If you need to add new unauthenticated attributes in the future, |
| 72 | + # you can easily make the corresponding update to your `attributeActionsOnEncrypt` |
| 73 | + # and immediately start writing to that new attribute, without |
| 74 | + # any other configuration update needed. |
| 75 | + # Once you configure this field, it is not safe to update it. |
| 76 | + # |
| 77 | + # - Configure `allowedUnsignedAttributes`: You may also explicitly list |
| 78 | + # a set of attributes that should be considered unauthenticated when encountered |
| 79 | + # on read. Be careful if you use this configuration. Do not remove an attribute |
| 80 | + # name from this configuration, even if you are no longer writing with that attribute, |
| 81 | + # as old items may still include this attribute, and our configuration needs to know |
| 82 | + # to continue to exclude this attribute from the signature scope. |
| 83 | + # If you add new attribute names to this field, you must first deploy the update to this |
| 84 | + # field to all readers in your host fleet before deploying the update to start writing |
| 85 | + # with that new attribute. |
| 86 | + # |
| 87 | + # For this example, we have designed our DynamoDb table such that any attribute name with |
| 88 | + # the ":" prefix should be considered unauthenticated. |
| 89 | + unsignAttrPrefix: str = ":" |
| 90 | + |
| 91 | + # 4. Create the DynamoDb Encryption configuration for the tables we will be writing to. |
| 92 | + # For each table, we create a DynamoDbTableEncryptionConfig and add it to a dictionary. |
| 93 | + # This dictionary is then added to a DynamoDbTablesEncryptionConfig, which is used to create the EncryptedResource. |
| 94 | + table_configs = {} |
| 95 | + for dynamodb_table_name in dynamodb_table_names: |
| 96 | + table_config = DynamoDbTableEncryptionConfig( |
| 97 | + logical_table_name=dynamodb_table_name, |
| 98 | + partition_key_name="partition_key", |
| 99 | + sort_key_name="sort_key", |
| 100 | + attribute_actions_on_encrypt=attribute_actions_on_encrypt, |
| 101 | + keyring=kms_mrk_multi_keyring, |
| 102 | + allowed_unsigned_attribute_prefix=unsignAttrPrefix, |
| 103 | + # Specifying an algorithm suite is not required, |
| 104 | + # but is done here to demonstrate how to do so. |
| 105 | + # We suggest using the |
| 106 | + # `ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384` suite, |
| 107 | + # which includes AES-GCM with key derivation, signing, and key commitment. |
| 108 | + # This is also the default algorithm suite if one is not specified in this config. |
| 109 | + # For more information on supported algorithm suites, see: |
| 110 | + # https://docs.aws.amazon.com/database-encryption-sdk/latest/devguide/supported-algorithms.html |
| 111 | + algorithm_suite_id=DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384, |
| 112 | + ) |
| 113 | + table_configs[dynamodb_table_name] = table_config |
| 114 | + tables_config = DynamoDbTablesEncryptionConfig(table_encryption_configs=table_configs) |
| 115 | + |
| 116 | + # 5. Create the EncryptedResource |
| 117 | + encrypted_resource = EncryptedResource( |
| 118 | + resource=boto3.resource("dynamodb"), |
| 119 | + encryption_config=tables_config, |
| 120 | + ) |
| 121 | + |
| 122 | + # 6. Retrieve the EncryptedTablesCollectionManager from the EncryptedResource |
| 123 | + encrypted_tables_collection_manager = encrypted_resource.tables |
| 124 | + |
| 125 | + # 7. Use the EncryptedTablesCollectionManager to get EncryptedTables to write to. |
| 126 | + # **IMPORTANT**: This will return all tables in the collection, not just the ones you want to write to. |
| 127 | + # This will include all tables that are associated with the current account and endpoint. |
| 128 | + # You should consider filtering the tables you write to based on the table name. |
| 129 | + encrypted_tables = encrypted_tables_collection_manager.all() |
| 130 | + |
| 131 | + # 8. Write a batch of items to the table. |
| 132 | + # Before the items get sent to DynamoDb, they will be encrypted |
| 133 | + # client-side, according to our configuration. |
| 134 | + items = [] |
| 135 | + for encrypted_table in encrypted_tables: |
| 136 | + # Here, you should consider filtering the tables you write. |
| 137 | + # If you do not, you will write to all tables in the collection. |
| 138 | + # This may include tables with incompatible schemas, or tables that you do not have permission to write to. |
| 139 | + if encrypted_table.table_name in dynamodb_table_names: |
| 140 | + encrypted_table.put_item(Item={ |
| 141 | + "partition_key": "PythonEncryptedTablesCollectionManagerExample", |
| 142 | + "sort_key": 0, |
| 143 | + "attribute1": "encrypt and sign me!", |
| 144 | + "attribute2": "sign me!", |
| 145 | + ":attribute3": "ignore me!", |
| 146 | + }) |
| 147 | + |
| 148 | + # 9. Read the items back from the table. |
| 149 | + # After the items are retrieved from DynamoDb, but before the EncryptedResource |
| 150 | + # returns them to the caller, they will be decrypted client-side according to our configuration. |
| 151 | + items = [] |
| 152 | + for encrypted_table in encrypted_tables: |
| 153 | + # Here, you should consider filtering the tables you read from. |
| 154 | + # If you do not, you will read from all tables in the collection. |
| 155 | + # This may include tables with incompatible schemas, or tables that you do not have permission to read from. |
| 156 | + if encrypted_table.table_name in dynamodb_table_names: |
| 157 | + get_item_response = encrypted_table.get_item(Key={ |
| 158 | + "partition_key": "PythonEncryptedTablesCollectionManagerExample", |
| 159 | + "sort_key": 0, |
| 160 | + }) |
| 161 | + |
| 162 | + item = get_item_response["Item"] |
| 163 | + items.append(item) |
| 164 | + |
| 165 | + # 10. Assert the items are as expected. |
| 166 | + for item in items: |
| 167 | + assert item["attribute1"] == "encrypt and sign me!" |
| 168 | + assert item["attribute2"] == "sign me!" |
| 169 | + assert item[":attribute3"] == "ignore me!" |
0 commit comments