Skip to main content

Simple VAPID header generation library

Project description

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 -m pip install -e .

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.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_vapid-1.9.2.tar.gz (20.3 kB view details)

Uploaded Source

Built Distribution

py_vapid-1.9.2-py3-none-any.whl (21.5 kB view details)

Uploaded Python 3

File details

Details for the file py_vapid-1.9.2.tar.gz.

File metadata

  • Download URL: py_vapid-1.9.2.tar.gz
  • Upload date:
  • Size: 20.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for py_vapid-1.9.2.tar.gz
Algorithm Hash digest
SHA256 3c8973b6cf8384ad0c9ae64d6270ccc480e0b92c702d8f5ea2cc03e6b51247f9
MD5 95e835d9cfff788ad1755c46709dbe4b
BLAKE2b-256 ff575c1c61f27ce01f939443cf3f6c279a295f7ec0327b18a1cbbcfefe0b5456

See more details on using hashes here.

File details

Details for the file py_vapid-1.9.2-py3-none-any.whl.

File metadata

  • Download URL: py_vapid-1.9.2-py3-none-any.whl
  • Upload date:
  • Size: 21.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for py_vapid-1.9.2-py3-none-any.whl
Algorithm Hash digest
SHA256 4ccf8a00fc54f1f99f66fb543c96f2c82622508ad814b6e9225f2c26948934d7
MD5 4cd50a41124b6895d42cd023c6e85934
BLAKE2b-256 73fbb877a221b09dabcebeb073d5e7f19244f3fa1d5aec87092c359a6049a006

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page