Merge branch 'master' into crl_ossl_backend

9 files changed, 81 insertions, 42 deletions

diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index bfe76330..0b249ccb 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -302,6 +302,8 @@ Custom X.509 Certificate Revocation List Vectors
   to "1.2.3.4". The CRL uses an unsupported MD2 signature algorithm.
 * ``crl_unsupported_reason.pem`` - Contains a CRL with one revocation which has
   an unsupported reason code.
+* ``crl_inval_cert_issuer_entry_ext.pem`` - Contains a CRL with one revocation
+  which has one entry extension for certificate issuer with an empty value.
 
 Hashes
 ~~~~~~
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 4eb17e30..1429cb09 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -86,8 +86,14 @@ described in :rfc:`3279`. This can be decoded using
 Verification
 ~~~~~~~~~~~~
 
-Using a :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`
-provider.
+Verification is performed using a
+:class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` provider.
+You can get a public key object with
+:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`,
+:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`,
+:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers.public_key`
+, or
+:meth:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey.public_key`.
 
 .. doctest::
 
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 6356c278..e4df9b10 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -12,7 +12,7 @@ Elliptic curve cryptography
 
     Generate a new private key on ``curve`` for use with ``backend``.
 
-    :param backend: A :class:`EllipticCurve` provider.
+    :param curve: A :class:`EllipticCurve` provider.
 
     :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend`
@@ -122,6 +122,32 @@ Elliptic Curve Signature Algorithms
         :returns: A new instance of a :class:`EllipticCurvePublicKey`
             provider.
 
+Elliptic Curve Key Exchange algorithm
+-------------------------------------
+
+.. class:: ECDH()
+
+    .. versionadded:: 1.1
+
+    The Elliptic Curve Diffie-Hellman Key Exchange algorithm first standardized
+    in NIST publication `800-56A`_, and later in `800-56Ar2`_.
+
+    For most applications the ``shared_key`` should be passed to a key
+    derivation function.
+
+    .. doctest::
+
+        >>> from cryptography.hazmat.backends import default_backend
+        >>> from cryptography.hazmat.primitives.asymmetric import ec
+        >>> private_key = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... )
+        >>> peer_public_key = ec.generate_private_key(
+        ...     ec.SECP384R1(), default_backend()
+        ... ).public_key()
+        >>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key)
+
+
 Elliptic Curves
 ---------------
 
@@ -314,6 +340,22 @@ Key Interfaces
         :returns:
             :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
 
+    .. method:: exchange(algorithm, peer_public_key)
+
+        Perform's a key exchange operation using the provided algorithm with
+        the peer's public key.
+
+        For most applications the result should be passed to a key derivation
+        function.
+
+        :param algorithm: The key exchange algorithm, currently only
+            :class:`~cryptography.hazmat.primitives.asymmetric.ec.ECDH` is
+            supported.
+        :param EllipticCurvePublicKey peer_public_key: The public key for the
+            peer.
+
+        :returns bytes: A shared key.
+
     .. method:: public_key()
 
         :return: :class:`EllipticCurvePublicKey`
@@ -419,6 +461,8 @@ Key Interfaces
 
 .. _`FIPS 186-3`: http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf
 .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
+.. _`800-56A`: http://csrc.nist.gov/publications/nistpubs/800-56A/SP800-56A_Revision1_Mar08-2007.pdf
+.. _`800-56Ar2`: http://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-56Ar2.pdf
 .. _`some concern`: https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters
 .. _`less than 224 bits`: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf
 .. _`elliptic curve diffie-hellman is faster than diffie-hellman`: http://digitalcommons.unl.edu/cgi/viewcontent.cgi?article=1100&context=cseconfwork
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index f88750cf..bc2402de 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -163,9 +163,15 @@ Verification
 ~~~~~~~~~~~~
 
 The previous section describes what to do if you have a private key and want to
-sign something. If you have a public key, a message, and a signature, you can
-check that the public key genuinely was used to sign that specific message. You
-also need to know which signing algorithm was used:
+sign something. If you have a public key, a message, a signature, and the
+signing algorithm that was used you can check that the private key associated
+with a given public key was used to sign that specific message.  You can obtain
+a public key to use in verification using
+:func:`~cryptography.hazmat.primitives.serialization.load_pem_public_key`,
+:func:`~cryptography.hazmat.primitives.serialization.load_der_public_key`,
+:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers.public_key`
+, or
+:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey.public_key`.
 
 .. doctest::
 
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 8d51f0d7..f14f4037 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -337,8 +337,6 @@ Serialization Encodings
 
 .. class:: Encoding
 
-    .. versionadded:: 0.8
-
     An enumeration for encoding types. Used with the ``private_bytes`` method
     available on
     :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization`
