core identifiers, structures, and helpers

Author: mattsb42-aws

src/dynamodb_encryption_sdk/__init__.py

@@ -0,0 +1,34 @@
+# Copyright 2018 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.
+""""""
+from dynamodb_encryption_sdk.encrypted.item import (
+    decrypt_dynamodb_item, decrypt_python_item,
+    encrypt_dynamodb_item, encrypt_python_item
+)
+
+# encrypt_item
+# encrypt_raw_item
+# decrypt_item
+# decrypt_raw_item
+# EncryptedTable
+# EncryptedResource
+# EncryptedClient
+
+# TableConfiguration
+# MaterialDescription
+# ItemConfiguration
+
+__all__ = (
+    'decrypt_dynamodb_item', 'decrypt_python_item',
+    'encrypt_dynamodb_item', 'encrypt_python_item'
+)

src/dynamodb_encryption_sdk/exceptions.py

@@ -0,0 +1,86 @@
+# Copyright 2018 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.
+
+
+class DynamodbEncryptionSdkError(Exception):
+    """Base class for all custom exceptions."""
+
+
+class SerializationError(DynamodbEncryptionSdkError):
+    """Otherwise undifferentiated errors encountered while serializing data."""
+
+
+class DeserializationError(DynamodbEncryptionSdkError):
+    """Otherwise undifferentiated errors encountered while deserializing data."""
+
+
+class InvalidMaterialsetError(DeserializationError):
+    """Raised when errors are encountered processing a material description."""
+    # TODO: MaterialDescription, not Materialset...
+
+
+class InvalidMaterialsetVersionError(DeserializationError):
+    """Raised when a material description is encountered with an invalid version."""
+    # TODO: MaterialDescription, not Materialset...
+
+
+class InvalidAlgorithmError(DynamodbEncryptionSdkError):
+    """Raised when an invalid algorithm identifier is encountered."""
+
+
+class JceTransformationError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class DelegatedKeyError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class DelegatedKeyEncryptionError(DelegatedKeyError):
+    """"""
+
+
+class DelegatedKeyDecryptionError(DelegatedKeyError):
+    """"""
+
+
+class AwsKmsMaterialsProviderError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class UnknownRegionError(AwsKmsMaterialsProviderError):
+    """"""
+
+
+class DecryptionError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class UnwrappingError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class EncryptionError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class WrappingError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class SigningError(DynamodbEncryptionSdkError):
+    """"""
+
+
+class SignatureVerificationError(DynamodbEncryptionSdkError):
+    """"""

src/dynamodb_encryption_sdk/identifiers.py

@@ -0,0 +1,44 @@
+# Copyright 2018 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.
+from enum import Enum
+
+__version__ = '0.0.0'
+
+LOGGER_NAME = 'dynamodb_encryption_sdk'
+
+
+class ItemAction(Enum):
+    """Possible actions to take on an item attribute."""
+    DO_NOTHING = 0
+    SIGN_ONLY = 1
+    ENCRYPT_AND_SIGN = 2
+
+    def __lt__(self, other):
+        return self.value < other.value
+
+    def __eq__(self, other):
+        return self.value == other.value
+
+
+class EncryptionKeyTypes(Enum):
+    """Supported types of encryption keys."""
+    SYMMETRIC = 0
+    PRIVATE = 1
+    PUBLIC = 2
+
+
+class KeyEncodingType(Enum):
+    """Supported key encoding schemes."""
+    RAW = 0
+    DER = 1
+    PEM = 2

src/dynamodb_encryption_sdk/internal/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2018 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.
+"""Internal implementation details.
+
+.. warning::
+    No guarantee is provided on the modules and APIs within this
+    namespace staying consistent. Directly reference at your own risk.
+"""

src/dynamodb_encryption_sdk/internal/defaults.py

@@ -0,0 +1,17 @@
+# Copyright 2018 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.
+""""""
+
+ENCODING = 'utf-8'
+LOGGING_NAME = 'dynamodb_encryption_sdk'
+MATERIAL_DESCRIPTION_VERSION = b'\00' * 4

src/dynamodb_encryption_sdk/internal/identifiers.py

