Merge branch 'master' into prioritized-multi-backend

9 files changed, 134 insertions, 16 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index f401fe7c..2de9a329 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -15,6 +15,7 @@ Changelog
 * Fixed compilation on systems where OpenSSL's ``ec.h`` header is not
   available, such as CentOS.
 * Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`.
+* Added :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
 
 0.1 - 2014-01-08
 ~~~~~~~~~~~~~~~~
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 184ba214..74b854bd 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -41,7 +41,7 @@ follow the directions on the :doc:`security page </security>`.
 Code
 ----
 
-When in doubt, refer to `PEP 8`_ for Python code.
+When in doubt, refer to :pep:`8` for Python code.
 
 Every code file must start with the boilerplate notice of the Apache License.
 Additionally, every Python code file must contain
@@ -287,7 +287,6 @@ The HTML documentation index can now be found at
 
 .. _`GitHub`: https://github.com/pyca/cryptography
 .. _`our mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev
-.. _`PEP 8`: http://www.peps.io/8/
 .. _`syntax`: http://sphinx-doc.org/domains.html#info-field-lists
 .. _`pytest`: https://pypi.python.org/pypi/pytest
 .. _`tox`: https://pypi.python.org/pypi/tox
diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst
index af2032b6..16a61337 100644
--- a/docs/hazmat/backends/commoncrypto.rst
+++ b/docs/hazmat/backends/commoncrypto.rst
@@ -11,7 +11,16 @@ The `CommonCrypto`_ C library provided by Apple on OS X and iOS.
 
 .. data:: cryptography.hazmat.backends.commoncrypto.backend
 
-    This is the exposed API for the CommonCrypto backend. It has one public attribute.
+    This is the exposed API for the CommonCrypto backend.
+
+    It implements the following interfaces:
+
+    * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
+
+    It has one additional public attribute.
 
     .. attribute:: name
 
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 12d2d9f6..4db3972d 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -7,7 +7,16 @@ The `OpenSSL`_ C library.
 
 .. data:: cryptography.hazmat.backends.openssl.backend
 
-    This is the exposed API for the OpenSSL backend. It has one public attribute.
+    This is the exposed API for the OpenSSL backend.
+
+    It implements the following interfaces:
+
+    * :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.HashBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
+    * :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend`
+
+    It has one additional public attribute.
 
     .. attribute:: name
 
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 09a5a4ce..cbca5ed6 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -130,7 +130,13 @@ Asymmetric Interfaces
 
         The public exponent.
 
-    .. attribute:: key_length
+    .. attribute:: private_exponent
+
+        :type: int
+
+        The private exponent.
+
+    .. attribute:: key_size
 
         :type: int
 
@@ -152,7 +158,7 @@ Asymmetric Interfaces
 
         :type: int
 
-        The private exponent.
+        The private exponent. Alias for :attr:`private_exponent`.
 
     .. attribute:: n
 
@@ -179,7 +185,7 @@ Asymmetric Interfaces
 
         The public modulus.
 
-    .. attribute:: key_length
+    .. attribute:: key_size
 
         :type: int
 
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/index.rst b/docs/index.rst
index 86cd42c6..49e99be4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -28,7 +28,9 @@ existing libraries:
 * Use of poor implementations of algorithms (i.e. ones with known side-channel
   attacks).
 * Lack of high level, "Cryptography for humans", APIs.
-* Absence of algorithms such as AES-GCM.
+* Absence of algorithms such as
+  :class:`AES-GCM <cryptography.hazmat.primitives.ciphers.modes.GCM>` and
+  :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF`.
 * Poor introspectability, and thus poor testability.
 * Extremely error prone APIs, and bad defaults.
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 2206107e..7e7348e2 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -1,5 +1,5 @@
-Installing
-==========
+Installation
+============
 
 You can install ``cryptography`` with ``pip``:
 
@@ -7,10 +7,9 @@ You can install ``cryptography`` with ``pip``:
 
     $ pip install cryptography
 
-Installation Notes
-==================
 On Windows
 ----------
+
 If you're on Windows you'll need to make sure you have OpenSSL installed.
 There are `pre-compiled binaries`_ available. If your installation is in
 an unusual location set the ``LIB`` and ``INCLUDE`` environment variables
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