aws-cryptographic-materials-providers-library-python

MPL-python-tests Code style: black Documentation Status

These are the docs for the AWS Cryptographic Materials Providers Library for Python.

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

Find us on GitHub.

Security

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.

Getting Started

Required Prerequisites

  • Python 3.11+

  • cryptography >= 43.0.1

  • boto3 >= 1.35.42

Installation

Note

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-cryptographic-material-providers

Concepts

The AWS Cryptographic Materials Providers Library (MPL) is available in multiple languages. The concepts in the Python implementation of the MPL are the same as in other languages. For more information on concepts in the MPL, see the README for all languages.

Thread safety

The MaterialProviders client and all provided CryptoMaterialsManagers (CMMs) are thread safe. But keyrings that call AWS Key Management Service (KMS) and CMMs that use keyrings that call KMS MUST not be shared between threads, for reasons outlined in the boto3 docs.

(Keyrings that call KMS are identified by the string Kms in their name. ex. AwsKmsKeyring, AwsKmsMrkDiscoveryMultiKeyring, etc.)

Finally, while the provided implementations of ICryptographicMaterialsCache are thread-safe, there is currently no thread-safe keyring implementation that supports using a cache.

AWS Cryptographic Material Providers Library

📣 Note: This repository contains the source code and related files for all language implementations of the AWS Cryptographic Material Providers Library. See our supported languages section for more information.

The AWS Cryptographic Material Providers Library abstracts lower level cryptographic materials management of encryption and decryption materials. It uses cryptographic best practices to protect the data keys that protect your data. The data key is protected with a key encryption key called a wrapping key. The encryption method returns the data key and one or more encrypted data keys. Supported libraries use this information to perform envelope encryption. The data key is used to protect your data, and the encrypted data keys are stored alongside your data so you don’t need to keep track of the data keys separately. You can use AWS KMS keys in AWS Key Management Service(AWS KMS) as wrapping keys. The AWS Cryptographic Material Providers Library also provides APIs to define and use wrapping keys from other key providers.

The AWS Cryptographic Material Providers Library provides methods for encrypting and decrypting cryptographic materials used in higher level client side encryption libraries.

Security issue notifications

Security

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page. Please do not create a public GitHub issue.

Getting Started
Repository structure

This repository is a top level repository which houses all source code in order to compile this library into different runtimes.

This library is written in Dafny, a formally verifiable programming language that can be compiled into different runtimes. This library is currently ONLY supported in Java, .NET, Python, Rust and Go.

Optional Prerequisites
AWS Integration

You don’t need an Amazon Web Services (AWS) account to use the AWS Cryptographic Material Providers Library, but some APIs require an AWS account, an AWS KMS key, or an Amazon DynamoDB Table. If you are using the AWS Cryptographic Material Providers Library for Java you will need the AWS SDK for Java V2. If you are using the AWS Cryptographic Material Providers Library for .NET you will need the AWS SDK for .NET V3. If you are using the AWS Cryptographic Material Providers Library for Python you will need boto3. If you are using the AWS Cryptographic Material Providers Library for Rust you will need the AWS SDK for Rust V1. If you are using the AWS Cryptographic Material Providers Library for Go you will need the AWS SDK for Go V2.

NOTE: The KmsAsyncClient and DynamoDBAsyncClient are not supported, only the synchronous clients.

Supported Languages

  • Java

  • .NET

  • Python

  • Rust

  • Go

  • Dafny

FAQ

See the Frequently Asked Questions page in the official documentation.

Modules

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_keystore.client

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_keystore.config

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_keystore.errors

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_keystore.models

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_materialproviders.client

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_materialproviders.config

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_materialproviders.errors

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_materialproviders.models

aws_cryptographic_material_providers.smithygenerated.aws_cryptography_materialproviders.references

Changelog

Note: Starting April 20, 2026, all runtime-specific changes are tracked in separate changelogs:

If a runtime-specific changelog is not present, there has been no new release for that runtime after April 20, 2026.

Each changelog entry below applies to all runtimes unless specified by a language suffix.

