RSA doc update for deprecation. Move some examples.

1 files changed, 260 insertions, 258 deletions

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index c3962901..f621dbd7 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -7,6 +7,8 @@ RSA
 
 `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 @@ RSA
         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 @@ RSA
         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 @@ RSA
 
         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 @@ RSA
             :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 @@ RSA
         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 @@ RSA
             :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