Merge pull request #1668 from reaperhulk/move-kdf-interfaces

move KDF interface

7 files changed, 92 insertions, 63 deletions

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 6439a4c8..97b0d6c7 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -10,6 +10,9 @@ Changelog
   now load elliptic curve public keys.
 * Added
   :func:`~cryptography.hazmat.primitives.asymmetric.rsa.rsa_recover_prime_factors`
+* :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction` was moved
+  from :mod:`~cryptography.hazmat.primitives.interfaces` to
+  :mod:`~cryptography.hazmat.primitives.kdf`.
 * :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` and
   :class:`~cryptography.hazmat.primitives.hashes.HashContext` were moved from
   :mod:`~cryptography.hazmat.primitives.interfaces` to
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 6029d1a9..f58d324d 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -47,46 +47,8 @@ In 0.8 the EC key interfaces were moved to the
 Key derivation functions
 ------------------------
 
-.. class:: KeyDerivationFunction
-
-    .. versionadded:: 0.2
-
-    .. method:: derive(key_material)
-
-        :param bytes key_material: The input key material. Depending on what
-                                   key derivation function you are using this
-                                   could be either random bytes, or a user
-                                   supplied password.
-        :return: The new key.
-        :raises cryptography.exceptions.AlreadyFinalized: This is raised when
-                                                          :meth:`derive` or
-                                                          :meth:`verify` is
-                                                          called more than
-                                                          once.
-
-        This generates and returns a new key from the supplied key material.
-
-    .. method:: verify(key_material, expected_key)
-
-        :param bytes key_material: The input key material. This is the same as
-                                   ``key_material`` in :meth:`derive`.
-        :param bytes expected_key: The expected result of deriving a new key,
-                                   this is the same as the return value of
-                                   :meth:`derive`.
-        :raises cryptography.exceptions.InvalidKey: This is raised when the
-                                                    derived key does not match
-                                                    the expected key.
-        :raises cryptography.exceptions.AlreadyFinalized: This is raised when
-                                                          :meth:`derive` or
-                                                          :meth:`verify` is
-                                                          called more than
-                                                          once.
-
-        This checks whether deriving a new key from the supplied
-        ``key_material`` generates the same key as the ``expected_key``, and
-        raises an exception if they do not match. This can be used for
-        something like checking whether a user's password attempt matches the
-        stored derived key.
+In 0.8 the key derivation function interface was moved to the
+:mod:`cryptography.hazmat.primitives.kdf` module.
 
 
 `Message Authentication Code`_
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index 4a47159f..78d40315 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -3,7 +3,7 @@
 Key derivation functions
 ========================
 
-.. currentmodule:: cryptography.hazmat.primitives.kdf
+.. module:: cryptography.hazmat.primitives.kdf
 
 Key derivation functions derive bytes suitable for cryptographic operations
 from passwords or other data sources using a pseudo-random function (PRF).
@@ -38,7 +38,7 @@ Different KDFs are suitable for different tasks such as:
     considered a better solution.
 
     This class conforms to the
-    :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction`
+    :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction`
     interface.
 
     .. doctest::
@@ -324,6 +324,53 @@ Different KDFs are suitable for different tasks such as:
         ``key_material`` generates the same key as the ``expected_key``, and
         raises an exception if they do not match.
 
+Interface
+~~~~~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf
+
+.. class:: KeyDerivationFunction
+
+    .. versionadded:: 0.2
+
+    .. method:: derive(key_material)
+
+        :param bytes key_material: The input key material. Depending on what
+                                   key derivation function you are using this
+                                   could be either random bytes, or a user
+                                   supplied password.
+        :return: The new key.
+        :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+                                                          :meth:`derive` or
+                                                          :meth:`verify` is
+                                                          called more than
+                                                          once.
+
+        This generates and returns a new key from the supplied key material.
+
+    .. method:: verify(key_material, expected_key)
+
+        :param bytes key_material: The input key material. This is the same as
+                                   ``key_material`` in :meth:`derive`.
+        :param bytes expected_key: The expected result of deriving a new key,
+                                   this is the same as the return value of
+                                   :meth:`derive`.
+        :raises cryptography.exceptions.InvalidKey: This is raised when the
+                                                    derived key does not match
+                                                    the expected key.
+        :raises cryptography.exceptions.AlreadyFinalized: This is raised when
+                                                          :meth:`derive` or
+                                                          :meth:`verify` is
+                                                          called more than
+                                                          once.
+
+        This checks whether deriving a new key from the supplied
+        ``key_material`` generates the same key as the ``expected_key``, and
+        raises an exception if they do not match. This can be used for
+        something like checking whether a user's password attempt matches the
+        stored derived key.
+
+
 .. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf
 .. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet
 .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
diff --git a/src/cryptography/hazmat/primitives/interfaces/__init__.py b/src/cryptography/hazmat/primitives/interfaces/__init__.py
index acd56458..6b4241bd 100644
--- a/src/cryptography/hazmat/primitives/interfaces/__init__.py
+++ b/src/cryptography/hazmat/primitives/interfaces/__init__.py
@@ -15,6 +15,7 @@ from cryptography.hazmat.primitives.asymmetric import (
     padding, rsa
 )
 from cryptography.hazmat.primitives.ciphers import modes
+from cryptography.hazmat.primitives.kdf import KeyDerivationFunction
 from cryptography.hazmat.primitives.padding import PaddingContext
 
 
@@ -347,22 +348,15 @@ AsymmetricVerificationContext = utils.deprecated(
     utils.DeprecatedIn08
 )
 
-
-@six.add_metaclass(abc.ABCMeta)
-class KeyDerivationFunction(object):
-    @abc.abstractmethod
-    def derive(self, key_material):
-        """
-        Deterministically generates and returns a new key based on the existing
-        key material.
-        """
-
-    @abc.abstractmethod
-    def verify(self, key_material, expected_key):
-        """
-        Checks whether the key generated by the key material matches the
-        expected derived key. Raises an exception if they do not match.
-        """
+KeyDerivationFunction = utils.deprecated(
+    KeyDerivationFunction,
+    __name__,
+    (
+        "The KeyDerivationFunction interface has moved to the "
+        "cryptography.hazmat.primitives.kdf module"
+    ),
+    utils.DeprecatedIn08
+)
 
 
 @six.add_metaclass(abc.ABCMeta)
diff --git a/src/cryptography/hazmat/primitives/kdf/__init__.py b/src/cryptography/hazmat/primitives/kdf/__init__.py
index 4b540884..2d0724e5 100644
--- a/src/cryptography/hazmat/primitives/kdf/__init__.py
+++ b/src/cryptography/hazmat/primitives/kdf/__init__.py
@@ -3,3 +3,24 @@
 # for complete details.
 
 from __future__ import absolute_import, division, print_function
+
+import abc
+
+import six
+
+
+@six.add_metaclass(abc.ABCMeta)
+class KeyDerivationFunction(object):
+    @abc.abstractmethod
+    def derive(self, key_material):
+        """
+        Deterministically generates and returns a new key based on the existing
+        key material.
+        """
+
+    @abc.abstractmethod
+    def verify(self, key_material, expected_key):
+        """
+        Checks whether the key generated by the key material matches the
+        expected derived key. Raises an exception if they do not match.
+        """
diff --git a/src/cryptography/hazmat/primitives/kdf/hkdf.py b/src/cryptography/hazmat/primitives/kdf/hkdf.py
index 3d4c9fb1..65b7091a 100644
--- a/src/cryptography/hazmat/primitives/kdf/hkdf.py
+++ b/src/cryptography/hazmat/primitives/kdf/hkdf.py
@@ -11,10 +11,11 @@ from cryptography.exceptions import (
     AlreadyFinalized, InvalidKey, UnsupportedAlgorithm, _Reasons
 )
 from cryptography.hazmat.backends.interfaces import HMACBackend
-from cryptography.hazmat.primitives import constant_time, hmac, interfaces
+from cryptography.hazmat.primitives import constant_time, hmac
+from cryptography.hazmat.primitives.kdf import KeyDerivationFunction
 
 
-@utils.register_interface(interfaces.KeyDerivationFunction)
+@utils.register_interface(KeyDerivationFunction)
 class HKDF(object):
     def __init__(self, algorithm, length, salt, info, backend):
         if not isinstance(backend, HMACBackend):
@@ -53,7 +54,7 @@ class HKDF(object):
             raise InvalidKey
 
 
-@utils.register_interface(interfaces.KeyDerivationFunction)
+@utils.register_interface(KeyDerivationFunction)
 class HKDFExpand(object):
     def __init__(self, algorithm, length, info, backend):
         if not isinstance(backend, HMACBackend):
diff --git a/src/cryptography/hazmat/primitives/kdf/pbkdf2.py b/src/cryptography/hazmat/primitives/kdf/pbkdf2.py
index 3d565be2..f8ce7a3b 100644
--- a/src/cryptography/hazmat/primitives/kdf/pbkdf2.py
+++ b/src/cryptography/hazmat/primitives/kdf/pbkdf2.py
@@ -9,10 +9,11 @@ from cryptography.exceptions import (
     AlreadyFinalized, InvalidKey, UnsupportedAlgorithm, _Reasons
 )
 from cryptography.hazmat.backends.interfaces import PBKDF2HMACBackend
-from cryptography.hazmat.primitives import constant_time, interfaces
+from cryptography.hazmat.primitives import constant_time
+from cryptography.hazmat.primitives.kdf import KeyDerivationFunction
 
 
-@utils.register_interface(interfaces.KeyDerivationFunction)
+@utils.register_interface(KeyDerivationFunction)
 class PBKDF2HMAC(object):
     def __init__(self, algorithm, length, salt, iterations, backend):
         if not isinstance(backend, PBKDF2HMACBackend):