Merge branch 'master' of github.com:web-push-libs/pywebpush

Author: jrconlin

.travis.yml

@@ -1,11 +1,12 @@
 language: python
 python:
-- "2.7"
+  - "2.7"
+  - "3.6"
 install:
-- pip install -r requirements.txt
-- pip install -r test-requirements.txt
+  - pip install -r requirements.txt
+  - pip install -r test-requirements.txt
 script:
-- nosetests
-- flake8 pywebpush
+  - nosetests
+  - flake8 pywebpush
 after_success:
-- codecov
+  - codecov

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.7.0 (2017-02-14)
+feat: update to http-ece 0.7.0 (with draft-06 support)
+feat: Allow empty payloads for send()
+feat: Add python3 classfiers & python3.6 travis tests
+feat: Add README.rst
+bug: change long to int to support python3
+
 ## 0.4.0 (2016-06-05)
 feat: make python 2.7 / 3.5 polyglot
 

README.md

@@ -1,4 +1,7 @@
 [![Build_Status](https://travis-ci.org/jrconlin/pywebpush.svg?branch=master)](https://travis-ci.org/jrconlin/pywebpush)
+[![Requirements
+Status](https://requires.io/github/web-push-libs/pywebpush/requirements.svg?branch=master)]
+
 
 # Webpush Data encryption library for Python
 

README.rst

@@ -0,0 +1,71 @@
+|Build\_Status| [|Requirements Status|]
+
+Webpush Data encryption library for Python
+==========================================
+
+This is a work in progress. This library is available on `pypi as
+pywebpush <https://pypi.python.org/pypi/pywebpush>`__. Source is
+available on `github <https://github.com/web-push-libs/pywebpush>`__
+
+Installation
+------------
+
+You'll need to run ``python virtualenv``. Then
+
+::
+
+    bin/pip install -r requirements.txt
+    bin/python setup.py develop
+
+Usage
+-----
+
+In the browser, the promise handler for
+`registration.pushManager.subscribe() <https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe>`__
+returns a
+`PushSubscription <https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription>`__
+object. This object has a .toJSON() method that will return a JSON
+object that contains all the info we need to encrypt and push data.
+
+As illustration, a subscription info object may look like:
+
+::
+
+    {"endpoint": "https://updates.push.services.mozilla.com/push/v1/gAA...", "keys": {"auth": "k8J...", "p256dh": "BOr..."}}
+
+How you send the PushSubscription data to your backend, store it
+referenced to the user who requested it, and recall it when there's new
+a new push subscription update is left as an excerise for the reader.
+
+The data can be any serial content (string, bit array, serialized JSON,
+etc), but be sure that your receiving application is able to parse and
+understand it. (e.g. ``data = "Mary had a little lamb."``)
+
+gcm\_key is the API key obtained from the Google Developer Console. It
+is only needed if endpoint is https://android.googleapis.com/gcm/send
+
+``headers`` is a ``dict``\ ionary of additional HTTP header values (e.g.
+`VAPID <https://github.com/mozilla-services/vapid/tree/master/python>`__
+self identification headers). It is optional and may be omitted.
+
+to send:
+
+::
+
+    WebPusher(subscription_info).send(data, headers)
+
+to send for Chrome:
+
+::
+
+    WebPusher(subscription_info).send(data, headers, ttl, gcm_key)
+
+You can also simply encode the data to send later by calling
+
+::
+
+    encoded = WebPush(subscription_info).encode(data)
+
+.. |Build\_Status| image:: https://travis-ci.org/web-push-libs/pywebpush.svg?branch=master
+   :target: https://travis-ci.org/web-push-libs/pywebpush
+.. |Requirements Status| image:: https://requires.io/github/web-push-libs/pywebpush/requirements.svg?branch=master

circle.yml

@@ -0,0 +1,12 @@
+# circle ci file
+machine:
+  post:
+    - pyenv global 2.7.13 3.5
+
+dependencies:
+  pre:
+    - pip install -r test-requirements.txt
+
+test:
+  override:
+    - nosetests -v pywebpush

convert_readme.sh

@@ -0,0 +1 @@
+ pandoc --from=markdown --to=rst --output README.rst README.md

pywebpush/__init__.py

@@ -82,6 +82,11 @@ class WebPusher:
 
     """
     subscription_info = {}
+    valid_encodings = [
+        # "aesgcm128",  # this is draft-0, but DO NOT USE.
+        "aesgcm",  # draft-httpbis-encryption-encoding-01
+        "aes128gcm"  # draft-httpbis-encryption-encoding-04
+    ]
 
     def __init__(self, subscription_info):
         """Initialize using the info provided by the client PushSubscription
@@ -113,16 +118,28 @@ def _repad(self, data):
         """Add base64 padding to the end of a string, if required"""
         return data + b"===="[:len(data) % 4]
 
-    def encode(self, data):
+    def encode(self, data, content_encoding="aesgcm"):
         """Encrypt the data.
 
         :param data: A serialized block of byte data (String, JSON, bit array,
             etc.) Make sure that whatever you send, your client knows how
             to understand it.
+        :type data: str
+        :param content_encoding: The content_encoding type to use to encrypt
+            the data. Defaults to draft-01 "aesgcm". Latest draft-04 is
+            "aes128gcm", however not all clients may be able to use this
+            format.
+        :type content_encoding: enum("aesgcm", "aes128gcm")
 
         """
         # Salt is a random 16 byte array.
-        salt = os.urandom(16)
+        salt = None
+        if content_encoding not in self.valid_encodings:
+            raise WebPushException("Invalid content encoding specified. "
+                                   "Select from " +
+                                   json.dumps(self.valid_encodings))
+        if (content_encoding == "aesgcm"):
+            salt = os.urandom(16)
         # The server key is an ephemeral ECDH key used only for this
         # transaction
         server_key = pyelliptic.ECC(curve="prime256v1")
@@ -133,26 +150,31 @@ def encode(self, data):
         if isinstance(data, six.string_types):
             data = bytes(data.encode('utf8'))
 
+        key_id = server_key_id.decode('utf8')
         # http_ece requires that these both be set BEFORE encrypt or
         # decrypt is called if you specify the key as "dh".
-        http_ece.keys[server_key_id] = server_key
-        http_ece.labels[server_key_id] = "P-256"
+        http_ece.keys[key_id] = server_key
+        http_ece.labels[key_id] = "P-256"
 
         encrypted = http_ece.encrypt(
             data,
             salt=salt,
-            keyid=server_key_id,
+            keyid=key_id,
             dh=self.receiver_key,
-            authSecret=self.auth_key)
+            authSecret=self.auth_key,
+            version=content_encoding)
 
-        return CaseInsensitiveDict({
+        reply = CaseInsensitiveDict({
             'crypto_key': base64.urlsafe_b64encode(
                 server_key.get_pubkey()).strip(b'='),
-            'salt': base64.urlsafe_b64encode(salt).strip(b'='),
             'body': encrypted,
         })
+        if salt:
+            reply['salt'] = base64.urlsafe_b64encode(salt).strip(b'=')
+        return reply
 
-    def send(self, data, headers=None, ttl=0, gcm_key=None, reg_id=None):
+    def send(self, data=None, headers=None, ttl=0, gcm_key=None, reg_id=None,
+             content_encoding="aesgcm"):
         """Encode and send the data to the Push Service.
 
         :param data: A serialized block of data (see encode() ).
@@ -169,22 +191,25 @@ def send(self, data, headers=None, ttl=0, gcm_key=None, reg_id=None):
         # Encode the data.
         if headers is None:
             headers = dict()
-        encoded = self.encode(data)
-        # Append the p256dh to the end of any existing crypto-key
+        encoded = {}
         headers = CaseInsensitiveDict(headers)
-        crypto_key = headers.get("crypto-key", "")
-        if crypto_key:
-            # due to some confusion by a push service provider, we should
-            # use ';' instead of ',' to append the headers.
-            # see https://github.com/webpush-wg/webpush-encryption/issues/6
-            crypto_key += ';'
-        crypto_key += "keyid=p256dh;dh=" + encoded["crypto_key"].decode('utf8')
-        headers.update({
-            'crypto-key': crypto_key,
-            'content-encoding': 'aesgcm',
-            'encryption': "keyid=p256dh;salt=" +
-            encoded['salt'].decode('utf8'),
-        })
+        if data:
+            encoded = self.encode(data)
+            # Append the p256dh to the end of any existing crypto-key
+            crypto_key = headers.get("crypto-key", "")
+            if crypto_key:
+                # due to some confusion by a push service provider, we should
+                # use ';' instead of ',' to append the headers.
+                # see https://github.com/webpush-wg/webpush-encryption/issues/6
+                crypto_key += ';'
+            crypto_key += (
+                "keyid=p256dh;dh=" + encoded["crypto_key"].decode('utf8'))
+            headers.update({
+                'crypto-key': crypto_key,
+                'content-encoding': 'aesgcm',
+                'encryption': "keyid=p256dh;salt=" +
+                encoded['salt'].decode('utf8'),
+            })
         gcm_endpoint = 'https://android.googleapis.com/gcm/send'
         if self.subscription_info['endpoint'].startswith(gcm_endpoint):
             if not gcm_key:
@@ -194,12 +219,14 @@ def send(self, data, headers=None, ttl=0, gcm_key=None, reg_id=None):
             if not reg_id:
                 reg_id = self.subscription_info['endpoint'].rsplit('/', 1)[-1]
             reg_ids.append(reg_id)
-            data = dict()
-            data['registration_ids'] = reg_ids
-            data['raw_data'] = base64.b64encode(
-                encoded.get('body')).decode('utf8')
-            data['time_to_live'] = int(headers['ttl'] if 'ttl' in headers else ttl)
-            encoded_data = json.dumps(data)
+            gcm_data = dict()
+            gcm_data['registration_ids'] = reg_ids
+            if data:
+                gcm_data['raw_data'] = base64.b64encode(
+                    encoded.get('body')).decode('utf8')
+            gcm_data['time_to_live'] = int(
+                headers['ttl'] if 'ttl' in headers else ttl)
+            encoded_data = json.dumps(gcm_data)
             headers.update({
                 'Authorization': 'key='+gcm_key,
                 'Content-Type': 'application/json',

pywebpush/tests/test_webpush.py

@@ -3,9 +3,9 @@
 import os
 import unittest
 
-import http_ece
 from mock import patch
 from nose.tools import eq_, ok_
+import http_ece
 import pyelliptic
 
 from pywebpush import WebPusher, WebPushException, CaseInsensitiveDict
@@ -65,32 +65,44 @@ def test_init(self):
         eq_(push.auth_key, b'\x93\xc2U\xea\xc8\xddn\x10"\xd6}\xff,0K\xbc')
 
     def test_encode(self):
+        for content_encoding in ["aesgcm", "aes128gcm"]:
+            recv_key = pyelliptic.ECC(curve="prime256v1")
+            subscription_info = self._gen_subscription_info(recv_key)
+            data = "Mary had a little lamb, with some nice mint jelly"
+            push = WebPusher(subscription_info)
+            encoded = push.encode(data, content_encoding=content_encoding)
+            keyid = base64.urlsafe_b64encode(recv_key.get_pubkey()[1:])
+            http_ece.keys[keyid] = recv_key
+            http_ece.labels[keyid] = 'P-256'
+            # Convert these b64 strings into their raw, binary form.
+            raw_salt = None
+            if 'salt' in encoded:
+                raw_salt = base64.urlsafe_b64decode(
+                    push._repad(encoded['salt']))
+            raw_dh = base64.urlsafe_b64decode(
+                push._repad(encoded['crypto_key']))
+            raw_auth = base64.urlsafe_b64decode(
+                push._repad(subscription_info['keys']['auth']))
+
+            decoded = http_ece.decrypt(
+                encoded['body'],
+                salt=raw_salt,
+                dh=raw_dh,
+                keyid=keyid,
+                authSecret=raw_auth,
+                version=content_encoding
+                )
+            eq_(decoded.decode('utf8'), data)
+
+    def test_bad_content_encoding(self):
         recv_key = pyelliptic.ECC(curve="prime256v1")
         subscription_info = self._gen_subscription_info(recv_key)
         data = "Mary had a little lamb, with some nice mint jelly"
         push = WebPusher(subscription_info)
-        encoded = push.encode(data)
-
-        keyid = base64.urlsafe_b64encode(recv_key.get_pubkey()[1:])
-
-        http_ece.keys[keyid] = recv_key
-        http_ece.labels[keyid] = 'P-256'
-
-        # Convert these b64 strings into their raw, binary form.
-        raw_salt = base64.urlsafe_b64decode(push._repad(encoded['salt']))
-        raw_dh = base64.urlsafe_b64decode(push._repad(encoded['crypto_key']))
-        raw_auth = base64.urlsafe_b64decode(
-            push._repad(subscription_info['keys']['auth']))
-
-        decoded = http_ece.decrypt(
-            buffer=encoded['body'],
-            salt=raw_salt,
-            dh=raw_dh,
-            keyid=keyid,
-            authSecret=raw_auth
-            )
-
-        eq_(decoded.decode('utf8'), data)
+        self.assertRaises(WebPushException,
+                          push.encode,
+                          data,
+                          content_encoding="aesgcm128")
 
     @patch("requests.post")
     def test_send(self, mock_post):
@@ -109,6 +121,22 @@ def test_send(self, mock_post):
         ok_('pre-existing' in ckey)
         eq_(pheaders.get('content-encoding'), 'aesgcm')
 
+    @patch("requests.post")
+    def test_send_empty(self, mock_post):
+        recv_key = pyelliptic.ECC(curve="prime256v1")
+        subscription_info = self._gen_subscription_info(recv_key)
+        headers = {"Crypto-Key": "pre-existing",
+                   "Authentication": "bearer vapid"}
+        data = None
+        WebPusher(subscription_info).send(data, headers)
+        eq_(subscription_info.get('endpoint'), mock_post.call_args[0][0])
+        pheaders = mock_post.call_args[1].get('headers')
+        eq_(pheaders.get('ttl'), '0')
+        ok_('encryption' not in pheaders)
+        eq_(pheaders.get('AUTHENTICATION'), headers.get('Authentication'))
+        ckey = pheaders.get('crypto-key')
+        ok_('pre-existing' in ckey)
+
     @patch("requests.post")
     def test_send_no_headers(self, mock_post):
         recv_key = pyelliptic.ECC(curve="prime256v1")

requirements.txt

@@ -1,4 +1,4 @@
-http-ece==0.5.0
+http-ece==0.7.0
 python-jose>1.2.0
 requests>2.11.0
 flake8