Merge pull request #1191 from reaperhulk/dsa-deprecate-backend-methods
deprecate DSA backend methods
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index a880c7e..e057b63 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -28,6 +28,15 @@
* Deprecated :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`
in favor of backend specific providers of the
:class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` interface.
+* Deprecated :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`
+ in favor of backend specific providers of the
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` interface.
+* Deprecated :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`
+ in favor of backend specific providers of the
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` interface.
+* Deprecated :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`
+ in favor of backend specific providers of the
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` interface.
* Deprecated ``encrypt_rsa``, ``decrypt_rsa``, ``create_rsa_signature_ctx`` and
``create_rsa_verification_ctx`` on
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`.
diff --git a/cryptography/hazmat/primitives/asymmetric/dsa.py b/cryptography/hazmat/primitives/asymmetric/dsa.py
index 7a8a61c..04b2272 100644
--- a/cryptography/hazmat/primitives/asymmetric/dsa.py
+++ b/cryptography/hazmat/primitives/asymmetric/dsa.py
@@ -13,6 +13,8 @@
from __future__ import absolute_import, division, print_function
+import warnings
+
import six
from cryptography import utils
@@ -56,6 +58,12 @@
@utils.register_interface(interfaces.DSAParameters)
class DSAParameters(object):
def __init__(self, modulus, subgroup_order, generator):
+ warnings.warn(
+ "The DSAParameters class is deprecated and will be removed in a "
+ "future version.",
+ utils.DeprecatedIn05,
+ stacklevel=2
+ )
_check_dsa_parameters(
DSAParameterNumbers(
p=modulus,
@@ -70,6 +78,11 @@
@classmethod
def generate(cls, key_size, backend):
+ warnings.warn(
+ "generate is deprecated and will be removed in a future version.",
+ utils.DeprecatedIn05,
+ stacklevel=2
+ )
if not isinstance(backend, DSABackend):
raise UnsupportedAlgorithm(
"Backend object does not implement DSABackend.",
@@ -112,6 +125,12 @@
@utils.register_interface(interfaces.DSAPrivateKey)
class DSAPrivateKey(object):
def __init__(self, modulus, subgroup_order, generator, x, y):
+ warnings.warn(
+ "The DSAPrivateKey class is deprecated and will be removed in a "
+ "future version.",
+ utils.DeprecatedIn05,
+ stacklevel=2
+ )
if (
not isinstance(x, six.integer_types) or
not isinstance(y, six.integer_types)
@@ -140,6 +159,11 @@
@classmethod
def generate(cls, parameters, backend):
+ warnings.warn(
+ "generate is deprecated and will be removed in a future version.",
+ utils.DeprecatedIn05,
+ stacklevel=2
+ )
if not isinstance(backend, DSABackend):
raise UnsupportedAlgorithm(
"Backend object does not implement DSABackend.",
@@ -189,6 +213,12 @@
@utils.register_interface(interfaces.DSAPublicKey)
class DSAPublicKey(object):
def __init__(self, modulus, subgroup_order, generator, y):
+ warnings.warn(
+ "The DSAPublicKey class is deprecated and will be removed in a "
+ "future version.",
+ utils.DeprecatedIn05,
+ stacklevel=2
+ )
_check_dsa_parameters(
DSAParameterNumbers(
p=modulus,
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 095c49b..6cb624d 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -7,6 +7,9 @@
`DSA`_ is a `public-key`_ algorithm for signing messages.
+Generation
+~~~~~~~~~~
+
.. function:: generate_private_key(key_size, backend)
.. versionadded:: 0.5
@@ -28,6 +31,10 @@
: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,208 +59,41 @@
the provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.DSABackend`
-.. class:: DSAParameters(modulus, subgroup_order, generator)
+Signing
+~~~~~~~
- .. versionadded:: 0.4
+Using a :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`
+provider.
- DSA Parameters are required for generating a DSA private key.
+.. doctest::
- You should use :meth:`~generate` to generate new parameters.
+ >>> 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()
- .. 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.
+Verification
+~~~~~~~~~~~~
+Using a :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
+provider.
- This class conforms to the
- :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`
- interface.
+.. doctest::
- :raises TypeError: This is raised when the arguments are not all integers.
+ >>> public_key = private_key.public_key()
+ >>> verifier = public_key.verifier(signature, hashes.SHA256())
+ >>> verifier.update(data)
+ >>> verifier.verify()
- :raises ValueError: This is raised when the values of ``modulus``,
- ``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)
-
- .. versionadded:: 0.4
-
- 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.
-
- :raises TypeError: This is raised when the arguments are not all integers.
-
- :raises ValueError: This is raised when the values of ``modulus``,
- ``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.
-
- .. method:: signer(algorithm, backend)
-
- .. versionadded:: 0.4
-
- 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.
-
- :param backend: A
- :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
- provider.
-
- :returns:
- :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
-
- :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
- the provided ``backend`` does not implement
- :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
-
-
-.. class:: DSAPublicKey(modulus, subgroup_order, generator, y)
-
- .. versionadded:: 0.4
-
- A DSA public key is required for verifying messages.
-
- Normally you do not need to directly construct public keys because you'll
- be loading them from a file, generating them automatically or receiving
- them from a 3rd party.
-
- This class conforms to the
- :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
- interface.
-
- :raises TypeError: This is raised when the arguments are not all integers.
-
- :raises ValueError: This is raised when the values of ``modulus``,
- ``subgroup_order``, ``generator``, or ``y``
- do not match the bounds specified in `FIPS 186-4`_.
-
- .. method:: verifier(signature, algorithm, backend)
-
- .. versionadded:: 0.4
-
- 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`.
-
- :param algorithm: An instance of a
- :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
- provider.
-
- :param backend: A
- :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
- provider.
-
- :returns:
- :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
+Numbers
+~~~~~~~
.. class:: DSAParameterNumbers(p, q, g)
@@ -322,6 +162,175 @@
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.
+
+ .. 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.
+
+ :raises TypeError: This is raised when the arguments are not all integers.
+
+ :raises ValueError: This is raised when the values of ``modulus``,
+ ``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)
+
+ .. versionadded:: 0.4
+
+ .. deprecated:: 0.5
+
+ 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.
+
+ :raises TypeError: This is raised when the arguments are not all integers.
+
+ :raises ValueError: This is raised when the values of ``modulus``,
+ ``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.
+
+ .. method:: signer(algorithm, backend)
+
+ .. versionadded:: 0.4
+
+ Sign data which can be verified later by others using the public key.
+
+ :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.AsymmetricSignatureContext`
+
+ :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+ the provided ``backend`` does not implement
+ :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+
+
+.. class:: DSAPublicKey(modulus, subgroup_order, generator, y)
+
+ .. 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
+ be loading them from a file, generating them automatically or receiving
+ them from a 3rd party.
+
+ This class conforms to the
+ :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`
+ interface.
+
+ :raises TypeError: This is raised when the arguments are not all integers.
+
+ :raises ValueError: This is raised when the values of ``modulus``,
+ ``subgroup_order``, ``generator``, or ``y``
+ do not match the bounds specified in `FIPS 186-4`_.
+
+ .. method:: verifier(signature, algorithm, backend)
+
+ .. versionadded:: 0.4
+
+ Verify data was signed by the private key associated with this public
+ key.
+
+ :param bytes signature: The signature to verify. DER encoded as
+ specified in :rfc:`6979`.
+
+ :param algorithm: An instance of a
+ :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+ provider.
+
+ :param backend: A
+ :class:`~cryptography.hazmat.backends.interfaces.DSABackend`
+ provider.
+
+ :returns:
+ :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
+
.. _`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
diff --git a/tests/hazmat/primitives/test_dsa.py b/tests/hazmat/primitives/test_dsa.py
index 531b448..8c87cfd 100644
--- a/tests/hazmat/primitives/test_dsa.py
+++ b/tests/hazmat/primitives/test_dsa.py
@@ -698,9 +698,17 @@
verifier.verify()
def test_dsa_verify_invalid_asn1(self, backend):
- parameters = dsa.DSAParameters.generate(1024, backend)
- private_key = dsa.DSAPrivateKey.generate(parameters, backend)
- public_key = private_key.public_key()
+ parameters = pytest.deprecated_call(
+ dsa.DSAParameters.generate,
+ 1024,
+ backend
+ )
+ private_key = pytest.deprecated_call(
+ dsa.DSAPrivateKey.generate,
+ parameters,
+ backend
+ )
+ public_key = pytest.deprecated_call(private_key.public_key)
verifier = public_key.verifier(b'fakesig', hashes.SHA1(), backend)
verifier.update(b'fakesig')
with pytest.raises(InvalidSignature):