feat: enable use of keyrings (#216)

* chore: add __all__ values for keyring modules

* chore: add versionadded tags for keyrings

* feat: plump keyrings into stream handlers and default CMM

* chore: incorporate keyrings into tests

* add raw AES keyring-MKP compatibility tests

* add raw RSA MKP-keyring compatibility tests

* fix: fix integ test to run when default region is set

* chore: add public-private keyring-MKP compat tests

* fix: fix typo

* add DefaultCryptographicMaterialsProvider tests for keyrings that return incomplete or broken materials

* feat: enable caching CMM to accept either MKP or keyring

* fix: rename test keyring to avoid name collision

* chore: caching CMM has too many instance attributes and that's ok

* docs: add versionadded flags to docstrings for keyring values

* docs: update docs on encrypt/decrypt helper functions to match underlying docs

* chore: update copyright notices on modified files

* docs: render keyring docs

* docs: clean up keyring method docs

* fix: fix linting issues

* fix: autoformat

* docs: fix typo

* fix: fix docs and error message inconsistency

* fix: re-order checks to avoid misleading error messages if materials are invalid

* chore: test broken paths in default CMM with more algorithm suites

* docs: make docs correctly link to pyca/cryptography docs

Author: mattsb42-aws

doc/conf.py

@@ -67,7 +67,10 @@ def get_version():
 htmlhelp_basename = "%sdoc" % project
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"http://docs.python.org/": None}
+intersphinx_mapping = {
+    "python": ("http://docs.python.org/3/", None),
+    "cryptography": ("https://cryptography.io/en/latest/", None),
+}
 
 # autosummary
 autosummary_generate = True

doc/index.rst

@@ -14,6 +14,9 @@ Modules
     aws_encryption_sdk.caches.base
     aws_encryption_sdk.caches.local
     aws_encryption_sdk.caches.null
+    aws_encryption_sdk.keyrings.base
+    aws_encryption_sdk.keyrings.multi
+    aws_encryption_sdk.keyrings.raw
     aws_encryption_sdk.key_providers.base
     aws_encryption_sdk.key_providers.kms
     aws_encryption_sdk.key_providers.raw

src/aws_encryption_sdk/__init__.py

@@ -1,15 +1,5 @@
-# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You
-# may not use this file except in compliance with the License. A copy of
-# the License is located at
-#
-# http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is
-# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
-# ANY KIND, either express or implied. See the License for the specific
-# language governing permissions and limitations under the License.
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 """High level AWS Encryption SDK client functions."""
 # Below are imported for ease of use by implementors
 from aws_encryption_sdk.caches.local import LocalCryptoMaterialsCache  # noqa
@@ -33,6 +23,9 @@ def encrypt(**kwargs):
         When using this function, the entire ciphertext message is encrypted into memory before returning
         any data.  If streaming is desired, see :class:`aws_encryption_sdk.stream`.
 
+    .. versionadded:: 1.5.0
+       The *keyring* parameter.
+
     .. code:: python
 
         >>> import aws_encryption_sdk
@@ -49,12 +42,14 @@ def encrypt(**kwargs):
     :type config: aws_encryption_sdk.streaming_client.EncryptorConfig
     :param source: Source data to encrypt or decrypt
     :type source: str, bytes, io.IOBase, or file
-    :param materials_manager: `CryptoMaterialsManager` from which to obtain cryptographic materials
-        (either `materials_manager` or `key_provider` required)
-    :type materials_manager: aws_encryption_sdk.materials_managers.base.CryptoMaterialsManager
-    :param key_provider: `MasterKeyProvider` from which to obtain data keys for encryption
-        (either `materials_manager` or `key_provider` required)
-    :type key_provider: aws_encryption_sdk.key_providers.base.MasterKeyProvider
+    :param CryptoMaterialsManager materials_manager:
+        Cryptographic materials manager to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
+    :param Keyring keyring: Keyring to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
+    :param MasterKeyProvider key_provider:
+        Master key provider to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
     :param int source_length: Length of source data (optional)
 
         .. note::
@@ -87,6 +82,9 @@ def decrypt(**kwargs):
         When using this function, the entire ciphertext message is decrypted into memory before returning
         any data.  If streaming is desired, see :class:`aws_encryption_sdk.stream`.
 
+    .. versionadded:: 1.5.0
+       The *keyring* parameter.
+
     .. code:: python
 
         >>> import aws_encryption_sdk
@@ -103,12 +101,14 @@ def decrypt(**kwargs):
     :type config: aws_encryption_sdk.streaming_client.DecryptorConfig
     :param source: Source data to encrypt or decrypt
     :type source: str, bytes, io.IOBase, or file
-    :param materials_manager: `CryptoMaterialsManager` from which to obtain cryptographic materials
-        (either `materials_manager` or `key_provider` required)
-    :type materials_manager: aws_encryption_sdk.materials_managers.base.CryptoMaterialsManager
-    :param key_provider: `MasterKeyProvider` from which to obtain data keys for decryption
-        (either `materials_manager` or `key_provider` required)
-    :type key_provider: aws_encryption_sdk.key_providers.base.MasterKeyProvider
+    :param CryptoMaterialsManager materials_manager:
+        Cryptographic materials manager to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
+    :param Keyring keyring: Keyring to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
+    :param MasterKeyProvider key_provider:
+        Master key provider to use for encryption
+        (either ``materials_manager``, ``keyring``, ``key_provider`` required)
     :param int source_length: Length of source data (optional)
 
         .. note::

src/aws_encryption_sdk/exceptions.py

@@ -1,15 +1,5 @@
-# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You
-# may not use this file except in compliance with the License. A copy of
-# the License is located at
-#
-# http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is
-# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
-# ANY KIND, either express or implied. See the License for the specific
-# language governing permissions and limitations under the License.
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 """Contains exception classes for AWS Encryption SDK."""
 
 
@@ -87,6 +77,13 @@ class SignatureKeyError(AWSEncryptionSDKClientError):
     """
 
 
+class InvalidCryptographicMaterialsError(AWSEncryptionSDKClientError):
+    """Exception class for errors encountered when attempting to validate cryptographic materials.
+
+    .. versionadded:: 1.5.0
+    """
+
+
 class ActionNotAllowedError(AWSEncryptionSDKClientError):
     """Exception class for errors encountered when attempting to perform unallowed actions."""
 

src/aws_encryption_sdk/keyrings/base.py

@@ -1,15 +1,5 @@
-# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You
-# may not use this file except in compliance with the License. A copy of
-# the License is located at
-#
-# http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is
-# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
-# ANY KIND, either express or implied. See the License for the specific
-# language governing permissions and limitations under the License.
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 """Base class interface for Keyrings."""
 from aws_encryption_sdk.materials_managers import (  # only used for mypy; pylint: disable=unused-import
     DecryptionMaterials,
@@ -23,6 +13,8 @@
     # We only actually need these imports when running the mypy checks
     pass
 
+__all__ = ("Keyring",)
+
 
 class Keyring(object):
     """Parent interface for Keyring classes.
@@ -34,10 +26,9 @@ def on_encrypt(self, encryption_materials):
         # type: (EncryptionMaterials) -> EncryptionMaterials
         """Generate a data key if not present and encrypt it using any available wrapping key.
 
-        :param encryption_materials: Encryption materials for the keyring to modify.
-        :type encryption_materials: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :param EncryptionMaterials encryption_materials: Encryption materials for keyring to modify.
         :returns: Optionally modified encryption materials.
-        :rtype: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :rtype: EncryptionMaterials
         :raises NotImplementedError: if method is not implemented
         """
         raise NotImplementedError("Keyring does not implement on_encrypt function")
@@ -46,12 +37,10 @@ def on_decrypt(self, decryption_materials, encrypted_data_keys):
         # type: (DecryptionMaterials, Iterable[EncryptedDataKey]) -> DecryptionMaterials
         """Attempt to decrypt the encrypted data keys.
 
-        :param decryption_materials: Decryption materials for the keyring to modify.
-        :type decryption_materials: aws_encryption_sdk.materials_managers.DecryptionMaterials
-        :param encrypted_data_keys: List of encrypted data keys.
-        :type: Iterable of :class:`aws_encryption_sdk.structures.EncryptedDataKey`
+        :param DecryptionMaterials decryption_materials: Decryption materials for keyring to modify.
+        :param List[EncryptedDataKey] encrypted_data_keys: List of encrypted data keys.
         :returns: Optionally modified decryption materials.
-        :rtype: aws_encryption_sdk.materials_managers.DecryptionMaterials
+        :rtype: DecryptionMaterials
         :raises NotImplementedError: if method is not implemented
         """
         raise NotImplementedError("Keyring does not implement on_decrypt function")

src/aws_encryption_sdk/keyrings/multi.py

@@ -1,15 +1,5 @@
-# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License"). You
-# may not use this file except in compliance with the License. A copy of
-# the License is located at
-#
-# http://aws.amazon.com/apache2.0/
-#
-# or in the "license" file accompanying this file. This file is
-# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
-# ANY KIND, either express or implied. See the License for the specific
-# language governing permissions and limitations under the License.
+# Copyright Amazon.com Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
 """Resources required for Multi Keyrings."""
 import itertools
 
@@ -31,21 +21,24 @@
     # We only actually need these imports when running the mypy checks
     pass
 
+__all__ = ("MultiKeyring",)
+
 
 @attr.s
 class MultiKeyring(Keyring):
     """Public class for Multi Keyring.
 
-    :param generator: Generator keyring used to generate data encryption key (optional)
-    :type generator: Keyring
-    :param list children: List of keyrings used to encrypt the data encryption key (optional)
+    .. versionadded:: 1.5.0
+
+    :param Keyring generator: Generator keyring used to generate data encryption key (optional)
+    :param List[Keyring] children: List of keyrings used to encrypt the data encryption key (optional)
     :raises EncryptKeyError: if encryption of data key fails for any reason
     """
 
+    generator = attr.ib(default=None, validator=optional(instance_of(Keyring)))
     children = attr.ib(
         default=attr.Factory(tuple), validator=optional(deep_iterable(member_validator=instance_of(Keyring)))
     )
-    generator = attr.ib(default=None, validator=optional(instance_of(Keyring)))
 
     def __attrs_post_init__(self):
         # type: () -> None
@@ -62,10 +55,9 @@ def on_encrypt(self, encryption_materials):
         """Generate a data key using generator keyring
         and encrypt it using any available wrapping key in any child keyring.
 
-        :param encryption_materials: Encryption materials for keyring to modify.
-        :type encryption_materials: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :param EncryptionMaterials encryption_materials: Encryption materials for keyring to modify.
         :returns: Optionally modified encryption materials.
-        :rtype: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :rtype: EncryptionMaterials
         :raises EncryptKeyError: if unable to encrypt data key.
         """
         # Check if generator keyring is not provided and data key is not generated
@@ -94,12 +86,10 @@ def on_decrypt(self, decryption_materials, encrypted_data_keys):
         # type: (DecryptionMaterials, Iterable[EncryptedDataKey]) -> DecryptionMaterials
         """Attempt to decrypt the encrypted data keys.
 
-        :param decryption_materials: Decryption materials for keyring to modify.
-        :type decryption_materials: aws_encryption_sdk.materials_managers.DecryptionMaterials
-        :param encrypted_data_keys: List of encrypted data keys.
-        :type: List of `aws_encryption_sdk.structures.EncryptedDataKey`
+        :param DecryptionMaterials decryption_materials: Decryption materials for keyring to modify.
+        :param List[EncryptedDataKey] encrypted_data_keys: List of encrypted data keys.
         :returns: Optionally modified decryption materials.
-        :rtype: aws_encryption_sdk.materials_managers.DecryptionMaterials
+        :rtype: DecryptionMaterials
         """
         # Call on_decrypt on all keyrings till decryption is successful
         for keyring in self._decryption_keyrings: