deprecate concrete DSA classes and update DSA docs

1 files changed, 126 insertions, 117 deletions

diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 095c49b9..6cb624dd 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -7,6 +7,9 @@ DSA
 
 `DSA`_ is a `public-key`_ algorithm for signing messages.
 
+Generation
+~~~~~~~~~~
+
 .. function:: generate_private_key(key_size, backend)
 
     .. versionadded:: 0.5
@@ -28,6 +31,10 @@ DSA
     :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_parameters(key_size, backend)
 
     .. versionadded:: 0.5
@@ -52,10 +59,125 @@ DSA
         the provided ``backend`` does not implement
         :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
 
+Signing
+~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+provider.
+
+.. doctest::
+
+    >>> from cryptography.hazmat.backends import default_backend
+    >>> from cryptography.hazmat.primitives import hashes
+    >>> from cryptography.hazmat.primitives.asymmetric import dsa
+    >>> private_key = dsa.generate_private_key(
+    ...     key_size=1024,
+    ...     backend=default_backend()
+    ... )
+    >>> signer = private_key.signer(hashes.SHA256())
+    >>> data = b"this is some data I'd like to sign"
+    >>> signer.update(data)
+    >>> signature = signer.finalize()
+
+Verification
+~~~~~~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
+provider.
+
+.. doctest::
+
+    >>> public_key = private_key.public_key()
+    >>> verifier = public_key.verifier(signature, hashes.SHA256())
+    >>> verifier.update(data)
+    >>> verifier.verify()
+
+Numbers
+~~~~~~~
+
+.. class:: DSAParameterNumbers(p, q, g)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up a set of DSA parameters.
+
+    .. attribute:: p
+
+        :type: int
+
+        The public modulus.
+
+    .. attribute:: q
+
+        :type: int
+
+        The sub-group order.
+
+    .. attribute:: g
+
+        :type: int
+
+        The generator.
+
+.. class:: DSAPublicNumbers(y, parameter_numbers)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up a DSA public key.
+
+    .. attribute:: y
+
+        :type: int
+
+        The public value ``y``.
+
+    .. attribute:: parameter_numbers
+
+        :type: :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
+
+        The :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
+        associated with the public key.
+
+.. class:: DSAPrivateNumbers(x, public_numbers)
+
+    .. versionadded:: 0.5
+
+    The collection of integers that make up a DSA private key.
+
+    .. warning::
+
+        Revealing the value of ``x`` will compromise the security of any
+        cryptographic operations performed.
+
+    .. attribute:: x
+
+        :type: int
+
+        The private value ``x``.
+
+    .. attribute:: public_numbers
+
+        :type: :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
+
+        The :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
+        associated with the private key.
+
+Deprecated Concrete Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These classes were deprecated in version 0.5 in favor of backend specific
+providers of the
+:class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`,
+:class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`, and
+:class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` interfaces.
+>>>>>>> deprecate concrete DSA classes and update DSA docs
+
 .. class:: DSAParameters(modulus, subgroup_order, generator)
 
     .. versionadded:: 0.4
 
+    .. deprecated:: 0.5
+
     DSA Parameters are required for generating a DSA private key.
 
     You should use :meth:`~generate` to generate new parameters.
@@ -100,6 +222,8 @@ DSA
 
     .. versionadded:: 0.4
 
+    .. deprecated:: 0.5
+
     A DSA private key is required for signing messages.
 
     You should use :meth:`~generate` to generate new keys.
@@ -148,27 +272,6 @@ DSA
 
         Sign data which can be verified later by others using the public key.
 
-        .. doctest::
-
-            >>> from cryptography.hazmat.backends import default_backend
-            >>> from cryptography.hazmat.primitives import hashes
-            >>> from cryptography.hazmat.primitives.asymmetric import dsa
-            >>> parameters = dsa.DSAParameters.generate(
-            ...     key_size=1024,
-            ...     backend=default_backend()
-            ... )
-            >>> private_key = dsa.DSAPrivateKey.generate(
-            ...     parameters=parameters,
-            ...     backend=default_backend()
-            ... )
-            >>> signer = private_key.signer(
-            ...     hashes.SHA256(),
-            ...     default_backend()
-            ... )
-            >>> data = b"this is some data I'd like to sign"
-            >>> signer.update(data)
-            >>> signature = signer.finalize()
-
         :param algorithm: An instance of a
             :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
             provider.
@@ -189,6 +292,8 @@ DSA
 
     .. versionadded:: 0.4
 
+    .. deprecated:: 0.5
+
     A DSA public key is required for verifying messages.
 
     Normally you do not need to directly construct public keys because you'll
@@ -212,35 +317,6 @@ DSA
         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 dsa
-            >>> parameters = dsa.DSAParameters.generate(
-            ...     key_size=1024,
-            ...     backend=default_backend()
-            ... )
-            >>> private_key = dsa.DSAPrivateKey.generate(
-            ...     parameters=parameters,
-            ...     backend=default_backend()
-            ... )
-            >>> signer = private_key.signer(
-            ...     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,
-            ...     hashes.SHA256(),
-            ...     default_backend()
-            ... )
-            >>> verifier.update(data)
-            >>> verifier.verify()
-
         :param bytes signature: The signature to verify. DER encoded as
             specified in :rfc:`6979`.
 
@@ -255,73 +331,6 @@ DSA
         :returns:
             :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
 
-.. class:: DSAParameterNumbers(p, q, g)
-
-    .. versionadded:: 0.5
-
-    The collection of integers that make up a set of DSA parameters.
-
-    .. attribute:: p
-
-        :type: int
-
-        The public modulus.
-
-    .. attribute:: q
-
-        :type: int
-
-        The sub-group order.
-
-    .. attribute:: g
-
-        :type: int
-
-        The generator.
-
-.. class:: DSAPublicNumbers(y, parameter_numbers)
-
-    .. versionadded:: 0.5
-
-    The collection of integers that make up a DSA public key.
-
-    .. attribute:: y
-
-        :type: int
-
-        The public value ``y``.
-
-    .. attribute:: parameter_numbers
-
-        :type: :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
-
-        The :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
-        associated with the public key.
-
-.. class:: DSAPrivateNumbers(x, public_numbers)
-
-    .. versionadded:: 0.5
-
-    The collection of integers that make up a DSA private key.
-
-    .. warning::
-
-        Revealing the value of ``x`` will compromise the security of any
-        cryptographic operations performed.
-
-    .. attribute:: x
-
-        :type: int
-
-        The private value ``x``.
-
-    .. attribute:: public_numbers
-
-        :type: :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
-
-        The :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
-        associated with the private key.
-
 .. _`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