Merge pull request #888 from reaperhulk/rsa-decrypt

RSA PKCS1v15 Decryption Support

4 files changed, 66 insertions, 4 deletions

diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst
index 394d060b..71cd4564 100644
--- a/docs/hazmat/backends/interfaces.rst
+++ b/docs/hazmat/backends/interfaces.rst
@@ -263,6 +263,18 @@ A specific ``backend`` may provide one or more of these interfaces.
         :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 89af7eaa..f33ca4e2 100644
--- a/docs/hazmat/primitives/asymmetric/padding.rst
+++ b/docs/hazmat/primitives/asymmetric/padding.rst
@@ -19,7 +19,8 @@ Padding
 
     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 +38,8 @@ Padding
     .. 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index c9de2831..c282d9ef 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -116,6 +116,36 @@ RSA
         :raises ValueError: This is raised when the chosen hash algorithm is
             too large for the key size.
 
+    .. method:: decrypt(ciphertext, padding, backend)
+
+        .. versionadded:: 0.4
+
+        Decrypt data that was encrypted with the public key.
+
+        :param bytes ciphertext: The ciphertext to decrypt.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :return bytes: Decrypted data.
+
+        :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if
+            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.
+
+        :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.
+
 
 .. class:: RSAPublicKey(public_exponent, modulus)
 
@@ -221,7 +251,7 @@ 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 ``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.
@@ -241,7 +271,7 @@ this without having to do the math themselves.
     ``p``.
 
 .. function:: rsa_crt_dmq1(private_exponent, q)
-    
+
     .. versionadded:: 0.4
 
     Generates the ``dmq1`` parameter from the RSA private exponent and prime
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index 95fd6f9f..3b837a0d 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -133,6 +133,24 @@ Asymmetric interfaces
         :returns:
             :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
 
+    .. method:: decrypt(ciphertext, padding, backend)
+
+        .. versionadded:: 0.4
+
+        Decrypt data that was encrypted via the public key.
+
+        :param bytes ciphertext: The ciphertext to decrypt.
+
+        :param padding: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding`
+            provider.
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :return bytes: Decrypted data.
+
     .. method:: public_key()
 
         :return: :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey`