feat: expose keyring trace in results (#224)

* feat: add CryptoResult and plumb in use

* chore: simplify test parametrization

* chore: adjust RawKeyring functional tests to use CryptoResult and check keyring trace

* chore: add unit tests for CryptoResult

* docs: fix docstrings and typehints in structures

* chore: verify that CryptoResult casts to a tuple as expected

* docs: add keyrings link and clarify how CryptoResult could break you

Author: mattsb42-aws

CHANGELOG.rst

@@ -2,6 +2,25 @@
 Changelog
 *********
 
+1.5.0 -- 2020-xx-xx
+===================
+
+Major Features
+--------------
+
+* Add `keyrings`_.
+* Change one-step APIs to return a :class:`CryptoResult` rather than a tuple.
+    * Modified APIs: ``aws_encryption_sdk.encrypt`` and ``aws_encryption_sdk.decrypt``.
+
+.. note::
+
+    For backwards compatibility,
+    :class:`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 :class:`tuple`.
+
+
 1.4.1 -- 2019-09-20
 ===================
 
@@ -193,3 +212,4 @@ Minor
 .. _pylint: https://www.pylint.org/
 .. _flake8: http://flake8.pycqa.org/en/latest/
 .. _doc8: https://launchpad.net/doc8
+.. _keyrings: https://docs.aws.amazon.com/encryption-sdk/latest/developer-guide/choose-keyring.html

src/aws_encryption_sdk/__init__.py

@@ -14,6 +14,9 @@
     StreamDecryptor,
     StreamEncryptor,
 )
+from aws_encryption_sdk.structures import CryptoResult
+
+__all__ = ("encrypt", "decrypt", "stream")
 
 
 def encrypt(**kwargs):
@@ -26,6 +29,13 @@ def encrypt(**kwargs):
     .. versionadded:: 1.5.0
        The *keyring* parameter.
 
+    .. versionadded:: 1.5.0
+
+        For backwards compatibility,
+        the new :class:`CryptoResult` return value 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.
+
     .. code:: python
 
         >>> import aws_encryption_sdk
@@ -67,12 +77,13 @@ def encrypt(**kwargs):
     :param algorithm: Algorithm to use for encryption
     :type algorithm: aws_encryption_sdk.identifiers.Algorithm
     :param int frame_length: Frame length in bytes
-    :returns: Tuple containing the encrypted ciphertext and the message header object
-    :rtype: tuple of bytes and :class:`aws_encryption_sdk.structures.MessageHeader`
+    :returns: Encrypted message, message metadata (header), and keyring trace
+    :rtype: CryptoResult
     """
     with StreamEncryptor(**kwargs) as encryptor:
         ciphertext = encryptor.read()
-    return ciphertext, encryptor.header
+
+    return CryptoResult(result=ciphertext, header=encryptor.header, keyring_trace=encryptor.keyring_trace)
 
 
 def decrypt(**kwargs):
@@ -85,6 +96,13 @@ def decrypt(**kwargs):
     .. versionadded:: 1.5.0
        The *keyring* parameter.
 
+    .. versionadded:: 1.5.0
+
+        For backwards compatibility,
+        the new :class:`CryptoResult` return value 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.
+
     .. code:: python
 
         >>> import aws_encryption_sdk
@@ -117,12 +135,13 @@ def decrypt(**kwargs):
 
     :param int max_body_length: Maximum frame size (or content length for non-framed messages)
         in bytes to read from ciphertext message.
-    :returns: Tuple containing the decrypted plaintext and the message header object
-    :rtype: tuple of bytes and :class:`aws_encryption_sdk.structures.MessageHeader`
+    :returns: Decrypted plaintext, message metadata (header), and keyring trace
+    :rtype: CryptoResult
     """
     with StreamDecryptor(**kwargs) as decryptor:
         plaintext = decryptor.read()
-    return plaintext, decryptor.header
+
+    return CryptoResult(result=plaintext, header=decryptor.header, keyring_trace=decryptor.keyring_trace)
 
 
 def stream(**kwargs):
@@ -182,6 +201,3 @@ def stream(**kwargs):
         return _stream_map[mode.lower()](**kwargs)
     except KeyError:
         raise ValueError("Unsupported mode: {}".format(mode))
-
-
-__all__ = ("encrypt", "decrypt", "stream")

src/aws_encryption_sdk/materials_managers/__init__.py

@@ -25,7 +25,7 @@
 from aws_encryption_sdk.structures import DataKey, EncryptedDataKey, KeyringTrace, RawDataKey
 
 try:  # Python 3.5.0 and 3.5.1 have incompatible typing modules
-    from typing import Any, FrozenSet, Iterable, Tuple, Union  # noqa pylint: disable=unused-import
+    from typing import Any, Iterable, Tuple, Union  # noqa pylint: disable=unused-import
 except ImportError:  # pragma: no cover
     # We only actually need these imports when running the mypy checks
     pass
@@ -238,10 +238,10 @@ def __init__(
 
     @property
     def encrypted_data_keys(self):
-        # type: () -> FrozenSet[EncryptedDataKey]
+        # type: () -> Tuple[EncryptedDataKey]
         """Return a read-only version of the encrypted data keys.
 
-        :rtype: frozenset
+        :rtype: Tuple[EncryptedDataKey]
         """
         return tuple(self._encrypted_data_keys)
 

src/aws_encryption_sdk/streaming_client.py

@@ -137,6 +137,7 @@ class _EncryptionStream(io.IOBase):
     _message_prepped = None  # type: bool
     source_stream = None
     _stream_length = None  # type: int
+    keyring_trace = ()
 
     def __new__(cls, **kwargs):
         """Perform necessary handling for _EncryptionStream instances that should be
@@ -443,6 +444,7 @@ def _prep_message(self):
         self._encryption_materials = self.config.materials_manager.get_encryption_materials(
             request=encryption_materials_request
         )
+        self.keyring_trace = self._encryption_materials.keyring_trace
 
         if self.config.algorithm is not None and self._encryption_materials.algorithm != self.config.algorithm:
             raise ActionNotAllowedError(
@@ -779,6 +781,8 @@ def _read_header(self):
             encryption_context=header.encryption_context,
         )
         decryption_materials = self.config.materials_manager.decrypt_materials(request=decrypt_materials_request)
+        self.keyring_trace = decryption_materials.keyring_trace
+
         if decryption_materials.verification_key is None:
             self.verifier = None
         else:

src/aws_encryption_sdk/structures.py

@@ -20,6 +20,12 @@
 from aws_encryption_sdk.identifiers import Algorithm, ContentType, KeyringTraceFlag, ObjectType, SerializationVersion
 from aws_encryption_sdk.internal.str_ops import to_bytes, to_str
 
+try:  # Python 3.5.0 and 3.5.1 have incompatible typing modules
+    from typing import Tuple  # noqa pylint: disable=unused-import
+except ImportError:  # pragma: no cover
+    # We only actually need these imports when running the mypy checks
+    pass
+
 
 @attr.s(hash=True)
 class MasterKeyInfo(object):
@@ -107,8 +113,7 @@ class KeyringTrace(object):
     .. versionadded:: 1.5.0
 
     :param MasterKeyInfo wrapping_key: Wrapping key used
-    :param flags: Actions performed
-    :type flags: set of :class:`KeyringTraceFlag`
+    :param Set[KeyringTraceFlag] flags: Actions performed
     """
 
     wrapping_key = attr.ib(validator=instance_of(MasterKeyInfo))
@@ -120,19 +125,14 @@ class MessageHeader(object):
     # pylint: disable=too-many-instance-attributes
     """Deserialized message header object.
 
-    :param version: Message format version, per spec
-    :type version: SerializationVersion
-    :param type: Message content type, per spec
-    :type type: ObjectType
-    :param algorithm: Algorithm to use for encryption
-    :type algorithm: Algorithm
+    :param SerializationVersion version: Message format version, per spec
+    :param ObjectType type: Message content type, per spec
+    :param AlgorithmSuite algorithm: Algorithm to use for encryption
     :param bytes message_id: Message ID
-    :param dict encryption_context: Dictionary defining encryption context
-    :param encrypted_data_keys: Encrypted data keys
-    :type encrypted_data_keys: set of :class:`aws_encryption_sdk.structures.EncryptedDataKey`
-    :param content_type: Message content framing type (framed/non-framed)
-    :type content_type: ContentType
-    :param bytes content_aad_length: empty
+    :param Dict[str,str] encryption_context: Dictionary defining encryption context
+    :param Sequence[EncryptedDataKey] encrypted_data_keys: Encrypted data keys
+    :param ContentType content_type: Message content framing type (framed/non-framed)
+    :param int content_aad_length: empty
     :param int header_iv_length: Bytes in Initialization Vector value found in header
     :param int frame_length: Length of message frame in bytes
     """
@@ -152,3 +152,41 @@ class MessageHeader(object):
     content_aad_length = attr.ib(hash=True, validator=instance_of(six.integer_types))
     header_iv_length = attr.ib(hash=True, validator=instance_of(six.integer_types))
     frame_length = attr.ib(hash=True, validator=instance_of(six.integer_types))
+
+
+@attr.s
+class CryptoResult(object):
+    """Result container for one-shot cryptographic API results.
+
+    .. versionadded:: 1.5.0
+
+    .. note::
+
+        For backwards compatibility,
+        this container also unpacks like a 2-member tuple.
+        This allows for backwards compatibility with the previous outputs.
+
+    :param bytes result: Binary results of the cryptographic operation
+    :param MessageHeader header: Encrypted message metadata
+    :param Tuple[KeyringTrace] keyring_trace: Keyring trace entries
+    """
+
+    result = attr.ib(validator=instance_of(bytes))
+    header = attr.ib(validator=instance_of(MessageHeader))
+    keyring_trace = attr.ib(validator=deep_iterable(member_validator=instance_of(KeyringTrace)))
+
+    def __attrs_post_init__(self):
+        """Construct the inner tuple for backwards compatibility."""
+        self._legacy_container = (self.result, self.header)
+
+    def __len__(self):
+        """Emulate the inner tuple."""
+        return self._legacy_container.__len__()
+
+    def __iter__(self):
+        """Emulate the inner tuple."""
+        return self._legacy_container.__iter__()
+
+    def __getitem__(self, key):
+        """Emulate the inner tuple."""
+        return self._legacy_container.__getitem__(key)