Add #is_webhook_authentic (#10)

* Add #is_webhook_authentic

* Update README.rst

* Fix python 3.x

* More updates for python 3

* Remove u'' prefix (not supported in python 3.2)

* Update utils_test.py

* Pull verison back down to 2.0.0

Author: Will Myers

README.rst

@@ -275,6 +275,30 @@ supply for the next page of results. If ``prev_cursor()`` returns
     # <class pybutton.Response [100 elements]>
 
 
+Utils
+---------
+
+Utils houses generic helpers useful in a Button Integration.
+
+#is_webhook_authentic
+~~~~~~~~~~~~~~~~~~~
+
+Used to verify that requests sent to a webhook endpoint are from Button and that
+their payload can be trusted. Returns ``True`` if a webhook request body matches
+the sent signature and ``False`` otherwise.  See `Webhook Security <https://www.usebutton.com/developers/webhooks/#security>`__ for more details.
+
+.. code:: python
+
+    import os
+
+    from pybutton.utils import is_webhook_authentic
+
+    is_webhook_authentic(
+        os.environ['WEBHOOK_SECRET'],
+        request.data,
+        request.headers.get('X-Button-Signature')
+    )
+
 Contributing
 ------------
 

pybutton/utils.py

@@ -0,0 +1,70 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+import sys
+import hmac
+import hashlib
+
+
+def is_webhook_authentic(webhook_secret, request_body, sent_signature):
+    '''Used to verify that requests sent to a webhook endpoint are from Button
+    and that their payload can be trusted. Returns True if a webhook request
+    body matches the sent signature and False otherwise.
+
+    Args:
+        webhook_secret (basestring): Your webhooks's secret key.  Find yours at
+            https://app.usebutton.com/webhooks.
+
+        request_body (basestring): UTF8 encoded byte-string of the request body
+
+        sent_signature (basestring): "X-Button-Siganture" HTTP Header sent with
+            the request.
+
+    Returns:
+        (bool) Whether or not the request is authentic
+    '''
+
+    computed_signature = hmac.new(
+      as_bytes(webhook_secret),
+      as_bytes(request_body),
+      hashlib.sha256
+    ).hexdigest()
+
+    if hasattr(hmac, 'compare_digest'):
+        return hmac.compare_digest(
+            computed_signature,
+            as_bytes(sent_signature, True)
+        )
+
+    return computed_signature == sent_signature
+
+
+def as_bytes(v, only_py_2=False):
+    '''Converts v to a UTF-8 byte string if unicode, else returns identity.
+
+    Args:
+        v (str|unicode): the string to convert
+
+        only_py_2 (bool): If true, only converts to bytes if running in a
+            python 2 interpretter
+
+    Returns:
+        (byte string): A byte string copy, UTF-8 enccoded
+    '''
+
+    python_version = sys.version_info[0]
+
+    if only_py_2 and python_version != 2:
+        return v
+
+    should_encode = (
+        python_version == 2 and isinstance(v, unicode)
+        or python_version == 3 and isinstance(v, str)
+    )
+
+    if should_encode:
+        return v.encode('utf8')
+
+    return v

test/utils_test.py

@@ -0,0 +1,49 @@
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from unittest import TestCase
+
+from pybutton.utils import is_webhook_authentic
+
+
+class UtilsTestCase(TestCase):
+
+    def test_is_webhook_authentic(self):
+        signature = (
+            '79a3a5291c94340ff0058a6319063757'
+            '68d706357ee86826c3c692e6b9aa6817'
+        )
+        payload = '{ "a": 1 }'
+
+        self.assertFalse(is_webhook_authentic('secret', payload, 'XXX'))
+        self.assertTrue(is_webhook_authentic('secret', payload, signature))
+        self.assertFalse(is_webhook_authentic('secret?', payload, signature))
+        self.assertFalse(is_webhook_authentic(
+            'secret', '{ "a": 2 }', signature)
+        )
+
+    def test_is_webhook_authentic_unicode_payload(self):
+        signature = (
+            '3040cf48ab225ca539c1d23841175bc2'
+            '2e565cdb0975bd690ecaeca2c39dfcf7'
+        )
+
+        self.assertTrue(
+            is_webhook_authentic('secret', '{ "a": \u1f60e }', signature)
+        )
+
+    def test_is_webhook_authentic_byte_strings(self):
+        signature = (
+            '79a3a5291c94340ff0058a6319063757'
+            '68d706357ee86826c3c692e6b9aa6817'
+        )
+        payload = b'{ "a": 1 }'
+
+        self.assertFalse(is_webhook_authentic(b'secret', payload, 'XXX'))
+        self.assertTrue(is_webhook_authentic(b'secret', payload, signature))
+        self.assertFalse(is_webhook_authentic(b'secret?', payload, signature))
+        self.assertFalse(
+            is_webhook_authentic(b'secret', b'{ "a": 2 }', signature)
+        )