{"id":2396,"library":"aws-encryption-sdk","title":"AWS Encryption SDK for Python","description":"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.","status":"active","version":"4.0.4","language":"python","source_language":"en","source_url":"https://github.com/aws/aws-encryption-sdk-python","tags":["aws","encryption","cryptography","security","kms"],"install":[{"cmd":"pip install \"aws-encryption-sdk[MPL]\"","lang":"bash","label":"Recommended with Cryptographic Material Providers Library"},{"cmd":"pip install aws-encryption-sdk","lang":"bash","label":"Without Cryptographic Material Providers Library"}],"dependencies":[{"reason":"Highly recommended optional dependency for using keyrings and newer cryptographic constructs introduced in v4.0.0. Required for Python 3.11+ for its own installation.","package":"aws-cryptographic-material-providers-library","optional":true},{"reason":"Required prerequisite for all platforms.","package":"cryptography"},{"reason":"Required prerequisite, especially for AWS KMS integration.","package":"boto3"}],"imports":[{"symbol":"EncryptionSDKClient","correct":"from aws_encryption_sdk import EncryptionSDKClient"},{"symbol":"CommitmentPolicy","correct":"from aws_encryption_sdk import CommitmentPolicy"},{"note":"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]`.","wrong":"from aws_encryption_sdk.keyrings.aws_kms import AwsKmsKeyring","symbol":"AwsKmsKeyring","correct":"from aws_cryptographic_material_providers.kms import KmsKeyring as AwsKmsKeyring"},{"note":"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.","wrong":"from aws_encryption_sdk.key_providers.kms import KMSMasterKeyProvider","symbol":"MasterKeyProvider","correct":"from aws_cryptographic_material_providers.kms import KmsKeyring as AwsKmsKeyring # Use Keyrings instead"}],"quickstart":{"code":"import os\nfrom aws_encryption_sdk import EncryptionSDKClient, CommitmentPolicy\nfrom aws_cryptographic_material_providers.kms import KmsKeyring # from aws_cryptographic_material_providers.mpl import AwsCryptographicMaterialProviders, CreateAwsKmsKeyringInput, AwsKmsKeyring\n\n# NOTE: Replace with your actual KMS Key ARN and AWS Account ID\nKMS_KEY_ARN = os.environ.get('AWS_KMS_KEY_ARN', 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd-1234-abcd-1234-abcd1234abcd')\nAWS_ACCOUNT_ID = os.environ.get('AWS_ACCOUNT_ID', '111122223333')\n\n# 1. Instantiate the encryption SDK client with the default commitment policy.\nclient = EncryptionSDKClient(commitment_policy=CommitmentPolicy.REQUIRE_ENCRYPT_REQUIRE_DECRYPT)\n\n# 2. Create a KMS Keyring. In production, ensure appropriate IAM permissions.\nkeyring = KmsKeyring(key_ids=[KMS_KEY_ARN])\n\n# 3. Define your plaintext and encryption context\nplaintext = b\"my secret data\"\nencryption_context = {\n    \"purpose\": \"test\",\n    \"origin\": \"us-west-2\"\n}\n\n# 4. Encrypt the data\nciphertext, header = client.encrypt(\n    source=plaintext,\n    keyring=keyring,\n    encryption_context=encryption_context\n)\n\nprint(f\"Ciphertext: {ciphertext.hex()}\")\n\n# 5. Decrypt the data using the same keyring (or a compatible one).\n# For decryption, the KMS Keyring will attempt to decrypt the data key using KMS.\ndecrypted_plaintext, header = client.decrypt(\n    source=ciphertext,\n    keyring=keyring,\n    encryption_context=encryption_context # Context validated only if using MPL CMM\n)\n\nprint(f\"Decrypted plaintext: {decrypted_plaintext.decode()}\")\n\n# 6. Verify that the decrypted plaintext is identical to the original plaintext.\nassert plaintext == decrypted_plaintext\nprint(\"Encryption and decryption successful!\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.0.1"},{"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.","message":"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.","severity":"deprecated","affected_versions":"1.x.x, 2.x.x"},{"fix":"Ensure `aws-encryption-sdk[MPL]` is installed if you intend to use Keyrings.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"fix":"Always provide the full AWS KMS Key ARN when configuring AWS KMS Keyrings for decryption.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'activ':51 'aw':1,7,21,67 'best':43 'client':28 'client-sid':27 'compliant':15 'cryptographi':69 'data':35 'decrypt':38 'design':32 'employ':45 'encrypt':2,8,22,30,36,47,68 'envelop':46 'frequent':63 'fulli':14 'implement':18 'industri':40 'kms':71 'less':62 'librari':31,49 'maintain':52 'major':64 'minor':57 'nativ':16 'patch':55 'practic':44 'provid':12 'python':5,11,17 'quarter':60 'regular':54 'releas':58 'sdk':3,9,23 'secur':70 'side':29 'simplifi':34 'standard':41 'typic':59 'updat':66 'use':39 'version':65","created_at":"2026-04-11T01:26:23.288703+00:00","updated_at":"2026-04-15T21:51:01.849723+00:00","problems":[{"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.","cause":"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.","error":"Unable to import module 'lambdaMain': libffi-d78936b1.so.6.0.4: cannot open shared object file: No such file or directory"},{"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.","cause":"This error arises when the specified algorithm suite conflicts with the commitment policy set in the AWS Encryption SDK.","error":"Configuration conflict: Commitment policy and algorithm suite"},{"fix":"Verify the integrity of the encrypted message and ensure it was generated by the AWS Encryption SDK without modification.","cause":"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.","error":"Key commitment validation failed"},{"fix":"Install the AWS Encryption SDK using pip: `pip install aws-encryption-sdk`.","cause":"This error occurs when the AWS Encryption SDK is not installed or not available in the Python environment.","error":"ImportError: No module named 'aws_encryption_sdk'"},{"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.","cause":"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.","error":"AttributeError: module 'aws_encryption_sdk' has no attribute 'encrypt'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.0.6","cli_name":"","cli_version":null,"type":"library","homepage":"https://aws.amazon.com/encryption-sdk/","github":"https://github.com/aws/aws-encryption-sdk-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/aws-encryption-sdk/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","auth-security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}