From 1040b39be5ddfaa1fc2a0b2c22780a832cd39aaf Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 3 Nov 2021 05:48:18 +0800 Subject: [PATCH] deprecate backend part 3 of n (#6521) finish the asymmetric docs --- docs/hazmat/primitives/asymmetric/dh.rst | 26 ++---- docs/hazmat/primitives/asymmetric/dsa.rst | 35 ++------ docs/hazmat/primitives/asymmetric/ed25519.rst | 8 +- docs/hazmat/primitives/asymmetric/rsa.rst | 22 +---- .../primitives/asymmetric/serialization.rst | 85 +++++-------------- 5 files changed, 42 insertions(+), 134 deletions(-) diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst index 3b8b58bae..e880b8145 100644 --- a/docs/hazmat/primitives/asymmetric/dh.rst +++ b/docs/hazmat/primitives/asymmetric/dh.rst @@ -115,27 +115,20 @@ peer:: peer_public_key = peer_public_numbers.public_key() -See also the :class:`~cryptography.hazmat.backends.interfaces.DHBackend` -API for additional functionality. - Group parameters ~~~~~~~~~~~~~~~~ -.. function:: generate_parameters(generator, key_size, backend=None) +.. function:: generate_parameters(generator, key_size) .. versionadded:: 1.7 - Generate a new DH parameter group for use with ``backend``. + Generate a new DH parameter group. :param generator: The :class:`int` to use as a generator. Must be 2 or 5. :param key_size: The bit length of the prime modulus to generate. - :param backend: An optional - :class:`~cryptography.hazmat.backends.interfaces.DHBackend` - instance. - :returns: DH parameters as a new instance of :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters`. @@ -336,13 +329,10 @@ Numbers p subgroup order value. - .. method:: parameters(backend=None) + .. method:: parameters() .. versionadded:: 1.7 - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DHBackend`. - :returns: A new instance of :class:`DHParameters`. .. class:: DHPrivateNumbers(x, public_numbers) @@ -364,13 +354,10 @@ Numbers The private value. - .. method:: private_key(backend=None) + .. method:: private_key() .. versionadded:: 1.7 - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DHBackend`. - :returns: A new instance of :class:`DHPrivateKey`. @@ -392,13 +379,10 @@ Numbers The public value. - .. method:: public_key(backend=None) + .. method:: public_key() .. versionadded:: 1.7 - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DHBackend`. - :returns: A new instance of :class:`DHPublicKey`. diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 60b162cb5..68059de93 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -17,7 +17,7 @@ DSA Generation ~~~~~~~~~~ -.. function:: generate_private_key(key_size, backend=None) +.. function:: generate_private_key(key_size) .. versionadded:: 0.5 @@ -34,17 +34,10 @@ Generation be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be `at least 2048`_ (See page 41). - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. - :return: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`. - :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=None) +.. function:: generate_parameters(key_size) .. versionadded:: 0.5 @@ -54,22 +47,15 @@ Generation continue to use DSA despite the wider cryptographic community's `ongoing protestations`_. - Generate DSA parameters using the provided ``backend``. + Generate DSA parameters. :param int key_size: The length of :attr:`~DSAParameterNumbers.q`. It should be either 1024, 2048, 3072, or 4096. For keys generated in 2015 this should be `at least 2048`_ (See page 41). - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. - :return: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`. - :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if - the provided ``backend`` does not implement - :class:`~cryptography.hazmat.backends.interfaces.DSABackend` - Signing ~~~~~~~ @@ -181,10 +167,7 @@ Numbers The generator. - .. method:: parameters(backend=None) - - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. + .. method:: parameters() :returns: A new instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameters`. @@ -208,10 +191,7 @@ Numbers The :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers` associated with the public key. - .. method:: public_key(backend=None) - - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. + .. method:: public_key() :returns: A new instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`. @@ -240,10 +220,7 @@ Numbers The :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers` associated with the private key. - .. method:: private_key(backend=None) - - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`. + .. method:: private_key() :returns: A new instance of :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`. diff --git a/docs/hazmat/primitives/asymmetric/ed25519.rst b/docs/hazmat/primitives/asymmetric/ed25519.rst index 152dcfe6f..3229f0932 100644 --- a/docs/hazmat/primitives/asymmetric/ed25519.rst +++ b/docs/hazmat/primitives/asymmetric/ed25519.rst @@ -45,8 +45,8 @@ Key interfaces :raises ValueError: This is raised if the private key is not 32 bytes long. - :raises cryptography.exceptions.UnsupportedAlgorithm: If the private key - is of a type that is not supported by the backend. + :raises cryptography.exceptions.UnsupportedAlgorithm: If Ed25519 is not + supported by the OpenSSL version ``cryptography`` is using. .. doctest:: @@ -115,8 +115,8 @@ Key interfaces :raises ValueError: This is raised if the public key is not 32 bytes long. - :raises cryptography.exceptions.UnsupportedAlgorithm: If the public key - is of a type that is not supported by the backend. + :raises cryptography.exceptions.UnsupportedAlgorithm: If Ed25519 is not + supported by the OpenSSL version ``cryptography`` is using. .. doctest:: diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 009e23ea4..1010c5280 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -14,7 +14,7 @@ Unlike symmetric cryptography, where the key is typically just a random series of bytes, RSA keys have a complex internal structure with `specific mathematical properties`_. -.. function:: generate_private_key(public_exponent, key_size, backend=None) +.. function:: generate_private_key(public_exponent, key_size) .. versionadded:: 0.5 @@ -22,7 +22,7 @@ mathematical properties`_. Tightened restrictions on ``public_exponent``. - Generates a new RSA private key using the provided ``backend``. + Generates a new RSA private key. ``key_size`` describes how many :term:`bits` long the key should be. Larger keys provide more security; currently ``1024`` and below are considered breakable while ``2048`` or ``4096`` are reasonable default key sizes for @@ -45,18 +45,10 @@ mathematical properties`_. :param int key_size: The length of the modulus in :term:`bits`. For keys generated in 2015 it is strongly recommended to be `at least 2048`_ (See page 41). It must not be less than 512. - Some backends may have additional limitations. - - :param backend: An optional backend which implements - :class:`~cryptography.hazmat.backends.interfaces.RSABackend`. :return: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`. - :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if - the provided ``backend`` does not implement - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - Key loading ~~~~~~~~~~~ @@ -402,10 +394,7 @@ is unavailable. The public exponent. - .. method:: public_key(backend=None) - - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.RSABackend`. + .. method:: public_key() :returns: A new instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`. @@ -469,10 +458,7 @@ is unavailable. A `Chinese remainder theorem`_ coefficient used to speed up RSA operations. Calculated as: q\ :sup:`-1` mod p - .. method:: private_key(backend=None) - - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.RSABackend`. + .. method:: private_key() :returns: An instance of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`. diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 05f2c2968..2cb2cda6f 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -125,7 +125,7 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END extract the public key with :meth:`Certificate.public_key `. -.. function:: load_pem_private_key(data, password, backend=None) +.. function:: load_pem_private_key(data, password) .. versionadded:: 0.6 @@ -139,9 +139,6 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END be ``None`` if the private key is not encrypted. :type data: :term:`bytes-like` - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`. - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`, :class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey`, @@ -162,9 +159,9 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END password was supplied. :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key - is of a type that is not supported by the backend. + type is not supported by the OpenSSL version ``cryptography`` is using. -.. function:: load_pem_public_key(data, backend=None) +.. function:: load_pem_public_key(data) .. versionadded:: 0.6 @@ -181,10 +178,6 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END :param bytes data: The PEM encoded key data. - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`. - - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`, :class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey`, @@ -201,10 +194,9 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END successfully. :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key - is of a type that is not supported by the backend. - -.. function:: load_pem_parameters(data, backend=None) + type is not supported by the OpenSSL version ``cryptography`` is using. +.. function:: load_pem_parameters(data) .. versionadded:: 2.0 Deserialize parameters from PEM encoded data to one of the supported @@ -220,10 +212,6 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END :param bytes data: The PEM encoded parameters data. - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.PEMSerializationBackend`. - - :returns: Currently only :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` supported. @@ -231,8 +219,8 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END :raises ValueError: If the PEM data's structure could not be decoded successfully. - :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized parameters - is of a type that is not supported by the backend. + :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key + type is not supported by the OpenSSL version ``cryptography`` is using. DER ~~~ @@ -242,7 +230,7 @@ data is binary. DER keys may be in a variety of formats, but as long as you know whether it is a public or private key the loading functions will handle the rest. -.. function:: load_der_private_key(data, password, backend=None) +.. function:: load_der_private_key(data, password) .. versionadded:: 0.8 @@ -256,9 +244,6 @@ the rest. be ``None`` if the private key is not encrypted. :type password: :term:`bytes-like` - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`. - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PrivateKey`, :class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PrivateKey`, @@ -279,7 +264,7 @@ the rest. password was supplied. :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key - is of a type that is not supported by the backend. + type is not supported by the OpenSSL version ``cryptography`` is using. .. doctest:: @@ -289,7 +274,7 @@ the rest. >>> isinstance(key, rsa.RSAPrivateKey) True -.. function:: load_der_public_key(data, backend=None) +.. function:: load_der_public_key(data) .. versionadded:: 0.8 @@ -299,9 +284,6 @@ the rest. :param bytes data: The DER encoded key data. - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`. - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.ed25519.Ed25519PublicKey`, :class:`~cryptography.hazmat.primitives.asymmetric.x25519.X25519PublicKey`, @@ -317,8 +299,8 @@ the rest. :raises ValueError: If the DER data's structure could not be decoded successfully. - :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that - is not supported by the backend. + :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key + type is not supported by the OpenSSL version ``cryptography`` is using. .. doctest:: @@ -328,7 +310,7 @@ the rest. >>> isinstance(key, rsa.RSAPublicKey) True -.. function:: load_der_parameters(data, backend=None) +.. function:: load_der_parameters(data) .. versionadded:: 2.0 @@ -337,9 +319,6 @@ the rest. :param bytes data: The DER encoded parameters data. - :param backend: An optional instance of - :class:`~cryptography.hazmat.backends.interfaces.DERSerializationBackend`. - :returns: Currently only :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` supported. @@ -347,8 +326,8 @@ the rest. :raises ValueError: If the DER data's structure could not be decoded successfully. - :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that - is not supported by the backend. + :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key + type is not supported by the OpenSSL version ``cryptography`` is using. .. doctest:: @@ -379,23 +358,17 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than ``ssh-rsa``. ECDSA keys have a slightly different format, they begin with ``ecdsa-sha2-{curve}``. -.. function:: load_ssh_public_key(data, backend=None) +.. function:: load_ssh_public_key(data) .. versionadded:: 0.7 Deserialize a public key from OpenSSH (:rfc:`4253` and `PROTOCOL.certkeys`_) encoded data to an - instance of the public key type for the specified backend. + instance of the public key type. :param data: The OpenSSH encoded key data. :type data: :term:`bytes-like` - :param backend: An optional backend which implements - :class:`~cryptography.hazmat.backends.interfaces.RSABackend`, - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`, or - :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` - depending on the key's type. - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKey`, :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicKey`, @@ -428,12 +401,12 @@ An example ECDSA key in OpenSSH format:: BAUGBw== -----END OPENSSH PRIVATE KEY----- -.. function:: load_ssh_private_key(data, password, backend=None) +.. function:: load_ssh_private_key(data, password) .. versionadded:: 3.0 Deserialize a private key from OpenSSH encoded data to an - instance of the private key type for the specified backend. + instance of the private key type. :param data: The PEM encoded OpenSSH private key data. :type data: :term:`bytes-like` @@ -441,12 +414,6 @@ An example ECDSA key in OpenSSH format:: :param bytes password: Password bytes to use to decrypt password-protected key. Or ``None`` if not needed. - :param backend: An optional backend which implements - :class:`~cryptography.hazmat.backends.interfaces.RSABackend`, - :class:`~cryptography.hazmat.backends.interfaces.DSABackend`, or - :class:`~cryptography.hazmat.backends.interfaces.EllipticCurveBackend` - depending on the key's type. - :returns: One of :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKey`, :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKey`, @@ -476,7 +443,7 @@ file suffix. ``cryptography`` only supports a single private key and associated certificates when parsing PKCS12 files at this time. -.. function:: load_key_and_certificates(data, password, backend=None) +.. function:: load_key_and_certificates(data, password) .. versionadded:: 2.5 @@ -489,8 +456,6 @@ file suffix. if the PKCS12 is not encrypted. :type password: :term:`bytes-like` - :param backend: An optional backend instance. - :returns: A tuple of ``(private_key, certificate, additional_certificates)``. ``private_key`` is a private key type or ``None``, ``certificate`` @@ -499,7 +464,7 @@ file suffix. ``additional_certificates`` is a list of all other :class:`~cryptography.x509.Certificate` instances in the PKCS12 object. -.. function:: load_pkcs12(data, password, backend=None) +.. function:: load_pkcs12(data, password) .. versionadded:: 36.0 @@ -514,8 +479,6 @@ file suffix. if the PKCS12 is not encrypted. :type password: :term:`bytes-like` - :param backend: An optional backend instance. - :returns: A :class:`~cryptography.hazmat.primitives.serialization.pkcs12.PKCS12KeyAndCertificates` instance. @@ -734,7 +697,7 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``, :param certificate: The :class:`~cryptography.x509.Certificate` to add. - .. method:: sign(encoding, options, backend=None) + .. method:: sign(encoding, options) :param encoding: :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM`, :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`, @@ -745,8 +708,6 @@ contain certificates, CRLs, and much more. PKCS7 files commonly have a ``p7b``, :return bytes: The signed PKCS7 message. - :param backend: An optional backend. - .. class:: PKCS7Options @@ -1011,7 +972,7 @@ Serialization Encryption Types .. class:: BestAvailableEncryption(password) - Encrypt using the best available encryption for a given key's backend. + Encrypt using the best available encryption for a given key. This is a curated encryption choice and the algorithm may change over time.