feat: add CryptoResult and plumb in use

Author: mattsb42-aws

CHANGELOG.rst

@@ -2,6 +2,24 @@
 Changelog
 *********
 
+1.5.0 -- 2020-xx-xx
+===================
+
+Major Features
+--------------
+
+* Add Keyrings
+* Change one-step APIs to return a :class:`CryptoResult` rather than a tuple.
+    * Changed 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.
+
+
 1.4.1 -- 2019-09-20
 ===================
 

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/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):
@@ -152,3 +158,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)

test/unit/test_client.py

@@ -17,7 +17,12 @@
 import aws_encryption_sdk
 import aws_encryption_sdk.internal.defaults
 
+from .vectors import VALUES
+
 pytestmark = [pytest.mark.unit, pytest.mark.local]
+_CIPHERTEXT = b"CIPHERTEXT"
+_PLAINTEXT = b"PLAINTEXT"
+_HEADER = VALUES["deserialized_header_frame"]
 
 
 class TestAwsEncryptionSdk(object):
@@ -27,16 +32,16 @@ def apply_fixtures(self):
         self.mock_stream_encryptor_patcher = patch("aws_encryption_sdk.StreamEncryptor")
         self.mock_stream_encryptor = self.mock_stream_encryptor_patcher.start()
         self.mock_stream_encryptor_instance = MagicMock()
-        self.mock_stream_encryptor_instance.read.return_value = sentinel.ciphertext
-        self.mock_stream_encryptor_instance.header = sentinel.header
+        self.mock_stream_encryptor_instance.read.return_value = _CIPHERTEXT
+        self.mock_stream_encryptor_instance.header = _HEADER
         self.mock_stream_encryptor.return_value = self.mock_stream_encryptor_instance
         self.mock_stream_encryptor_instance.__enter__.return_value = self.mock_stream_encryptor_instance
         # Set up StreamDecryptor patch
         self.mock_stream_decryptor_patcher = patch("aws_encryption_sdk.StreamDecryptor")
         self.mock_stream_decryptor = self.mock_stream_decryptor_patcher.start()
         self.mock_stream_decryptor_instance = MagicMock()
-        self.mock_stream_decryptor_instance.read.return_value = sentinel.plaintext
-        self.mock_stream_decryptor_instance.header = sentinel.header
+        self.mock_stream_decryptor_instance.read.return_value = _PLAINTEXT
+        self.mock_stream_decryptor_instance.header = _HEADER
         self.mock_stream_decryptor.return_value = self.mock_stream_decryptor_instance
         self.mock_stream_decryptor_instance.__enter__.return_value = self.mock_stream_decryptor_instance
         yield
@@ -47,14 +52,14 @@ def apply_fixtures(self):
     def test_encrypt(self):
         test_ciphertext, test_header = aws_encryption_sdk.encrypt(a=sentinel.a, b=sentinel.b, c=sentinel.b)
         self.mock_stream_encryptor.called_once_with(a=sentinel.a, b=sentinel.b, c=sentinel.b)
-        assert test_ciphertext is sentinel.ciphertext
-        assert test_header is sentinel.header
+        assert test_ciphertext is _CIPHERTEXT
+        assert test_header is _HEADER
 
     def test_decrypt(self):
         test_plaintext, test_header = aws_encryption_sdk.decrypt(a=sentinel.a, b=sentinel.b, c=sentinel.b)
         self.mock_stream_encryptor.called_once_with(a=sentinel.a, b=sentinel.b, c=sentinel.b)
-        assert test_plaintext is sentinel.plaintext
-        assert test_header is sentinel.header
+        assert test_plaintext is _PLAINTEXT
+        assert test_header is _HEADER
 
     def test_stream_encryptor_e(self):
         test = aws_encryption_sdk.stream(mode="e", a=sentinel.a, b=sentinel.b, c=sentinel.b)