Latest Version Supported Python Versions Code style: black Documentation Status

The AWS Encryption SDK for Python provides a fully compliant, native Python implementation of the AWS Encryption SDK.

The latest full documentation can be found at Read the Docs.

Find us on GitHub.

Security issue notifications

Getting Started

Required Prerequisites

  • Python 2.7 or 3.5+
  • cryptography >= 1.8.1
  • boto3
  • attrs



If you have not already installed cryptography, you might need to install additional prerequisites as detailed in the cryptography installation guide for your operating system.

$ pip install aws-encryption-sdk


There are three main concepts that are helpful to understand when using the AWS Encryption SDK.

For further information, see the AWS Encryption SDK developer guide concepts.

Cryptographic Materials Managers

The cryptographic materials manager (CMM) assembles the cryptographic materials that are used to encrypt and decrypt data.

For more details, see the AWS Encryption SDK developer guide cryptographic materials manager concept.


A keyring generates, encrypts, and decrypts data keys.

For more details, see the AWS Encryption SDK developer guide keyring concept.

Data Keys

A data key is an encryption key that the AWS Encryption SDK uses to encrypt your data.

For more details, see the AWS Encryption SDK developer guide data key concept.


For examples of how to use these concepts to accomplish different tasks, see our examples.

Performance Considerations

Adjusting the frame size can significantly improve the performance of encrypt/decrypt operations with this library.

Processing each frame in a framed message involves a certain amount of overhead. If you are encrypting a large file, increasing the frame size can offer potentially significant performance gains. We recommend that you tune these values to your use-case in order to obtain peak performance.


aws_encryption_sdk High level AWS Encryption SDK client functions.
aws_encryption_sdk.exceptions Contains exception classes for AWS Encryption SDK.
aws_encryption_sdk.identifiers AWS Encryption SDK native data structures for defining implementation-specific characteristics.
aws_encryption_sdk.caches Common functions and structures for use in cryptographic materials caches.
aws_encryption_sdk.caches.base Base class interface for caches for use with caching crypto material managers.
aws_encryption_sdk.caches.local Local, in-memory, LRU, cryptographic materials cache for use with caching cryptographic materials providers.
aws_encryption_sdk.caches.null Null cache: a cache which does not cache.
aws_encryption_sdk.keyrings.base Base class interface for Keyrings.
aws_encryption_sdk.keyrings.aws_kms Keyring for use with AWS Key Management Service (KMS).
aws_encryption_sdk.keyrings.aws_kms.client_suppliers AWS KMS client suppliers for use with AWS KMS keyring.
aws_encryption_sdk.keyrings.multi Resources required for Multi Keyrings.
aws_encryption_sdk.keyrings.raw Resources required for Raw Keyrings.
aws_encryption_sdk.key_providers.base Base class interface for Master Key Providers.
aws_encryption_sdk.key_providers.kms Master Key Providers for use with AWS KMS
aws_encryption_sdk.key_providers.raw Resources required for Raw Master Keys.
aws_encryption_sdk.materials_managers Primitive structures for use when interacting with crypto material managers.
aws_encryption_sdk.materials_managers.base Base class interface for crypto material managers.
aws_encryption_sdk.materials_managers.caching Caching crypto material manager.
aws_encryption_sdk.materials_managers.default Default crypto material manager class.
aws_encryption_sdk.streaming_client High level AWS Encryption SDK client for streaming objects.
aws_encryption_sdk.structures Public data structures for aws_encryption_sdk.
aws_encryption_sdk.internal Internal Implementation Details
aws_encryption_sdk.internal.crypto.authentication Contains authentication primitives.
aws_encryption_sdk.internal.crypto.data_keys Contains data key helper functions.
aws_encryption_sdk.internal.crypto.elliptic_curve Contains elliptic curve functionality.
aws_encryption_sdk.internal.crypto.encryption Contains encryption primitives and helper functions.
aws_encryption_sdk.internal.crypto.iv Helper functions used for generating deterministic initialization vectors (IVs).
aws_encryption_sdk.internal.crypto.wrapping_keys Contains wrapping key primitives.
aws_encryption_sdk.internal.defaults Default values for AWS Encryption SDK.
aws_encryption_sdk.internal.formatting Formatting functions for aws_encryption_sdk.
aws_encryption_sdk.internal.formatting.deserialize Components for handling AWS Encryption SDK message deserialization.
aws_encryption_sdk.internal.formatting.encryption_context Components for handling serialization and deserialization of encryption context data in AWS Encryption SDK messages.
aws_encryption_sdk.internal.formatting.serialize Components for handling AWS Encryption SDK message serialization.
aws_encryption_sdk.internal.str_ops Helper functions for consistently obtaining str and bytes objects in both Python2 and Python3.
aws_encryption_sdk.internal.structures Public data structures for aws_encryption_sdk.
aws_encryption_sdk.internal.validators Common attrs validators.
aws_encryption_sdk.internal.utils Helper utility functions for AWS Encryption SDK.
aws_encryption_sdk.keyrings.aws_kms._client_cache boto3 client cache for use by client suppliers.


