Merge branch 'keyring' into moar-examples

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/identifiers.py

@@ -14,6 +14,7 @@
 import struct
 from enum import Enum
 
+import attr
 from cryptography.hazmat.primitives import hashes
 from cryptography.hazmat.primitives.asymmetric import ec, padding, rsa
 from cryptography.hazmat.primitives.ciphers import algorithms, modes
@@ -333,8 +334,22 @@ class ContentAADString(Enum):
 class KeyringTraceFlag(Enum):
     """KeyRing Trace actions."""
 
-    WRAPPING_KEY_GENERATED_DATA_KEY = 1
-    WRAPPING_KEY_ENCRYPTED_DATA_KEY = 1 << 1
-    WRAPPING_KEY_DECRYPTED_DATA_KEY = 1 << 2
-    WRAPPING_KEY_SIGNED_ENC_CTX = 1 << 3
-    WRAPPING_KEY_VERIFIED_ENC_CTX = 1 << 4
+    @attr.s
+    class KeyringTraceFlagValue(object):
+        """Keyring trace flags do not have defined serializable values."""
+
+        name = attr.ib()
+
+    #: A flag to represent that a keyring has generated a plaintext data key.
+    GENERATED_DATA_KEY = KeyringTraceFlagValue("GENERATED_DATA_KEY")
+    #: A flag to represent that a keyring has created an encrypted data key.
+    ENCRYPTED_DATA_KEY = KeyringTraceFlagValue("ENCRYPTED_DATA_KEY")
+    #: A flag to represent that a keyring has obtained
+    #: the corresponding plaintext data key from an encrypted data key.
+    DECRYPTED_DATA_KEY = KeyringTraceFlagValue("DECRYPTED_DATA_KEY")
+    #: A flag to represent that the keyring has cryptographically
+    #: bound the encryption context to a newly created encrypted data key.
+    SIGNED_ENCRYPTION_CONTEXT = KeyringTraceFlagValue("SIGNED_ENCRYPTION_CONTEXT")
+    #: A flag to represent that the keyring has verified that an encrypted
+    #: data key was originally created with a particular encryption context.
+    VERIFIED_ENCRYPTION_CONTEXT = KeyringTraceFlagValue("VERIFIED_ENCRYPTION_CONTEXT")

src/aws_encryption_sdk/keyrings/aws_kms/__init__.py

@@ -34,9 +34,9 @@
 
 _LOGGER = logging.getLogger(__name__)
 _PROVIDER_ID = "aws-kms"
-_GENERATE_FLAGS = {KeyringTraceFlag.WRAPPING_KEY_GENERATED_DATA_KEY}
-_ENCRYPT_FLAGS = {KeyringTraceFlag.WRAPPING_KEY_ENCRYPTED_DATA_KEY, KeyringTraceFlag.WRAPPING_KEY_SIGNED_ENC_CTX}
-_DECRYPT_FLAGS = {KeyringTraceFlag.WRAPPING_KEY_DECRYPTED_DATA_KEY, KeyringTraceFlag.WRAPPING_KEY_VERIFIED_ENC_CTX}
+_GENERATE_FLAGS = {KeyringTraceFlag.GENERATED_DATA_KEY}
+_ENCRYPT_FLAGS = {KeyringTraceFlag.ENCRYPTED_DATA_KEY, KeyringTraceFlag.SIGNED_ENCRYPTION_CONTEXT}
+_DECRYPT_FLAGS = {KeyringTraceFlag.DECRYPTED_DATA_KEY, KeyringTraceFlag.VERIFIED_ENCRYPTION_CONTEXT}
 
 
 @attr.s

src/aws_encryption_sdk/keyrings/raw.py

@@ -52,7 +52,7 @@ def _generate_data_key(encryption_materials, key_provider):
         raise GenerateKeyError("Unable to generate data encryption key.")
 
     # Create a keyring trace
-    keyring_trace = KeyringTrace(wrapping_key=key_provider, flags={KeyringTraceFlag.WRAPPING_KEY_GENERATED_DATA_KEY})
+    keyring_trace = KeyringTrace(wrapping_key=key_provider, flags={KeyringTraceFlag.GENERATED_DATA_KEY})
 
     # plaintext_data_key to RawDataKey
     data_encryption_key = RawDataKey(key_provider=key_provider, data_key=plaintext_data_key)
