add generate_private_key to DSAParameters + add a new function to dsa

dsa.generate_private_key(key_size, backend) will allow you to generate a
new DSA key and implicitly generate new parameters. This streamlines the
common case and will be an avenue to support future backends that don't
allow independent generation of DSAParameters (e.g. CommonCrypto)

2 files changed, 31 insertions, 12 deletions

diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 42e3af2e..095c49b9 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -7,11 +7,12 @@ DSA
 
 `DSA`_ is a `public-key`_ algorithm for signing messages.
 
-.. function:: generate_parameters(key_size, backend)
+.. function:: generate_private_key(key_size, backend)
 
     .. versionadded:: 0.5
 
-    Generate DSA parameters using the provided ``backend``.
+    Generate a DSA private key from the given key size. This function will
+    generate a new set of parameters and key in one step.
 
     :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
@@ -24,26 +25,33 @@ DSA
         :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
         provider.
 
-    :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+    :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
         provider.
 
-    :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
-        the provided ``backend`` does not implement
-        :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
-
-.. function:: generate_private_key(parameters)
+.. function:: generate_parameters(key_size, backend)
 
     .. versionadded:: 0.5
 
-    Generate an DSA private key using the provided parameters.
+    Generate DSA parameters using the provided ``backend``.
 
-    :param parameters: A
-        :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
+    :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.
+
+    :param backend: A
+        :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
         provider.
 
-    :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+    :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
         provider.
 
+    :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+        the provided ``backend`` does not implement
+        :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+
 .. class:: DSAParameters(modulus, subgroup_order, generator)
 
     .. versionadded:: 0.4
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 755cef41..ac47c1e1 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -282,6 +282,17 @@ DSA
 
     `DSA`_ parameters.
 
+    .. method:: generate_private_key()
+
+        .. versionadded:: 0.5
+
+        Generate a DSA private key. This method can be used to generate many
+        new private keys from a single set of parameters.
+
+        :return: A
+            :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+            provider.
+
 
 .. class:: DSAParametersWithNumbers