Merge branch 'master' into exception-heirarchy-refactor

Conflicts:
	cryptography/hazmat/backends/openssl/backend.py

8 files changed, 190 insertions, 16 deletions

diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst
index c96b6d89..a70b82d3 100644
--- a/docs/development/test-vectors.rst
+++ b/docs/development/test-vectors.rst
@@ -15,10 +15,15 @@ Asymmetric Ciphers
 
 * RSA PKCS #1 from the RSA FTP site (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/
   and ftp://ftp.rsa.com/pub/rsalabs/tmp/).
-* OpenSSL PEM serialization vectors from the `OpenSSL test suite`_ and `GnuTLS test suite`_.
+* RSA FIPS 186-2 and PKCS1 v1.5 vulnerability test vectors from `NIST CAVP`_.
+* DSA test vectors from `FIPS 186-2`_ and `FIPS 186-3`_.
+* OpenSSL PEM RSA serialization vectors from the `OpenSSL example key`_ and
+  `GnuTLS key parsing tests`_.
+* OpenSSL PEM DSA serialization vectors from the `GnuTLS example keys`_.
 * PKCS #8 PEM serialization vectors from
 
-  * GnuTLS: `encpkcs8.pem`_, `enc2pkcs8.pem`_, `unencpkcs8.pem`_, `pkcs12_s2k_pem.c`_.
+  * GnuTLS: `encpkcs8.pem`_, `enc2pkcs8.pem`_, `unencpkcs8.pem`_,
+    `pkcs12_s2k_pem.c`_.
   * `Botan's ECC private keys`_.
 
 Hashes
@@ -43,6 +48,7 @@ Key Derivation Functions
 
 * HKDF (SHA1, SHA256) from :rfc:`5869`.
 * PBKDF2 (HMAC-SHA1) from :rfc:`6070`.
+* scrypt from the `draft RFC`_.
 
 Recipes
 ~~~~~~~
@@ -62,12 +68,14 @@ Symmetric Ciphers
 * CAST5 (ECB) from :rfc:`2144`.
 * CAST5 (CBC, CFB, OFB) generated by this project.
   See: :doc:`/development/custom-vectors/cast5`
+* IDEA (ECB) from the `NESSIE IDEA vectors`_ created by `NESSIE`_.
 
 Two Factor Authentication
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 * HOTP from :rfc:`4226`
-* TOTP from :rfc:`6238` (Note that an `errata`_ for the test vectors in RFC 6238 exists)
+* TOTP from :rfc:`6238` (Note that an `errata`_ for the test vectors in RFC
+  6238 exists)
 
 
 Creating Test Vectors
@@ -103,12 +111,18 @@ header format (substituting the correct information):
 .. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232
 .. _`RIPEMD website`: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html
 .. _`Whirlpool website`: http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html
+.. _`draft RFC`: https://tools.ietf.org/html/draft-josefsson-scrypt-kdf-01
 .. _`Specification repository`: https://github.com/fernet/spec
 .. _`errata`: http://www.rfc-editor.org/errata_search.php?rfc=6238
-.. _`OpenSSL test suite`: http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=test/testrsa.pem;h=aad21067a8f7cb93a52a511eb9162fd83be39135;hb=66e8211c0b1347970096e04b18aa52567c325200
-.. _`GnuTLS test suite`: https://gitorious.org/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d
+.. _`OpenSSL example key`: http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=test/testrsa.pem;h=aad21067a8f7cb93a52a511eb9162fd83be39135;hb=66e8211c0b1347970096e04b18aa52567c325200
+.. _`GnuTLS key parsing tests`: https://gitorious.org/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d
 .. _`encpkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/encpkcs8.pem
 .. _`enc2pkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/enc2pkcs8.pem
 .. _`unencpkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/unencpkcs8.pem
 .. _`pkcs12_s2k_pem.c`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs12_s2k_pem.c
 .. _`Botan's ECC private keys`: https://github.com/randombit/botan/tree/4917f26a2b154e841cd27c1bcecdd41d2bdeb6ce/src/tests/data/ecc
+.. _`FIPS 186-2`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-2dsatestvectors.zip
+.. _`FIPS 186-3`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-3dsatestvectors.zip
+.. _`GnuTLS example keys`: https://gitorious.org/gnutls/gnutls/commit/ad2061deafdd7db78fd405f9d143b0a7c579da7b
+.. _`NESSIE IDEA vectors`: https://www.cosic.esat.kuleuven.be/nessie/testvectors/bc/idea/Idea-128-64.verified.test-vectors
+.. _`NESSIE`: https://en.wikipedia.org/wiki/NESSIE
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index 0982426f..7f9ae347 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -10,8 +10,8 @@ Exceptions
 
 .. class:: InvalidSignature
 
-    This is raised when the verify method of a hash context's computed digest
-    does not match the expected digest.
+    This is raised when signature verification fails. This can occur with
+    HMAC or asymmetric key signature validation.
 
 
 .. class:: NotYetFinalized
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 682820b3..7943981e 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -111,6 +111,49 @@ RSA
                         or ``modulus`` do not match the bounds specified in
                         :rfc:`3447`.
 
