From f8796b15a279db82cdefcd00bebfef4cdef8fee8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 13 Dec 2013 20:28:55 -0800 Subject: Renamed bindings to backends --- docs/architecture.rst | 6 +- docs/contributing.rst | 2 +- docs/hazmat/backends/index.rst | 34 ++++++ docs/hazmat/backends/interfaces.rst | 141 ++++++++++++++++++++++++ docs/hazmat/backends/openssl.rst | 25 +++++ docs/hazmat/bindings/index.rst | 34 ------ docs/hazmat/bindings/interfaces.rst | 141 ------------------------ docs/hazmat/bindings/openssl.rst | 25 ----- docs/hazmat/primitives/cryptographic-hashes.rst | 4 +- docs/hazmat/primitives/hmac.rst | 4 +- docs/hazmat/primitives/symmetric-encryption.rst | 8 +- docs/index.rst | 2 +- 12 files changed, 213 insertions(+), 213 deletions(-) create mode 100644 docs/hazmat/backends/index.rst create mode 100644 docs/hazmat/backends/interfaces.rst create mode 100644 docs/hazmat/backends/openssl.rst delete mode 100644 docs/hazmat/bindings/index.rst delete mode 100644 docs/hazmat/bindings/interfaces.rst delete mode 100644 docs/hazmat/bindings/openssl.rst (limited to 'docs') diff --git a/docs/architecture.rst b/docs/architecture.rst index 5ca2c252..bacde1bb 100644 --- a/docs/architecture.rst +++ b/docs/architecture.rst @@ -8,6 +8,6 @@ Architecture ``cryptography.hazmat.primitives``. * ``cryptography.hazmat.primitives``: This packages contains low level algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of - ``cryptography.hazmat.bindings``. -* ``cryptography.hazmat.bindings``: This package contains bindings to low level - cryptographic libraries. Our initial target will be OpenSSL. + ``cryptography.hazmat.backends``. +* ``cryptography.hazmat.backends``: This package contains bindings to low level + cryptographic libraries. Our initial target is OpenSSL. diff --git a/docs/contributing.rst b/docs/contributing.rst index a8010a9a..cb9c7283 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -79,7 +79,7 @@ whether the signature was valid. APIs at the :doc:`/hazmat/primitives/index` layer should always take an explicit backend, APIs at the recipes layer should automatically use the -:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +:func:`~cryptography.hazmat.backends.default_backend`, but optionally allow specifying a different backend. C bindings diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst new file mode 100644 index 00000000..a89cf0d5 --- /dev/null +++ b/docs/hazmat/backends/index.rst @@ -0,0 +1,34 @@ +.. hazmat:: + +Bindings +======== + +.. toctree:: + :maxdepth: 1 + + openssl + interfaces + + +Getting a Backend Provider +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: cryptography.hazmat.backends + +``cryptography`` aims to support multiple backends to ensure it can provide +the widest number of supported cryptographic algorithms as well as supporting +platform specific implementations. + +You can get the default backend by calling +:func:`~default_backend`. + +The default backend will change over time as we implement new backends and +the libraries we use in those backends changes. + + +.. function:: default_backend() + + :returns: An object that provides at least + :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and + :class:`~interfaces.HMACBackend`. + diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst new file mode 100644 index 00000000..b524943d --- /dev/null +++ b/docs/hazmat/backends/interfaces.rst @@ -0,0 +1,141 @@ +.. hazmat:: + +Backend Interfaces +================== + +.. currentmodule:: cryptography.hazmat.backends.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` + + :raises ValueError: When tag is not None in an AEAD mode + + + .. 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` + + :raises ValueError: When tag is None in an AEAD mode + + +.. 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` diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst new file mode 100644 index 00000000..12fbff04 --- /dev/null +++ b/docs/hazmat/backends/openssl.rst @@ -0,0 +1,25 @@ +.. hazmat:: + +OpenSSL +======= + +These are `CFFI`_ bindings to the `OpenSSL`_ C library. + +.. data:: cryptography.hazmat.backends.openssl.backend + + This is the exposed API for the OpenSSL bindings. It has two public + attributes: + + .. attribute:: ffi + + This is a :class:`cffi.FFI` instance. It can be used to allocate and + otherwise manipulate OpenSSL structures. + + .. attribute:: lib + + This is a ``cffi`` library. It can be used to call OpenSSL functions, + and access constants. + + +.. _`CFFI`: https://cffi.readthedocs.org/ +.. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst deleted file mode 100644 index 746f4596..00000000 --- a/docs/hazmat/bindings/index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. hazmat:: - -Bindings -======== - -.. toctree:: - :maxdepth: 1 - - openssl - interfaces - - -Getting a Backend Provider -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. currentmodule:: cryptography.hazmat.bindings - -``cryptography`` aims to support multiple backends to ensure it can provide -the widest number of supported cryptographic algorithms as well as supporting -platform specific implementations. - -You can get the default backend by calling -:func:`~default_backend`. - -The default backend will change over time as we implement new backends and -the libraries we use in those backends changes. - - -.. function:: default_backend() - - :returns: An object that provides at least - :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and - :class:`~interfaces.HMACBackend`. - diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst deleted file mode 100644 index 711c82c2..00000000 --- a/docs/hazmat/bindings/interfaces.rst +++ /dev/null @@ -1,141 +0,0 @@ -.. 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` - - :raises ValueError: When tag is not None in an AEAD mode - - - .. 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` - - :raises ValueError: When tag is None in an AEAD mode - - -.. 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` diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst deleted file mode 100644 index d6bfa672..00000000 --- a/docs/hazmat/bindings/openssl.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. hazmat:: - -OpenSSL -======= - -These are `CFFI`_ bindings to the `OpenSSL`_ C library. - -.. data:: cryptography.hazmat.bindings.openssl.backend - - This is the exposed API for the OpenSSL bindings. It has two public - attributes: - - .. attribute:: ffi - - This is a :class:`cffi.FFI` instance. It can be used to allocate and - otherwise manipulate OpenSSL structures. - - .. attribute:: lib - - This is a ``cffi`` library. It can be used to call OpenSSL functions, - and access constants. - - -.. _`CFFI`: https://cffi.readthedocs.org/ -.. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 312d7e69..90ca198a 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -20,7 +20,7 @@ Message Digests .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> digest = hashes.Hash(hashes.SHA256(), backend=default_backend()) >>> digest.update(b"abc") @@ -39,7 +39,7 @@ Message Digests provider such as those described in :ref:`below `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HashBackend` + :class:`~cryptography.hazmat.backends.interfaces.HashBackend` provider. .. method:: update(data) diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index db5e98d3..0c0d0220 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -27,7 +27,7 @@ message. .. doctest:: - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes, hmac >>> h = hmac.HMAC(key, hashes.SHA256(), backend=default_backend()) >>> h.update(b"message to hash") @@ -41,7 +41,7 @@ message. provider such as those described in :ref:`Cryptographic Hashes `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.HMACBackend` + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. .. method:: update(msg) diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index ef6f0871..9fccf552 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -34,7 +34,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> backend = default_backend() >>> cipher = Cipher(algorithms.AES(key), modes.CBC(iv), backend=backend) >>> encryptor = cipher.encryptor() @@ -51,7 +51,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. provider such as those described :ref:`below `. :param backend: A - :class:`~cryptography.hazmat.bindings.interfaces.CipherBackend` + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. .. method:: encryptor() @@ -229,7 +229,7 @@ Weak Ciphers .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> algorithm = algorithms.ARC4(key) >>> cipher = Cipher(algorithm, mode=None, backend=default_backend()) >>> encryptor = cipher.encryptor() @@ -356,7 +356,7 @@ Modes .. doctest:: >>> from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes - >>> from cryptography.hazmat.bindings import default_backend + >>> from cryptography.hazmat.backends import default_backend >>> cipher = Cipher(algorithms.AES(key), modes.GCM(iv), backend=default_backend()) >>> encryptor = cipher.encryptor() >>> encryptor.authenticate_additional_data(b"authenticated but not encrypted payload") diff --git a/docs/index.rst b/docs/index.rst index 2263c32f..776c9d37 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,4 +53,4 @@ Hazardous Materials :maxdepth: 2 hazmat/primitives/index - hazmat/bindings/index + hazmat/backends/index -- cgit v1.2.3