AWS Encryption SDK for Python example code
The following examples show you how to use the AWS Encryption SDK for Python to encrypt and decrypt data.
The examples in this section show how to use version 4.x of the
AWS Encryption SDK for Python with the optional Cryptographic Material Providers
Library
When you use version 4.x of the AWS Encryption SDK for Python with the MPL, it uses
keyrings to perform envelope encryption. The AWS Encryption SDK provides keyrings that are compatible with the master key
providers that you used in previous versions. For more information, see Keyring compatibility. For examples on migrating from master key providers to
keyrings, see Migration Examplesaws-encryption-sdk-python repository on GitHub;
Topics
Encrypting and decrypting strings
The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt strings. This example uses an AWS KMS keyring with a symmetric encryption KMS key.
This example instantiates the AWS Encryption SDK client with the default commitment policy,
REQUIRE_ENCRYPT_REQUIRE_DECRYPT. For more information, see Setting your commitment policy.
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example sets up the KMS Keyring The AWS KMS keyring uses symmetric encryption KMS keys to generate, encrypt and decrypt data keys. This example creates a KMS Keyring and then encrypts a custom input EXAMPLE_DATA with an encryption context. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. AWS KMS keyrings can be used independently or in a multi-keyring with other keyrings of the same or a different type. """ import boto3 from aws_cryptographic_materialproviders.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_materialproviders.mpl.config import MaterialProvidersConfig from aws_cryptographic_materialproviders.mpl.models import CreateAwsKmsKeyringInput from aws_cryptographic_materialproviders.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy EXAMPLE_DATA: bytes = b"Hello World" def encrypt_and_decrypt_with_keyring( kms_key_id: str ): """Demonstrate an encrypt/decrypt cycle using an AWS KMS keyring. Usage: encrypt_and_decrypt_with_keyring(kms_key_id) :param kms_key_id: KMS Key identifier for the KMS key you want to use for encryption and decryption of your data keys. :type kms_key_id: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. Create a boto3 client for KMS. kms_client = boto3.client('kms', region_name="us-west-2") # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "encryption": "context", "is not": "secret", "but adds": "useful metadata", "that can help you": "be confident that", "the data you are handling": "is what you think it is", } # 4. Create your keyring mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateAwsKmsKeyringInput = CreateAwsKmsKeyringInput( kms_key_id=kms_key_id, kms_client=kms_client ) kms_keyring: IKeyring = mat_prov.create_aws_kms_keyring( input=keyring_input ) # 5. Encrypt the data with the encryptionContext. ciphertext, _ = client.encrypt( source=EXAMPLE_DATA, keyring=kms_keyring, encryption_context=encryption_context ) # 6. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert ciphertext != EXAMPLE_DATA, \ "Ciphertext and plaintext data are the same. Invalid encryption" # 7. Decrypt your encrypted data using the same keyring you used on encrypt. plaintext_bytes, _ = client.decrypt( source=ciphertext, keyring=kms_keyring, # Provide the encryption context that was supplied to the encrypt method encryption_context=encryption_context, ) # 8. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert plaintext_bytes == EXAMPLE_DATA, \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
Encrypting and decrypting byte streams
The following example shows you how to use the AWS Encryption SDK to encrypt and decrypt byte streams. This example uses a Raw AES keyring.
This example instantiates the AWS Encryption SDK client with the default commitment policy,
REQUIRE_ENCRYPT_REQUIRE_DECRYPT. For more information, see Setting your commitment policy.
# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 """ This example demonstrates file streaming for encryption and decryption. File streaming is useful when the plaintext or ciphertext file/data is too large to load into memory. Therefore, the AWS Encryption SDK allows users to stream the data, instead of loading it all at once in memory. In this example, we demonstrate file streaming for encryption and decryption using a Raw AES keyring. However, you can use any keyring with streaming. This example creates a Raw AES Keyring and then encrypts an input stream from the file `plaintext_filename` with an encryption context to an output (encrypted) file `ciphertext_filename`. It then decrypts the ciphertext from `ciphertext_filename` to a new file `decrypted_filename`. This example also includes some sanity checks for demonstration: 1. Ciphertext and plaintext data are not the same 2. Encryption context is correct in the decrypted message header 3. Decrypted plaintext value matches EXAMPLE_DATA These sanity checks are for demonstration in the example only. You do not need these in your code. See raw_aes_keyring_example.py in the same directory for another raw AES keyring example in the AWS Encryption SDK for Python. """ import filecmp import secrets from aws_cryptographic_materialproviders.mpl import AwsCryptographicMaterialProviders from aws_cryptographic_materialproviders.mpl.config import MaterialProvidersConfig from aws_cryptographic_materialproviders.mpl.models import AesWrappingAlg, CreateRawAesKeyringInput from aws_cryptographic_materialproviders.mpl.references import IKeyring from typing import Dict # noqa pylint: disable=wrong-import-order import aws_encryption_sdk from aws_encryption_sdk import CommitmentPolicy def encrypt_and_decrypt_with_keyring( plaintext_filename: str, ciphertext_filename: str, decrypted_filename: str ): """Demonstrate a streaming encrypt/decrypt cycle. Usage: encrypt_and_decrypt_with_keyring(plaintext_filename ciphertext_filename decrypted_filename) :param plaintext_filename: filename of the plaintext data :type plaintext_filename: string :param ciphertext_filename: filename of the ciphertext data :type ciphertext_filename: string :param decrypted_filename: filename of the decrypted data :type decrypted_filename: string """ # 1. Instantiate the encryption SDK client. # This builds the client with the REQUIRE_ENCRYPT_REQUIRE_DECRYPT commitment policy, # which enforces that this client only encrypts using committing algorithm suites and enforces # that this client will only decrypt encrypted messages that were created with a committing # algorithm suite. # This is the default commitment policy if you were to build the client as # `client = aws_encryption_sdk.EncryptionSDKClient()`. client = aws_encryption_sdk.EncryptionSDKClient( commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT ) # 2. The key namespace and key name are defined by you. # and are used by the Raw AES keyring to determine # whether it should attempt to decrypt an encrypted data key. key_name_space = "Some managed raw keys" key_name = "My 256-bit AES wrapping key" # 3. Optional: create encryption context. # Remember that your encryption context is NOT SECRET. encryption_context: Dict[str, str] = { "encryption": "context", "is not": "secret", "but adds": "useful metadata", "that can help you": "be confident that", "the data you are handling": "is what you think it is", } # 4. Generate a 256-bit AES key to use with your keyring. # In practice, you should get this key from a secure key management system such as an HSM. # Here, the input to secrets.token_bytes() = 32 bytes = 256 bits static_key = secrets.token_bytes(32) # 5. Create a Raw AES keyring # We choose to use a raw AES keyring, but any keyring can be used with streaming. mat_prov: AwsCryptographicMaterialProviders = AwsCryptographicMaterialProviders( config=MaterialProvidersConfig() ) keyring_input: CreateRawAesKeyringInput = CreateRawAesKeyringInput( key_namespace=key_name_space, key_name=key_name, wrapping_key=static_key, wrapping_alg=AesWrappingAlg.ALG_AES256_GCM_IV12_TAG16 ) raw_aes_keyring: IKeyring = mat_prov.create_raw_aes_keyring( input=keyring_input ) # 6. Encrypt the data stream with the encryptionContext with open(plaintext_filename, 'rb') as pt_file, open(ciphertext_filename, 'wb') as ct_file: with client.stream( mode='e', source=pt_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as encryptor: for chunk in encryptor: ct_file.write(chunk) # 7. Demonstrate that the ciphertext and plaintext are different. # (This is an example for demonstration; you do not need to do this in your own code.) assert not filecmp.cmp(plaintext_filename, ciphertext_filename), \ "Ciphertext and plaintext data are the same. Invalid encryption" # 8. Decrypt your encrypted data stream using the same keyring you used on encrypt. with open(ciphertext_filename, 'rb') as ct_file, open(decrypted_filename, 'wb') as pt_file: with client.stream( mode='d', source=ct_file, keyring=raw_aes_keyring, encryption_context=encryption_context ) as decryptor: for chunk in decryptor: pt_file.write(chunk) # 10. Demonstrate that the decrypted plaintext is identical to the original plaintext. # (This is an example for demonstration; you do not need to do this in your own code.) assert filecmp.cmp(plaintext_filename, decrypted_filename), \ "Decrypted plaintext should be identical to the original plaintext. Invalid decryption"
