Install & Compatibility
Where this runs
tested against v4.0.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 1.814s · 70.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.9s · import 1.707s · 71MB
79MB installed
● package 79MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✗ from aws_encryption_sdk.keyrings.aws_kms import 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
✗ from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider
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.
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!")
Errors
Common errors & fixes
Unable to import module 'lambdaMain': libffi-d78936b1.so.6.0.4: cannot open shared object file: No such file or directory
This error occurs when deploying an AWS Lambda function that uses the AWS Encryption SDK, which depends on native libraries not included in the Lambda environment.
fixInclude the required native libraries in your deployment package by building the package in an environment similar to Lambda's Amazon Linux and ensuring all dependencies are bundled.
Configuration conflict: Commitment policy and algorithm suite
This error arises when the specified algorithm suite conflicts with the commitment policy set in the AWS Encryption SDK.
fixEnsure that the algorithm suite selected is compatible with the commitment policy; for example, use an algorithm suite with key commitment when the commitment policy requires it.
Key commitment validation failed
This error indicates that during decryption, the data key in the encrypted message does not match the expected unique data key, possibly due to data corruption or tampering.
fixVerify the integrity of the encrypted message and ensure it was generated by the AWS Encryption SDK without modification.
ImportError: No module named 'aws_encryption_sdk'
This error occurs when the AWS Encryption SDK is not installed or not available in the Python environment.
fixInstall the AWS Encryption SDK using pip: `pip install aws-encryption-sdk`.
AttributeError: module 'aws_encryption_sdk' has no attribute 'encrypt'
This error occurs when attempting to call a method that does not exist in the AWS Encryption SDK module, possibly due to a version mismatch or incorrect usage.
fixEnsure you are using the correct method names as per the AWS Encryption SDK documentation and that your SDK version supports the methods you are calling.
Upgrade
Version history
4.0.6latest on PyPI · released May 7, 2026
Audit
Dependencies
aws-cryptographic-material-providers-libraryoptionalHighly recommended optional dependency for using keyrings and newer cryptographic constructs introduced in v4.0.0. Required for Python 3.11+ for its own installation.
cryptographyrequiredRequired prerequisite for all platforms.
boto3requiredRequired prerequisite, especially for AWS KMS integration.