@@ -147,7 +147,7 @@ def on_encrypt(self, encryption_materials):
 
         # Update Keyring Trace
         keyring_trace = KeyringTrace(
-            wrapping_key=encrypted_data_key.key_provider, flags={KeyringTraceFlag.WRAPPING_KEY_ENCRYPTED_DATA_KEY}
+            wrapping_key=encrypted_data_key.key_provider, flags={KeyringTraceFlag.ENCRYPTED_DATA_KEY}
         )
 
         # Add encrypted data key to encryption_materials
@@ -198,9 +198,7 @@ def on_decrypt(self, decryption_materials, encrypted_data_keys):
                 return decryption_materials
 
             # Create a keyring trace
-            keyring_trace = KeyringTrace(
-                wrapping_key=self._key_provider, flags={KeyringTraceFlag.WRAPPING_KEY_DECRYPTED_DATA_KEY}
-            )
+            keyring_trace = KeyringTrace(wrapping_key=self._key_provider, flags={KeyringTraceFlag.DECRYPTED_DATA_KEY})
 
             # Update decryption materials
             data_encryption_key = RawDataKey(key_provider=self._key_provider, data_key=plaintext_data_key)
@@ -365,7 +363,7 @@ def on_encrypt(self, encryption_materials):
 
         # Update Keyring Trace
         keyring_trace = KeyringTrace(
-            wrapping_key=encrypted_data_key.key_provider, flags={KeyringTraceFlag.WRAPPING_KEY_ENCRYPTED_DATA_KEY}
+            wrapping_key=encrypted_data_key.key_provider, flags={KeyringTraceFlag.ENCRYPTED_DATA_KEY}
         )
 
         # Add encrypted data key to encryption_materials
@@ -406,9 +404,7 @@ def on_decrypt(self, decryption_materials, encrypted_data_keys):
                 continue
 
             # Create a keyring trace
-            keyring_trace = KeyringTrace(
-                wrapping_key=self._key_provider, flags={KeyringTraceFlag.WRAPPING_KEY_DECRYPTED_DATA_KEY}
-            )
+            keyring_trace = KeyringTrace(wrapping_key=self._key_provider, flags={KeyringTraceFlag.DECRYPTED_DATA_KEY})
 
             # Update decryption materials
             data_encryption_key = RawDataKey(key_provider=self._key_provider, data_key=plaintext_data_key)

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)
 
@@ -280,7 +280,7 @@ def add_data_encryption_key(self, data_encryption_key, keyring_trace):
         self._add_data_encryption_key(
             data_encryption_key=data_encryption_key,
             keyring_trace=keyring_trace,
-            required_flags={KeyringTraceFlag.WRAPPING_KEY_GENERATED_DATA_KEY},
+            required_flags={KeyringTraceFlag.GENERATED_DATA_KEY},
         )
 
     def add_encrypted_data_key(self, encrypted_data_key, keyring_trace):
@@ -299,7 +299,7 @@ def add_encrypted_data_key(self, encrypted_data_key, keyring_trace):
         if self.data_encryption_key is None:
             raise AttributeError("Data encryption key is not set.")
 
-        if KeyringTraceFlag.WRAPPING_KEY_ENCRYPTED_DATA_KEY not in keyring_trace.flags:
+        if KeyringTraceFlag.ENCRYPTED_DATA_KEY not in keyring_trace.flags:
             raise InvalidKeyringTraceError("Keyring flags do not match action.")
 
         if keyring_trace.wrapping_key != encrypted_data_key.key_provider:
@@ -445,7 +445,7 @@ def add_data_encryption_key(self, data_encryption_key, keyring_trace):
         self._add_data_encryption_key(
             data_encryption_key=data_encryption_key,
             keyring_trace=keyring_trace,
-            required_flags={KeyringTraceFlag.WRAPPING_KEY_DECRYPTED_DATA_KEY},
+            required_flags={KeyringTraceFlag.DECRYPTED_DATA_KEY},
         )
 
     def add_verification_key(self, verification_key):

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)