{"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":"en","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,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}