pre-release update

Author: mattsb42-aws

aws_encryption_sdk/__init__.py

@@ -8,6 +8,12 @@
 def encrypt(**kwargs):
     """Encrypts and serializes provided plaintext.
 
+    .. note::
+        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`.
+
+    .. code:: python
+
         >>> import aws_encryption_sdk
         >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(key_ids=[
         ...     'arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222',
@@ -49,6 +55,12 @@ def encrypt(**kwargs):
 def decrypt(**kwargs):
     """Deserializes and decrypts provided ciphertext.
 
+    .. note::
+        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`.
+
+    .. code:: python
+
         >>> import aws_encryption_sdk
         >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(key_ids=[
         ...     'arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222',
@@ -75,6 +87,8 @@ def decrypt(**kwargs):
         .. note::
             The concept of "lines" is used to match Python file-like-object terminology.  In this
             context it defines the number of bytes returned by readline().
+    :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 str and :class:`aws_encryption_sdk.structure.MessageHeader`
     """
@@ -86,6 +100,22 @@ def decrypt(**kwargs):
 def stream(**kwargs):
     """Provides an :py:func:`open`-like interface to the streaming encryptor/decryptor classes.
 
+    .. note::
+        Take care when decrypting framed messages with large frame length and large non-framed
+        messages. In order to protect the authenticity of the encrypted data, no plaintext
+        is returned until it has been authenticated. Because of this, potentially large amounts
+        of data may be read into memory.  In the case of framed messages, the entire contents
+        of each frame are read into memory and authenticated before returning any plaintext.
+        In the case of non-framed messages, the entire message is read into memory and
+        authenticated before returning any plaintext.  The authenticated plaintext is held in
+        memory until it is requested.
+
+    .. note::
+        Consequently, keep the above decrypting consideration in mind when encrypting messages
+        to ensure that issues are not encountered when decrypting those messages.
+
+    .. code:: python
+
         >>> import aws_encryption_sdk
         >>> kms_key_provider = aws_encryption_sdk.KMSMasterKeyProvider(key_ids=[
         ...     'arn:aws:kms:us-east-1:2222222222222:key/22222222-2222-2222-2222-222222222222',

aws_encryption_sdk/exceptions.py

@@ -9,6 +9,10 @@ class SerializationError(AWSEncryptionSDKClientError):
     """Exception class for serialization/deserialization errors."""
 
 
+class CustomMaximumValueExceeded(SerializationError):
+    """Exception class for use when values are found which exceed user-defined custom maximum values."""
+
+
 class UnknownIdentityError(AWSEncryptionSDKClientError):
     """Exception class for unknown identity errors."""
 

aws_encryption_sdk/identifiers.py

@@ -197,4 +197,4 @@ class ContentAADString(Enum):
     """Body Additional Authenticated Data values for building the AAD for a message body."""
     FRAME_STRING_ID = b'AWSKMSEncryptionClient Frame'
     FINAL_FRAME_STRING_ID = b'AWSKMSEncryptionClient Final Frame'
-    SINGLE_BLOCK_STRING_ID = b'AWSKMSEncryptionClient Single Block'
+    NON_FRAMED_STRING_ID = b'AWSKMSEncryptionClient Single Block'

aws_encryption_sdk/internal/defaults.py

@@ -26,8 +26,8 @@
 MAX_FRAME_COUNT = 4294967295  # 2 ** 32 - 1
 #: Maximum bytes allowed in a single frame as defined in specification
 MAX_FRAME_SIZE = 2147483647  # 2 ** 31 - 1
-#: Maximum bytes allowed in a single block message ciphertext as defined in specification
-MAX_SINGLE_BLOCK_SIZE = 68719476704  # 2 ** 36 - 32
+#: Maximum bytes allowed in a non-framed message ciphertext as defined in specification
+MAX_NON_FRAMED_SIZE = 68719476704  # 2 ** 36 - 32
 
 #: Maximum number of AAD bytes allowed as defined in specification
 MAX_BYTE_ARRAY_SIZE = 65535  # 2 ** 16 - 1

aws_encryption_sdk/internal/formatting/deserialize.py

@@ -175,6 +175,13 @@ def deserialize_header(stream):
     header['header_iv_length'] = iv_length
 
     (frame_length,) = unpack_values('>I', stream)
+    if content_type == ContentType.FRAMED_DATA and frame_length > aws_encryption_sdk.internal.defaults.MAX_FRAME_SIZE:
+        raise SerializationError('Specified frame length larger than allowed maximum: {found} > {max}'.format(
+            found=frame_length,
+            max=aws_encryption_sdk.internal.defaults.MAX_FRAME_SIZE
+        ))
+    elif content_type == ContentType.NO_FRAMING and frame_length != 0:
+        raise SerializationError('Non-zero frame length found for non-framed message')
     header['frame_length'] = frame_length
 
     return MessageHeader(**header)
@@ -200,8 +207,8 @@ def deserialize_header_auth(stream, algorithm, verifier=None):
     return MessageHeaderAuthentication(*unpack_values(format_string, stream, verifier))
 
 
-def deserialize_single_block_values(stream, header, verifier=None):
-    """Deserializes the IV and Tag from a single block stream.
+def deserialize_non_framed_values(stream, header, verifier=None):
+    """Deserializes the IV and Tag from a non-framed stream.
 
     :param stream: Source data stream
     :type stream: io.BytesIO
@@ -212,7 +219,7 @@ def deserialize_single_block_values(stream, header, verifier=None):
     :returns: IV, Tag, and Data Length values for body
     :rtype: tuple of str, str, and int
     """
-    _LOGGER.debug('Starting single block body iv/tag deserialization')
+    _LOGGER.debug('Starting non-framed body iv/tag deserialization')
     (data_iv, data_length) = unpack_values(
         '>{}sQ'.format(header.algorithm.iv_len),
         stream,
@@ -233,7 +240,7 @@ def update_verifier_with_tag(stream, header, verifier):
     """Updates verifier with data for authentication tag.
 
     .. note::
-        This is meant to be used in conjunction with deserialize_single_block_values
+        This is meant to be used in conjunction with deserialize_non_framed_values
         to update the verifier over information which has already been retrieved.
 
     :param stream: Source data stream
@@ -284,6 +291,11 @@ def deserialize_frame(stream, header, verifier=None):
     frame_data['iv'] = frame_iv
     if final_frame is True:
         (content_length,) = unpack_values('>I', stream, verifier)
+        if content_length >= header.frame_length:
+            raise SerializationError('Invalid final frame length: {final} >= {normal}'.format(
+                final=content_length,
+                normal=header.frame_length
+            ))
     else:
         content_length = header.frame_length
     (frame_content, frame_tag) = unpack_values(
@@ -312,19 +324,19 @@ def deserialize_footer(stream, verifier=None):
     """
     _LOGGER.debug('Starting footer deserialization')
     signature = b''
+    if verifier is None:
+        return MessageFooter(signature=signature)
     try:
         (sig_len,) = unpack_values('>H', stream)
         (signature,) = unpack_values(
             '>{sig_len}s'.format(sig_len=sig_len),
             stream
         )
-        if verifier:
-            verifier.set_signature(signature)
-            verifier.verify()
-    except struct.error:
-        # If there is a struct error, assume that there is no footer to read.
-        if verifier:
-            raise SerializationError('No signature found in message')
+    except SerializationError:
+        raise SerializationError('No signature found in message')
+    if verifier:
+        verifier.set_signature(signature)
+        verifier.verify()
     return MessageFooter(signature=signature)
 
 
@@ -340,10 +352,14 @@ def unpack_values(format_string, stream, verifier=None):
     :returns: Unpacked values
     :rtype: tuple
     """
-    message_bytes = stream.read(struct.calcsize(format_string))
-    if verifier:
-        verifier.update(message_bytes)
-    return struct.unpack(format_string, message_bytes)
+    try:
+        message_bytes = stream.read(struct.calcsize(format_string))
+        if verifier:
+            verifier.update(message_bytes)
+        values = struct.unpack(format_string, message_bytes)
+    except struct.error as e:
+        raise SerializationError('Unexpected deserialization error', type(e), e.args)
+    return values
 
 
 def deserialize_wrapped_key(wrapping_algorithm, wrapping_key_id, wrapped_encrypted_key):

aws_encryption_sdk/internal/formatting/serialize.py

@@ -131,7 +131,7 @@ def serialize_header_auth(algorithm, header, message_id, encryption_data_key, si
     return output
 
 
-def serialize_single_block_open(algorithm, iv, plaintext_length, signer=None):
+def serialize_non_framed_open(algorithm, iv, plaintext_length, signer=None):
     """Serializes the opening block for a non-framed message body.
 
     :param algorithm: Algorithm to use for encryption
@@ -160,7 +160,7 @@ def serialize_single_block_open(algorithm, iv, plaintext_length, signer=None):
     return body_start
 
 
-def serialize_single_block_close(tag, signer=None):
+def serialize_non_framed_close(tag, signer=None):
     """Serializes the closing block for a non-framed message body.
 
     :param bytes tag: Auth tag value from body encryptor

aws_encryption_sdk/internal/utils.py

@@ -72,7 +72,7 @@ def get_aad_content_string(content_type, is_final_frame):
     :raises UnknownIdentityError: if unknown content type
     """
     if content_type == ContentType.NO_FRAMING:
-        aad_content_string = ContentAADString.SINGLE_BLOCK_STRING_ID
+        aad_content_string = ContentAADString.NON_FRAMED_STRING_ID
     elif content_type == ContentType.FRAMED_DATA:
         if is_final_frame:
             aad_content_string = ContentAADString.FINAL_FRAME_STRING_ID

aws_encryption_sdk/key_providers/kms.py

@@ -13,7 +13,7 @@
 from aws_encryption_sdk.key_providers.base import (
     MasterKeyProvider, MasterKeyProviderConfig, MasterKey, MasterKeyConfig
 )
-from aws_encryption_sdk.structures import DataKey, EncryptedDataKey
+from aws_encryption_sdk.structures import DataKey, EncryptedDataKey, MasterKeyInfo
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -203,10 +203,14 @@ def _generate_data_key(self, algorithm, encryption_context=None):
             response = self.config.client.generate_data_key(**kms_params)
             plaintext = response['Plaintext']
             ciphertext = response['CiphertextBlob']
+            key_id = response['KeyId']
         except (ClientError, KeyError):
             raise GenerateKeyError('Master Key {key_id} unable to generate data key'.format(key_id=self._key_id))
         return DataKey(
-            key_provider=self.key_provider,
+            key_provider=MasterKeyInfo(
+                provider_id=self.provider_id,
+                key_info=key_id
+            ),
             data_key=plaintext,
             encrypted_data_key=ciphertext
         )
@@ -235,10 +239,14 @@ def _encrypt_data_key(self, data_key, algorithm, encryption_context=None):
         try:
             response = self.config.client.encrypt(**kms_params)
             ciphertext = response['CiphertextBlob']
+            key_id = response['KeyId']
         except (ClientError, KeyError):
             raise EncryptKeyError('Master Key {key_id} unable to encrypt data key'.format(key_id=self._key_id))
         return EncryptedDataKey(
-            key_provider=self.key_provider,
+            key_provider=MasterKeyInfo(
+                provider_id=self.provider_id,
+                key_info=key_id
+            ),
             encrypted_data_key=ciphertext
         )