Keyring base API

src/aws_encryption_sdk/keyring/base.py

@@ -0,0 +1,54 @@
+# Copyright 2017 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.
+"""Base class interface for Keyrings."""
+from aws_encryption_sdk.materials_managers import DecryptionMaterials, EncryptionMaterials
+from aws_encryption_sdk.structures import EncryptedDataKey
+
+try:  # Python 3.5.0 and 3.5.1 have incompatible typing modules
+    from typing import Iterable  # noqa pylint: disable=unused-import
+except ImportError:  # pragma: no cover
+    # We only actually need these imports when running the mypy checks
+    pass
+
+
+class Keyring(object):
+    """Parent interface for Keyring classes.
+
+    .. versionadded:: 1.5.0
+    """
+
+    def on_encrypt(self, encryption_materials):
+        # type: (EncryptionMaterials) -> EncryptionMaterials
+        """Generate a data key if not present and encrypt it using any available wrapping key.
+
+        :param encryption_materials: Encryption materials for the keyring to modify.
+        :type encryption_materials: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :returns: Optionally modified encryption materials.
+        :rtype: aws_encryption_sdk.materials_managers.EncryptionMaterials
+        :raises NotImplementedError: if method is not implemented
+        """
+        raise NotImplementedError("Keyring does not implement on_encrypt function")
+
+    def on_decrypt(self, decryption_materials, encrypted_data_keys):
+        # type: (DecryptionMaterials, Iterable[EncryptedDataKey]) -> DecryptionMaterials
+        """Attempt to decrypt the encrypted data keys.
+
+        :param decryption_materials: Decryption materials for the keyring to modify.
+        :type decryption_materials: aws_encryption_sdk.materials_managers.DecryptionMaterials
+        :param encrypted_data_keys: List of encrypted data keys.
+        :type: Iterable of :class:`aws_encryption_sdk.structures.EncryptedDataKey`
+        :returns: Optionally modified decryption materials.
+        :rtype: aws_encryption_sdk.materials_managers.DecryptionMaterials
+        :raises NotImplementedError: if method is not implemented
+        """
+        raise NotImplementedError("Keyring does not implement on_decrypt function")