1.5.0 – 2020-xx-xx

Major Features

  • Add keyrings.

  • Change one-step APIs to return a CryptoResult rather than a tuple.

    • Modified APIs: aws_encryption_sdk.encrypt and aws_encryption_sdk.decrypt.


For backwards compatibility, CryptoResult also unpacks like a 2-member tuple. This allows for backwards compatibility with the previous outputs so this change should not break any existing consumers unless you are specifically relying on the output being an instance of tuple.


  • Deprecate master key providers in favor of keyrings.

    • We still support using master key providers and are not removing them yet. When we decide to remove them, we will communicate that as defined in our versioning policy.
  • Deprecate support for Python 3.4.

    • This does not mean that this library will no longer work or install with 3.4, but we are no longer testing against or advertising support for 3.4.


  • Added new examples demonstrating how to use APIs, keyrings, cryptographic materials managers, and master key providers. #221 #236 #239

1.4.1 – 2019-09-20


  • Fix region configuration override in botocore sessions. #190 #193


  • Caching CMM must require that max age configuration value is greater than 0. #147 #172

1.4.0 – 2019-05-23


  • Remove dependence on all source_stream APIs except for read(). #103
Potentially Backwards Incompatible
  • Encryption streams no longer close the source_stream when they themselves close. If you are using context managers for all of your stream handling, this change will not affect you. However, if you have been relying on the StreamDecryptor or StreamEncryptor to close your source_stream for you, you will now need to close those streams yourself.
  • StreamDecryptor.body_start and StreamDecryptor.body_end, deprecated in a prior release, have now been removed.


  • Move all remaining unittest tests to pytest. #99


  • Fix MasterKeyprovider.decrypt_data_key_from_list error handling. #150

1.3.8 – 2018-11-15


  • Remove debug logging that may contain input data when encrypting non-default unframed messages. #105


  • Add support to remove clients from KMSMasterKeyProvider client cache if they fail to connect to endpoint. #86
  • Add support for SHA384 and SHA512 for use with RSA OAEP wrapping algorithms. #56
  • Fix streaming_client classes to properly interpret short reads in source streams. #24

1.3.7 – 2018-09-20


  • Fix KMSMasterKeyProvider to determine the default region before trying to create the requested master keys. #83

1.3.6 – 2018-09-04


  • StreamEncryptor and StreamDecryptor should always report as readable if they are open. #73
  • Allow duck-typing of source streams. #75

1.3.5 – 2018-08-01

  • Move the aws-encryption-sdk-python repository from awslabs to aws.

1.3.4 – 2018-04-12


  • AWS KMS master key/provider user agent extension fixed. #47


  • New minimum pytest version 3.3.1 to avoid bugs in 3.3.0 #32
  • New minimum attrs version 17.4.0 to allow use of converter rather than convert #39
  • Algorithm Suites are modeled as collections of sub-suites now #36
  • Selecting test suites is more sane now, with pytest markers. #41

1.3.3 – 2017-12-05


  • Remove use of attrs functionality deprecated in 17.3.0 #29


1.3.2 – 2017-09-28

  • Addressed issue #13 to properly handle non-seekable source streams.

1.3.1 – 2017-09-12


  • Moved source into src.
  • Moved examples into examples.
  • Broke out internal.crypto into smaller, feature-oriented, modules.


  • Added tox configuration to support automation and development tooling.
  • Added pylint, flake8, and doc8 configuration to enforce style rules.


  • Updated internal.crypto.authentication.Verifier to use Prehashed.
  • Addressed docstring issue #7.
  • Addressed docstring issue #8.
  • Addressed logging issue #10.
  • Addressed assorted linting issues to bring source, tests, examples, and docs up to configured linting standards.

1.3.0 – 2017-08-04


  • Added cryptographic materials managers as a concept
  • Added data key caching
  • Moved to deterministic IV generation


  • Added changelog
  • Fixed attrs usage to provide consistent behavior with 16.3.0 and 17.x
  • Fixed performance bug which caused KDF calculations to be performed too frequently
  • Removed line_length as a configurable parameter of EncryptingStream and DecryptingStream objects to simplify class APIs after it was found in further testing to have no measurable impact on performance
  • Added deterministic length eliptic curve signature generation
  • Added support for calculating ciphertext message length from header
  • Migrated README from md to rst

1.2.2 – 2017-05-23

1.2.0 – 2017-03-21

  • Initial public release