Add docs for DSA parameters and key generation
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index c38f818..9c401d2 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -285,3 +285,37 @@
: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 69e8d58..1a6a6e0 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -13,6 +13,16 @@
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 @@
``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 @@
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 @@
``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`: 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 4ec8a11..f46009d 100644
--- a/tests/hazmat/backends/test_multibackend.py
+++ b/tests/hazmat/backends/test_multibackend.py
@@ -18,8 +18,8 @@
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 ...utils import raises_unsupported_algorithm
-from pretend import stub
-
@utils.register_interface(CipherBackend)
class DummyCipherBackend(object):
@@ -213,7 +211,7 @@
backend.generate_dsa_parameters(key_size=1024)
- parameters = stub()
+ parameters = object()
backend.generate_dsa_private_key(parameters)
backend = MultiBackend([])