Merge pull request #490 from dreid/hkdf

HKDF - RFC5869 implementation.

6 files changed, 447 insertions, 4 deletions

diff --git a/cryptography/hazmat/primitives/kdf/hkdf.py b/cryptography/hazmat/primitives/kdf/hkdf.py
new file mode 100644
index 00000000..af15b64d
--- /dev/null
+++ b/cryptography/hazmat/primitives/kdf/hkdf.py
@@ -0,0 +1,91 @@
+# 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.
+
+import six
+
+from cryptography import utils
+from cryptography.exceptions import AlreadyFinalized, InvalidKey
+from cryptography.hazmat.primitives import constant_time, hmac, interfaces
+
+
+@utils.register_interface(interfaces.KeyDerivationFunction)
+class HKDF(object):
+    def __init__(self, algorithm, length, salt, info, backend):
+        self._algorithm = algorithm
+
+        max_length = 255 * (algorithm.digest_size // 8)
+
+        if length > max_length:
+            raise ValueError(
+                "Can not derive keys larger than {0} octets.".format(
+                    max_length
+                ))
+
+        self._length = length
+
+        if isinstance(salt, six.text_type):
+            raise TypeError(
+                "Unicode-objects must be encoded before using them as a salt.")
+
+        if salt is None:
+            salt = b"\x00" * (self._algorithm.digest_size // 8)
+
+        self._salt = salt
+
+        if isinstance(info, six.text_type):
+            raise TypeError(
+                "Unicode-objects must be encoded before using them as info.")
+
+        if info is None:
+            info = b""
+
+        self._info = info
+        self._backend = backend
+
+        self._used = False
+
+    def _extract(self, key_material):
+        h = hmac.HMAC(self._salt, self._algorithm, backend=self._backend)
+        h.update(key_material)
+        return h.finalize()
+
+    def _expand(self, key_material):
+        output = [b""]
+        counter = 1
+
+        while (self._algorithm.digest_size // 8) * len(output) < self._length:
+            h = hmac.HMAC(key_material, self._algorithm, backend=self._backend)
+            h.update(output[-1])
+            h.update(self._info)
+            h.update(six.int2byte(counter))
+            output.append(h.finalize())
+            counter += 1
+
+        return b"".join(output)[:self._length]
+
+    def derive(self, key_material):
+        if isinstance(key_material, six.text_type):
+            raise TypeError(
+                "Unicode-objects must be encoded before using them as key "
+                "material."
+            )
+
+        if self._used:
+            raise AlreadyFinalized
+
+        self._used = True
+        return self._expand(self._extract(key_material))
+
+    def verify(self, key_material, expected_key):
+        if not constant_time.bytes_eq(self.derive(key_material), expected_key):
+            raise InvalidKey
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index f96eae06..1937c2ec 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -13,7 +13,8 @@ Different KDFs are suitable for different tasks such as:
 
     Deriving a key suitable for use as input to an encryption algorithm.
     Typically this means taking a password and running it through an algorithm
-    such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or HKDF.
+    such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or
+    :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
     This process is typically known as `key stretching`_.
 
 * Password storage
@@ -118,8 +119,99 @@ Different KDFs are suitable for different tasks such as:
         checking whether the password a user provides matches the stored derived
         key.
 
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.hkdf
+
+.. class:: HKDF(algorithm, length, salt, info, backend)
+
+    .. versionadded:: 0.2
+
+    `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable
+    for deriving keys of a fixed size used for other cryptographic operations.
+
+    .. doctest::
+
+        >>> import os
+        >>> from cryptography.hazmat.primitives import hashes
+        >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> backend = default_backend()
+        >>> salt = os.urandom(16)
+        >>> info = b"hkdf-example"
+        >>> hkdf = HKDF(
+        ...     algorithm=hashes.SHA256(),
+        ...     length=32,
+        ...     salt=salt,
+        ...     info=info,
+        ...     backend=backend
+        ... )
+        >>> key = hkdf.derive(b"input key")
+        >>> hkdf = HKDF(
+        ...     algorithm=hashes.SHA256(),
+        ...     length=32,
+        ...     salt=salt,
+        ...     info=info,
+        ...     backend=backend
+        ... )
+        >>> hkdf.verify(b"input key", key)
+
+    :param algorithm: An instance of a
+        :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+        provider.
+
+    :param int length: The desired length of the derived key. Maximum is
+        ``255 * (algorithm.digest_size // 8)``.
+
+    :param bytes salt: A salt. Randomizes the KDF's output. Optional, but
+        highly recommended. Ideally as many bits of entropy as the security
+        level of the hash: often that means cryptographically random and as
+        long as the hash output. Worse (shorter, less entropy) salt values can
+        still meaningfully contribute to security. May be reused. Does not have
+        to be secret, but may cause stronger security guarantees if secret; see
+        `RFC 5869`_ and the `HKDF paper`_ for more details. If ``None`` is
+        explicitly passed a default salt of ``algorithm.digest_size // 8`` null
+        bytes will be used.
+
+    :param bytes info: Application specific context information.  If ``None``
+        is explicitly passed an empty byte string will be used.
+
+    :params backend: A
+        :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+        provider.
+
+    .. method:: derive(key_material)
+
+        :param bytes key_material: The input key material.
+        :retunr bytes: The derived key.
+
+        Derives a new key from the input key material by performing both the
+        extract and expand operations.
+
+    .. method:: verify(key_material, expected_key)
+
+        :param key_material bytes: The input key material. This is the same as
+                                   ``key_material`` in :meth:`derive`.
+        :param expected_key bytes: 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.
+
 .. _`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`: http://en.wikipedia.org/wiki/PBKDF2
-.. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt
-.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching
+.. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2
+.. _`scrypt`: https://en.wikipedia.org/wiki/Scrypt
+.. _`key stretching`: https://en.wikipedia.org/wiki/Key_stretching
+.. _`HKDF`:
+.. _`RFC 5869`: https://tools.ietf.org/html/rfc5869
+.. _`HKDF paper`: https://eprint.iacr.org/2010/264
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 75628ba5..cf421ea6 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -17,6 +17,7 @@ invariants
 iOS
 pickleable
 plaintext
+pseudorandom
 testability
 unencrypted
 unpadded
diff --git a/tests/hazmat/primitives/test_hkdf.py b/tests/hazmat/primitives/test_hkdf.py
new file mode 100644
index 00000000..e3e2a9df
--- /dev/null
+++ b/tests/hazmat/primitives/test_hkdf.py
@@ -0,0 +1,147 @@
+# 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 six
+
+import pytest
+
+from cryptography.exceptions import AlreadyFinalized, InvalidKey
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+
+@pytest.mark.hmac
+class TestHKDF(object):
+    def test_length_limit(self, backend):
+        big_length = 255 * (hashes.SHA256().digest_size // 8) + 1
+
+        with pytest.raises(ValueError):
+            HKDF(
+                hashes.SHA256(),
+                big_length,
+                salt=None,
+                info=None,
+                backend=backend
+            )
+
+    def test_already_finalized(self, backend):
+        hkdf = HKDF(
+            hashes.SHA256(),
+            16,
+            salt=None,
+            info=None,
+            backend=backend
+        )
+
+        hkdf.derive(b"\x01" * 16)
+
+        with pytest.raises(AlreadyFinalized):
+            hkdf.derive(b"\x02" * 16)
+
+        hkdf = HKDF(
+            hashes.SHA256(),
+            16,
+            salt=None,
+            info=None,
+            backend=backend
+        )
+
+        hkdf.verify(b"\x01" * 16, b"gJ\xfb{\xb1Oi\xc5sMC\xb7\xe4@\xf7u")
+
+        with pytest.raises(AlreadyFinalized):
+            hkdf.verify(b"\x02" * 16, b"gJ\xfb{\xb1Oi\xc5sMC\xb7\xe4@\xf7u")
+
+        hkdf = HKDF(
+            hashes.SHA256(),
+            16,
+            salt=None,
+            info=None,
+            backend=backend
+        )
+
+    def test_verify(self, backend):
+        hkdf = HKDF(
+            hashes.SHA256(),
+            16,
+            salt=None,
+            info=None,
+            backend=backend
+        )
+
+        hkdf.verify(b"\x01" * 16, b"gJ\xfb{\xb1Oi\xc5sMC\xb7\xe4@\xf7u")
+
+    def test_verify_invalid(self, backend):
+        hkdf = HKDF(
+            hashes.SHA256(),
+            16,
+            salt=None,
+            info=None,
+            backend=backend
+        )
+
+        with pytest.raises(InvalidKey):
+            hkdf.verify(b"\x02" * 16, b"gJ\xfb{\xb1Oi\xc5sMC\xb7\xe4@\xf7u")
+
+    def test_unicode_typeerror(self, backend):
+        with pytest.raises(TypeError):
+            HKDF(
+                hashes.SHA256(),
+                16,
+                salt=six.u("foo"),
+                info=None,
+                backend=backend
+            )
+
+        with pytest.raises(TypeError):
+            HKDF(
+                hashes.SHA256(),
+                16,
+                salt=None,
+                info=six.u("foo"),
+                backend=backend
+            )
+
+        with pytest.raises(TypeError):
+            hkdf = HKDF(
+                hashes.SHA256(),
+                16,
+                salt=None,
+                info=None,
+                backend=backend
+            )
+
+            hkdf.derive(six.u("foo"))
+
+        with pytest.raises(TypeError):
+            hkdf = HKDF(
+                hashes.SHA256(),
+                16,
+                salt=None,
+                info=None,
+                backend=backend
+            )
+
+            hkdf.verify(six.u("foo"), b"bar")
+
+        with pytest.raises(TypeError):
+            hkdf = HKDF(
+                hashes.SHA256(),
+                16,
+                salt=None,
+                info=None,
+                backend=backend
+            )
+
+            hkdf.verify(b"foo", six.u("bar"))
diff --git a/tests/hazmat/primitives/test_hkdf_vectors.py b/tests/hazmat/primitives/test_hkdf_vectors.py
new file mode 100644
index 00000000..1e67234f
--- /dev/null
+++ b/tests/hazmat/primitives/test_hkdf_vectors.py
@@ -0,0 +1,51 @@
+# 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 os
+
+import pytest
+
+from cryptography.hazmat.primitives import hashes
+
+from .utils import generate_hkdf_test
+from ...utils import load_nist_vectors
+
+
+@pytest.mark.supported(
+    only_if=lambda backend: backend.hmac_supported(hashes.SHA1()),
+    skip_message="Does not support SHA1."
+)
+@pytest.mark.hmac
+class TestHKDFSHA1(object):
+    test_HKDFSHA1 = generate_hkdf_test(
+        load_nist_vectors,
+        os.path.join("KDF"),
+        ["rfc-5869-HKDF-SHA1.txt"],
+        hashes.SHA1()
+    )
+
+
+@pytest.mark.supported(
+    only_if=lambda backend: backend.hmac_supported(hashes.SHA256()),
+    skip_message="Does not support SHA256."
+)
+@pytest.mark.hmac
+class TestHKDFSHA256(object):
+    test_HKDFSHA1 = generate_hkdf_test(
+        load_nist_vectors,
+        os.path.join("KDF"),
+        ["rfc-5869-HKDF-SHA256.txt"],
+        hashes.SHA256()
+    )
diff --git a/tests/hazmat/primitives/utils.py b/tests/hazmat/primitives/utils.py
index 6b1d055d..5a8dc3ab 100644
--- a/tests/hazmat/primitives/utils.py
+++ b/tests/hazmat/primitives/utils.py
@@ -1,11 +1,15 @@
 import binascii
 import os
 
+import itertools
+
 import pytest
 
 from cryptography.hazmat.primitives import hashes, hmac
 from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
 from cryptography.hazmat.primitives.ciphers import Cipher
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
 from cryptography.exceptions import (
     AlreadyFinalized, NotYetFinalized, AlreadyUpdated, InvalidTag,
 )
@@ -297,3 +301,60 @@ def aead_tag_exception_test(backend, cipher_factory, mode_factory):
     )
     with pytest.raises(ValueError):
         cipher.encryptor()
+
+
+def hkdf_derive_test(backend, algorithm, params):
+    hkdf = HKDF(
+        algorithm,
+        int(params["l"]),
+        salt=binascii.unhexlify(params["salt"]) or None,
+        info=binascii.unhexlify(params["info"]) or None,
+        backend=backend
+    )
+
+    okm = hkdf.derive(binascii.unhexlify(params["ikm"]))
+
+    assert okm == binascii.unhexlify(params["okm"])
+
+
+def hkdf_extract_test(backend, algorithm, params):
+    hkdf = HKDF(
+        algorithm,
+        int(params["l"]),
+        salt=binascii.unhexlify(params["salt"]) or None,
+        info=binascii.unhexlify(params["info"]) or None,
+        backend=backend
+    )
+
+    prk = hkdf._extract(binascii.unhexlify(params["ikm"]))
+
+    assert prk == binascii.unhexlify(params["prk"])
+
+
+def hkdf_expand_test(backend, algorithm, params):
+    hkdf = HKDF(
+        algorithm,
+        int(params["l"]),
+        salt=binascii.unhexlify(params["salt"]) or None,
+        info=binascii.unhexlify(params["info"]) or None,
+        backend=backend
+    )
+
+    okm = hkdf._expand(binascii.unhexlify(params["prk"]))
+
+    assert okm == binascii.unhexlify(params["okm"])
+
+
+def generate_hkdf_test(param_loader, path, file_names, algorithm):
+    all_params = _load_all_params(path, file_names, param_loader)
+
+    all_tests = [hkdf_extract_test, hkdf_expand_test, hkdf_derive_test]
+
+    @pytest.mark.parametrize(
+        ("params", "hkdf_test"),
+        itertools.product(all_params, all_tests)
+    )
+    def test_hkdf(self, backend, params, hkdf_test):
+        hkdf_test(backend, algorithm, params)
+
+    return test_hkdf