8000 docs: add raw AES MKP example · aws/aws-encryption-sdk-python@cbfe9b0 · GitHub
[go: up one dir, main page]
Skip to content

Commit cbfe9b0

Browse files
mattsb42-awsmattsb42-aws
committed
docs: add raw AES MKP example
1 parent cbce224 commit cbfe9b0

File tree

3 files changed

+89
-1
lines changed

3 files changed

+89
-1
lines changed

‎examples/src/keyring/raw_aes/raw_aes.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ def run(source_plaintext):
4242
# Create the keyring that determines how your data keys are protected.
4343
keyring = RawAESKeyring(
4444
# The key namespace and key name are defined by you
45-
# and are used by the raw RSA keyring
45+
# and are used by the raw AES keyring
4646
# to determine whether it should attempt to decrypt
4747
# an encrypted data key.
4848
#

‎examples/src/master_key_provider/raw_aes/__init__.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
"""
4+
Raw AES master key provider examples.
5+
6+
These examples show how to use the raw AES master key.
7+
"""

‎examples/src/master_key_provider/raw_aes/raw_aes.py

Lines changed: 81 additions & 0 deletions
8000
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
2+
# SPDX-License-Identifier: Apache-2.0
3+
"""
4+
This example is provided as a reference for users migrating away from master key providers.
5+
We recommend that all new use should use keyrings.
6+
For examples using keyrings, see the ``examples/src/keyrings`` directory.
7+
8+
This examples shows how to configure and use a raw AES master key.
9+
10+
https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#master-key-provider
11+
12+
In this example, we use the one-step encrypt and decrypt APIs.
13+
"""
14+
import os
15+
16+
import aws_encryption_sdk
17+
from aws_encryption_sdk.identifiers import EncryptionKeyType, WrappingAlgorithm
18+
from aws_encryption_sdk.key_providers.raw import RawMasterKey, WrappingKey
19+
20+
21+
def run(source_plaintext):
22+
# type: (bytes) -> None
23+
"""Demonstrate an encrypt/decrypt cycle using a raw AES master key.
24+
25+
:param bytes source_plaintext: Plaintext to encrypt
26+
"""
27+
# Prepare your encryption context.
28+
# https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
29+
encryption_context = {
30+
"encryption": "context",
31+
"is not": "secret",
32+
"but adds": "useful metadata",
33+
"that can help you": "be confident that",
34+
"the data you are handling": "is what you think it is",
35+
}
36+
37+
# Choose the wrapping algorithm for your master key to use.
38+
wrapping_algorithm = WrappingAlgorithm.AES_256_GCM_IV12_TAG16_NO_PADDING
39+
40+
# Generate an AES key to use with your master key.
41+
# The key size depends on the wrapping algorithm.
42+
#
43+
# In practice, you should get this key from a secure key management system such as an HSM.
44+
key = os.urandom(wrapping_algorithm.algorithm.kdf_input_len)
45+
46+
# Create the master key that determines how your data keys are protected.
47+
master_key = RawMasterKey(
48+
# The provider ID and key ID are defined by you
49+
# and are used by the raw AES master key
50+
# to determine whether it should attempt to decrypt
51+
# an encrypted data key.
52+
provider_id="some managed raw keys", # provider ID corresponds to key namespace for keyrings
53+
key_id=b"my AES wrapping key", # key ID corresponds to key name for keyrings
54+
wrapping_key=WrappingKey(
55+
wrapping_algorithm=wrapping_algorithm, wrapping_key_type=EncryptionKeyType.SYMMETRIC, wrapping_key=key,
56+
),
57+
)
58+
59+
# Encrypt your plaintext data.
60+
ciphertext, _encrypt_header = aws_encryption_sdk.encrypt(
61+
source=source_plaintext, encryption_context=encryption_context, key_provider=master_key
62+
)
63+
64+
# Demonstrate that the ciphertext and plaintext are different.
65+
assert ciphertext != source_plaintext
66+
67+
# Decrypt your encrypted data using the same master key you used on encrypt.
68+
#
69+
# You do not need to specify the encryption context on decrypt
70+
# because the header of the encrypted message includes the encryption context.
71+
decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, key_provider=master_key)
72+
73+
# Demonstrate that the decrypted plaintext is identical to the original plaintext.
74+
assert decrypted == source_plaintext
75+
76+
# Verify that the encryption context used in the decrypt operation includes
77+
# the encryption context that you specified when encrypting.
78+
# The AWS Encryption SDK can add pairs, so don't require an exact match.
79+
#
80+
# In production, always use a meaningful encryption context.
81+
assert set(encryption_context.items()) <= set(decrypt_header.encryption_context.items())

0 commit comments

Comments
 (0)
0