diff options
| -rw-r--r-- | cryptography/hazmat/bindings/interfaces.py | 66 | ||||
| -rw-r--r-- | cryptography/hazmat/bindings/openssl/backend.py | 6 | ||||
| -rw-r--r-- | docs/hazmat/bindings/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/bindings/interfaces.rst | 137 |
4 files changed, 210 insertions, 0 deletions
diff --git a/cryptography/hazmat/bindings/interfaces.py b/cryptography/hazmat/bindings/interfaces.py new file mode 100644 index 00000000..912476bb --- /dev/null +++ b/cryptography/hazmat/bindings/interfaces.py @@ -0,0 +1,66 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License 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 __future__ import absolute_import, division, print_function + +import abc + +import six + + +class CipherBackend(six.with_metaclass(abc.ABCMeta)): + @abc.abstractmethod + def cipher_supported(self, cipher, mode): + """ + Return True if the given cipher and mode are supported. + """ + + @abc.abstractmethod + def register_cipher_adapter(self, cipher, mode, adapter): + """ + Register an adapter for a cipher and mode to a backend specific object. + """ + + @abc.abstractmethod + def create_symmetric_encryption_ctx(self, cipher, mode): + """ + Get a CipherContext that can be used for encryption. + """ + + @abc.abstractmethod + def create_symmetric_decryption_ctx(self, cipher, mode): + """ + Get a CipherContext that can be used for decryption. + """ + + +class HashBackend(six.with_metaclass(abc.ABCMeta)): + @abc.abstractmethod + def hash_supported(self, algorithm): + """ + Return True if the hash algorithm is supported by this backend. + """ + + @abc.abstractmethod + def create_hash_ctx(self, algorithm): + """ + Create a HashContext for calculating a message digest. + """ + + +class HMACBackend(six.with_metaclass(abc.ABCMeta)): + @abc.abstractmethod + def create_hmac_ctx(self, key, algorithm): + """ + Create a HashContext for calculating a message authentication code. + """ diff --git a/cryptography/hazmat/bindings/openssl/backend.py b/cryptography/hazmat/bindings/openssl/backend.py index 92cd3868..db4d18e7 100644 --- a/cryptography/hazmat/bindings/openssl/backend.py +++ b/cryptography/hazmat/bindings/openssl/backend.py @@ -20,6 +20,9 @@ import cffi from cryptography import utils from cryptography.exceptions import UnsupportedAlgorithm +from cryptography.hazmat.bindings.interfaces import ( + CipherBackend, HashBackend, HMACBackend +) from cryptography.hazmat.primitives import interfaces from cryptography.hazmat.primitives.ciphers.algorithms import ( AES, Blowfish, Camellia, CAST5, TripleDES, ARC4, @@ -29,6 +32,9 @@ from cryptography.hazmat.primitives.ciphers.modes import ( ) +@utils.register_interface(CipherBackend) +@utils.register_interface(HashBackend) +@utils.register_interface(HMACBackend) class Backend(object): """ OpenSSL API wrapper. diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index 19e03999..11355bfa 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -7,3 +7,4 @@ Bindings :maxdepth: 1 openssl + interfaces diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst new file mode 100644 index 00000000..c55d86dc --- /dev/null +++ b/docs/hazmat/bindings/interfaces.rst @@ -0,0 +1,137 @@ +.. hazmat:: + +Backend Interfaces +================== + +.. currentmodule:: cryptography.hazmat.bindings.interfaces + + +Backend implementations may provide a number of interfaces to support operations +such as :doc:`/hazmat/primitives/symmetric-encryption`, +:doc:`/hazmat/primitives/cryptographic-hashes`, and +:doc:`/hazmat/primitives/hmac`. + +A specific ``backend`` may provide one or more of these interfaces. + + +.. class:: CipherBackend + + A backend which provides methods for using ciphers for encryption + and decryption. + + .. method:: cipher_supported(cipher, mode) + + Check if a ``cipher`` and ``mode`` combination is supported by + this backend. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: ``True`` if the specified ``cipher`` and ``mode`` combination + is supported by this backend, otherwise ``False`` + + .. method:: register_cipher_adapter(cipher_cls, mode_cls, adapter) + + Register an adapter which can be used to create a backend specific + object from instances of the + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` and + the :class:`~cryptography.hazmat.primitives.interfaces.Mode` primitives. + + :param cipher_cls: A class whose instances provide + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :param mode_cls: A class whose instances provide: + :class:`~cryptography.hazmat.primitives.interfaces.Mode` + :param adapter: A ``function`` that takes 3 arguments, ``backend`` (a + :class:`CipherBackend` provider), ``cipher`` (a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider ), and ``mode`` (a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider). + It returns a backend specific object which may be used to construct + a :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext`. + + + .. method:: create_symmetric_encryption_ctx(cipher, mode) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + can be used for encrypting data with the symmetric ``cipher`` using + the given ``mode``. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + + + .. method:: create_symmetric_decryption_ctx(cipher, mode) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that + can be used for decrypting data with the symmetric ``cipher`` using + the given ``mode``. + + :param cipher: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + provider. + :param mode: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + + +.. class:: HashBackend + + A backend with methods for using cryptographic hash functions. + + .. method:: hash_supported(algorithm) + + Check if the specified ``algorithm`` is supported by this backend. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported by this + backend, otherwise ``False``. + + + .. method:: create_hash_ctx(algorithm) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + uses the specified ``algorithm`` to calculate a message digest. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` + + +.. class:: HMACBackend + + A backend with methods for using cryptographic hash functions as message + authentication codes. + + .. method:: create_hmac_ctx(algorithm) + + Create a + :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that + uses the specified ``algorithm`` to calculate a hash-based message + authentication code. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` |