Merge pull request #1179 from reaperhulk/dsa-numbers-opaque-backend

DSA Opaque Keys for OpenSSL

3 files changed, 72 insertions, 0 deletions

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 5cbd47d1..fea935ce 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -421,6 +421,22 @@ A specific ``backend`` may provide one or more of these interfaces.
             1.0.0 and the key size is larger than 1024; older OpenSSL versions
             do not support keys larger than 1024 bits.
 
+    .. method:: generate_dsa_private_key_and_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.DSAPrivateKey`
+            provider.
+
+        :raises ValueError: This is raised if the key size is not supported
+            by the backend.
+
     .. method:: create_dsa_signature_ctx(private_key, algorithm)
 
         :param private_key: An instance of a
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 2167e528..095c49b9 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -7,6 +7,51 @@ DSA
 
 `DSA`_ is a `public-key`_ algorithm for signing messages.
 
+.. function:: generate_private_key(key_size, backend)
+
+    .. versionadded:: 0.5
+
+    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
+        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`
+        provider.
+
+.. function:: generate_parameters(key_size, backend)
+
+    .. versionadded:: 0.5
+
+    Generate DSA parameters using the provided ``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.
+
+    :param backend: A
+        :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+        provider.
+
+    :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