Merge pull request #673 from reaperhulk/rsa-pkcs1-signature-only

Add RSA PKCS1 signing (and structure for PSS + verification)

5 files changed, 76 insertions, 1 deletions

diff --git a/docs/exceptions.rst b/docs/exceptions.rst
index 8ca9df29..0982426f 100644
--- a/docs/exceptions.rst
+++ b/docs/exceptions.rst
@@ -42,3 +42,8 @@ Exceptions
 
     This is raised when the verify method of a one time password function's
     computed token does not match the expected token.
+
+
+.. class:: UnsupportedPadding
+
+    This is raised when the chosen padding is not supported by the backend.
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
new file mode 100644
index 00000000..10319fad
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -0,0 +1,10 @@
+.. hazmat::
+
+Asymmetric Algorithms
+=====================
+
+.. toctree::
+    :maxdepth: 1
+
+    rsa
+    padding
diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst
new file mode 100644
index 00000000..7aec3bd3
--- /dev/null
+++ b/docs/hazmat/primitives/asymmetric/padding.rst
@@ -0,0 +1,20 @@
+.. 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:: 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`.
+
+.. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/
diff --git a/docs/hazmat/primitives/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 4e1f8e49..682820b3 100644
--- a/docs/hazmat/primitives/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -50,6 +50,46 @@ RSA
             provider.
         :return: A new instance of ``RSAPrivateKey``.
 
+    .. method:: signer(padding, algorithm, backend)
+
+        .. versionadded:: 0.3
+
+        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.PKCS1v15(),
+            ...     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.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
+            provider.
+
+        :param backend: A
+            :class:`~cryptography.hazmat.backends.interfaces.RSABackend`
+            provider.
+
+        :returns:
+            :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext`
+
 
 .. class:: RSAPublicKey(public_exponent, modulus)
 
diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst
index 5199d493..90deec8b 100644
--- a/docs/hazmat/primitives/index.rst
+++ b/docs/hazmat/primitives/index.rst
@@ -11,7 +11,7 @@ Primitives
     symmetric-encryption
     padding
     key-derivation-functions
-    rsa
+    asymmetric/index
     constant-time
     interfaces
     twofactor