+    .. method:: verifier(signature, padding, algorithm, backend)
+
+        .. versionadded:: 0.3
+
+        Verify data was signed by the private key associated with this public
+        key.
+
+        .. doctest::
+
+            >>> from cryptography.hazmat.backends import default_backend
+            >>> from cryptography.hazmat.primitives import hashes
+            >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding
+            >>> private_key = rsa.RSAPrivateKey.generate(
+            ...     public_exponent=65537,
+            ...     key_size=2048,
+            ...     backend=default_backend()
+            ... )
+            >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend())
+            >>> data= b"this is some data I'd like to sign"
+            >>> signer.update(data)
+            >>> signature = signer.finalize()
+            >>> public_key = private_key.public_key()
+            >>> verifier = public_key.verifier(signature, padding.PKCS1v15(), hashes.SHA256(), default_backend())
+            >>> verifier.update(data)
+            >>> verifier.verify()
+
+        :param bytes signature: The signature to verify.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
+
 .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
 .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
 .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 5be3dd95..cc2a3000 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -231,6 +231,113 @@ Asymmetric Interfaces
         The public exponent. Alias for :attr:`public_exponent`.
 
 
+.. class:: DSAParameters
+
+    .. versionadded:: 0.3
+
+    `DSA`_ parameters.
+
+    .. attribute:: modulus
+
+        :type: int
+
+        The prime modulus that is used in generating the DSA key pair and used
+        in the DSA signing and verification processes.
+
+    .. attribute:: subgroup_order
+
+        :type: int
+
+        The subgroup order that is used in generating the DSA key pair
+        by the generator and used in the DSA signing and verification
+        processes.
+
+    .. attribute:: generator
+
+        :type: int
+
+        The generator that is used in generating the DSA key pair and used
+        in the DSA signing and verification processes.
+
+    .. attribute:: p
+
+        :type: int
+
+        The prime modulus that is used in generating the DSA key pair and used
+        in the DSA signing and verification processes. Alias for :attr:`modulus`.
+
+    .. attribute:: q
+
+        :type: int
+
+        The subgroup order that is used in generating the DSA key pair
+        by the generator and used in the DSA signing and verification
+        processes. Alias for :attr:`subgroup_order`.
+
+    .. attribute:: g
+
+        :type: int
+
+        The generator that is used in generating the DSA key pair and used
+        in the DSA signing and verification processes. Alias for :attr:`generator`.
+
+
+.. class:: DSAPrivateKey
+
+    .. versionadded:: 0.3
+
+    A `DSA`_ private key.
+
+    .. method:: public_key()
+
+        :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
+
+        An DSA public key object corresponding to the values of the private key.
+
+    .. method:: parameters()
+
+        :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+
+        The DSAParameters object associated with this private key.
+
+    .. attribute:: key_size
+
+        :type: int
+
+        The bit length of the modulus.
+
+    .. attribute:: x
+
+        :type: int
+
+        The private key.
+
+    .. attribute:: y
+
+        :type: int
+
+        The public key.
+
+
+.. class:: DSAPublicKey
+
+    .. versionadded:: 0.3
+
+    A `DSA`_ private key.
+
+    .. method:: parameters()
+
+        :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+
+        The DSAParameters object associated with this public key.
+
+    .. attribute:: y
+
+        :type: int
+
+        The public key.
+
+
 .. class:: AsymmetricSignatureContext
 
     .. versionadded:: 0.2
@@ -254,8 +361,8 @@ Asymmetric Interfaces
 
     .. method:: verify()
 
-        :raises cryptography.exceptions.InvalidSignature: If signature does not
-            validate.
+        :raises cryptography.exceptions.InvalidSignature: If the signature does
+            not validate.
 
 
 .. class:: AsymmetricPadding
@@ -335,3 +442,4 @@ Key Derivation Functions
 
 .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
 .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem
+.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index d8a0e241..851dbb0b 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -179,7 +179,7 @@ Different KDFs are suitable for different tasks such as:
     :param bytes info: Application specific context information.  If ``None``
         is explicitly passed an empty byte string will be used.
 
-    :params backend: A
+    :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
         provider.
 
diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index 3df1a147..3912d483 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -47,10 +47,11 @@ codes (HMAC).
         provider.
     :raises ValueError: This is raised if the provided ``key`` is shorter than
         128 bits or if the ``length`` parameter is not 6, 7 or 8.
-    :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm``
-        is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
+    :raises TypeError: This is raised if the provided ``algorithm`` is not
+        :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
         :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or
-        :class:`~cryptography.hazmat.primitives.hashes.SHA512()`.
+        :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the
+        ``length`` parameter is not an integer.
 
     .. method:: generate(counter)
 
@@ -142,10 +143,11 @@ similar to the following code.
         provider.
     :raises ValueError: This is raised if the provided ``key`` is shorter than
         128 bits or if the ``length`` parameter is not 6, 7 or 8.
-    :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm``
-        is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
+    :raises TypeError: This is raised if the provided ``algorithm`` is not
+        :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
         :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or
-        :class:`~cryptography.hazmat.primitives.hashes.SHA512()`.
+        :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the
+        ``length`` parameter is not an integer.
 
     .. method:: generate(time)
 
diff --git a/docs/index.rst b/docs/index.rst
index 176405b5..a25f4470 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -91,4 +91,10 @@ The ``cryptography`` open source project
     community
 
 
+.. note::
+
+    ``cryptography`` has not been subjected to an external audit of its code or
+    documentation. If you're interested in discussing an audit please
+    :doc:`get in touch </community>`.
+
 .. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 7200855d..bf5ae05e 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -28,6 +28,7 @@ pickleable
 plaintext
 pseudorandom
 Schneier
+scrypt
 testability
 unencrypted
 unpadded