Skip to content

Commit 4fae616

Browse files
author
Lucas McDonald
committed
m
1 parent bb5e192 commit 4fae616

File tree

2 files changed

+137
-101
lines changed

2 files changed

+137
-101
lines changed

‎DynamoDbEncryption/runtimes/python/src/aws_dbesdk_dynamodb/encrypted/item.py‎

Lines changed: 109 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ def __init__(
3131
item_encryptor_config: DynamoDbItemEncryptorConfig,
3232
):
3333
"""
34-
Create an ItemEncryptor.
34+
Create an ``ItemEncryptor``.
3535
3636
Args:
3737
item_encryptor_config (DynamoDbItemEncryptorConfig): Encryption configuration object.
@@ -47,37 +47,39 @@ def encrypt_python_item(
4747
Encrypt a Python dictionary.
4848
4949
This method will transform the Python dictionary into DynamoDB JSON,
50-
encrypt the DynamoDB JSON,
51-
transform the encrypted DynamoDB JSON into an encrypted Python dictionary,
52-
then return the encrypted Python dictionary.
50+
encrypt the DynamoDB JSON,
51+
transform the encrypted DynamoDB JSON into an encrypted Python dictionary,
52+
then return the encrypted Python dictionary.
5353
5454
See the boto3 documentation for details on Python/DynamoDB type transfomations:
55+
5556
https://boto3.amazonaws.com/v1/documentation/api/latest/_modules/boto3/dynamodb/types.html
5657
5758
boto3 DynamoDB Tables and Resources expect items formatted as native Python dictionaries.
5859
Use this method to encrypt an item if you intend to pass the encrypted item
59-
to a boto3 DynamoDB Table or Resource interface to store it.
60-
(Alternatively, you can use this library's EncryptedTable or EncryptedResource interfaces
61-
to transparently encrypt items without an intermediary ItemEncryptor.)
60+
to a boto3 DynamoDB Table or Resource interface to store it.
61+
(Alternatively, you can use this library's ``EncryptedTable`` or ``EncryptedResource`` interfaces
62+
to transparently encrypt items without an intermediary ``ItemEncryptor``.)
6263
6364
Args:
6465
plaintext_dict_item (dict[str, Any]): A standard Python dictionary.
6566
6667
Returns:
6768
EncryptItemOutput: Structure containing the following fields:
68-
- `encrypted_item` (dict[str, Any]): The encrypted Python dictionary.
69-
**Note:** The item was encrypted as DynamoDB JSON, then transformed to a Python dictionary.
70-
- `parsed_header` (Optional[ParsedHeader]): The encrypted DynamoDB item's header (parsed
71-
`aws_dbe_head` value).
69+
70+
- **encrypted_item** (*dict[str, Any]*): The encrypted Python dictionary.
71+
**Note:** The item was encrypted as DynamoDB JSON, then transformed to a Python dictionary.
72+
- **parsed_header** (*Optional[ParsedHeader]*): The encrypted DynamoDB item's header
73+
(parsed ``aws_dbe_head`` value).
7274
7375
Example:
74-
>>> plaintext_item = {
75-
... 'some': 'data',
76-
... 'more': 5
77-
... }
78-
>>> encrypt_output = item_encryptor.encrypt_python_item(plaintext_item)
79-
>>> encrypted_item = encrypt_output.encrypted_item
80-
>>> header = encrypt_output.parsed_header
76+
>>> plaintext_item = {
77+
... 'some': 'data',
78+
... 'more': 5
79+
... }
80+
>>> encrypt_output = item_encryptor.encrypt_python_item(plaintext_item)
81+
>>> encrypted_item = encrypt_output.encrypted_item
82+
>>> header = encrypt_output.parsed_header
8183
8284
"""
8385
plaintext_ddb_item = dict_to_ddb(plaintext_dict_item)
@@ -93,29 +95,33 @@ def encrypt_dynamodb_item(
9395
Encrypt DynamoDB-formatted JSON.
9496
9597
boto3 DynamoDB clients expect items formatted as DynamoDB JSON:
98+
9699
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html
100+
97101
Use this method to encrypt an item if you intend to pass the encrypted item
98-
to a boto3 DynamoDB client to store it.
99-
(Alternatively, you can use this library's EncryptedClient interface
100-
to transparently encrypt items without an intermediary ItemEncryptor.)
102+
to a boto3 DynamoDB client to store it.
103+
(Alternatively, you can use this library's ``EncryptedClient`` interface
104+
to transparently encrypt items without an intermediary ``ItemEncryptor``.)
101105
102106
Args:
103107
plaintext_dynamodb_item (dict[str, dict[str, Any]]): The item to encrypt formatted as DynamoDB JSON.
104108
105109
Returns:
106110
EncryptItemOutput: Structure containing the following fields:
107-
- `encrypted_item` (dict[str, Any]): A dictionary containing the encrypted DynamoDB item
108-
formatted as DynamoDB JSON.
109-
- `parsed_header` (Optional[ParsedHeader]): The encrypted DynamoDB item's header (`aws_dbe_head` value).
111+
112+
- **encrypted_item** (*dict[str, Any]*): A dictionary containing the encrypted DynamoDB item
113+
formatted as DynamoDB JSON.
114+
- **parsed_header** (*Optional[ParsedHeader]*): The encrypted DynamoDB item's header
115+
(``aws_dbe_head`` value).
110116
111117
Example:
112-
>>> plaintext_item = {
113-
... 'some': {'S': 'data'},
114-
... 'more': {'N': '5'}
115-
... }
116-
>>> encrypt_output = item_encryptor.encrypt_dynamodb_item(plaintext_item)
117-
>>> encrypted_item = encrypt_output.encrypted_item
118-
>>> header = encrypt_output.parsed_header
118+
>>> plaintext_item = {
119+
... 'some': {'S': 'data'},
120+
... 'more': {'N': '5'}
121+
... }
122+
>>> encrypt_output = item_encryptor.encrypt_dynamodb_item(plaintext_item)
123+
>>> encrypted_item = encrypt_output.encrypted_item
124+
>>> header = encrypt_output.parsed_header
119125
120126
"""
121127
return self.encrypt_item(EncryptItemInput(plaintext_item=plaintext_dynamodb_item))
@@ -128,30 +134,33 @@ def encrypt_item(
128134
Encrypt a DynamoDB item.
129135
130136
The input item should contain a dictionary formatted as DynamoDB JSON:
137+
131138
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html
132139
133140
Args:
134141
encrypt_item_input (EncryptItemInput): Structure containing the following field:
135-
- `plaintext_item` (dict[str, Any]): The item to encrypt formatted as DynamoDB JSON.
142+
143+
- plaintext_item (dict[str, Any]): The item to encrypt formatted as DynamoDB JSON.
136144
137145
Returns:
138146
EncryptItemOutput: Structure containing the following fields:
139-
- `encrypted_item` (dict[str, Any]): The encrypted DynamoDB item formatted as DynamoDB JSON.
140-
- `parsed_header` (Optional[ParsedHeader]): The encrypted DynamoDB item's header
141-
(`aws_dbe_head` value).
147+
148+
- **encrypted_item** (*dict[str, Any]*): The encrypted DynamoDB item formatted as DynamoDB JSON.
149+
- **parsed_header** (*Optional[ParsedHeader]*): The encrypted DynamoDB item's header
150+
(``aws_dbe_head`` value).
142151
143152
Example:
144-
>>> plaintext_item = {
145-
... 'some': {'S': 'data'},
146-
... 'more': {'N': '5'}
147-
... }
148-
>>> encrypt_output = item_encryptor.encrypt_item(
149-
... EncryptItemInput(
150-
... plaintext_ddb_item = plaintext_item
151-
... )
152-
... )
153-
>>> encrypted_item = encrypt_output.encrypted_item
154-
>>> header = encrypt_output.parsed_header
153+
>>> plaintext_item = {
154+
... 'some': {'S': 'data'},
155+
... 'more': {'N': '5'}
156+
... }
157+
>>> encrypt_output = item_encryptor.encrypt_item(
158+
... EncryptItemInput(
159+
... plaintext_ddb_item = plaintext_item
160+
... )
161+
... )
162+
>>> encrypted_item = encrypt_output.encrypted_item
163+
>>> header = encrypt_output.parsed_header
155164
156165
"""
157166
return self._internal_client.encrypt_item(encrypt_item_input)
@@ -164,37 +173,39 @@ def decrypt_python_item(
164173
Decrypt a Python dictionary.
165174
166175
This method will transform the Python dictionary into DynamoDB JSON,
167-
decrypt the DynamoDB JSON,
168-
transform the plaintext DynamoDB JSON into a plaintext Python dictionary,
169-
then return the plaintext Python dictionary.
176+
decrypt the DynamoDB JSON,
177+
transform the plaintext DynamoDB JSON into a plaintext Python dictionary,
178+
then return the plaintext Python dictionary.
170179
171180
See the boto3 documentation for details on Python/DynamoDB type transfomations:
181+
172182
https://boto3.amazonaws.com/v1/documentation/api/latest/_modules/boto3/dynamodb/types.html
173183
174184
boto3 DynamoDB Tables and Resources return items formatted as native Python dictionaries.
175185
Use this method to decrypt an item if you retrieve the encrypted item
176-
from a boto3 DynamoDB Table or Resource interface.
177-
(Alternatively, you can use this library's EncryptedTable or EncryptedResource interfaces
178-
to transparently decrypt items without an intermediary ItemEncryptor.)
186+
from a boto3 DynamoDB Table or Resource interface.
187+
(Alternatively, you can use this library's ``EncryptedTable`` or ``EncryptedResource`` interfaces
188+
to transparently decrypt items without an intermediary ``ItemEncryptor``.)
179189
180190
Args:
181191
encrypted_dict_item (dict[str, Any]): A standard Python dictionary with encrypted values.
182192
183193
Returns:
184194
DecryptItemOutput: Structure containing the following fields:
185-
- `plaintext_item` (dict[str, Any]): The decrypted Python dictionary.
186-
**Note:** The item was decrypted as DynamoDB JSON, then transformed to a Python dictionary.
187-
- `parsed_header` (Optional[ParsedHeader]): The encrypted DynamoDB item's header
188-
(parsed `aws_dbe_head` value).
195+
196+
- **plaintext_item** (*dict[str, Any]*): The decrypted Python dictionary.
197+
**Note:** The item was decrypted as DynamoDB JSON, then transformed to a Python dictionary.
198+
- **parsed_header** (*Optional[ParsedHeader]*): The encrypted DynamoDB item's header
199+
(parsed ``aws_dbe_head`` value).
189200
190201
Example:
191-
>>> encrypted_item = {
192-
... 'some': b'ENCRYPTED_DATA',
193-
... 'more': b'ENCRYPTED_DATA',
194-
... }
195-
>>> decrypt_output = item_encryptor.decrypt_python_item(encrypted_item)
196-
>>> plaintext_item = decrypt_output.plaintext_item
197-
>>> header = decrypt_output.parsed_header
202+
>>> encrypted_item = {
203+
... 'some': b'ENCRYPTED_DATA',
204+
... 'more': b'ENCRYPTED_DATA',
205+
... }
206+
>>> decrypt_output = item_encryptor.decrypt_python_item(encrypted_item)
207+
>>> plaintext_item = decrypt_output.plaintext_item
208+
>>> header = decrypt_output.parsed_header
198209
199210
"""
200211
encrypted_ddb_item = dict_to_ddb(encrypted_dict_item)
@@ -210,28 +221,32 @@ def decrypt_dynamodb_item(
210221
Decrypt DynamoDB-formatted JSON.
211222
212223
boto3 DynamoDB clients return items formatted as DynamoDB JSON:
224+
213225
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html
226+
214227
Use this method to decrypt an item if you retrieved the encrypted item
215-
from a boto3 DynamoDB client.
216-
(Alternatively, you can use this library's EncryptedClient interface
217-
to transparently decrypt items without an intermediary ItemEncryptor.)
228+
from a boto3 DynamoDB client.
229+
(Alternatively, you can use this library's ``EncryptedClient`` interface
230+
to transparently decrypt items without an intermediary ``ItemEncryptor``.)
218231
219232
Args:
220233
encrypted_dynamodb_item (dict[str, dict[str, Any]]): The item to decrypt formatted as DynamoDB JSON.
221234
222235
Returns:
223236
DecryptItemOutput: Structure containing the following fields:
224-
- `plaintext_item` (dict[str, Any]): The plaintext DynamoDB item formatted as DynamoDB JSON.
225-
- `parsed_header` (Optional[ParsedHeader]): The decrypted DynamoDB item's header (`aws_dbe_head` value).
237+
238+
- **plaintext_item** (*dict[str, Any]*): The plaintext DynamoDB item formatted as DynamoDB JSON.
239+
- **parsed_header** (*Optional[ParsedHeader]*): The decrypted DynamoDB item's header
240+
(``aws_dbe_head`` value).
226241
227242
Example:
228-
>>> encrypted_item = {
229-
... 'some': {'B': b'ENCRYPTED_DATA'},
230-
... 'more': {'B': b'ENCRYPTED_DATA'}
231-
... }
232-
>>> decrypt_output = item_encryptor.decrypt_dynamodb_item(encrypted_item)
233-
>>> plaintext_item = decrypt_output.plaintext_item
234-
>>> header = decrypt_output.parsed_header
243+
>>> encrypted_item = {
244+
... 'some': {'B': b'ENCRYPTED_DATA'},
245+
... 'more': {'B': b'ENCRYPTED_DATA'}
246+
... }
247+
>>> decrypt_output = item_encryptor.decrypt_dynamodb_item(encrypted_item)
248+
>>> plaintext_item = decrypt_output.plaintext_item
249+
>>> header = decrypt_output.parsed_header
235250
236251
"""
237252
return self.decrypt_item(DecryptItemInput(encrypted_item=encrypted_dynamodb_item))
@@ -244,29 +259,33 @@ def decrypt_item(
244259
Decrypt a DynamoDB item.
245260
246261
The input item should contain a dictionary formatted as DynamoDB JSON:
262+
247263
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html
248264
249265
Args:
250-
decrypt_item_input (DecryptItemInput): Structure containing the following field:
251-
- `encrypted_item` (dict[str, Any]): The item to decrypt formatted as DynamoDB JSON.
266+
decrypt_item_input (DecryptItemInput): Structure containing the following fields:
267+
268+
- **encrypted_item** (*dict[str, Any]*): The item to decrypt formatted as DynamoDB JSON.
252269
253270
Returns:
254271
DecryptItemOutput: Structure containing the following fields:
255-
- `plaintext_item` (dict[str, Any]): The decrypted DynamoDB item formatted as DynamoDB JSON.
256-
- `parsed_header` (Optional[ParsedHeader]): The decrypted DynamoDB item's header (`aws_dbe_head` value).
272+
273+
- **plaintext_item** (*dict[str, Any]*): The decrypted DynamoDB item formatted as DynamoDB JSON.
274+
- **parsed_header** (*Optional[ParsedHeader]*): The decrypted DynamoDB item's header
275+
(``aws_dbe_head`` value).
257276
258277
Example:
259-
>>> encrypted_item = {
260-
... 'some': {'B': b'ENCRYPTED_DATA'},
261-
... 'more': {'B': b'ENCRYPTED_DATA'}
262-
... }
263-
>>> decrypted_item = item_encryptor.decrypt_item(
264-
... DecryptItemInput(
265-
... encrypted_item = encrypted_item,
266-
... )
267-
... )
268-
>>> plaintext_item = decrypted_item.plaintext_item
269-
>>> header = decrypted_item.parsed_header
278+
>>> encrypted_item = {
279+
... 'some': {'B': b'ENCRYPTED_DATA'},
280+
... 'more': {'B': b'ENCRYPTED_DATA'}
281+
... }
282+
>>> decrypted_item = item_encryptor.decrypt_item(
283+
... DecryptItemInput(
284+
... encrypted_item = encrypted_item,
285+
... )
286+
... )
287+
>>> plaintext_item = decrypted_item.plaintext_item
288+
>>> header = decrypted_item.parsed_header
270289
271290
"""
272291
return self._internal_client.decrypt_item(decrypt_item_input)

0 commit comments

Comments
 (0)