From 5bbcf7660b07f5a77ce9ff5666bede3c3377dfc7 Mon Sep 17 00:00:00 2001
From: Alex Gaynor <alex.gaynor@gmail.com>
Date: Wed, 8 Jan 2014 18:36:57 -0800
Subject: Make verify on HMAC more prominent

---
 docs/hazmat/primitives/hmac.rst | 33 ++++++++++++++++++++++-----------
 1 file changed, 22 insertions(+), 11 deletions(-)

(limited to 'docs/hazmat/primitives/hmac.rst')

diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst
index dc5c54f8..f4f5daa1 100644
--- a/docs/hazmat/primitives/hmac.rst
+++ b/docs/hazmat/primitives/hmac.rst
@@ -37,6 +37,17 @@ message.
     If the backend doesn't support the requested ``algorithm`` an
     :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised.
 
+    If you've been given a signature and need to check that it's correct, this
+    can be done with the :meth:`verify` method, you'll get an exception if the
+    signature is wrong:
+
+    .. code-block:: pycon
+
+        >>> h.verify(b"an incorrect signature")
+        Traceback (most recent call last):
+        ...
+        cryptography.exceptions.InvalidSignature: Signature did not match digest.
+
     :param key: Secret key as ``bytes``.
     :param algorithm: A
         :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
@@ -61,17 +72,6 @@ message.
             and finalized independently of the original instance.
         :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
 
-    .. method:: finalize()
-
-        Finalize the current context and return the message digest as bytes.
-
-        Once ``finalize`` is called this object can no longer be used and
-        :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise
-        :class:`~cryptography.exceptions.AlreadyFinalized`.
-
-        :return bytes: The message digest as bytes.
-        :raises cryptography.exceptions.AlreadyFinalized:
-
     .. method:: verify(signature)
 
         Finalize the current context and securely compare digest to
@@ -82,3 +82,14 @@ message.
         :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`
         :raises cryptography.exceptions.InvalidSignature: If signature does not
                                                           match digest
+
+    .. method:: finalize()
+
+        Finalize the current context and return the message digest as bytes.
+
+        Once ``finalize`` is called this object can no longer be used and
+        :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise
+        :class:`~cryptography.exceptions.AlreadyFinalized`.
+
+        :return bytes: The message digest as bytes.
+        :raises cryptography.exceptions.AlreadyFinalized:
-- 
cgit v1.2.3