From 1a5d70e876346653b3dfa2a95f188ef0eb92bd7d Mon Sep 17 00:00:00 2001
From: Paul Kehrer <paul.l.kehrer@gmail.com>
Date: Sat, 3 Jun 2017 17:11:55 -1000
Subject: deprecate signer/verifier on asymmetric keys (#3663)

* deprecate signer/verifier on asymmetric keys

* review feedback, switch deprecated_call to work around a bug
---
 docs/hazmat/primitives/asymmetric/ec.rst | 74 +++++++++++++++-----------------
 1 file changed, 35 insertions(+), 39 deletions(-)

(limited to 'docs/hazmat/primitives/asymmetric/ec.rst')

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`
-- 
cgit v1.2.3