Add convenience methods to sign and verify w/ RSA (#2945)

This patch adds wrapper methods to allow the user to sign and verify a
single message block without having to go through the multi-step
process of creating a signer or verifier, updating it with the one
message, and finalizing the result. This will make signing and
verifying data more user-friendly when only using small messages.

Partial bug #1529

1 files changed, 73 insertions, 3 deletions

diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index c2a6d437..70e1678e 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -153,6 +153,20 @@ secure hash function and padding:
     >>> signer.update(message)
     >>> signature = signer.finalize()
 
+There is a shortcut to sign sufficiently short messages directly:
+
+.. doctest::
+
+    >>> message = b"A message I want to sign"
+    >>> signature = private_key.sign(
+    ...     message,
+    ...     padding.PSS(
+    ...         mgf=padding.MGF1(hashes.SHA256()),
+    ...         salt_length=padding.PSS.MAX_LENGTH
+    ...     ),
+    ...     hashes.SHA256()
+    ... )
+
 Valid paddings for signatures are
 :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` and
 :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15`. ``PSS``
@@ -190,6 +204,20 @@ a public key to use in verification using
 If the signature does not match, ``verify()`` will raise an
 :class:`~cryptography.exceptions.InvalidSignature` exception.
 
+There is a shortcut to verify sufficiently short messages directly:
+
+.. doctest::
+
+    >>> public_key.verify(
+    ...     signature,
+    ...     message,
+    ...     padding.PSS(
+    ...         mgf=padding.MGF1(hashes.SHA256()),
+    ...         salt_length=padding.PSS.MAX_LENGTH
+    ...     ),
+    ...     hashes.SHA256()
+    ... )
+
 Encryption
 ~~~~~~~~~~
 
@@ -486,7 +514,8 @@ Key interfaces
 
         .. versionadded:: 0.3
 
-        Sign data which can be verified later by others using the public key.
+        Get signer to sign data which can be verified later by others using
+        the public key.
 
         :param padding: An instance of a
             :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`
@@ -525,6 +554,25 @@ Key interfaces
 
         The bit length of the modulus.
 
+    .. method:: sign(data, padding, algorithm)
+
+        .. versionadded:: 1.4
+
+        Sign one block of data which can be verified later by others using the
+        public key.
+
+        :param bytes data: The message string to sign.
+
+        :param padding: An instance of an
+            :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`
+            provider.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+            provider.
+
+        :return: bytes: Signature.
+
 
 .. class:: RSAPrivateKeyWithSerialization
 
@@ -580,8 +628,8 @@ Key interfaces
 
         .. versionadded:: 0.3
 
-        Verify data was signed by the private key associated with this public
-        key.
+        Get verifier to verify data was signed by the private key associated
+        with this public key.
 
         :param bytes signature: The signature to verify.
 
@@ -645,6 +693,28 @@ Key interfaces
 
         :return bytes: Serialized key.
 
+    .. method:: verify(signature, data, padding, algorithm)
+
+        .. versionadded:: 1.4
+
+        Verify one block of data which can be verified later by others using the
+        public key.
+
+        :param bytes signature: The signature to verify.
+
+        :param bytes data: The message string that was signed.
+
+        :param padding: An instance of an
+            :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`
+            provider.
+
+        :param algorithm: An instance of a
+            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`
+            provider.
+
+        :raises cryptography.exceptions.InvalidSignature: If the signature does
+            not validate.
+
 
 .. class:: RSAPublicKeyWithSerialization