RSA doc update for deprecation. Move some examples.
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index c396290..f621dbd 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -7,6 +7,8 @@
`RSA`_ is a `public-key`_ algorithm for encrypting and signing messages.
+Generation
+~~~~~~~~~~
.. function:: generate_private_key(public_exponent, key_size, backend)
@@ -31,10 +33,266 @@
the provided ``backend`` does not implement
:class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+Signing
+~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+provider.
+
+.. doctest::
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding
+ >>> private_key = rsa.generate_private_key(
+ ... public_exponent=65537,
+ ... key_size=2048,
+ ... backend=default_backend()
+ ... )
+ >>> signer = private_key.signer(
+ ... padding.PSS(
+ ... mgf=padding.MGF1(hashes.SHA256()),
+ ... salt_length=padding.PSS.MAX_LENGTH
+ ... ),
+ ... hashes.SHA256()
+ ... )
+ >>> signer.update(b"this is some data I'd like")
+ >>> signer.update(b" to sign")
+ >>> signature = signer.finalize()
+
+
+Verification
+~~~~~~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
+provider.
+
+.. doctest::
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding
+ >>> private_key = rsa.generate_private_key(
+ ... public_exponent=65537,
+ ... key_size=2048,
+ ... backend=default_backend()
+ ... )
+ >>> signer = private_key.signer(
+ ... padding.PSS(
+ ... mgf=padding.MGF1(hashes.SHA256()),
+ ... salt_length=padding.PSS.MAX_LENGTH
+ ... ),
+ ... hashes.SHA256()
+ ... )
+ >>> data = b"this is some data I'd like to sign"
+ >>> signer.update(data)
+ >>> signature = signer.finalize()
+ >>> public_key = private_key.public_key()
+ >>> verifier = public_key.verifier(
+ ... signature,
+ ... padding.PSS(
+ ... mgf=padding.MGF1(hashes.SHA256()),
+ ... salt_length=padding.PSS.MAX_LENGTH
+ ... ),
+ ... hashes.SHA256()
+ ... )
+ >>> verifier.update(data)
+ >>> verifier.verify()
+
+Encryption
+~~~~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
+provider.
+
+.. doctest::
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.asymmetric import padding
+
+ >>> # Generate a key
+ >>> private_key = rsa.generate_private_key(
+ ... public_exponent=65537,
+ ... key_size=2048,
+ ... backend=default_backend()
+ ... )
+ >>> public_key = private_key.public_key()
+ >>> # encrypt some data
+ >>> ciphertext = public_key.encrypt(
+ ... b"encrypted data",
+ ... padding.OAEP(
+ ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
+ ... algorithm=hashes.SHA1(),
+ ... label=None
+ ... )
+ ... )
+
+Decryption
+~~~~~~~~~~
+
+Using a :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+provider.
+
+.. doctest::
+
+ >>> from cryptography.hazmat.backends import default_backend
+ >>> from cryptography.hazmat.primitives import hashes
+ >>> from cryptography.hazmat.primitives.asymmetric import padding
+
+ >>> # Generate a key
+ >>> private_key = rsa.generate_private_key(
+ ... public_exponent=65537,
+ ... key_size=2048,
+ ... backend=default_backend()
+ ... )
+ >>> public_key = private_key.public_key()
+ >>> # encrypt some data
+ >>> ciphertext = public_key.encrypt(
+ ... b"encrypted data",
+ ... padding.OAEP(
+ ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
+ ... algorithm=hashes.SHA1(),
+ ... label=None
+ ... )
+ ... )
+ >>> # Now do the actual decryption
+ >>> plaintext = private_key.decrypt(
+ ... ciphertext,
+ ... padding.OAEP(
+ ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
+ ... algorithm=hashes.SHA1(),
+ ... label=None
+ ... )
+ ... )
+
+Numbers
+~~~~~~~
+
+These classes hold the constituent components of an RSA key. They are useful
+only when more traditional :doc:`/hazmat/primitives/asymmetric/serialization`
+is unavailable.
+
+.. class:: RSAPublicNumbers(e, n)
+
+ .. versionadded:: 0.5
+
+ The collection of integers that make up an RSA public key.
+
+ .. attribute:: n
+
+ :type: int
+
+ The public modulus.
+
+ .. attribute:: e
+
+ :type: int
+
+ The public exponent.
+
+
+.. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers)
+
+ .. versionadded:: 0.5
+
+ The collection of integers that make up an RSA private key.
+
+ .. warning::
+
+ With the exception of the integers contained in the
+ :class:`RSAPublicNumbers` all attributes of this class must be kept
+ secret. Revealing them will compromise the security of any
+ cryptographic operations performed with a key loaded from them.
+
+ .. attribute:: public_numbers
+
+ :type: :class:`~cryptography.hazmat.primitives.rsa.RSAPublicNumbers`
+
+ The :class:`RSAPublicNumbers` which makes up the RSA public key
+ associated with this RSA private key.
+
+ .. attribute:: p
+
+ :type: int
+
+ ``p``, one of the two primes composing the :attr:`modulus`.
+
+ .. attribute:: q
+
+ :type: int
+
+ ``q``, one of the two primes composing the :attr:`modulus`.
+
+ .. attribute:: d
+
+ :type: int
+
+ The private exponent. Alias for :attr:`private_exponent`.
+
+ .. attribute:: dmp1
+
+ :type: int
+
+ A `Chinese remainder theorem`_ coefficient used to speed up RSA
+ operations. Calculated as: d mod (p-1)
+
+ .. attribute:: dmq1
+
+ :type: int
+
+ A `Chinese remainder theorem`_ coefficient used to speed up RSA
+ operations. Calculated as: d mod (q-1)
+
+ .. attribute:: iqmp
+
+ :type: int
+
+ A `Chinese remainder theorem`_ coefficient used to speed up RSA
+ operations. Calculated as: q\ :sup:`-1` mod p
+
+Handling partial RSA private keys
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are trying to load RSA private keys yourself you may find that not all
+parameters required by ``RSAPrivateNumbers`` are available. In particular the
+`Chinese Remainder Theorem`_ (CRT) values ``dmp1``, ``dmq1``, ``iqmp`` may be
+missing or present in a different form. For example `OpenPGP`_ does not include
+the ``iqmp``, ``dmp1`` or ``dmq1`` parameters.
+
+The following functions are provided for users who want to work with keys like
+this without having to do the math themselves.
+
+.. function:: rsa_crt_iqmp(p, q)
+
+ .. versionadded:: 0.4
+
+ Generates the ``iqmp`` (also known as ``qInv``) parameter from the RSA
+ primes ``p`` and ``q``.
+
+.. function:: rsa_crt_dmp1(private_exponent, p)
+
+ .. versionadded:: 0.4
+
+ Generates the ``dmp1`` parameter from the RSA private exponent and prime
+ ``p``.
+
+.. function:: rsa_crt_dmq1(private_exponent, q)
+
+ .. versionadded:: 0.4
+
+ Generates the ``dmq1`` parameter from the RSA private exponent and prime
+ ``q``.
+
+Deprecated Concrete Classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
.. class:: RSAPrivateKey(p, q, private_exponent, dmp1, dmq1, iqmp, public_exponent, modulus)
.. versionadded:: 0.2
+ .. deprecated:: 0.5
+
An RSA private key is required for decryption and signing of messages.
You should use :func:`generate_private_key` to generate new keys.
@@ -47,10 +305,6 @@
generated with software you trust.
- This class conforms to the
- :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
- interface.
-
:raises TypeError: This is raised when the arguments are not all integers.
:raises ValueError: This is raised when the values of ``p``, ``q``,
@@ -85,28 +339,6 @@
Sign data which can be verified later by others using the public key.
- .. doctest::
-
- >>> from cryptography.hazmat.backends import default_backend
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding
- >>> private_key = rsa.RSAPrivateKey.generate(
- ... public_exponent=65537,
- ... key_size=2048,
- ... backend=default_backend()
- ... )
- >>> signer = private_key.signer(
- ... padding.PSS(
- ... mgf=padding.MGF1(hashes.SHA256()),
- ... salt_length=padding.PSS.MAX_LENGTH
- ... ),
- ... hashes.SHA256(),
- ... default_backend()
- ... )
- >>> signer.update(b"this is some data I'd like")
- >>> signer.update(b" to sign")
- >>> signature = signer.finalize()
-
:param padding: An instance of a
:class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
provider. Valid values are
@@ -181,55 +413,19 @@
:class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP`
it may also be raised for invalid label values.
- .. doctest::
-
- >>> from cryptography.hazmat.backends import default_backend
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.asymmetric import padding
-
- >>> # Generate a key
- >>> private_key = rsa.RSAPrivateKey.generate(
- ... public_exponent=65537,
- ... key_size=2048,
- ... backend=default_backend()
- ... )
- >>> public_key = private_key.public_key()
- >>> # encrypt some data
- >>> ciphertext = public_key.encrypt(
- ... b"encrypted data",
- ... padding.OAEP(
- ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
- ... algorithm=hashes.SHA1(),
- ... label=None
- ... ),
- ... default_backend()
- ... )
- >>> # Now do the actual decryption
- >>> plaintext = private_key.decrypt(
- ... ciphertext,
- ... padding.OAEP(
- ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
- ... algorithm=hashes.SHA1(),
- ... label=None
- ... ),
- ... default_backend()
- ... )
-
.. class:: RSAPublicKey(public_exponent, modulus)
.. versionadded:: 0.2
+ .. deprecated:: 0.5
+
An RSA public key is required for encryption and verification of messages.
Normally you do not need to directly construct public keys because you'll
be loading them from a file, generating them automatically or receiving
them from a 3rd party.
- This class conforms to the
- :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
- interface.
-
:raises TypeError: This is raised when the arguments are not all integers.
:raises ValueError: This is raised when the values of ``public_exponent``
@@ -243,40 +439,6 @@
Verify data was signed by the private key associated with this public
key.
- .. doctest::
-
- >>> from cryptography.hazmat.backends import default_backend
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.asymmetric import rsa, padding
- >>> private_key = rsa.RSAPrivateKey.generate(
- ... public_exponent=65537,
- ... key_size=2048,
- ... backend=default_backend()
- ... )
- >>> signer = private_key.signer(
- ... padding.PSS(
- ... mgf=padding.MGF1(hashes.SHA256()),
- ... salt_length=padding.PSS.MAX_LENGTH
- ... ),
- ... hashes.SHA256(),
- ... default_backend()
- ... )
- >>> data = b"this is some data I'd like to sign"
- >>> signer.update(data)
- >>> signature = signer.finalize()
- >>> public_key = private_key.public_key()
- >>> verifier = public_key.verifier(
- ... signature,
- ... padding.PSS(
- ... mgf=padding.MGF1(hashes.SHA256()),
- ... salt_length=padding.PSS.MAX_LENGTH
- ... ),
- ... hashes.SHA256(),
- ... default_backend()
- ... )
- >>> verifier.update(data)
- >>> verifier.verify()
-
:param bytes signature: The signature to verify.
:param padding: An instance of a
@@ -354,166 +516,6 @@
:class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP`
it may also be raised for invalid label values.
- .. doctest::
-
- >>> from cryptography.hazmat.backends import default_backend
- >>> from cryptography.hazmat.primitives import hashes
- >>> from cryptography.hazmat.primitives.asymmetric import padding
-
- >>> # Generate a key
- >>> private_key = rsa.RSAPrivateKey.generate(
- ... public_exponent=65537,
- ... key_size=2048,
- ... backend=default_backend()
- ... )
- >>> public_key = private_key.public_key()
- >>> # encrypt some data
- >>> ciphertext = public_key.encrypt(
- ... b"encrypted data",
- ... padding.OAEP(
- ... mgf=padding.MGF1(algorithm=hashes.SHA1()),
- ... algorithm=hashes.SHA1(),
- ... label=None
- ... ),
- ... default_backend()
- ... )
-
-
-.. class:: RSAPublicNumbers(e, n)
-
- .. versionadded:: 0.5
-
- The collection of integers that make up an RSA public key.
-
- .. method:: public_key(backend)
-
- :param backend: A
- :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
- provider.
-
- :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`
- provider.
-
- :raises UnsupportedAlgorithm: If the given backend does not support
- loading numbers.
-
- .. attribute:: n
-
- :type: int
-
- The public modulus.
-
- .. attribute:: e
-
- :type: int
-
- The public exponent.
-
-
-.. class:: RSAPrivateNumbers(p, q, d, dmp1, dmq1, iqmp, public_numbers)
-
- .. versionadded:: 0.5
-
- The collection of integers that make up an RSA private key.
-
- .. warning::
-
- With the exception of the integers contained in the
- :class:`RSAPublicNumbers` all attributes of this class must be kept
- secret. Revealing them will compromise the security of any
- cryptographic operations performed with a key loaded from them.
-
- .. method:: private_key(backend)
-
- :param backend: A
- :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
- provider.
-
- :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
- provider.
-
- :raises UnsupportedAlgorithm: If the given backend does not support
- loading numbers.
-
- .. attribute:: public_numbers
-
- :type: :class:`~cryptography.hazmat.primitives.rsa.RSAPublicNumbers`
-
- The :class:`RSAPublicNumbers` which makes up the RSA public key
- associated with this RSA private key.
-
- .. attribute:: p
-
- :type: int
-
- ``p``, one of the two primes composing the :attr:`modulus`.
-
- .. attribute:: q
-
- :type: int
-
- ``q``, one of the two primes composing the :attr:`modulus`.
-
- .. attribute:: d
-
- :type: int
-
- The private exponent. Alias for :attr:`private_exponent`.
-
- .. attribute:: dmp1
-
- :type: int
-
- A `Chinese remainder theorem`_ coefficient used to speed up RSA
- operations. Calculated as: d mod (p-1)
-
- .. attribute:: dmq1
-
- :type: int
-
- A `Chinese remainder theorem`_ coefficient used to speed up RSA
- operations. Calculated as: d mod (q-1)
-
- .. attribute:: iqmp
-
- :type: int
-
- A `Chinese remainder theorem`_ coefficient used to speed up RSA
- operations. Calculated as: q\ :sup:`-1` mod p
-
-
-Handling partial RSA private keys
----------------------------------
-
-If you are trying to load RSA private keys yourself you may find that not all
-parameters required by ``RSAPrivateKey`` are available. In particular the
-`Chinese Remainder Theorem`_ (CRT) values ``dmp1``, ``dmq1``, ``iqmp`` may be
-missing or present in a different form. For example `OpenPGP`_ does not include
-the ``iqmp``, ``dmp1`` or ``dmq1`` parameters.
-
-The following functions are provided for users who want to work with keys like
-this without having to do the math themselves.
-
-.. function:: rsa_crt_iqmp(p, q)
-
- .. versionadded:: 0.4
-
- Generates the ``iqmp`` (also known as ``qInv``) parameter from the RSA
- primes ``p`` and ``q``.
-
-.. function:: rsa_crt_dmp1(private_exponent, p)
-
- .. versionadded:: 0.4
-
- Generates the ``dmp1`` parameter from the RSA private exponent and prime
- ``p``.
-
-.. function:: rsa_crt_dmq1(private_exponent, q)
-
- .. versionadded:: 0.4
-
- Generates the ``dmq1`` parameter from the RSA private exponent and prime
- ``q``.
.. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)
.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography