Merge branch 'master' into pbkdf2-commoncrypto

* master:
  a bit more language work + changelog changes for pbkdf2hmac
  one more style fix
  a few typo fixes, capitalization, etc
  switch to private attributes in pbkdf2hmac
  expand docs to talk more about the purposes of KDFs
  update docs re: PBKDF2HMAC iterations
  add test for null char replacement
  Added installation section to index.rst
  called -> used
  quotes inside, diff examples
  Expose this method because probably someone will need it eventually
  fix spacing, remove versionadded since HashAlgorithm was in 0.1
  document HashAlgorithm
  Added canonical installation document with details about various platforms, fixes #519
  update docs for pbkdf2
  Add bindings for X509_REQ_get_extensions.
  add Konstantinos Koukopoulos to AUTHORS.rst
  review fixes
  doc updates based on review

Conflicts:
	docs/changelog.rst

11 files changed, 174 insertions, 94 deletions

diff --git a/AUTHORS.rst b/AUTHORS.rst
index ad27cec6..0e3979ad 100644
--- a/AUTHORS.rst
+++ b/AUTHORS.rst
@@ -12,3 +12,5 @@ PGP key fingerprints are enclosed in parentheses.
 * Jarret Raim <jarito@gmail.com>
 * Alex Stapleton <alexs@prol.etari.at> (A1C7 E50B 66DE 39ED C847 9665 8E3C 20D1 9BD9 5C4C)
 * David Reid <dreid@dreid.org> (0F83 CC87 B32F 482B C726  B58A 9FBF D8F4 DA89 6D74)
+* Konstantinos Koukopoulos <koukopoulos@gmail.com> (D6BD 52B6 8C99 A91C E2C8  934D 3300 566B 3A46 726E)
+* Stephen Holsapple <sholsapp@gmail.com>
diff --git a/cryptography/hazmat/bindings/openssl/x509.py b/cryptography/hazmat/bindings/openssl/x509.py
index 840254a2..e4021a12 100644
--- a/cryptography/hazmat/bindings/openssl/x509.py
+++ b/cryptography/hazmat/bindings/openssl/x509.py
@@ -119,6 +119,7 @@ int X509_REQ_sign(X509_REQ *, EVP_PKEY *, const EVP_MD *);
 int X509_REQ_verify(X509_REQ *, EVP_PKEY *);
 EVP_PKEY *X509_REQ_get_pubkey(X509_REQ *);
 int X509_REQ_add_extensions(X509_REQ *, X509_EXTENSIONS *);
+X509_EXTENSIONS *X509_REQ_get_extensions(X509_REQ *);
 int X509_REQ_print_ex(BIO *, X509_REQ *, unsigned long, unsigned long);
 
 int X509V3_EXT_print(BIO *, X509_EXTENSION *, unsigned long, int);
@@ -165,6 +166,7 @@ int X509_set_serialNumber(X509 *, ASN1_INTEGER *);
 X509_STORE *X509_STORE_new(void);
 void X509_STORE_free(X509_STORE *);
 int X509_STORE_add_cert(X509_STORE *, X509 *);
+int X509_verify_cert(X509_STORE_CTX *);
 """
 
 MACROS = """
diff --git a/cryptography/hazmat/primitives/kdf/pbkdf2.py b/cryptography/hazmat/primitives/kdf/pbkdf2.py
index fec1d5c2..71b88211 100644
--- a/cryptography/hazmat/primitives/kdf/pbkdf2.py
+++ b/cryptography/hazmat/primitives/kdf/pbkdf2.py
@@ -30,8 +30,8 @@ class PBKDF2HMAC(object):
                 "{0} is not supported for PBKDF2 by this backend".format(
                     algorithm.name)
             )
-        self._called = False
-        self.algorithm = algorithm
+        self._used = False
+        self._algorithm = algorithm
         self._length = length
         if isinstance(salt, six.text_type):
             raise TypeError(
@@ -39,14 +39,13 @@ class PBKDF2HMAC(object):
                 "material."
             )
         self._salt = salt
-        self.iterations = iterations
+        self._iterations = iterations
         self._backend = backend
 
     def derive(self, key_material):
-        if self._called:
-            raise AlreadyFinalized("PBKDF2 instances can only be called once")
-        else:
-            self._called = True
+        if self._used:
+            raise AlreadyFinalized("PBKDF2 instances can only be used once")
+        self._used = True
 
         if isinstance(key_material, six.text_type):
             raise TypeError(
@@ -54,10 +53,10 @@ class PBKDF2HMAC(object):
                 "material."
             )
         return self._backend.derive_pbkdf2_hmac(
-            self.algorithm,
+            self._algorithm,
             self._length,
             self._salt,
-            self.iterations,
+            self._iterations,
             key_material
         )
 
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 14019c81..f401fe7c 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -14,7 +14,7 @@ Changelog
 * Improved thread-safety for the OpenSSL backend.
 * Fixed compilation on systems where OpenSSL's ``ec.h`` header is not
   available, such as CentOS.
-* Added PBKDF2HMAC support to OpenSSL and CommonCrypto backends.
+* Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`.
 
 0.1 - 2014-01-08
 ~~~~~~~~~~~~~~~~
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index e22c6bb3..49e4c88c 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -37,7 +37,7 @@ A specific ``backend`` may provide one or more of these interfaces.
     .. method:: create_symmetric_encryption_ctx(cipher, mode)
 
         Create a
-        :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that
+        :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that
         can be used for encrypting data with the symmetric ``cipher`` using
         the given ``mode``.
 
@@ -56,7 +56,7 @@ A specific ``backend`` may provide one or more of these interfaces.
     .. method:: create_symmetric_decryption_ctx(cipher, mode)
 
         Create a
-        :class:`~cryptogrpahy.hazmat.primitives.interfaces.CipherContext` that
+        :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that
         can be used for decrypting data with the symmetric ``cipher`` using
         the given ``mode``.
 
@@ -91,7 +91,7 @@ A specific ``backend`` may provide one or more of these interfaces.
     .. method:: create_hash_ctx(algorithm)
 
         Create a
-        :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that
+        :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that
         uses the specified ``algorithm`` to calculate a message digest.
 
         :param algorithm: An instance of a
@@ -121,7 +121,7 @@ A specific ``backend`` may provide one or more of these interfaces.
     .. method:: create_hmac_ctx(algorithm)
 
         Create a
-        :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that
+        :class:`~cryptography.hazmat.primitives.interfaces.HashContext` that
         uses the specified ``algorithm`` to calculate a hash-based message
         authentication code.
 
@@ -133,7 +133,6 @@ A specific ``backend`` may provide one or more of these interfaces.
             :class:`~cryptography.hazmat.primitives.interfaces.HashContext`
 
 
-
 .. class:: PBKDF2HMACBackend
 
     .. versionadded:: 0.2
@@ -144,7 +143,7 @@ A specific ``backend`` may provide one or more of these interfaces.
 
         Check if the specified ``algorithm`` is supported by this backend.
 
-        :param prf: An instance of a
+        :param algorithm: An instance of a
             :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
             provider.
 
@@ -164,7 +163,9 @@ A specific ``backend`` may provide one or more of these interfaces.
         :param bytes salt: A salt.
 
         :param int iterations: The number of iterations to perform of the hash
-            function.
+            function. This can be used to control the length of time the
+            operation takes. Higher numbers help mitigate brute force attacks
+            against derived keys.
 
         :param bytes key_material: The key material to use as a basis for
             the derived key. This is typically a password.
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 926ec7d1..12d2d9f6 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -13,52 +13,4 @@ The `OpenSSL`_ C library.
 
         The string name of this backend: ``"openssl"``
 
-Using your own OpenSSL on Linux
--------------------------------
-
-Python links to OpenSSL for its own purposes and this can sometimes cause
-problems when you wish to use a different version of OpenSSL with cryptography.
-If you want to use cryptography with your own build of OpenSSL you will need to
-make sure that the build is configured correctly so that your version of
-OpenSSL doesn't conflict with Python's.
-
-The options you need to add allow the linker to identify every symbol correctly
-even when multiple versions of the library are linked into the same program. If
-you are using your distribution's source packages these will probably be
-patched in for you already, otherwise you'll need to use options something like
-this when configuring OpenSSL:
-
-.. code-block:: console
-
-    $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
-
-You'll also need to generate your own ``openssl.ld`` file. For example::
-
-    OPENSSL_1.0.1F_CUSTOM {
-        global:
-            *;
-    };
-
-You should replace the version string on the first line as appropriate for your
-build.
-
-Using your own OpenSSL on OS X
-------------------------------
-
-To link cryptography against a custom version of OpenSSL you'll need to set
-``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via
-`Homebrew`_:
-
-.. code-block:: console
-
-    $ brew install openssl
-
-Then install cryptography linking against the brewed version:
-
-.. code-block:: console
-
-    $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
-
-
 .. _`OpenSSL`: https://www.openssl.org/
-.. _`Homebrew`: http://brew.sh
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 2adad913..09a5a4ce 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -204,6 +204,31 @@ Asymmetric Interfaces
         The public exponent. Alias for :attr:`public_exponent`.
 
 
+Hash Algorithms
+~~~~~~~~~~~~~~~
+
+.. class:: HashAlgorithm
+
+    .. attribute:: name
+
+        :type: str
+
+        The standard name for the hash algorithm, for example: ``"sha256"`` or
+        ``"whirlpool"``.
+
+    .. attribute:: digest_size
+
+        :type: int
+
+        The size of the resulting digest in bytes.
+
+    .. attribute:: block_size
+
+        :type: int
+
+        The internal block size of the hash algorithm in bytes.
+
+
 Key Derivation Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index c77b763a..529f4416 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -5,20 +5,36 @@ Key Derivation Functions
 
 .. currentmodule:: cryptography.hazmat.primitives.kdf
 
-Key derivation functions derive key material from passwords or other data
-sources using a pseudo-random function (PRF). Each KDF is suitable for
-different tasks (cryptographic key derivation, password storage,
-key stretching) so match your needs to their capabilities.
+Key derivation functions derive bytes suitable for cryptographic operations
+from passwords or other data sources using a pseudo-random function (PRF).
+Different KDFs are suitable for different tasks such as:
 
-.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend):
+* Cryptographic key derivation
+
+    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.
+    This process is typically known as `key stretching`_.
+
+* Password storage
+
+    When storing passwords you want to use an algorithm that is computationally
+    intensive. Legitimate users will only need to compute it once (for example,
+    taking the user's password, running it through the KDF, then comparing it
+    to the stored value), while attackers will need to do it billions of times.
+    Ideal password storage KDFs will be demanding on both computational and
+    memory resources.
+
+.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2
+
+.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend)
 
     .. versionadded:: 0.2
 
-    PBKDF2 (Password Based Key Derivation Function 2) is typically used for
+    `PBKDF2`_ (Password Based Key Derivation Function 2) is typically used for
     deriving a cryptographic key from a password. It may also be used for
-    key storage, but other key storage KDFs such as `scrypt`_ or `bcrypt`_
-    are generally considered better solutions since they are designed to be
-    slow.
+    key storage, but an alternate key storage KDF such as `scrypt`_ is generally
+    considered a better solution.
 
     This class conforms to the
     :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction`
@@ -59,7 +75,9 @@ key stretching) so match your needs to their capabilities.
     :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or
         longer.
     :param int iterations: The number of iterations to perform of the hash
-        function. See OWASP's `Password Storage Cheat Sheet`_ for more
+        function. This can be used to control the length of time the operation
+        takes. Higher numbers help mitigate brute force attacks against derived
+        keys. See OWASP's `Password Storage Cheat Sheet`_ for more
         detailed recommendations if you intend to use this for password storage.
     :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
@@ -69,7 +87,7 @@ key stretching) so match your needs to their capabilities.
 
         :param key_material bytes: The input key material. For PBKDF2 this
             should be a password.
-        :return: The new key.
+        :return bytes: the derived key.
         :raises cryptography.exceptions.AlreadyFinalized: This is raised when
                                                           :meth:`derive` or
                                                           :meth:`verify` is
@@ -102,5 +120,6 @@ key stretching) so match your needs to their capabilities.
 
 .. _`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
-.. _`bcrypt`: http://en.wikipedia.org/wiki/Bcrypt
+.. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2
 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt
+.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching
diff --git a/docs/index.rst b/docs/index.rst
index b800bcaf..86cd42c6 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,29 +5,15 @@ Welcome to ``cryptography``
 primitives. We hope it'll be your one-stop-shop for all your cryptographic
 needs in Python.
 
-Installing
-----------
-
+Installation
+------------
 You can install ``cryptography`` with ``pip``:
 
 .. code-block:: console
 
     $ pip install cryptography
 
-.. note::
-
-    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
-    to include the corresponding locations. For example:
-    
-    .. code-block:: console
-    
-        C:\> \path\to\vcvarsall.bat x86_amd64
-        C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB%
-        C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
-        C:\> pip install cryptography
-
+See :doc:`Installation <installation>` for more information.
 
 Why a new crypto library for Python?
 ------------------------------------
@@ -90,6 +76,7 @@ The ``cryptography`` open source project
 .. toctree::
     :maxdepth: 2
 
+    installation
     contributing
     security
     api-stability
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 00000000..2206107e
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,74 @@
+Installing
+==========
+
+You can install ``cryptography`` with ``pip``:
+
+.. code-block:: console
+
+    $ 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
+to include the corresponding locations. For example:
+
+.. code-block:: console
+
+    C:\> \path\to\vcvarsall.bat x86_amd64
+    C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB%
+    C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
+    C:\> pip install cryptography
+
+Using your own OpenSSL on Linux
+-------------------------------
+
+Python links to OpenSSL for its own purposes and this can sometimes cause
+problems when you wish to use a different version of OpenSSL with cryptography.
+If you want to use cryptography with your own build of OpenSSL you will need to
+make sure that the build is configured correctly so that your version of
+OpenSSL doesn't conflict with Python's.
+
+The options you need to add allow the linker to identify every symbol correctly
+even when multiple versions of the library are linked into the same program. If
+you are using your distribution's source packages these will probably be
+patched in for you already, otherwise you'll need to use options something like
+this when configuring OpenSSL:
+
+.. code-block:: console
+
+    $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
+
+You'll also need to generate your own ``openssl.ld`` file. For example::
+
+    OPENSSL_1.0.1F_CUSTOM {
+        global:
+            *;
+    };
+
+You should replace the version string on the first line as appropriate for your
+build.
+
+Using your own OpenSSL on OS X
+------------------------------
+
+To link cryptography against a custom version of OpenSSL you'll need to set
+``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via
+`Homebrew`_:
+
+.. code-block:: console
+
+    $ brew install openssl
+
+Then install cryptography linking against the brewed version:
+
+.. code-block:: console
+
+    $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
+
+
+.. _`Homebrew`: http://brew.sh
+.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html
diff --git a/tests/test_utils.py b/tests/test_utils.py
index f852f3ab..8ecb33f9 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -180,6 +180,25 @@ def test_load_nist_vectors():
     ]
 
 
+def test_load_nist_vectors_with_null_chars():
+    vector_data = textwrap.dedent("""
+    COUNT = 0
+    KEY = thing\\0withnulls
+
+    COUNT = 1
+    KEY = 00000000000000000000000000000000
+    """).splitlines()
+
+    assert load_nist_vectors(vector_data) == [
+        {
+            "key": b"thing\x00withnulls",
+        },
+        {
+            "key": b"00000000000000000000000000000000",
+        },
+    ]
+
+
 def test_load_cryptrec_vectors():
     vector_data = textwrap.dedent("""
     # Vectors taken from http://info.isl.ntt.co.jp/crypt/eng/camellia/