From 29474ac7dab3f5c8b664463ed28ec83b7b77250b Mon Sep 17 00:00:00 2001 From: Mohammed Attia Date: Wed, 2 Apr 2014 04:03:09 +0200 Subject: Add docs for DSA parameters and key generation --- docs/hazmat/backends/interfaces.rst | 34 ++++++++++++++++++ docs/hazmat/primitives/asymmetric/dsa.rst | 59 ++++++++++++++++++++++++++++++- 2 files changed, 92 insertions(+), 1 deletion(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index c38f818f..9c401d28 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -285,3 +285,37 @@ A specific ``backend`` may provide one or more of these interfaces. :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 69e8d58e..1a6a6e0e 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -13,6 +13,16 @@ DSA 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 @@ DSA ``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 @@ DSA 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 @@ DSA ``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 .. _`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 -- cgit v1.2.3