From 2a746ce5a4e4b69c9c8fa3ab0e90fb87b053a186 Mon Sep 17 00:00:00 2001 From: David Reid Date: Fri, 15 Nov 2013 15:32:14 -0800 Subject: Start documenting the backend interfaces. --- docs/hazmat/bindings/index.rst | 1 + docs/hazmat/bindings/interfaces.rst | 43 +++++++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 docs/hazmat/bindings/interfaces.rst (limited to 'docs/hazmat') 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..2f163267 --- /dev/null +++ b/docs/hazmat/bindings/interfaces.rst @@ -0,0 +1,43 @@ +.. hazmat:: + +Backend Interfaces +================== + +.. currentmodule:: cryptography.hazmat.bindings.interfaces + + +.. class:: CipherBackend + + .. method:: cipher_supported(cipher, mode) + + pass + + .. method:: register_cipher_adapter(cipher_cls, mode_cls, adapter) + + pass + + .. method:: create_symmetric_encryption_ctx(cipher, mode) + + pass + + .. method:: create_symmetric_decryption_ctx(cipher, mode) + + pass + + +.. class:: HashBackend + + .. method:: hash_supported(algorithm) + + pass + + .. method:: create_hash_ctx(algorithm) + + pass + + +.. class:: HMACBackend + + .. method:: create_hmac_ctx(algorithm) + + pass -- cgit v1.2.3 From 5973f4cc78a5afeab010d44fc7962660158f1d30 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 18 Nov 2013 11:29:44 -0800 Subject: Document backend interfaces. --- docs/hazmat/bindings/interfaces.rst | 89 ++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 7 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst index 2f163267..851b31a9 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/bindings/interfaces.rst @@ -8,36 +8,111 @@ Backend Interfaces .. class:: CipherBackend + A backend which provides methods for using ciphers for encryption + and decryption. + .. method:: cipher_supported(cipher, mode) - pass + 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) - pass + 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) - pass + 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) - pass + 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) - pass + :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) - pass + :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) - pass + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.HashContext` -- cgit v1.2.3 From 6624a444c665ff6655cb0f2b9cece131afab6e49 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 18 Nov 2013 12:44:30 -0800 Subject: Hashes and HMACs. --- docs/hazmat/bindings/interfaces.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst index 851b31a9..98c099bb 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/bindings/interfaces.rst @@ -85,6 +85,8 @@ Backend Interfaces .. 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. @@ -95,6 +97,10 @@ Backend Interfaces .. 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. @@ -110,6 +116,11 @@ Backend Interfaces .. 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. -- cgit v1.2.3 From 6b9df81232514bd36c14a07ef3beb901ddb2af7a Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 18 Nov 2013 14:13:02 -0800 Subject: Describe what backends provide via these interfaces and that not all backends must provide all interfaces. --- docs/hazmat/bindings/interfaces.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/bindings/interfaces.rst b/docs/hazmat/bindings/interfaces.rst index 98c099bb..c55d86dc 100644 --- a/docs/hazmat/bindings/interfaces.rst +++ b/docs/hazmat/bindings/interfaces.rst @@ -6,6 +6,14 @@ 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 -- cgit v1.2.3