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

Commit 97c60ba

Browse files
mattsb42-awsmattsb42-aws
committed
docs: add raw RSA MKP example
1 parent cbfe9b0 commit 97c60ba

File tree

2 files changed

+111
-0
lines changed

2 files changed

+111
-0
lines changed

‎examples/src/master_key_provider/raw_rsa/__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 RSA master key provider examples.
5+
6+
These examples show how to use the raw RSA master key.
7+
"""

‎examples/src/master_key_provider/raw_rsa/private_key_only_from_pem.py

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
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 example shows how to configure and use a raw RSA master key using a PEM-encoded RSA private key.
9+
10+
The most commonly used encodings for RSA keys tend to be PEM and DER.
11+
The raw RSA master key supports loading both public and private keys from PEM encoding.
12+
13+
https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#master-key-provider
14+
15+
In this example, we use the one-step encrypt and decrypt APIs.
16+
"""
17+
from cryptography.hazmat.backends import default_backend
18+
from cryptography.hazmat.primitives import serialization
19+
from cryptography.hazmat.primitives.asymmetric import rsa
20+
21+
import aws_encryption_sdk
22+
from aws_encryption_sdk.identifiers import EncryptionKeyType, WrappingAlgorithm
23+
from aws_encryption_sdk.key_providers.raw import RawMasterKey, WrappingKey
24+
25+
26+
def run(source_plaintext):
27+
# type: (bytes) -> None
28+
"""Demonstrate an encrypt/decrypt cycle using a raw RSA master key loaded from a PEM-encoded key.
29+
30+
:param bytes source_plaintext: Plaintext to encrypt
31+
"""
32+
# Prepare your encryption context.
33+
# https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/concepts.html#encryption-context
34+
encryption_context = {
35+
"encryption": "context",
36+
"is not": "secret",
37+
"but adds": "useful metadata",
38+
"that can help you": "be confident that",
39+
"the data you are handling": "is what you think it is",
40+
}
41+
42+
# Generate an RSA private key to use with your master key.
43+
# In practice, you should get this key from a secure key management system such as an HSM.
44+
#
45+
# The National Institute of Standards and Technology (NIST) recommends a minimum of 2048-bit keys for RSA.
46+
# https://www.nist.gov/publications/transitioning-use-cryptographic-algorithms-and-key-lengths
47+
#
48+
# Why did we use this public exponent?
49+
# https://crypto.stanford.edu/~dabo/pubs/papers/RSA-survey.pdf
50+
private_key = rsa.generate_private_key(public_exponent=65537, key_size=4096, backend=default_backend())
51+
52+
# Serialize the RSA private key to PEM encoding.
53+
# This or DER encoding is likely to be what you get from your key management system in practice.
54+
private_key_pem = private_key.private_bytes(
55+
encoding=serialization.Encoding.PEM,
56+
format=serialization.PrivateFormat.PKCS8,
57+
encryption_algorithm=serialization.NoEncryption(),
58+
)
59+
60+
# Create the master key that determines how your data keys are protected.
61+
#
62+
# WrappingKey can only load PEM-encoded keys.
63+
master_key = RawMasterKey(
64+
# The provider ID and key ID are defined by you
65+
# and are used by the raw RSA master key
66+
# to determine whether it should attempt to decrypt
67+
# an encrypted data key.
68+
provider_id="some managed raw keys", # provider ID corresponds to key namespace for keyrings
69+
key_id=b"my RSA wrapping key", # key ID corresponds to key name for keyrings
70+
wrapping_key=WrappingKey(
71+
wrapping_key=private_key_pem,
72+
wrapping_key_type=EncryptionKeyType.PRIVATE,
73+
# The wrapping algorithm tells the raw RSA master key
74+
# how to use your wrapping key to encrypt data keys.
75+
#
76+
# We recommend using RSA_OAEP_SHA256_MGF1.
77+
# You should not use RSA_PKCS1 unless you require it for backwards compatibility.
78+
wrapping_algorithm=WrappingAlgorithm.RSA_OAEP_SHA256_MGF1,
79+
),
80+
)
81+
82+
# Encrypt your plaintext data.
83+
ciphertext, _encrypt_header = aws_encryption_sdk.encrypt(
84+
source=source_plaintext, encryption_context=encryption_context, key_provider=master_key
85+
)
86+
87+
# Demonstrate that the ciphertext and plaintext are different.
88+
assert ciphertext != source_plaintext
89+
90+
# Decrypt your encrypted data using the same master key you used on encrypt.
91+
#
92+
# You do not need to specify the encryption context on decrypt
93+
# because the header of the encrypted message includes the encryption context.
94+
decrypted, decrypt_header = aws_encryption_sdk.decrypt(source=ciphertext, key_provider=master_key)
95+
96+
# Demonstrate that the decrypted plaintext is identical to the original plaintext.
97+
assert decrypted == source_plaintext
98+
99+
# Verify that the encryption context used in the decrypt operation includes
100+
# the encryption context that you specified when encrypting.
101+
# The AWS Encryption SDK can add pairs, so don't require an exact match.
102+
#
103+
# In production, always use a meaningful encryption context.
104+
assert set(encryption_context.items()) <= set(decrypt_header.encryption_context.items())

0 commit comments

Comments
 (0)
0