docs, tests, general huge improvements to RSA decryption
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 394d060..71cd456 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -263,6 +263,18 @@
:returns: ``True`` if the specified ``algorithm`` is supported by this
backend, otherwise ``False``.
+ .. method:: decrypt_rsa(private_key, ciphertext, padding)
+
+ :param private_key: An instance of an
+ :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey`
+ provider.
+
+ :param bytes ciphertext: The ciphertext to decrypt.
+
+ :param padding: An instance of an
+ :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+ provider.
+
.. class:: OpenSSLSerializationBackend
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst
index 89af7ea..0c2f7ce 100644
--- a/docs/hazmat/primitives/asymmetric/padding.rst
+++ b/docs/hazmat/primitives/asymmetric/padding.rst
@@ -10,6 +10,21 @@
correct padding signatures can be forged, messages decrypted, and private
keys compromised.
+.. 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 many
+ backends do not support it.
+
.. class:: PSS(mgf, salt_length)
.. versionadded:: 0.3
@@ -19,7 +34,8 @@
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.
+ 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`.
@@ -37,7 +53,8 @@
.. 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`.
+ developed for use with RSA keys. It is defined in :rfc:`3447`. This padding
+ can be used for signing and encryption.
Mask generation functions
~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,5 +75,6 @@
.. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/
+.. _`proven secure`: http://cseweb.ucsd.edu/users/mihir/papers/oae.pdf
.. _`security proof`: http://eprint.iacr.org/2001/062.pdf
.. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html