AWS Encryption SDK for Python

Warnings

• breaking Version 4.0.0 introduced significant changes, primarily with the adoption of the AWS Cryptographic Material Providers Library (MPL). Master Key Providers are deprecated in favor of Keyrings. If using the MPL's `Required Encryption Context Cryptographic Materials Manager (required EC CMM)`, encryption context handling changes and messages encrypted with it are not backward compatible with ESDK <4.0.0.
  Fix: Migrate from `MasterKeyProvider` to `Keyring` interfaces. If using `required EC CMM`, ensure all decrypting clients are also on ESDK v4.x and correctly supply the encryption context.
• breaking Python 3.7 support was dropped in version 3.3.0. Versions 3.2.0 and later require Python 3.8+. Earlier versions also dropped Python 2.x, 3.4, and 3.5 support in previous major and minor releases.
  Fix: Upgrade your Python environment to Python 3.8 or newer. For the latest `aws-cryptographic-material-providers-library` features, Python 3.11+ might be required.
• gotcha Versions of ESDK-Python prior to 4.0.1 would truncate non-ASCII key provider IDs written to message headers. This could lead to decryption failures if the original non-ASCII ID was not correctly supplied during decryption.
  Fix: Upgrade to version 4.0.1 or newer. If decrypting messages created by older versions with truncated IDs, you might need to manually supply the expected full key provider ID during decryption.
• deprecated Major versions 1 and 2 of the AWS Encryption SDK for Python are End of Support and will no longer receive security updates or bug fixes.
  Fix: Upgrade to the latest major version (4.x.x) to ensure you receive security updates and bug fixes, and to utilize current best practices.
• gotcha Using Keyrings (the recommended approach in v4.x) requires installing the `aws-cryptographic-material-providers-library` (MPL), typically done with `pip install "aws-encryption-sdk[MPL]"`. If the MPL is not installed, keyring functionality will not be available.
  Fix: Ensure `aws-encryption-sdk[MPL]` is installed if you intend to use Keyrings.
• gotcha When decrypting in strict mode with AWS KMS Keyrings, you must use a KMS key ARN to identify AWS KMS keys. Using aliases or key IDs is not supported for decryption in strict mode.
  Fix: Always provide the full AWS KMS Key ARN when configuring AWS KMS Keyrings for decryption.

Install

• pip install "aws-encryption-sdk[MPL]" Recommended with Cryptographic Material Providers Library
• pip install aws-encryption-sdk Without Cryptographic Material Providers Library

Imports

• EncryptionSDKClient

  from aws_encryption_sdk import EncryptionSDKClient

• CommitmentPolicy

  from aws_encryption_sdk import CommitmentPolicy

• AwsKmsKeyring

  from aws_cryptographic_material_providers.kms import KmsKeyring as AwsKmsKeyring

  Keyrings are now provided by the `aws-cryptographic-material-providers-library` (MPL) in v4, replacing older direct imports from `aws_encryption_sdk.keyrings`. The MPL is implicitly installed with `aws-encryption-sdk[MPL]`.
• MasterKeyProvider

  from aws_cryptographic_material_providers.kms import KmsKeyring as AwsKmsKeyring # Use Keyrings instead

  Master key providers are legacy components and have been superseded by keyrings provided by the AWS Cryptographic Material Providers Library (MPL) in v4. Migration to keyring interfaces is recommended.

Quickstart

This quickstart demonstrates how to encrypt and decrypt a simple byte string using the AWS Encryption SDK for Python with an AWS KMS Keyring. It leverages the recommended `aws-cryptographic-material-providers-library` for keyring management and sets the default `CommitmentPolicy`. Remember to replace placeholder values with your actual AWS KMS Key ARN and Account ID, and ensure your environment has appropriate AWS credentials configured.

import os
from aws_encryption_sdk import EncryptionSDKClient, CommitmentPolicy
from aws_cryptographic_material_providers.kms import KmsKeyring # from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders, CreateAwsKmsKeyringInput, AwsKmsKeyring

# NOTE: Replace with your actual KMS Key ARN and AWS Account ID
KMS_KEY_ARN = os.environ.get('AWS_KMS_KEY_ARN', 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd-1234-abcd-1234-abcd1234abcd')
AWS_ACCOUNT_ID = os.environ.get('AWS_ACCOUNT_ID', '111122223333')

# 1. Instantiate the encryption SDK client with the default commitment policy.
client = EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)

# 2. Create a KMS Keyring. In production, ensure appropriate IAM permissions.
keyring = KmsKeyring(key_ids=[KMS_KEY_ARN])

# 3. Define your plaintext and encryption context
plaintext = b"my secret data"
encryption_context = {
    "purpose": "test",
    "origin": "us-west-2"
}

# 4. Encrypt the data
ciphertext, header = client.encrypt(
    source=plaintext,
    keyring=keyring,
    encryption_context=encryption_context
)

print(f"Ciphertext: {ciphertext.hex()}")

# 5. Decrypt the data using the same keyring (or a compatible one).
# For decryption, the KMS Keyring will attempt to decrypt the data key using KMS.
decrypted_plaintext, header = client.decrypt(
    source=ciphertext,
    keyring=keyring,
    encryption_context=encryption_context # Context validated only if using MPL CMM
)

print(f"Decrypted plaintext: {decrypted_plaintext.decode()}")

# 6. Verify that the decrypted plaintext is identical to the original plaintext.
assert plaintext == decrypted_plaintext
print("Encryption and decryption successful!")