OAEP support for RSA decryption

2 files changed, 26 insertions, 2 deletions

diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst
index f33ca4e2..949fdaf2 100644
--- a/docs/hazmat/primitives/asymmetric/padding.rst
+++ b/docs/hazmat/primitives/asymmetric/padding.rst
@@ -33,6 +33,21 @@ Padding
         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""`` (equivalent values).
+
 .. class:: PKCS1v15()
 
     .. versionadded:: 0.3
@@ -62,3 +77,4 @@ Mask generation functions
 .. _`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 c282d9ef..cb8ce91a 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -138,13 +138,21 @@ RSA
             the provided ``backend`` does not implement
             :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if
             the backend does not support the chosen hash or padding algorithm.
+            If the padding is
+            :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP`
+            with the
+            :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1`
+            mask generation function it may also refer to the ``MGF1`` hash
+            algorithm.
 
         :raises TypeError: This is raised when the padding is not an
             :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
             provider.
 
-        :raises ValueError: This is raised when decryption fails or the chosen
-            hash algorithm is too large for the key size.
+        :raises ValueError: This is raised when decryption fails or the data
+            is too large for the key size. If the padding is
+            :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP`
+            it may also be raised for invalid label values.
 
 
 .. class:: RSAPublicKey(public_exponent, modulus)