saymrwulf/cryptography
1
0
Fork 0
mirror of https://github.com/saymrwulf/cryptography.git synced 2026-05-14 20:37:55 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

deprecate backend part 3 of n (#6521)

Browse source 
finish the asymmetric docs
This commit is contained in:
Paul Kehrer 2021-11-03 05:48:18 +08:00 committed by GitHub
parent dcf82c6c00
commit 1040b39be5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 42 additions and 134 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
docs/hazmat/primitives/asymmetric/dh.rst
View file

@ -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`.

35
docs/hazmat/primitives/asymmetric/dsa.rst
View file

@ -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`.

8
docs/hazmat/primitives/asymmetric/ed25519.rst
View file

@ -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::

22
docs/hazmat/primitives/asymmetric/rsa.rst
View file

@ -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`.

85
docs/hazmat/primitives/asymmetric/serialization.rst
View file

@ -125,7 +125,7 @@ all begin with ``-----BEGIN {format}-----`` and end with ``-----END
extract the public key with
:meth:`Certificate.public_key <cryptography.x509.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.