2.0.0-net (2026-03-11)

This release is available only in the following languages:

  • DotNet (as v2.0.0)

⚠ BREAKING CHANGES

  • .net: Add support for AWS SDK V4 and remove support for AWS SDK V3.

feat
1.11.2 (2026-02-02)

This release is available in the following languages:

  • DotNet

  • Python

NOTE

This library is NOT impacted by CVE-2026-26007. This library does not use SECT curves.

Fixes – DotNet
Maintenance – All Languages

  • dafny: add fuzz testing to MPL (#1622) (14fad38)

  • dafny: add new SearchAndReplaceWhole and friends (#1680) (74e98c1)

  • dafny: optimize mutation map for O(1) performance in Go (#1687) (68cd7cb)

Maintenance – Python

  • python: add user agent suffix to kms requests (#1686) (b69aaf2)

  • python: exclude generated tests from project distribution (#1627) (505eee0)

  • python: tests for OpaqueWithText (#1656) (25e1219)

  • python: bump cryptography upperbound to <47 due to CVE-2026-26007 (#1800)

Maintenance – Go
Maintenance – Rust
Miscellaneous
1.11.1 (2025-07-29)

This release is available in the following languages:

  • Python

Maintenance – All Languages

  • dafny: add Rust and Go to supported languages (#1492) (87ab402)

  • dafny: append our user agent in KMS client (#1564) (03d03ac)

  • dafny: remove negative test for codebuild runner (#1603) (8b45e40)

Maintenance – Python

  • python: Updated pytz version range to include 2025 releases (#1603) (1aced27)

Maintenance – Go

  • go: automate changelog for Go release (#1607) (f9eb8e0)

  • go: update go test matrix and clean up setup (#1625) (6baa15c)

Maintenance – Rust
Miscellaneous

  • 5 instead of 25 interop decrypt processes (#1620) (d82696b)

  • allow local testing for python (#1598) (cbfa209)

  • bump credentials to 2 hours, for python (#1621) (69991da)

  • cfn: add trusted policy for optools mpl-python roles (#1602) (436d939)

  • CI: fix daily CI and add slack notification to it (#1647) (c546646)

  • CI: send slack message on new GHI (#1632) (e80b7ae)

  • CI: Test Rust on Dafny prerelease in nightly build (#1623) (92070bc)

  • CI: update to not trigger workflow on PR comments (#1640) (c62e8cf)

  • deps: bump slackapi/slack-github-action from 2.1.0 to 2.1.1 in /.github/workflows (#1638) (40b643f)

  • Go: Add Go release script and workflow to run it (#1562) (1c563bd)

1.11.0 (2025-06-17)

This release is available in the following languages:

  • Java

  • Python

Fixes – All Languages

  • dafny: bump Dafny libraries for JSON fix (#1517) (d8679e5)

Maintenance – All Languages

  • dafny: BK fix to extract encryption context for branch key materials (#1523) (95856ac)

  • dafny: don’t recalculate RSA key on every decrypt (#1448) (f318912)

  • dafny: Make HasSubString generic (#1549) (6a1017f)

  • dafny: more using uint64 instead of nat (#1490) (571e3c5)

  • dafny: store privateKey in RawRSAKeyring because some Java code needs it (#1450) (1c29322)

  • dafny: support for memory size constraints (#1481) (8d2c2b5)

  • dafny: update UInt and MemoryMath as needed for DB-ESDK (#1488) (49e596b)

Maintenance – Java

  • java: migrate to Nexus Central for Maven publishing (#1553) (7d2fcd3)

Maintenance – Go

  • go: implement missing MutableMap::content() (#1519) (f033b91)

  • go: remove print statements from testLotsOfAdding (#1468) (594383c)

Maintenance – Rust

  • rust: remove print statements from testLotsOfAdding (#1469) (9cf1dce)

  • rust: update smithy-dafny, use small-int feature (#1437) (515995e)

Miscellaneous
1.10.1 (2025-03-27)

This release is available in the following languages:

  • Java

Maintenance – All Languages
Maintenance – Java
Miscellaneous

  • add proper sleep handling in StormTracker for Python and .NET (#1369) (77fd007)

  • CI: Allow local testing (#1358) (5ecb410)

1.10.0 (2025-03-24)

This release is available in the following languages:

  • Python

Miscellaneous – Python

  • deps: extend supported version of pytz library (#1333) (6f6876a)

Miscellaneous

1.9.0 (2025-02-03)

This release is available in the following languages:

  • Java

Bug Fixes
Features

1.8.0 (2024-11-19)

This release is available in the following languages:

  • Java

Bug Fixes

  • Drop SelectOpt from MutableMap (bdb6509)

  • Externs (0bc1f96)

  • formatting (b608ab8)

  • Python-Release: Run validate tests from release commit (41c0c94)

  • Python: CMCs release lock for unhandled runtime exceptions (#979) (1510b77)

  • Python: return error on interrupted sleep (#1003) (405cf37)

  • remove input and output traits on DynamoDB operations (#1012) (8377acf)

  • return error on interrupted sleep (#993) (f49460a)

  • rust CI (42e39cc)

Features

  • Rust: Interop test vectors; bump Dafny to 4.9.0 (#1004) (a505a30)

  • Storm cache supports millisecond resolution (#1011) (6f09d5d)

1.7.4 (2024-11-06)

This release is available in the following languages:

  • Python

Bug Fixes
1.7.3 (2024-10-31)

This release is available in the following languages:

  • Python

Bug Fixes

  • python time externs should return integers (#898) (56b9b67)

1.7.2 (2024-10-22)

This release is available in the following languages:

  • Python

Bug Fixes

  • Move Java helper methods out of extern class (#855) (61fddf8)

  • Smithy-Dafny update for separated classes and unions (#806) (4b7cc5f)

  • variable name collision fix for Go (ceaec06)

1.7.1 (2024-10-11)

This release is available in the following languages:

  • Python

This is the first release for the Python implementation of the AWS Cryptographic Material Providers Library. (#805) (cfb2f7e)

Bug Fixes

  • H-Keyring: if getCache returns Error not EntryDoesNotExist, raise error (#846) (3413fcb)

  • H-Keyring: if putCache throws EntryAlreadyExists, swallow (#856) (d01a182 )

1.7.0 (2024-09-23)

Features

  • HierarchyKeyring; CMC: Shared cache across Hierarchy Keyrings (#747) (d4709e9)

1.6.0 (2024-09-10)

Bug Fixes

  • add ECDH error message for Rust (#574) (473a34a)

  • DDB-Model: DDB Supports 100 actions per Transaction (#692) (8a67843)

  • GetCurrentTimeStamp returns ISO8601 format (#575) (c07a51f)

  • maintain order in test vectors for languages with parallel tests (#641) (8c8a38f)

  • Remove 4.4 DDB and KMS patches, abstract test to work on later Dafny versions (#611) (d51d648)

  • Remove uses of :| (#618) (f12fe5b)

  • test vector help text (#657) (0fedaf1)

  • post-release: Change back to 1.5.1-SNAPSHOT (09cd9a4)

Features

  • bump dafny verification and code gen to dafny 4.8.0 (#520) (e16539e)

1.5.1 (2024-07-08)
Fixes

  • SDK-Java: Generic SDK Error to Opaque & Back (#466) (f832ad1)

1.5.0 (2024-06-17)

Features

  • MPL: Add Raw ECDH and AWS KMS ECDH Keyrings (#419) (0946a7e)

1.4.0 (2024-05-20)

Features

  • Keystore: Introduce additional KMSConfiguration options (#316) (f3a0a52)

The Hierarchical Keyring’s Keystore now supports four (4) KMSConfigurations:

  • kmsKeyArn

  • kmsMRKeyArn

  • discovery

  • mrDiscovery

See our JavaDocs for details on how these options effect the relationship between a Keystore and KMS.

Maintenance

1.3.0 (2024-04-24)

Bug Fixes

  • dafny: Local Service Constructors MUST return concrete (64f72c1)

  • Improvements to the Java Release process (#162) (d92c06a)

  • Increase try-block scope when calling MPL components (#267) (7661bf4)

Features

  • Multi-Region Key Logic in the Keystore (#285) (d924395)

  • .NET : Enforce User input Constraints at Type Conversion (#281) (04102d7)

  • Update error message to include expected values when no Encrypted Data Keys found to match (#275) (da95f9a)

1.2.0 (2024-01-08)
Features
* add command line parser (#131)
Bug Fixes
* resolve awssdk:core dependency in TestVectors build.gradle.kts (#177)
* add more tests to ComputeSetToOrderedSequence (#111)
* Empty string defers to SDK default region (#127)
* update mpl .csproj to use project references (#134)
* newest polymorph for newest shims. Catch all exceptions. DDB only (#135)
* update README for repo rename update (#147)
* rerun latest polymorph. (#128)
* typo lead to two verification, no format (#130)
* Improve compatibility with Dafny 4.4 (#129)
Maintenance
* A variety of fixes to the libraries CI and testing
1.0.2 (2023-10-18)
Bug Fixes
* CmpError must return custom error message (#118) (86abacc)
* Deafult entryPruningTailSize (#93) (0344e9f)
* Fix brittle concurrent test (#105) (#60) (c043162)
* fix typo in encryption materials validation (cd6b0aa), closes #84
* fix typo in encryption materials validation (89a234c)
* Forward the underlying error (#90) (bc21551)
1.0.1 2023-07-26
Fix

  • Fixes a runtime check in VersionKey Key Store API that no longer checks for the CipherText length on the output of a KMS ReEncrypt API call.

1.0.0 2023-07-21
Features

  • Introduces Thread Safe Cryptographic Materials Caches (CMCs):

    • Storm Tracking Cache Safe for use in a multi threaded environment, tries to prevent redundant or overly parallel backend calls. See Spec changes for details.

    • Multi Threaded Cache Safe for use in a multi threaded environment, but no extra functionality

BREAKING CHANGES

  • CMCs:

    • Original Cryptographic Materials Cache has been renamed to Single Threaded Cache

    • CreateCryptographicMaterialsCacheInput now ONLY accepts CacheType, which determines which, if any, of the three implemented CMCs will be returned.

    • The DefaultCache is StormTrackingCache

  • CreateAwsKmsHierarchicalKeyringInput:

    • no longer has a maxCacheSize field

    • now has an optional cache field for a CacheType

  • Hierarchical Keyring’s Key Store:

    • The Hierarchical Keyring’s Key Store’s Data Structure has changed. As such, entries persisted in the Key Store with prior versions of this library are NOT compatibale. Instead, we recommend Creating a new DynamoDB Table for this version of the Key Store.

    • The Key Store’s CreateKeyInput now takes:

      • An Optional String branchKeyIdentifier

      • An Optional EncryptionContext encryptionContext

        • This encryptionContext will be added to the Encryption Context sent to KMS prefixed with aws-crypto-ec:

    • Creating a Key now also calls KMS:ReEncrypt

    • CreateKeyStore no longer creates a GSI

    • The Encryption Context used with KMS’ GenerateDataKeyWithoutPlaintext no longer include’s the discarded GSI’s status.

    • More details about the Key Store’s changes are avaible in our Specification:

Maintenance

  • A variety of fixes to the libraries CI and testing

Fix

  • Fixes Required Encryption Context CMM and UpdateUsageMetadata names in smithy model

1.0.0-preview-3 2023-06-22
Fix

  • Fixes PutCacheEntry

    • PutCacheEntry will now update an entry. This simplifies using the cache in concurrent situations. Rather than having the caller implement some retry logic the cache will now update the entry.

  • Fixes pom.xml to include runtime version of BouncyCastle and removes bundling of BC in the jar.

1.0.0-preview-2 2023-06-19
Fix

  • Fixes build file to correctly generate pom file with correct dependencies during release.

1.0.0-preview-1 2023-06-07
Features

  • Initial release of the AWS Cryptographic Material Providers Library. This release is considered a developer preview and is not intended for production use cases.