|
| 1 | +# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. |
| 2 | +# SPDX-License-Identifier: Apache-2.0 |
| 3 | +""" |
| 4 | +This example sets up an EncryptedClient wrapper for the AWS SDK client |
| 5 | +and uses the PutItem and GetItem DDB APIs to demonstrate |
| 6 | +putting a client-side encrypted item into DynamoDb |
| 7 | +and then retrieving and decrypting that item from DynamoDb. |
| 8 | +
|
| 9 | +Running this example requires access to the DDB Table whose name |
| 10 | +is provided in the function arguments. |
| 11 | +This table must be configured with the following |
| 12 | +primary key configuration: |
| 13 | +- Partition key is named "partition_key" with type (S) |
| 14 | +- Sort key is named "sort_key" with type (N) |
| 15 | +
|
| 16 | +This example also requires access to the KMS key ARN with permissions: (TODO) |
| 17 | +""" |
1 | 18 | import boto3 |
2 | 19 | from boto3.dynamodb.types import Binary |
3 | 20 | from decimal import Decimal |
|
13 | 30 | from aws_database_encryption_sdk.smithygenerated.aws_cryptography_dbencryptionsdk_structuredencryption.models import ( |
14 | 31 | CryptoAction, |
15 | 32 | ) |
16 | | - |
17 | | -mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( |
18 | | - config=MaterialProvidersConfig() |
19 | | -) |
20 | | - |
21 | | -kms_key_id = "arn:aws:kms:us-west-2:658956600833:key/b3537ef1-d8dc-4780-9f5a-55776cbb2f7f" |
22 | | -mrk_key_id = "arn:aws:kms:us-west-2:658956600833:key/mrk-80bd8ecdcd4342aebd84b7dc9da498a7" |
23 | | - |
24 | | -kms_mrk_multi_keyring_input: CreateAwsKmsMrkMultiKeyringInput =\ |
25 | | - CreateAwsKmsMrkMultiKeyringInput( |
26 | | - generator=mrk_key_id, |
27 | | - kms_key_ids=[kms_key_id] |
28 | | - ) |
29 | | - |
30 | | -kms_mrk_multi_keyring: IKeyring = mat_prov.create_aws_kms_mrk_multi_keyring( |
31 | | - input=kms_mrk_multi_keyring_input |
32 | | -) |
33 | | - |
34 | | -attribute_actions_on_encrypt = { |
35 | | - "partition_key": CryptoAction.SIGN_ONLY, |
36 | | - "sort_key": CryptoAction.SIGN_ONLY, |
37 | | - "attribute1": CryptoAction.ENCRYPT_AND_SIGN, |
38 | | - "attribute2": CryptoAction.SIGN_ONLY, |
39 | | - ":attribute3": CryptoAction.DO_NOTHING, |
40 | | -} |
41 | | - |
42 | | -# 2. Create encryption context. |
43 | | -# Remember that your encryption context is NOT SECRET. |
44 | | -# For more information, see |
45 | | -# https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context |
46 | | -encryption_context = { |
47 | | - "encryption": "context", |
48 | | - "is not": "secret", |
49 | | - "but adds": "useful metadata", |
50 | | - "that can help you": "be confident that", |
51 | | - "the data you are handling": "is what you think it is", |
52 | | -} |
53 | | - |
54 | | -unsignAttrPrefix: str = ":" |
55 | | - |
56 | 33 | from aws_database_encryption_sdk.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb.models import ( |
57 | 34 | DynamoDbTableEncryptionConfig, |
58 | 35 | DynamoDbTablesEncryptionConfig, |
59 | 36 | ) |
60 | | - |
61 | | -ddb_table_name = "DynamoDbEncryptionInterceptorTestTable" |
62 | | - |
63 | | -table_configs = {} |
64 | | - |
65 | | -table_config = DynamoDbTableEncryptionConfig( |
66 | | - logical_table_name = ddb_table_name, |
67 | | - partition_key_name = "partition_key", |
68 | | - sort_key_name = "sort_key", |
69 | | - attribute_actions_on_encrypt = attribute_actions_on_encrypt, |
70 | | - keyring = kms_mrk_multi_keyring, |
71 | | - allowed_unsigned_attribute_prefix = unsignAttrPrefix, |
72 | | - algorithm_suite_id = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384, |
73 | | -) |
74 | | - |
75 | | -table_configs[ddb_table_name] = table_config |
76 | | - |
77 | | -tables_config = DynamoDbTablesEncryptionConfig( |
78 | | - table_encryption_configs = table_configs |
79 | | -) |
80 | | - |
81 | 37 | from aws_database_encryption_sdk.smithygenerated.aws_cryptography_dbencryptionsdk_dynamodb_transforms.models import ( |
82 | 38 | GetItemOutputTransformInput, |
83 | 39 | PutItemInputTransformInput |
84 | 40 | ) |
85 | | - |
86 | | -# "Main" |
87 | | - |
88 | 41 | from aws_database_encryption_sdk.encryptor.client import ( |
89 | 42 | EncryptedClient |
90 | 43 | ) |
91 | 44 |
|
92 | | -item_to_encrypt = { |
93 | | - "partition_key": "LucasPythonTesting", |
94 | | - "sort_key": 1234, |
95 | | - "attribute1": "abc" |
96 | | -} |
97 | | - |
98 | | -encrypted_client = EncryptedClient( |
99 | | - client = boto3.client("dynamodb"), |
100 | | - encryption_config = tables_config, |
101 | | - expect_standard_dictionaries = True, |
102 | | -) |
103 | | - |
104 | | -put_item = { |
105 | | - "TableName": ddb_table_name, |
106 | | - "Item": item_to_encrypt, |
107 | | -} |
108 | | - |
109 | | -put_item_output = encrypted_client.put_item(**put_item) |
110 | | - |
111 | | -item_to_get = { |
112 | | - "partition_key": "LucasPythonTesting", |
113 | | - "sort_key": 1234, |
114 | | -} |
| 45 | +def encrypted_client_put_get_example( |
| 46 | + kms_key_id: str, |
| 47 | + dynamodb_table_name: str, |
| 48 | +): |
| 49 | + # 1. Create a Keyring. This Keyring will be responsible for protecting the data keys that protect your data. |
| 50 | + # For this example, we will create a AWS KMS Keyring with the AWS KMS Key we want to use. |
| 51 | + # We will use the `CreateMrkMultiKeyring` method to create this keyring, |
| 52 | + # as it will correctly handle both single region and Multi-Region KMS Keys. |
| 53 | + mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( |
| 54 | + config=MaterialProvidersConfig() |
| 55 | + ) |
| 56 | + kms_mrk_multi_keyring_input: CreateAwsKmsMrkMultiKeyringInput =\ |
| 57 | + CreateAwsKmsMrkMultiKeyringInput( |
| 58 | + generator=kms_key_id, |
| 59 | + ) |
| 60 | + kms_mrk_multi_keyring: IKeyring = mat_prov.create_aws_kms_mrk_multi_keyring( |
| 61 | + input=kms_mrk_multi_keyring_input |
| 62 | + ) |
115 | 63 |
|
116 | | -get_item = { |
117 | | - "TableName": ddb_table_name, |
118 | | - "Key": item_to_get |
119 | | -} |
| 64 | + # 2. Configure which attributes are encrypted and/or signed when writing new items. |
| 65 | + # For each attribute that may exist on the items we plan to write to our DynamoDbTable, |
| 66 | + # we must explicitly configure how they should be treated during item encryption: |
| 67 | + # - ENCRYPT_AND_SIGN: The attribute is encrypted and included in the signature |
| 68 | + # - SIGN_ONLY: The attribute not encrypted, but is still included in the signature |
| 69 | + # - DO_NOTHING: The attribute is not encrypted and not included in the signature |
| 70 | + attribute_actions_on_encrypt = { |
| 71 | + "partition_key": CryptoAction.SIGN_ONLY, |
| 72 | + "sort_key": CryptoAction.SIGN_ONLY, |
| 73 | + "attribute1": CryptoAction.ENCRYPT_AND_SIGN, |
| 74 | + "attribute2": CryptoAction.SIGN_ONLY, |
| 75 | + ":attribute3": CryptoAction.DO_NOTHING, |
| 76 | + } |
| 77 | + |
| 78 | + # 3. Configure which attributes we expect to be included in the signature |
| 79 | + # when reading items. There are two options for configuring this: |
| 80 | + # |
| 81 | + # - (Recommended) Configure `allowedUnsignedAttributesPrefix`: |
| 82 | + # When defining your DynamoDb schema and deciding on attribute names, |
| 83 | + # choose a distinguishing prefix (such as ":") for all attributes that |
| 84 | + # you do not want to include in the signature. |
| 85 | + # This has two main benefits: |
| 86 | + # - It is easier to reason about the security and authenticity of data within your item |
| 87 | + # when all unauthenticated data is easily distinguishable by their attribute name. |
| 88 | + # - If you need to add new unauthenticated attributes in the future, |
| 89 | + # you can easily make the corresponding update to your `attributeActionsOnEncrypt` |
| 90 | + # and immediately start writing to that new attribute, without |
| 91 | + # any other configuration update needed. |
| 92 | + # Once you configure this field, it is not safe to update it. |
| 93 | + # |
| 94 | + # - Configure `allowedUnsignedAttributes`: You may also explicitly list |
| 95 | + # a set of attributes that should be considered unauthenticated when encountered |
| 96 | + # on read. Be careful if you use this configuration. Do not remove an attribute |
| 97 | + # name from this configuration, even if you are no longer writing with that attribute, |
| 98 | + # as old items may still include this attribute, and our configuration needs to know |
| 99 | + # to continue to exclude this attribute from the signature scope. |
| 100 | + # If you add new attribute names to this field, you must first deploy the update to this |
| 101 | + # field to all readers in your host fleet before deploying the update to start writing |
| 102 | + # with that new attribute. |
| 103 | + # |
| 104 | + # For this example, we have designed our DynamoDb table such that any attribute name with |
| 105 | + # the ":" prefix should be considered unauthenticated. |
| 106 | + unsignAttrPrefix: str = ":" |
| 107 | + |
| 108 | + # 4. Create the DynamoDb Encryption configuration for the table we will be writing to. |
| 109 | + table_configs = {} |
| 110 | + table_config = DynamoDbTableEncryptionConfig( |
| 111 | + logical_table_name = dynamodb_table_name, |
| 112 | + partition_key_name = "partition_key", |
| 113 | + sort_key_name = "sort_key", |
| 114 | + attribute_actions_on_encrypt = attribute_actions_on_encrypt, |
| 115 | + keyring = kms_mrk_multi_keyring, |
| 116 | + allowed_unsigned_attribute_prefix = unsignAttrPrefix, |
| 117 | + algorithm_suite_id = DBEAlgorithmSuiteId.ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY_ECDSA_P384_SYMSIG_HMAC_SHA384, |
| 118 | + ) |
| 119 | + table_configs[dynamodb_table_name] = table_config |
| 120 | + tables_config = DynamoDbTablesEncryptionConfig( |
| 121 | + table_encryption_configs = table_configs |
| 122 | + ) |
120 | 123 |
|
121 | | -get_item_output = encrypted_client.get_item(**get_item) |
| 124 | + # 5. Create a new AWS SDK DynamoDb client using the TableEncryptionConfigs |
| 125 | + encrypted_client = EncryptedClient( |
| 126 | + client = boto3.client("dynamodb"), |
| 127 | + encryption_config = tables_config, |
| 128 | + expect_standard_dictionaries = True, |
| 129 | + ) |
122 | 130 |
|
123 | | -assert get_item_output["Item"] == item_to_encrypt |
| 131 | + # 6. Put an item into our table using the above client. |
| 132 | + # Before the item gets sent to DynamoDb, it will be encrypted |
| 133 | + # client-side, according to our configuration. |
| 134 | + item_to_encrypt = { |
| 135 | + "partition_key": "BasicPutGetExample", |
| 136 | + "sort_key": 0, |
| 137 | + "attribute1": "encrypt and sign me!", |
| 138 | + "attribute2": "sign me!", |
| 139 | + ":attribute3": "ignore me!", |
| 140 | + } |
| 141 | + |
| 142 | + put_item_request = { |
| 143 | + "TableName": dynamodb_table_name, |
| 144 | + "Item": item_to_encrypt, |
| 145 | + } |
| 146 | + |
| 147 | + put_item_response = encrypted_client.put_item(**put_item_request) |
| 148 | + |
| 149 | + # Demonstrate that PutItem succeeded |
| 150 | + assert put_item_response["ResponseMetadata"]["HTTPStatusCode"] == 200 |
| 151 | + |
| 152 | + # 7. Get the item back from our table using the same client. |
| 153 | + # The client will decrypt the item client-side, and return |
| 154 | + # back the original item. |
| 155 | + key_to_get = { |
| 156 | + "partition_key": "BasicPutGetExample", |
| 157 | + "sort_key": 0, |
| 158 | + } |
| 159 | + |
| 160 | + get_item_request = { |
| 161 | + "TableName": dynamodb_table_name, |
| 162 | + "Key": key_to_get |
| 163 | + } |
| 164 | + |
| 165 | + get_item_response = encrypted_client.get_item(**get_item_request) |
| 166 | + |
| 167 | + # Demonstrate that GetItem succeeded |
| 168 | + assert get_item_response["ResponseMetadata"]["HTTPStatusCode"] == 200 |
| 169 | + assert get_item_response["Item"] == item_to_encrypt |
| 170 | + assert get_item_response["Item"]["attribute1"] == "encrypt and sign me!" |
0 commit comments