diff options
Diffstat (limited to 'docs/ops.md')
| -rw-r--r-- | docs/ops.md | 14 |
1 files changed, 14 insertions, 0 deletions
diff --git a/docs/ops.md b/docs/ops.md index a622c04..678d2a4 100644 --- a/docs/ops.md +++ b/docs/ops.md @@ -21,3 +21,17 @@ By default, the `pilcrow` command will set the process' umask to a value that pr - any octal value corresponding to a valid umask, such as `0027`. Pilcrow does not check or change the permissions of the database after creation. Changing the umask of the server after the database has been created has no effect on the database's filesystem permissions. + +## VAPID keys + +Pilcrow uses [VAPID] to identify itself to public Web Push brokers, which then deliver notifications to Pilcrow's users of interesting events, such as messages. VAPID uses cryptographic signatures to authenticate the server. + +[VAPID]: https://datatracker.ietf.org/doc/html/rfc8292 + +The key is stored in the `pilcrow` database. Pilcrow will create its key automatically, and will rotate the key every 30 days. + +If the `pilcrow` database is accessed inappropriately or leaked, then the key can be used to send push notifications to Pilcrow users as if from the Pilcrow server. If this happens, the key _must_ be rotated to prevent misuse. + +The key can be rotated at any time running `pilcrow […options…] rotate-vapid-key`, as the same user Pilcrow normally runs as. This does not require that the server be shut down or restarted. The `[…options…]` must be set to the same values as used by the running server. + +When the key is rotated, no further push messages will be sent from the Pilcrow server using that key. Unfortunately, the Web Push protocol doesn't allow Pilcrow to proactively invalidate clients' push subscriptions, but Pilcrow will inform clients when the key is rotated so that they can invalidate the affected subscriptions themselves. |