From 125857f8ce6a7fc09d0e208d9bcd8321cc5ac2d4 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 25 Jun 2014 08:44:30 -0600 Subject: dsa docs --- docs/hazmat/primitives/asymmetric/dsa.rst | 37 +++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 2167e528..42e3af2e 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -7,6 +7,43 @@ DSA `DSA`_ is a `public-key`_ algorithm for signing messages. +.. 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` + +.. function:: generate_private_key(parameters) + + .. versionadded:: 0.5 + + Generate an DSA private key using the provided parameters. + + :param parameters: A + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + provider. + + :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + provider. + .. class:: DSAParameters(modulus, subgroup_order, generator) .. versionadded:: 0.4 -- cgit v1.2.3 From dacb5f9951064d19ac69c1198985af136f71a6db Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 27 Jun 2014 09:15:07 -0600 Subject: add generate_private_key to DSAParameters + add a new function to dsa dsa.generate_private_key(key_size, backend) will allow you to generate a new DSA key and implicitly generate new parameters. This streamlines the common case and will be an avenue to support future backends that don't allow independent generation of DSAParameters (e.g. CommonCrypto) --- docs/hazmat/primitives/asymmetric/dsa.rst | 32 +++++++++++++++++++------------ docs/hazmat/primitives/interfaces.rst | 11 +++++++++++ 2 files changed, 31 insertions(+), 12 deletions(-) (limited to 'docs/hazmat') diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 42e3af2e..095c49b9 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -7,11 +7,12 @@ DSA `DSA`_ is a `public-key`_ algorithm for signing messages. -.. function:: generate_parameters(key_size, backend) +.. function:: generate_private_key(key_size, backend) .. versionadded:: 0.5 - Generate DSA parameters using the provided ``backend``. + 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 @@ -24,26 +25,33 @@ DSA :class:`~cryptography.hazmat.backends.interfaces.DSABackend` provider. - :return: A :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + :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_private_key(parameters) +.. function:: generate_parameters(key_size, backend) .. versionadded:: 0.5 - Generate an DSA private key using the provided parameters. + Generate DSA parameters using the provided ``backend``. - :param parameters: A - :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + :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` + :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 -- cgit v1.2.3 From 298effd54c11ed47077f580f74d9204f7acce3f5 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 27 Jun 2014 14:07:59 -0600 Subject: rename backend method, add some docs --- docs/hazmat/backends/interfaces.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/hazmat') 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 -- cgit v1.2.3