Registry / aws / aws-encryption-sdk

aws-encryption-sdk

JSON →
library4.0.6pypypi✓ verified 25d ago

The AWS Encryption SDK for Python provides a fully compliant, native Python implementation of the AWS Encryption SDK. It is a client-side encryption library designed to simplify data encryption and decryption using industry standards and best practices, employing envelope encryption. The library is actively maintained with regular patch and minor releases, typically quarterly, and less frequent major version updates.

pip install "aws-encryption-sdk[MPL]"
INSTALL
IMPORT
SIG · AWS-ENCRYPTION-SDK
A
aws-encryption-sdk
awspythonv4.0.6
Install
5.9s avg
Import
1761ms
Disk
79MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 1.814s · 70.7MB
glibc
py 3.103.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!")
Debug
Known issues
breakingVersion 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.
affects: >=4.0.0
breakingPython 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.
affects: >=3.3.0
gotchaVersions 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.
affects: <4.0.1
deprecatedMajor 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.
affects: 1.x.x, 2.x.x
gotchaUsing 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.
affects: >=4.0.0
gotchaWhen 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.
affects: All versions
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.
fix
Include 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.
fix
Ensure 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.
fix
Verify 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.
fix
Install 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.
fix
Ensure 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.
Agent activity
38 hits · last 30 days
node
30
OpenAI (training)
1
Resources
aws-encryption-sdk — pip install aws-encryption-sdk · libregistry