Add docs for DSA parameters and key generation

3 files changed, 95 insertions, 6 deletions

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index c38f818f..9c401d28 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -285,3 +285,37 @@ A specific ``backend`` may provide one or more of these interfaces.
 
         :raises cryptography.exceptions.UnsupportedAlgorithm: If the data is
             encrypted with an unsupported algorithm.
+
+
+.. class:: DSABackend
+
+    .. versionadded:: 0.4
+
+    A backend with methods for using DSA.
+
+    .. method:: generate_dsa_parameters(key_size)
+
+        :param int key_size: The length of the modulus in bits. It should be 
+            either "1024, 2048 or 3072". For keys generated in 2014 this should 
+            be at least 2048.
+            Note that some applications (such as SSH) have not yet gained support 
+            for larger key sizes specified in FIPS 186-3 and are still restricted
+            to only the 1024-bit keys specified in FIPS 186-2.
+
+        :return: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+            provider.
+
+    .. method:: generate_dsa_private_key(parameters)
+
+        :param parameters: A
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+            provider.
+
+        :return: A new instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+            provider.
+
+        :raises ValueError: This is raised if the key size is not (1024 or 2048 or 3072)
+            or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024
+            because older OpenSSL versions don't support a key size larger than 1024.
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 69e8d58e..1a6a6e0e 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -13,6 +13,16 @@ DSA
 
     DSA Parameters are required for generating a DSA private key.
 
+    You should use :meth:`~generate` to generate new parameters.
+
+    .. warning::
+        This method only checks a limited set of properties of its arguments.
+        Using DSA parameters that you do not trust or with incorrect arguments
+        may lead to insecure operation, crashes, and other undefined behavior.
+        We recommend that you only ever load parameters that were generated
+        with software you trust.
+
+
     This class conforms to the
     :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
     interface.
@@ -23,6 +33,23 @@ DSA
                         ``subgroup_order``, or ``generator`` do
                         not match the bounds specified in `FIPS 186-4`_.
 
+    .. classmethod:: generate(key_size, backend)
+
+        Generate a new ``DSAParameters`` instance using ``backend``.
+
+        :param int key_size: The length of the modulus in bits. It should be 
+            either "1024, 2048 or 3072". For keys generated in 2014 this should 
+            be `at least 2048`_ (See page 41).
+            Note that some applications (such as SSH) have not yet gained support 
+            for larger key sizes specified in FIPS 186-3 and are still restricted
+            to only the 1024-bit keys specified in FIPS 186-2.
+            
+        :return: A new instance of ``DSAParameters``
+
+        :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+            the provided ``backend`` does not implement
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+
 
 .. class:: DSAPrivateKey(modulus, subgroup_order, generator, x, y)
 
@@ -30,6 +57,16 @@ DSA
 
     A DSA private key is required for signing messages.
 
+    You should use :meth:`~generate` to generate new keys.
+
+    .. warning::
+        This method only checks a limited set of properties of its arguments.
+        Using a DSA private key that you do not trust or with incorrect
+        parameters may lead to insecure operation, crashes, and other undefined
+        behavior. We recommend that you only ever load private keys that were
+        generated with software you trust.
+
+
     This class conforms to the
     :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
     interface.
@@ -40,6 +77,26 @@ DSA
                         ``subgroup_order``, or ``generator`` do
                         not match the bounds specified in `FIPS 186-4`_.
 
+    .. classmethod:: generate(parameters, backend)
+
+        Generate a new ``DSAPrivateKey`` instance using ``backend``.
+
+        :param parameters: A
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+            provider.
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+            provider.
+        :return: A new instance of ``DSAPrivateKey``.
+
+        :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+            the provided ``backend`` does not implement
+            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+        
+        :raises ValueError: This is raised if the key size is not (1024 or 2048 or 3072)
+            or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024
+            because older OpenSSL versions don't support a key size larger than 1024.
+
 
 .. class:: DSAPublicKey(modulus, subgroup_order, generator, y)
 
@@ -65,4 +122,4 @@ DSA
 .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm 
 .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
 .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf 
-
+.. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf
diff --git a/tests/hazmat/backends/test_multibackend.py b/tests/hazmat/backends/test_multibackend.py
index 4ec8a110..f46009d4 100644
--- a/tests/hazmat/backends/test_multibackend.py
+++ b/tests/hazmat/backends/test_multibackend.py
@@ -18,8 +18,8 @@ from cryptography.exceptions import (
     UnsupportedAlgorithm, _Reasons
 )
 from cryptography.hazmat.backends.interfaces import (
-    CipherBackend, HMACBackend, HashBackend, PBKDF2HMACBackend, RSABackend,
-    DSABackend
+    CipherBackend, DSABackend, HMACBackend, HashBackend, PBKDF2HMACBackend,
+    RSABackend
 )
 from cryptography.hazmat.backends.multibackend import MultiBackend
 from cryptography.hazmat.primitives import hashes, hmac
@@ -28,8 +28,6 @@ from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
 
 from ...utils import raises_unsupported_algorithm
 
-from pretend import stub
-
 
 @utils.register_interface(CipherBackend)
 class DummyCipherBackend(object):
@@ -213,7 +211,7 @@ class TestMultiBackend(object):
 
         backend.generate_dsa_parameters(key_size=1024)
 
-        parameters = stub()
+        parameters = object()
         backend.generate_dsa_private_key(parameters)
 
         backend = MultiBackend([])