aws-encryption-sdk¶
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.
Getting Started¶
Required Prerequisites¶
- Python 2.7 or 3.5+
- cryptography >= 1.8.1
- boto3
- attrs
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-encryption-sdk
Concepts¶
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.
Keyrings¶
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.
Usage¶
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.
Modules¶
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. |
Changelog¶
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
andaws_encryption_sdk.decrypt
.
- Modified APIs:
Note
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
.
Deprecations¶
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.
1.4.1 – 2019-09-20¶
1.4.0 – 2019-05-23¶
Minor¶
- Remove dependence on all
source_stream
APIs except forread()
. #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 theStreamDecryptor
orStreamEncryptor
to close yoursource_stream
for you, you will now need to close those streams yourself. StreamDecryptor.body_start
andStreamDecryptor.body_end
, deprecated in a prior release, have now been removed.
1.3.8 – 2018-11-15¶
1.3.7 – 2018-09-20¶
1.3.6 – 2018-09-04¶
1.3.5 – 2018-08-01¶
- Move the
aws-encryption-sdk-python
repository fromawslabs
toaws
.
1.3.4 – 2018-04-12¶
1.3.3 – 2017-12-05¶
Maintenance¶
- Blacklisted pytest 3.3.0 #32 pytest-dev/pytest#2957
1.3.1 – 2017-09-12¶
Reorganization¶
- Moved source into
src
. - Moved examples into
examples
. - Broke out
internal.crypto
into smaller, feature-oriented, modules.
Tooling¶
Maintenance¶
- Updated
internal.crypto.authentication.Verifier
to usePrehashed
. - 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¶
Major¶
- Added cryptographic materials managers as a concept
- Added data key caching
- Moved to deterministic IV generation
Minor¶
- 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 ofEncryptingStream
andDecryptingStream
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¶
- Fixed
attrs
version to 16.3.0 to avoid breaking changes in attrs 17.1.0
1.2.0 – 2017-03-21¶
- Initial public release