|PyPI version py_vapid|
Easy VAPID generation
=====================
This minimal library contains the minimal set of functions you need to
generate a VAPID key set and get the headers you’ll need to sign a
WebPush subscription update.
VAPID is a voluntary standard for WebPush subscription providers (sites
that send WebPush updates to remote customers) to self-identify to Push
Servers (the servers that convey the push notifications).
The VAPID “claims” are a set of JSON keys and values. There are two
required fields, one semi-optional and several optional additional
fields.
At a minimum a VAPID claim set should look like:
::
{"sub":"mailto:YourEmail@YourSite.com","aud":"https://PushServer","exp":"ExpirationTimestamp"}
A few notes:
**sub** is the email address you wish to have on record for this
request, prefixed with “``mailto:``”. If things go wrong, this is the
email that will be used to contact you (for instance). This can be a
general delivery address like “``mailto:push_operations@example.com``”
or a specific address like “``mailto:bob@example.com``”.
**aud** is the audience for the VAPID. This is the scheme and host you
use to send subscription endpoints and generally coincides with the
``endpoint`` specified in the Subscription Info block.
As example, if a WebPush subscription info contains:
``{"endpoint": "https://push.example.com:8012/v1/push/...", ...}``
then the ``aud`` would be “``https://push.example.com:8012``”
While some Push Services consider this an optional field, others may be
stricter.
**exp** This is the UTC timestamp for when this VAPID request will
expire. The maximum period is 24 hours. Setting a shorter period can
prevent “replay” attacks. Setting a longer period allows you to reuse
headers for multiple sends (e.g. if you’re sending hundreds of updates
within an hour or so.) If no ``exp`` is included, one that will expire
in 24 hours will be auto-generated for you.
Claims should be stored in a JSON compatible file. In the examples
below, we’ve stored the claims into a file named ``claims.json``.
py_vapid can either be installed as a library or used as a stand along
app, ``bin/vapid``.
App Installation
----------------
You’ll need ``python virtualenv`` Run that in the current directory.
Then run
::
bin/pip install -r requirements.txt
bin/python setup.py install
App Usage
---------
Run by itself, ``bin/vapid`` will check and optionally create the
public_key.pem and private_key.pem files.
``bin/vapid --gen`` can be used to generate a new set of public and
private key PEM files. These will overwrite the contents of
``private_key.pem`` and ``public_key.pem``.
``bin/vapid --sign claims.json`` will generate a set of HTTP headers
from a JSON formatted claims file. A sample ``claims.json`` is included
with this distribution.
``bin/vapid --sign claims.json --json`` will output the headers in JSON
format, which may be useful for other programs.
``bin/vapid --applicationServerKey`` will return the
``applicationServerKey`` value you can use to make a restricted
endpoint. See
https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe
for more details. Be aware that this value is tied to the generated
public/private key. If you remove or generate a new key, any restricted
URL you’ve previously generated will need to be reallocated. Please note
that some User Agents may require you `to decode this string into a
Uint8Array <https://github.com/GoogleChrome/push-notifications/blob/master/app/scripts/main.js>`__.
See ``bin/vapid -h`` for all options and commands.
CHANGELOG
---------
I’m terrible about updating the Changelog. Please see the
```git log`` <https://github.com/web-push-libs/vapid/pulls?q=is%3Apr+is%3Aclosed>`__
history for details.
.. |PyPI version py_vapid| image:: https://badge.fury.io/py/py-vapid.svg
:target: https://pypi.org/project/py-vapid/
Raw data
{
"_id": null,
"home_page": "https://github.com/mozilla-services/vapid",
"name": "py-vapid",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "vapid push webpush",
"author": "JR Conlin",
"author_email": "src+vapid@jrconlin.com",
"download_url": "https://files.pythonhosted.org/packages/a7/a8/2983cdf5f1c25274b941efd7ab0001067686c50640fba7f84fe490c1ce4b/py-vapid-1.9.0.tar.gz",
"platform": null,
"description": "|PyPI version py_vapid|\n\nEasy VAPID generation\n=====================\n\nThis minimal library contains the minimal set of functions you need to\ngenerate a VAPID key set and get the headers you\u2019ll need to sign a\nWebPush subscription update.\n\nVAPID is a voluntary standard for WebPush subscription providers (sites\nthat send WebPush updates to remote customers) to self-identify to Push\nServers (the servers that convey the push notifications).\n\nThe VAPID \u201cclaims\u201d are a set of JSON keys and values. There are two\nrequired fields, one semi-optional and several optional additional\nfields.\n\nAt a minimum a VAPID claim set should look like:\n\n::\n\n {\"sub\":\"mailto:YourEmail@YourSite.com\",\"aud\":\"https://PushServer\",\"exp\":\"ExpirationTimestamp\"}\n\nA few notes:\n\n**sub** is the email address you wish to have on record for this\nrequest, prefixed with \u201c``mailto:``\u201d. If things go wrong, this is the\nemail that will be used to contact you (for instance). This can be a\ngeneral delivery address like \u201c``mailto:push_operations@example.com``\u201d\nor a specific address like \u201c``mailto:bob@example.com``\u201d.\n\n**aud** is the audience for the VAPID. This is the scheme and host you\nuse to send subscription endpoints and generally coincides with the\n``endpoint`` specified in the Subscription Info block.\n\nAs example, if a WebPush subscription info contains:\n``{\"endpoint\": \"https://push.example.com:8012/v1/push/...\", ...}``\n\nthen the ``aud`` would be \u201c``https://push.example.com:8012``\u201d\n\nWhile some Push Services consider this an optional field, others may be\nstricter.\n\n**exp** This is the UTC timestamp for when this VAPID request will\nexpire. The maximum period is 24 hours. Setting a shorter period can\nprevent \u201creplay\u201d attacks. Setting a longer period allows you to reuse\nheaders for multiple sends (e.g.\u00a0if you\u2019re sending hundreds of updates\nwithin an hour or so.) If no ``exp`` is included, one that will expire\nin 24 hours will be auto-generated for you.\n\nClaims should be stored in a JSON compatible file. In the examples\nbelow, we\u2019ve stored the claims into a file named ``claims.json``.\n\npy_vapid can either be installed as a library or used as a stand along\napp, ``bin/vapid``.\n\nApp Installation\n----------------\n\nYou\u2019ll need ``python virtualenv`` Run that in the current directory.\n\nThen run\n\n::\n\n bin/pip install -r requirements.txt\n\n bin/python setup.py install\n\nApp Usage\n---------\n\nRun by itself, ``bin/vapid`` will check and optionally create the\npublic_key.pem and private_key.pem files.\n\n``bin/vapid --gen`` can be used to generate a new set of public and\nprivate key PEM files. These will overwrite the contents of\n``private_key.pem`` and ``public_key.pem``.\n\n``bin/vapid --sign claims.json`` will generate a set of HTTP headers\nfrom a JSON formatted claims file. A sample ``claims.json`` is included\nwith this distribution.\n\n``bin/vapid --sign claims.json --json`` will output the headers in JSON\nformat, which may be useful for other programs.\n\n``bin/vapid --applicationServerKey`` will return the\n``applicationServerKey`` value you can use to make a restricted\nendpoint. See\nhttps://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe\nfor more details. Be aware that this value is tied to the generated\npublic/private key. If you remove or generate a new key, any restricted\nURL you\u2019ve previously generated will need to be reallocated. Please note\nthat some User Agents may require you `to decode this string into a\nUint8Array <https://github.com/GoogleChrome/push-notifications/blob/master/app/scripts/main.js>`__.\n\nSee ``bin/vapid -h`` for all options and commands.\n\nCHANGELOG\n---------\n\nI\u2019m terrible about updating the Changelog. Please see the\n```git log`` <https://github.com/web-push-libs/vapid/pulls?q=is%3Apr+is%3Aclosed>`__\nhistory for details.\n\n.. |PyPI version py_vapid| image:: https://badge.fury.io/py/py-vapid.svg\n :target: https://pypi.org/project/py-vapid/\n\n\n",
"bugtrack_url": null,
"license": "MPL2",
"summary": "Simple VAPID header generation library",
"version": "1.9.0",
"split_keywords": [
"vapid",
"push",
"webpush"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "3ddd55aaafd0f123cbb3ab607c223d22",
"sha256": "0664ab7899742ef2b287397a4d461ef691ed0cc2f587205128d8cf617ffdb919"
},
"downloads": -1,
"filename": "py-vapid-1.9.0.tar.gz",
"has_sig": false,
"md5_digest": "3ddd55aaafd0f123cbb3ab607c223d22",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19795,
"upload_time": "2022-12-05T23:50:15",
"upload_time_iso_8601": "2022-12-05T23:50:15.769562Z",
"url": "https://files.pythonhosted.org/packages/a7/a8/2983cdf5f1c25274b941efd7ab0001067686c50640fba7f84fe490c1ce4b/py-vapid-1.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-05 23:50:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mozilla-services",
"github_project": "vapid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "py-vapid"
}
JSON
