# Webpush Data encryption library for Python
[](https://travis-ci.org/web-push-libs/pywebpush)
[](https://requires.io/github/web-push-libs/pywebpush/requirements/?branch=main)
This library is available on [pypi as pywebpush](https://pypi.python.org/pypi/pywebpush).
Source is available on [github](https://github.com/mozilla-services/pywebpush).
Please note: This library was designated as a `Critical Project` by PyPi, it is currently
maintained by [a single person](https://xkcd.com/2347/). I still accept PRs and Issues, but
make of that what you will.
## Installation
To work with this repo locally, you'll need to run `python -m venv venv`.
Then `venv/bin/pip install --editable .`
## 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:
```json
{
"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
a new push subscription update is left as an exercise for the
reader.
### Sending Data using `webpush()` One Call
In many cases, your code will be sending a single message to many
recipients. There's a "One Call" function which will make things
easier.
```python
from pywebpush import webpush
webpush(subscription_info,
data,
vapid_private_key="Private Key or File Path[1]",
vapid_claims={"sub": "mailto:YourEmailAddress"})
```
This will encode `data`, add the appropriate VAPID auth headers if required and send it to the push server identified
in the `subscription_info` block.
##### Parameters
_subscription_info_ - The `dict` of the subscription info (described above).
_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."`)
_content_type_ - specifies the form of Encryption to use, either `'aes128gcm'` or the deprecated `'aesgcm'`. NOTE that
not all User Agents can decrypt `'aesgcm'`, so the library defaults to the RFC 8188 standard form.
_vapid_claims_ - a `dict` containing the VAPID claims required for authorization (See
[py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details). If `aud` is not specified,
pywebpush will attempt to auto-fill from the `endpoint`. If `exp` is not specified or set in the past, it will be set
to 12 hours from now. In both cases, the passed `dict` **will be mutated** after the call.
_vapid_private_key_ - Either a path to a VAPID EC2 private key PEM file, or a string containing the DER representation.
(See [py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details.) The `private_key` may be
a base64 encoded DER formatted private key, or the path to an OpenSSL exported private key file.
e.g. the output of:
```bash
openssl ecparam -name prime256v1 -genkey -noout -out private_key.pem
```
##### Example
```python
from pywebpush import webpush, WebPushException
try:
webpush(
subscription_info={
"endpoint": "https://push.example.com/v1/12345",
"keys": {
"p256dh": "0123abcde...",
"auth": "abc123..."
}},
data="Mary had a little lamb, with a nice mint jelly",
vapid_private_key="path/to/vapid_private.pem",
vapid_claims={
"sub": "mailto:YourNameHere@example.org",
}
)
except WebPushException as ex:
print("I'm sorry, Dave, but I can't do that: {}", repr(ex))
# Mozilla returns additional information in the body of the response.
if ex.response is not None and ex.response.json():
extra = ex.response.json()
print("Remote service replied with a {}:{}, {}",
extra.code,
extra.errno,
extra.message
)
```
### Methods
If you expect to resend to the same recipient, or have more needs than just sending data quickly, you
can pass just `wp = WebPusher(subscription_info)`. This will return a `WebPusher` object.
The following methods are available:
#### `.send(data, headers={}, ttl=0, gcm_key="", reg_id="", content_encoding="aes128gcm", curl=False, timeout=None)`
Send the data using additional parameters. On error, returns a `WebPushException`
##### Parameters
_data_ Binary string of data to send
_headers_ A `dict` containing any additional headers to send
_ttl_ Message Time To Live on Push Server waiting for the client to reconnect (in seconds)
_gcm_key_ Google Cloud Messaging key (if using the older GCM push system) This is the API key obtained from the Google
Developer Console.
_reg_id_ Google Cloud Messaging registration ID (will be extracted from endpoint if not specified)
_content_encoding_ ECE content encoding type (defaults to "aes128gcm")
_curl_ Do not execute the POST, but return as a `curl` command. This will write the encrypted content to a local file
named `encrpypted.data`. This command is meant to be used for debugging purposes.
_timeout_ timeout for requests POST query.
See [requests documentation](http://docs.python-requests.org/en/master/user/quickstart/#timeouts).
##### Example
to send from Chrome using the old GCM mode:
```python
WebPusher(subscription_info).send(data, headers, ttl, gcm_key)
```
#### `.encode(data, content_encoding="aes128gcm")`
Encode the `data` for future use. On error, returns a `WebPushException`
##### Parameters
_data_ Binary string of data to send
_content_encoding_ ECE content encoding type (defaults to "aes128gcm")
*Note* This will return a `NoData` exception if the data is not present or empty. It is completely
valid to send a WebPush notification with no data, but encoding is a no-op in that case. Best not
to call it if you don't have data.
##### Example
```python
encoded_data = WebPush(subscription_info).encode(data)
```
## Stand Alone Webpush
If you're not really into coding your own solution, there's also a "stand-alone" `pywebpush` command in the
./bin directory.
This uses two files:
- the _data_ file, which contains the message to send, in whatever form you like.
- the _subscription info_ file, which contains the subscription information as JSON encoded data. This is usually returned by the Push `subscribe` method and looks something like:
```json
{
"endpoint": "https://push...",
"keys": {
"auth": "ab01...",
"p256dh": "aa02..."
}
}
```
If you're interested in just testing your applications WebPush interface, you could use the Command Line:
```bash
./bin/pywebpush --data stuff_to_send.data --info subscription.info
```
which will encrypt and send the contents of `stuff_to_send.data`.
See `./bin/pywebpush --help` for available commands and options.
Raw data
{
"_id": null,
"home_page": null,
"name": "pywebpush",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "webpush, vapid, notification",
"author": null,
"author_email": "JR Conlin <src+webpusher@jrconlin.com>",
"download_url": "https://files.pythonhosted.org/packages/41/ca/6e669bf676916d66c8c7adedc291e9a9758650f9d85ec040fda13e3c82f4/pywebpush-2.0.3.tar.gz",
"platform": null,
"description": "# Webpush Data encryption library for Python\n\n[](https://travis-ci.org/web-push-libs/pywebpush)\n[](https://requires.io/github/web-push-libs/pywebpush/requirements/?branch=main)\n\nThis library is available on [pypi as pywebpush](https://pypi.python.org/pypi/pywebpush).\nSource is available on [github](https://github.com/mozilla-services/pywebpush).\nPlease note: This library was designated as a `Critical Project` by PyPi, it is currently\nmaintained by [a single person](https://xkcd.com/2347/). I still accept PRs and Issues, but\nmake of that what you will.\n\n## Installation\n\nTo work with this repo locally, you'll need to run `python -m venv venv`.\nThen `venv/bin/pip install --editable .`\n\n\n## Usage\n\nIn the browser, the promise handler for\n[registration.pushManager.subscribe()](https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe)\nreturns a\n[PushSubscription](https://developer.mozilla.org/en-US/docs/Web/API/PushSubscription)\nobject. This object has a .toJSON() method that will return a JSON object that contains all the info we need to encrypt\nand push data.\n\nAs illustration, a `subscription_info` object may look like:\n\n```json\n{\n \"endpoint\": \"https://updates.push.services.mozilla.com/push/v1/gAA...\",\n \"keys\": { \"auth\": \"k8J...\", \"p256dh\": \"BOr...\" }\n}\n```\n\nHow you send the PushSubscription data to your backend, store it\nreferenced to the user who requested it, and recall it when there's\na new push subscription update is left as an exercise for the\nreader.\n\n### Sending Data using `webpush()` One Call\n\nIn many cases, your code will be sending a single message to many\nrecipients. There's a \"One Call\" function which will make things\neasier.\n\n```python\nfrom pywebpush import webpush\n\nwebpush(subscription_info,\n data,\n vapid_private_key=\"Private Key or File Path[1]\",\n vapid_claims={\"sub\": \"mailto:YourEmailAddress\"})\n```\n\nThis will encode `data`, add the appropriate VAPID auth headers if required and send it to the push server identified\nin the `subscription_info` block.\n\n##### Parameters\n\n_subscription_info_ - The `dict` of the subscription info (described above).\n\n_data_ - can be any serial content (string, bit array, serialized JSON, etc), but be sure that your receiving\napplication is able to parse and understand it. (e.g. `data = \"Mary had a little lamb.\"`)\n\n_content_type_ - specifies the form of Encryption to use, either `'aes128gcm'` or the deprecated `'aesgcm'`. NOTE that\nnot all User Agents can decrypt `'aesgcm'`, so the library defaults to the RFC 8188 standard form.\n\n_vapid_claims_ - a `dict` containing the VAPID claims required for authorization (See\n[py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details). If `aud` is not specified,\npywebpush will attempt to auto-fill from the `endpoint`. If `exp` is not specified or set in the past, it will be set\nto 12 hours from now. In both cases, the passed `dict` **will be mutated** after the call.\n\n_vapid_private_key_ - Either a path to a VAPID EC2 private key PEM file, or a string containing the DER representation.\n(See [py_vapid](https://github.com/web-push-libs/vapid/tree/master/python) for more details.) The `private_key` may be\na base64 encoded DER formatted private key, or the path to an OpenSSL exported private key file.\n\ne.g. the output of:\n\n```bash\nopenssl ecparam -name prime256v1 -genkey -noout -out private_key.pem\n```\n\n##### Example\n\n```python\nfrom pywebpush import webpush, WebPushException\n\ntry:\n webpush(\n subscription_info={\n \"endpoint\": \"https://push.example.com/v1/12345\",\n \"keys\": {\n \"p256dh\": \"0123abcde...\",\n \"auth\": \"abc123...\"\n }},\n data=\"Mary had a little lamb, with a nice mint jelly\",\n vapid_private_key=\"path/to/vapid_private.pem\",\n vapid_claims={\n \"sub\": \"mailto:YourNameHere@example.org\",\n }\n )\nexcept WebPushException as ex:\n print(\"I'm sorry, Dave, but I can't do that: {}\", repr(ex))\n # Mozilla returns additional information in the body of the response.\n if ex.response is not None and ex.response.json():\n extra = ex.response.json()\n print(\"Remote service replied with a {}:{}, {}\",\n extra.code,\n extra.errno,\n extra.message\n )\n```\n\n### Methods\n\nIf you expect to resend to the same recipient, or have more needs than just sending data quickly, you\ncan pass just `wp = WebPusher(subscription_info)`. This will return a `WebPusher` object.\n\nThe following methods are available:\n\n#### `.send(data, headers={}, ttl=0, gcm_key=\"\", reg_id=\"\", content_encoding=\"aes128gcm\", curl=False, timeout=None)`\n\nSend the data using additional parameters. On error, returns a `WebPushException`\n\n##### Parameters\n\n_data_ Binary string of data to send\n\n_headers_ A `dict` containing any additional headers to send\n\n_ttl_ Message Time To Live on Push Server waiting for the client to reconnect (in seconds)\n\n_gcm_key_ Google Cloud Messaging key (if using the older GCM push system) This is the API key obtained from the Google\nDeveloper Console.\n\n_reg_id_ Google Cloud Messaging registration ID (will be extracted from endpoint if not specified)\n\n_content_encoding_ ECE content encoding type (defaults to \"aes128gcm\")\n\n_curl_ Do not execute the POST, but return as a `curl` command. This will write the encrypted content to a local file\nnamed `encrpypted.data`. This command is meant to be used for debugging purposes.\n\n_timeout_ timeout for requests POST query.\nSee [requests documentation](http://docs.python-requests.org/en/master/user/quickstart/#timeouts).\n\n##### Example\n\nto send from Chrome using the old GCM mode:\n\n```python\nWebPusher(subscription_info).send(data, headers, ttl, gcm_key)\n```\n\n#### `.encode(data, content_encoding=\"aes128gcm\")`\n\nEncode the `data` for future use. On error, returns a `WebPushException`\n\n##### Parameters\n\n_data_ Binary string of data to send\n\n_content_encoding_ ECE content encoding type (defaults to \"aes128gcm\")\n\n*Note* This will return a `NoData` exception if the data is not present or empty. It is completely\nvalid to send a WebPush notification with no data, but encoding is a no-op in that case. Best not\nto call it if you don't have data.\n\n##### Example\n\n```python\nencoded_data = WebPush(subscription_info).encode(data)\n```\n\n## Stand Alone Webpush\n\nIf you're not really into coding your own solution, there's also a \"stand-alone\" `pywebpush` command in the\n./bin directory.\n\nThis uses two files:\n\n- the _data_ file, which contains the message to send, in whatever form you like.\n- the _subscription info_ file, which contains the subscription information as JSON encoded data. This is usually returned by the Push `subscribe` method and looks something like:\n\n```json\n{\n \"endpoint\": \"https://push...\",\n \"keys\": {\n \"auth\": \"ab01...\",\n \"p256dh\": \"aa02...\"\n }\n}\n```\n\nIf you're interested in just testing your applications WebPush interface, you could use the Command Line:\n\n```bash\n./bin/pywebpush --data stuff_to_send.data --info subscription.info\n```\n\nwhich will encrypt and send the contents of `stuff_to_send.data`.\n\nSee `./bin/pywebpush --help` for available commands and options.\n",
"bugtrack_url": null,
"license": "MPL-2.0",
"summary": "WebPush publication library",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://github.com/web-push-libs/pywebpush"
},
"split_keywords": [
"webpush",
" vapid",
" notification"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "908aecaa2a589338a038b89148b01a5db2dac53e45918342da69baca1fb058fc",
"md5": "a1ebf11fab507a6e63217797018769ee",
"sha256": "04666441715bc547918d7668b2ac7ad5c4b5de7d0a6cf528daf61e0c4bc5431c"
},
"downloads": -1,
"filename": "pywebpush-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1ebf11fab507a6e63217797018769ee",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 21364,
"upload_time": "2024-11-19T21:30:19",
"upload_time_iso_8601": "2024-11-19T21:30:19.312076Z",
"url": "https://files.pythonhosted.org/packages/90/8a/ecaa2a589338a038b89148b01a5db2dac53e45918342da69baca1fb058fc/pywebpush-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "41ca6e669bf676916d66c8c7adedc291e9a9758650f9d85ec040fda13e3c82f4",
"md5": "23be21d14250891b77dd36fe374449e6",
"sha256": "584878e3c243e873a22db8895505d95715bc796ef74cc1b8fe99f596174161e3"
},
"downloads": -1,
"filename": "pywebpush-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "23be21d14250891b77dd36fe374449e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25874,
"upload_time": "2024-11-19T21:30:20",
"upload_time_iso_8601": "2024-11-19T21:30:20.444451Z",
"url": "https://files.pythonhosted.org/packages/41/ca/6e669bf676916d66c8c7adedc291e9a9758650f9d85ec040fda13e3c82f4/pywebpush-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 21:30:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "web-push-libs",
"github_project": "pywebpush",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"circle": true,
"requirements": [
{
"name": "aiohttp",
"specs": []
},
{
"name": "cryptography",
"specs": [
[
">=",
"2.6.1"
]
]
},
{
"name": "http-ece",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.21.0"
]
]
},
{
"name": "six",
"specs": [
[
">=",
"1.15.0"
]
]
},
{
"name": "py-vapid",
"specs": [
[
">=",
"1.7.0"
]
]
}
],
"lcname": "pywebpush"
}
JSON
