diff options
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 34 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 59 | ||||
| -rw-r--r-- | tests/hazmat/backends/test_multibackend.py | 8 |
3 files changed, 95 insertions, 6 deletions
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 diff --git a/tests/hazmat/backends/test_multibackend.py b/tests/hazmat/backends/test_multibackend.py index 4ec8a110..f46009d4 100644 --- a/tests/hazmat/backends/test_multibackend.py +++ b/tests/hazmat/backends/test_multibackend.py @@ -18,8 +18,8 @@ from cryptography.exceptions import ( 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 cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from ...utils import raises_unsupported_algorithm -from pretend import stub - @utils.register_interface(CipherBackend) class DummyCipherBackend(object): @@ -213,7 +211,7 @@ class TestMultiBackend(object): backend.generate_dsa_parameters(key_size=1024) - parameters = stub() + parameters = object() backend.generate_dsa_private_key(parameters) backend = MultiBackend([]) |