deprecate signer/verifier on asymmetric keys (#3663)

* deprecate signer/verifier on asymmetric keys

* review feedback, switch deprecated_call to work around a bug

5 files changed, 105 insertions, 196 deletions

diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index d4c25256..13cd0412 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -72,15 +72,6 @@ instance.
     ...     key_size=1024,
     ...     backend=default_backend()
     ... )
-    >>> signer = private_key.signer(hashes.SHA256())
-    >>> data = b"this is some data I'd like to sign"
-    >>> signer.update(data)
-    >>> signature = signer.finalize()
-
-There is a shortcut to sign sufficiently short messages directly:
-
-.. doctest::
-
     >>> data = b"this is some data I'd like to sign"
     >>> signature = private_key.sign(
     ...     data,
@@ -91,6 +82,23 @@ The ``signature`` is a ``bytes`` object, whose contents is DER encoded as
 described in :rfc:`3279`. This can be decoded using
 :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`.
 
+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,
+    ...     utils.Prehashed(chosen_hash)
+    ... )
+
 Verification
 ~~~~~~~~~~~~
 
@@ -106,26 +114,35 @@ You can get a public key object with
 .. doctest::
 
     >>> public_key = private_key.public_key()
-    >>> verifier = public_key.verifier(signature, hashes.SHA256())
-    >>> verifier.update(data)
-    >>> verifier.verify()
-
-There is a shortcut to verify sufficiently short messages directly:
-
-.. doctest::
-
     >>> public_key.verify(
     ...     signature,
     ...     data,
     ...     hashes.SHA256()
     ... )
 
-``verifier()`` takes the signature in the same format as is returned by
-``signer.finalize()``.
+``verify()`` takes the signature in the same format as is returned by
+``sign()``.
 
 ``verify()`` will raise an :class:`~cryptography.exceptions.InvalidSignature`
 exception if the signature isn't valid.
 
+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(
+    ...     sig,
+    ...     digest,
+    ...     utils.Prehashed(chosen_hash)
+    ... )
+
 Numbers
 ~~~~~~~
 
@@ -275,23 +292,6 @@ Key interfaces
 
         The DSAParameters object associated with this private key.
 
-    .. method:: signer(algorithm, backend)
-
-        .. versionadded:: 0.4
-
-        Sign data which can be verified later by others using the public key.
-        The signature is formatted as DER-encoded bytes, as specified in
-        :rfc:`3279`.
-
-        :param algorithm: An instance of
-            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
-        :param backend: An instance of
-            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
-
     .. attribute:: key_size
 
         :type: int
@@ -380,25 +380,6 @@ Key interfaces
 
         The DSAParameters object associated with this public key.
 
-    .. method:: verifier(signature, algorithm, backend)
-
-        .. versionadded:: 0.4
-
-        Verify data was signed by the private key associated with this public
-        key.
-
-        :param bytes signature: The signature to verify. DER encoded as
-            specified in :rfc:`3279`.
-
-        :param algorithm: An instance of
-            :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm`.
-
-        :param backend: An instance of
-            :class:`~cryptography.hazmat.backends.interfaces.DSABackend`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext`
-
     .. method:: public_numbers()
 
         Create a
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 55146175..113168fa 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -58,15 +58,6 @@ Elliptic Curve Signature Algorithms
         >>> private_key = ec.generate_private_key(
         ...     ec.SECP384R1(), default_backend()
         ... )
-        >>> signer = private_key.signer(ec.ECDSA(hashes.SHA256()))
-        >>> signer.update(b"this is some data I'd like")
-        >>> signer.update(b" to sign")
-        >>> signature = signer.finalize()
-
-    There is a shortcut to sign sufficiently short messages directly:
-
-    .. doctest::
-
         >>> data = b"this is some data I'd like to sign"
         >>> signature = private_key.sign(
         ...     data,
@@ -77,20 +68,51 @@ Elliptic Curve Signature Algorithms
     described in :rfc:`3279`. This can be decoded using
     :func:`~cryptography.hazmat.primitives.asymmetric.utils.decode_dss_signature`.
 
+    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,
+        ...     ec.ECDSA(utils.Prehashed(chosen_hash))
+        ... )
+
 
     Verification requires the public key, the signature itself, the signed
     data, and knowledge of the hashing algorithm that was used when producing
     the signature:
 
     >>> public_key = private_key.public_key()
-    >>> verifier = public_key.verifier(signature, ec.ECDSA(hashes.SHA256()))
-    >>> verifier.update(b"this is some data I'd like")
-    >>> verifier.update(b" to sign")
-    >>> verifier.verify()
+    >>> public_key.verify(signature, data, ec.ECDSA(hashes.SHA256()))
 
     If the signature is not valid, an
     :class:`~cryptography.exceptions.InvalidSignature` exception will be raised.
 
+    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(
+        ...     sig,
+        ...     digest,
+        ...     ec.ECDSA(utils.Prehashed(chosen_hash))
+        ... )
+
     .. note::
         Although in this case the public key was derived from the private one,
         in a typical setting you will not possess the private key. The
@@ -421,18 +443,6 @@ Key Interfaces
     An elliptic curve private key for use with an algorithm such as `ECDSA`_ or
     `EdDSA`_.
 
-    .. method:: signer(signature_algorithm)
-
-        Sign data which can be verified later by others using the public key.
-        The signature is formatted as DER-encoded bytes, as specified in
-        :rfc:`3279`.
-
-        :param signature_algorithm: An instance of
-            :class:`EllipticCurveSignatureAlgorithm`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext`
-
     .. method:: exchange(algorithm, peer_public_key)
 
         .. versionadded:: 1.1
@@ -526,20 +536,6 @@ Key Interfaces
 
     An elliptic curve public key.
 
-    .. method:: verifier(signature, signature_algorithm)
-
-        Verify data was signed by the private key associated with this public
-        key.
-
-        :param bytes signature: The signature to verify. DER encoded as
-            specified in :rfc:`3279`.
-
-        :param signature_algorithm: An instance of
-            :class:`EllipticCurveSignatureAlgorithm`.
-
-        :returns:
-            :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext`
-
      .. attribute:: curve
 
         :type: :class:`EllipticCurve`
diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst
index e0080f0e..e14ce0d3 100644
--- a/docs/hazmat/primitives/asymmetric/index.rst
+++ b/docs/hazmat/primitives/asymmetric/index.rst
@@ -28,7 +28,6 @@ private key is able to decrypt it.
     rsa
     dh
     serialization
-    interfaces
     utils
 
 
diff --git a/docs/hazmat/primitives/asymmetric/interfaces.rst b/docs/hazmat/primitives/asymmetric/interfaces.rst
deleted file mode 100644
index a5dbc671..00000000
--- a/docs/hazmat/primitives/asymmetric/interfaces.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-.. hazmat::
-
-.. module:: cryptography.hazmat.primitives.asymmetric
-
-Signature Interfaces
-====================
-
-.. class:: AsymmetricSignatureContext
-
-    .. versionadded:: 0.2
-
-    .. note::
-
-        :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`
-        is not supported by this context. You must use the ``sign`` method
-        on the private key object.
-
-    .. method:: update(data)
-
-        :param bytes data: The data you want to sign.
-
-    .. method:: finalize()
-
-        :return bytes signature: The signature.
-
-
-.. class:: AsymmetricVerificationContext
-
-    .. versionadded:: 0.2
-
-    .. note::
-
-        :class:`~cryptography.hazmat.primitives.asymmetric.utils.Prehashed`
-        is not supported by this context. You must use the ``verify`` method
-        on the public key object.
-
-    .. method:: update(data)
-
-        :param bytes data: The data you wish to verify using the signature.
-
-    .. method:: verify()
-
-        :raises cryptography.exceptions.InvalidSignature: If the signature does
-            not validate.
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