1 files changed, 34 insertions, 57 deletions
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index 6cf0e499..121f156d 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -141,22 +141,6 @@ secure hash function and padding:
 
     >>> from cryptography.hazmat.primitives import hashes
     >>> from cryptography.hazmat.primitives.asymmetric import padding
-
-    >>> signer = private_key.signer(
-    ...     padding.PSS(
-    ...         mgf=padding.MGF1(hashes.SHA256()),
-    ...         salt_length=padding.PSS.MAX_LENGTH
-    ...     ),
-    ...     hashes.SHA256()
-    ... )
-    >>> message = b"A message I want to sign"
-    >>> 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,
@@ -173,6 +157,27 @@ Valid paddings for signatures are
 is the recommended choice for any new protocols or applications, ``PKCS1v15``
 should only be used to support legacy protocols.
 
+If your data is too large to be passed in a single call, you can hash it
+separately and pass that value using
+:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`.
+
+.. doctest::
+
+    >>> from cryptography.hazmat.primitives.asymmetric import utils
+    >>> chosen_hash = hashes.SHA256()
+    >>> hasher = hashes.Hash(chosen_hash, default_backend())
+    >>> hasher.update(b"data & ")
+    >>> hasher.update(b"more data")
+    >>> digest = hasher.finalize()
+    >>> sig = private_key.sign(
+    ...     digest,
+    ...     padding.PSS(
+    ...         mgf=padding.MGF1(hashes.SHA256()),
+    ...         salt_length=padding.PSS.MAX_LENGTH
+    ...     ),
+    ...     utils.Prehashed(chosen_hash)
+    ... )
+
 Verification
 ~~~~~~~~~~~~
 
@@ -190,32 +195,38 @@ a public key to use in verification using
 .. doctest::
 
     >>> public_key = private_key.public_key()
-    >>> verifier = public_key.verifier(
+    >>> public_key.verify(
     ...     signature,
+    ...     message,
     ...     padding.PSS(
     ...         mgf=padding.MGF1(hashes.SHA256()),
     ...         salt_length=padding.PSS.MAX_LENGTH
     ...     ),
     ...     hashes.SHA256()
     ... )
-    >>> verifier.update(message)
-    >>> verifier.verify()
 
 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:
+If your data is too large to be passed in a single call, you can hash it
+separately and pass that value using
+:class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`.
 
 .. doctest::
 
+    >>> chosen_hash = hashes.SHA256()
+    >>> hasher = hashes.Hash(chosen_hash, default_backend())
+    >>> hasher.update(b"data & ")
+    >>> hasher.update(b"more data")
+    >>> digest = hasher.finalize()
     >>> public_key.verify(
-    ...     signature,
-    ...     message,
+    ...     sig,
+    ...     digest,
     ...     padding.PSS(
     ...         mgf=padding.MGF1(hashes.SHA256()),
     ...         salt_length=padding.PSS.MAX_LENGTH
     ...     ),
-    ...     hashes.SHA256()
+    ...     utils.Prehashed(chosen_hash)
     ... )
 
 Encryption
@@ -520,22 +531,6 @@ Key interfaces
 
     An `RSA`_ private key.
 
-    .. method:: signer(padding, algorithm)
-
-        .. versionadded:: 0.3
-
-        Get signer to sign data which can be verified later by others using
-        the public key.
-
-        :param padding: An instance of
-            :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`.
-
-        :param algorithm: An instance of
-            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
-
     .. method:: decrypt(ciphertext, padding)
 
         .. versionadded:: 0.4
@@ -634,24 +629,6 @@ Key interfaces
 
     An `RSA`_ public key.
 
-    .. method:: verifier(signature, padding, algorithm)
-
-        .. versionadded:: 0.3
-
-        Get verifier to verify data was signed by the private key associated
-        with this public key.
-
-        :param bytes signature: The signature to verify.
-
-        :param padding: An instance of
-            :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding`.
-
-        :param algorithm: An instance of
-            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext`
-
     .. method:: encrypt(plaintext, padding)
 
         .. versionadded:: 0.4