@@ -0,0 +1,102 @@
+# Copyright 2018 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.
+""""""
+from enum import Enum
+
+try:  # Python 3.5.0 and 3.5.1 have incompatible typing modules
+    from typing import Any, ByteString, Dict, List, Text, Union  # pylint: disable=unused-import
+except ImportError:  # pragma: no cover
+    # We only actually need these imports when running the mypy checks
+    pass
+
+
+class ReservedAttributes(Enum):
+    """Item attributes reserved for use by DynamoDBEncryptionClient"""
+    MATERIAL_DESCRIPTION = '*amzn-ddb-map-desc*'
+    SIGNATURE = '*amzn-ddb-map-sig*'
+
+
+class Tag(Enum):
+    """Attribute data type identifiers used for serialization and deserialization of attributes."""
+
+    BINARY = (b'b', 'B')
+    BINARY_SET = (b'B', 'BS', b'b')
+    NUMBER = (b'n', 'N')
+    NUMBER_SET = (b'N', 'NS', b'n')
+    STRING = (b's', 'S')
+    STRING_SET = (b'S', 'SS', b's')
+    BOOLEAN = (b'?', 'BOOL')
+    NULL = (b'\x00', 'NULL')
+    LIST = (b'L', 'L')
+    MAP = (b'M', 'M')
+
+    def __init__(self, tag, dynamodb_tag, element_tag=None):
+        # type: (bytes, Text, Optional[bytes]) -> None
+        """Sets up new Tag object.
+
+        :param bytes tag: DynamoDB Encryption SDK tag
+        :param bytes dynamodb_tag: DynamoDB tag
+        :param bytes element_tag: The type of tag contained within attributes of this type
+        """
+        self.tag = tag
+        self.dynamodb_tag = dynamodb_tag
+        self.element_tag = element_tag
+
+
+class TagValues(Enum):
+    """Static values to use when serializing attribute values."""
+    FALSE = b'\x00'
+    TRUE = b'\x01'
+
+
+class SignatureValues(Enum):
+    """Values used when building the string to sign.
+
+    .. note::
+
+        The only time we actually use these values, we use the SHA256 hash of the value, so
+        we pre-compute these hashes here.
+    """
+    ENCRYPTED = (
+        b'ENCRYPTED',
+        b"9A\x15\xacN\xb0\x9a\xa4\x94)4\x88\x16\xb2\x03\x81'\xb0\xf9\xe3\xa5 7*\xe1\x00\xca\x19\xfb\x08\xfdP"
+    )
+    PLAINTEXT = (
+        b'PLAINTEXT',
+        b'\xcb@\xe7\xda\xdc\x86\x16\x1b\x97\x98\xdeHQ/3-!\xc1A\xfc\xc1\xe2\x8a\x08o\xdeJ3u\xaa\xb1\xb5'
+    )
+
+    def __init__(self, raw, sha256):
+        # type: (bytes, bytes) -> None
+        """Set up a new SignatureValues object.
+
+        :param bytes raw: Raw value
+        :param bytes sha256: SHA256 hash of raw value
+        """
+        self.raw = raw
+        self.sha256 = sha256
+
+
+class MaterialDescriptionKeys(Enum):
+    """Static keys for use when building and reading material descriptions."""
+    ATTRIBUTE_ENCRYPTION_MODE = 'amzn-ddb-map-sym-mode'
+    SIGNING_KEY_ALGORITHM = 'amzn-ddb-map-signingAlg'
+    WRAPPED_DATA_KEY = 'amzn-ddb-env-key'
+    CONTENT_ENCRYPTION_ALGORITHM = 'amzn-ddb-env-alg'
+    CONTENT_KEY_WRAPPING_ALGORITHM = 'amzn-ddb-wrap-alg'
+    ITEM_SIGNATURE_ALGORITHM = 'amzn-ddb-sig-alg'
+
+
+class MaterialDescriptionValues(Enum):
+    """Static default values for use when building material descriptions."""
+    CBC_PKCS5_ATTRIBUTE_ENCRYPTION = '/CBC/PKCS5Padding'

src/dynamodb_encryption_sdk/internal/str_ops.py

@@ -0,0 +1,42 @@
+# Copyright 2018 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.
+"""Helper functions for consistently obtaining str and bytes objects in both Python2 and Python3."""
+import codecs
+
+import six
+
+
+def to_str(data):
+    """Takes an input str or bytes object and returns an equivalent str object.
+
+    :param data: Input data
+    :type data: str or bytes
+    :returns: Data normalized to str
+    :rtype: str
+    """
+    if isinstance(data, bytes):
+        return codecs.decode(data, 'utf-8')
+    return data
+
+
+def to_bytes(data):
+    """Takes an input str or bytes object and returns an equivalent bytes object.
+
+    :param data: Input data
+    :type data: str or bytes
+    :returns: Data normalized to bytes
+    :rtype: bytes
+    """
+    if isinstance(data, six.string_types) and not isinstance(data, bytes):
+        return codecs.encode(data, 'utf-8')
+    return data