@@ -353,10 +351,14 @@ Serialization Encodings
 
     .. attribute:: PEM
 
+        .. versionadded:: 0.8
+
         For PEM format. This is a base64 format with delimiters.
 
     .. attribute:: DER
 
+        .. versionadded:: 0.9
+
         For DER format. This is a binary format.
 
 
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index 675111bb..a9ab38a0 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -15,4 +15,3 @@ Primitives
     constant-time
     interfaces
     twofactor
-    key-exchange-agreements
diff --git a/docs/hazmat/primitives/key-exchange-agreements.rst b/docs/hazmat/primitives/key-exchange-agreements.rst
deleted file mode 100644
index 8d79fbad..00000000
--- a/docs/hazmat/primitives/key-exchange-agreements.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. hazmat::
-
-Key Exchange agreements
-=======================
-
-.. module:: cryptography.hazmat.primitives.asymmetric.key_exchange
-
-Key exchange agreements are cryptographic operations, like Diffie-Hellman
-key exchanges, that allow two parties to use their public-private key pairs
-to establish a shared secret key over an insecure channel. Usually the
-negotiated key is further derived before using it for symmetric operations.
-
-Interfaces
-~~~~~~~~~~
-
-.. class:: KeyExchangeContext
-
-    .. versionadded:: 1.1
-
-    .. method:: agree(public_key)
-
-        :param public_key: The peer public key, the type depends on the
-            crypto system used, for example :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
diff --git a/docs/installation.rst b/docs/installation.rst
index 5d629e9f..61f9348e 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -46,7 +46,9 @@ dependencies are included. Just run
 
 If you prefer to compile it yourself you'll need to have OpenSSL installed.
 You can compile OpenSSL yourself as well or use the binaries we build for our
-release infrastructure (`32-bit`_ and `64-bit`_). Wherever you place your copy
+release infrastructure (`openssl-release`_). Be sure to download the proper
+version for your architecture and Python (2010 works for Python 2.6, 2.7, 3.3,
+and 3.4 while 2015 is required for 3.5). Wherever you place your copy
 of OpenSSL you'll need to set the ``LIB`` and ``INCLUDE`` environment variables
 to include the proper locations. For example:
 
@@ -166,7 +168,7 @@ dependencies.
     ./config no-shared no-ssl2 -fPIC --prefix=${CWD}/openssl
     make && make install
     cd ..
-    CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel cryptography
+    CFLAGS="-I${CWD}/openssl/include" LDFLAGS="-L${CWD}/openssl/lib" pip wheel --no-use-wheel cryptography
 
 Building cryptography on OS X
 -----------------------------
@@ -250,8 +252,7 @@ information, consult `Greg Wilson's blog post`_ on the subject.
 
 .. _`Homebrew`: http://brew.sh
 .. _`MacPorts`: https://www.macports.org
-.. _`32-bit`: https://jenkins.cryptography.io/job/openssl-win32-release/
-.. _`64-bit`: https://jenkins.cryptography.io/job/openssl-win64-release/
+.. _`openssl-release`: https://jenkins.cryptography.io/job/openssl-release/
 .. _`bug in conda`: https://github.com/conda/conda-recipes/issues/110
 .. _`Greg Wilson's blog post`: http://software-carpentry.org/blog/2014/04/mr-biczo-was-right.html
 .. _virtualenv: https://virtualenv.pypa.io/en/latest/
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index eec0cbcc..5ab6caa5 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -287,13 +287,13 @@ X.509 Certificate Object
 
     .. method:: public_key()
 
-        :type:
+        The public key associated with the certificate.
+
+        :returns:
             :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
 
-        The public key associated with the certificate.
-
         .. doctest::
 
             >>> from cryptography.hazmat.primitives.asymmetric import rsa
@@ -617,6 +617,8 @@ X.509 Certificate Builder
             :class:`~cryptography.hazmat.backends.interfaces.X509Backend`
             interface.
 
+        :returns: :class:`~cryptography.x509.Certificate`
+
 
 X.509 CSR (Certificate Signing Request) Object
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -627,13 +629,13 @@ X.509 CSR (Certificate Signing Request) Object
 
     .. method:: public_key()
 
-        :type:
+        The public key associated with the request.
+
+        :returns:
             :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey` or
             :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKey`
 
-        The public key associated with the request.
-
         .. doctest::
 
             >>> from cryptography.hazmat.primitives.asymmetric import rsa