Fixed #1555 and fixed #1556 -- moved the RSA padding docs into the primary RSA doc, and tell people that PKCS1v15 isn't great

3 files changed, 77 insertions, 81 deletions

diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index 24f0f5b1..dfa81d09 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -9,6 +9,5 @@ Asymmetric algorithms
     dsa
     ec
     rsa
-    padding
     serialization
     utils
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst
deleted file mode 100644
index 00c77590..00000000
--- a/docs/hazmat/primitives/asymmetric/padding.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-.. hazmat::
-
-Padding
-=======
-
-.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding
-
-.. warning::
-    `Padding is critical`_ when signing or encrypting data using RSA. Without
-    correct padding signatures can be forged, messages decrypted, and private
-    keys compromised.
-
-.. class:: PSS(mgf, salt_length)
-
-    .. versionadded:: 0.3
-
-    .. versionchanged:: 0.4
-        Added ``salt_length`` parameter.
-
-    PSS (Probabilistic Signature Scheme) is a signature scheme defined in
-    :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_.
-    This is the `recommended padding algorithm`_ for RSA signatures. It cannot
-    be used with RSA encryption.
-
-    :param mgf: A mask generation function object. At this time the only
-        supported MGF is :class:`MGF1`.
-
-    :param int salt_length: The length of the salt. It is recommended that this
-        be set to ``PSS.MAX_LENGTH``.
-
-    .. attribute:: MAX_LENGTH
-
-        Pass this attribute to ``salt_length`` to get the maximum salt length
-        available.
-
-.. class:: OAEP(mgf, label)
-
-    .. versionadded:: 0.4
-
-    OAEP (Optimal Asymmetric Encryption Padding) is a padding scheme defined in
-    :rfc:`3447`. It provides probabilistic encryption and is `proven secure`_
-    against several attack types. This is the `recommended padding algorithm`_
-    for RSA encryption. It cannot be used with RSA signing.
-
-    :param mgf: A mask generation function object. At this time the only
-        supported MGF is :class:`MGF1`.
-
-    :param bytes label: A label to apply. This is a rarely used field and
-        should typically be set to ``None`` or ``b""``, which are equivalent.
-
-.. class:: PKCS1v15()
-
-    .. versionadded:: 0.3
-
-    PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme
-    developed for use with RSA keys. It is defined in :rfc:`3447`. This padding
-    can be used for signing and encryption.
-
-Mask generation functions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. class:: MGF1(algorithm)
-
-    .. versionadded:: 0.3
-
-    .. versionchanged:: 0.6
-        Removed the deprecated ``salt_length`` parameter.
-
-    MGF1 (Mask Generation Function 1) is used as the mask generation function
-    in :class:`PSS` padding. It takes a hash algorithm and a salt length.
-
-    :param algorithm: An instance of a
-        :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
-        provider.
-
-
-.. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/
-.. _`security proof`: http://eprint.iacr.org/2001/062.pdf
-.. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
-.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 6c96090a..b553a067 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -128,9 +128,83 @@ provider.
     ...     )
     ... )
 
+Padding
+~~~~~~~
+
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding
+
+.. class:: PSS(mgf, salt_length)
+
+    .. versionadded:: 0.3
+
+    .. versionchanged:: 0.4
+        Added ``salt_length`` parameter.
+
+    PSS (Probabilistic Signature Scheme) is a signature scheme defined in
+    :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_.
+    This is the `recommended padding algorithm`_ for RSA signatures. It cannot
+    be used with RSA encryption.
+
+    :param mgf: A mask generation function object. At this time the only
+        supported MGF is :class:`MGF1`.
+
+    :param int salt_length: The length of the salt. It is recommended that this
+        be set to ``PSS.MAX_LENGTH``.
+
+    .. attribute:: MAX_LENGTH
+
+        Pass this attribute to ``salt_length`` to get the maximum salt length
+        available.
+
+.. class:: OAEP(mgf, label)
+
+    .. versionadded:: 0.4
+
+    OAEP (Optimal Asymmetric Encryption Padding) is a padding scheme defined in
+    :rfc:`3447`. It provides probabilistic encryption and is `proven secure`_
+    against several attack types. This is the `recommended padding algorithm`_
+    for RSA encryption. It cannot be used with RSA signing.
+
+    :param mgf: A mask generation function object. At this time the only
+        supported MGF is :class:`MGF1`.
+
+    :param bytes label: A label to apply. This is a rarely used field and
+        should typically be set to ``None`` or ``b""``, which are equivalent.
+
+.. class:: PKCS1v15()
+
+    .. versionadded:: 0.3
+
+    PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme
+    developed for use with RSA keys. It is defined in :rfc:`3447`. This padding
+    can be used for signing and encryption.
+
+    It is not recommended that ``PKCS1v15`` be used for new applications,
+    :class:`OAEP` should be preferred for encryption and :class:`PSS` should be
+    preferred for signatures.
+
+Mask generation functions
+-------------------------
+
+.. class:: MGF1(algorithm)
+
+    .. versionadded:: 0.3
+
+    .. versionchanged:: 0.6
+        Removed the deprecated ``salt_length`` parameter.
+
+    MGF1 (Mask Generation Function 1) is used as the mask generation function
+    in :class:`PSS` padding. It takes a hash algorithm and a salt length.
+
+    :param algorithm: An instance of a
+        :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+        provider.
+
 Numbers
 ~~~~~~~
 
+.. currentmodule:: cryptography.hazmat.primitives.asymmetric.rsa
+
 These classes hold the constituent components of an RSA key. They are useful
 only when more traditional :doc:`/hazmat/primitives/asymmetric/serialization`
 is unavailable.
@@ -272,3 +346,6 @@ this without having to do the math themselves.
 .. _`at least 2048`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf
 .. _`OpenPGP`: https://en.wikipedia.org/wiki/Pretty_Good_Privacy
 .. _`Chinese Remainder Theorem`: https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29#Using_the_Chinese_remainder_algorithm
+.. _`security proof`: http://eprint.iacr.org/2001/062.pdf
+.. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html
+.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf