Wallos: Open-source, self-hostable personal subscription tracker. Visualize your recurring expenses, manage your budget, and save money.
<?php
/*
Web Push (RFC 8030 / RFC 8291 / RFC 8292): standard browser push
notifications, sent directly to the browser vendor's own push service
(Chrome's, Firefox's, Apple's, ...) with no account of Wallos's own -
unlike Pushover, Gotify or ntfy, which all need the user to register
somewhere else first.
Two things a push message needs that nothing else in this codebase does:
- VAPID (RFC 8292): a JWT, signed with this installation's own EC
keypair, that tells the push service which application server sent the
message, so it can rate-limit and identify abuse by sender rather than
by subscription.
- End-to-end encryption (RFC 8291): the push service is an untrusted
relay that can read the message's metadata but never its payload,
which is encrypted between this server and the browser using a key
derived from the subscription's own public key and auth secret - the
push service is never able to decrypt it.
Both need elliptic-curve Diffie-Hellman, which ext-openssl only exposed a
plain function for (openssl_pkey_derive()) starting in PHP 8.1. Wallos
targets PHP 8.3, so this is written directly against ext-openssl - no
Composer package, the way every other vendored helper in this codebase is
(see includes/frankfurter.php for the same approach applied to an HTTP API
instead of a cryptographic one).
Every intermediate value this file computes (the ECDH secret, the two HKDF
outputs, the final ciphertext) is checked byte-for-byte against RFC 8291's
own published test vector in tests/cases/webpush_test.php - that is a much
stronger guarantee than "the output looks like a push message", which is
why the payload encryption function accepts an injectable ephemeral key and
salt: production always generates both fresh (forward secrecy depends on
the ephemeral key never being reused across messages), but a test needs the
RFC's fixed ones to reproduce its fixed output.
*/
function webpush_base64url_encode($data)
{
return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
}
function webpush_base64url_decode($data)
{
$data = strtr((string) $data, '-_', '+/');
$padded = str_pad($data, strlen($data) + (4 - strlen($data) % 4) % 4, '=');
$decoded = base64_decode($padded, true);
return $decoded === false ? '' : $decoded;
}
/**
* Left-pads (or, defensively, right-truncates) a big-endian byte string to a
* fixed length.
*
* ext-openssl's EC accessors (openssl_pkey_get_details()['ec']['x'/'y'/'d'],
* openssl_pkey_derive()'s return value) strip leading zero bytes, but every
* one of these values is a fixed-width 32-byte P-256 field element or scalar
* everywhere it is used here - the raw point format, the JWS signature
* format, and the shared secret all require the width restored.
*
* @param string $value
* @param int $length
* @return string
*/
function webpush_fixed_width($value, $length = 32)
{
if (strlen($value) > $length) {
return substr($value, -$length);
}
return str_pad($value, $length, "\x00", STR_PAD_LEFT);
}
/**
* A P-256 uncompressed point (65 bytes: 0x04 || X(32) || Y(32)) - what both
* a push subscription's p256dh and an applicationServerKey are - as an
* OpenSSL public key resource, for openssl_pkey_derive() and
* openssl_verify().
*
* ext-openssl has no "import a raw point" function; a SubjectPublicKeyInfo
* DER wrapper around the point does the same thing, and for a fixed named
* curve every byte of that wrapper except the point itself is constant -
* this is the standard encoding of "id-ecPublicKey, prime256v1". Verified
* against ext-openssl's own PEM output for a point it generated itself
* (same derived ECDH secret either way) before this was trusted for
* anything real.
*
* @param string $rawPoint
* @return OpenSSLAsymmetricKey|false
*/
function webpush_ec_public_key_from_raw($rawPoint)
{
if (strlen($rawPoint) !== 65 || $rawPoint[0] !== "\x04") {
return false;
}
$prefix = hex2bin('3059301306072a8648ce3d020106082a8648ce3d030107034200');
$der = $prefix . $rawPoint;
$pem = "-----BEGIN PUBLIC KEY-----\n" . chunk_split(base64_encode($der), 64, "\n") . "-----END PUBLIC KEY-----\n";
$key = openssl_pkey_get_public($pem);
return $key === false ? false : $key;
}
/**
* Reads one ASN.1 DER INTEGER at $offset.
*
* @param string $der
* @param int $offset
* @return array{0: string|false, 1: int} The integer's raw bytes (with any
* ASN.1 sign-avoidance zero pad stripped), and the offset just past
* it. [false, $offset] on a malformed input.
*/
function webpush_der_read_integer($der, $offset)
{
$len = strlen($der);
if ($offset >= $len || ord($der[$offset]) !== 0x02) {
return [false, $offset];
}
$offset++;
if ($offset >= $len) {
return [false, $offset];
}
$intLen = ord($der[$offset]);
$offset++;
if ($intLen & 0x80) {
$numLenBytes = $intLen & 0x7f;
if ($numLenBytes < 1 || $numLenBytes > 2 || $offset + $numLenBytes > $len) {
return [false, $offset];
}
$intLen = 0;
for ($i = 0; $i < $numLenBytes; $i++) {
$intLen = ($intLen << 8) | ord($der[$offset + $i]);
}
$offset += $numLenBytes;
}
if ($intLen < 0 || $offset + $intLen > $len) {
return [false, $offset];
}
$value = substr($der, $offset, $intLen);
$offset += $intLen;
// A leading 0x00 that exists only to keep a high first bit from reading
// as a two's-complement sign is not part of the fixed-width value a JWS
// wants - r and s are unsigned there.
while (strlen($value) > 1 && $value[0] === "\x00" && (ord($value[1]) & 0x80)) {
$value = substr($value, 1);
}
return [$value, $offset];
}
/**
* Converts the DER ECDSA-Sig-Value openssl_sign() produces into the raw
* r || s concatenation a JWS ES256 signature is.
*
* @param string $der
* @param int $partLength Width of each of r and s; 32 for P-256/ES256.
* @return string|false
*/
function webpush_der_signature_to_raw($der, $partLength = 32)
{
$offset = 0;
$len = strlen($der);
if ($len < 8 || ord($der[$offset]) !== 0x30) {
return false;
}
$offset++;
$seqLen = ord($der[$offset]);
$offset++;
if ($seqLen & 0x80) {
$numLenBytes = $seqLen & 0x7f;
if ($numLenBytes < 1 || $numLenBytes > 2 || $offset + $numLenBytes > $len) {
return false;
}
$seqLen = 0;
for ($i = 0; $i < $numLenBytes; $i++) {
$seqLen = ($seqLen << 8) | ord($der[$offset + $i]);
}
$offset += $numLenBytes;
}
[$r, $offset] = webpush_der_read_integer($der, $offset);
if ($r === false) {
return false;
}
[$s, $offset] = webpush_der_read_integer($der, $offset);
if ($s === false) {
return false;
}
return webpush_fixed_width($r, $partLength) . webpush_fixed_width($s, $partLength);
}
/**
* openssl.cnf paths worth retrying a failed key operation with.
*
* Some PHP-for-Windows builds (XAMPP's included) link an OpenSSL that cannot
* locate its own default config file, and every openssl_pkey_new()/
* openssl_pkey_export() call then fails outright - reproducibly, with
* OpenSSL's own "configuration file routines::no such file" - even for a
* plain RSA key with no EC or Web Push involved at all. This is an
* environment problem, not one this file can fix, but it is common enough
* (XAMPP is a standard local dev setup) that failing outright rather than
* working around it would leave the feature broken for a lot of installs
* that would otherwise never touch this at all - Docker, and most native
* Linux packagings, resolve their default config without any of this.
*
* @return string[] Existing, readable candidate paths, in the order to try.
*/
function webpush_openssl_config_candidates()
{
$candidates = [];
$envConf = getenv('OPENSSL_CONF');
if ($envConf !== false && trim($envConf) !== '') {
$candidates[] = $envConf;
}
// Where XAMPP for Windows ships an openssl.cnf next to the php.ini this
// exact request loaded - true for both the Apache module and the CLI
// binary, since XAMPP points both at the same php.ini by default.
$iniFile = php_ini_loaded_file();
if ($iniFile !== false) {
$iniDir = dirname($iniFile);
$candidates[] = $iniDir . '/extras/openssl/openssl.cnf';
$candidates[] = $iniDir . '/extras/ssl/openssl.cnf';
}
return array_values(array_filter($candidates, function ($path) {
return $path !== '' && is_readable($path);
}));
}
/**
* openssl_pkey_new(), retried with a discovered openssl.cnf if the plain
* call fails - see webpush_openssl_config_candidates() for why that can be
* necessary at all. The plain call is always tried first and is all that
* runs on an install where it already works.
*
* @param array $options As openssl_pkey_new() takes, without 'config'.
* @return OpenSSLAsymmetricKey|false
*/
function webpush_openssl_pkey_new($options)
{
$key = openssl_pkey_new($options);
if ($key !== false) {
return $key;
}
foreach (webpush_openssl_config_candidates() as $configPath) {
$key = openssl_pkey_new($options + ['config' => $configPath]);
if ($key !== false) {
return $key;
}
}
return false;
}
/**
* Generates a fresh P-256 keypair for this installation to identify itself
* to push services with.
*
* @return array{public: string, private_pem: string}|false 'public' is the
* raw uncompressed point, base64url - what both the VAPID
* Authorization header and the frontend's applicationServerKey need.
* 'private_pem' is kept in PEM, the form openssl_sign() and
* openssl_pkey_get_private() both take directly.
*/
function webpush_generate_vapid_keypair()
{
$key = webpush_openssl_pkey_new([
'curve_name' => 'prime256v1',
'private_key_type' => OPENSSL_KEYTYPE_EC,
]);
if ($key === false) {
return false;
}
$details = openssl_pkey_get_details($key);
if ($details === false || !isset($details['ec']['x'], $details['ec']['y'])) {
return false;
}
$publicRaw = "\x04" . webpush_fixed_width($details['ec']['x']) . webpush_fixed_width($details['ec']['y']);
// Exporting can hit the same missing-config failure key generation can -
// the same candidates are worth the same retry.
if (!openssl_pkey_export($key, $privatePem)) {
$exported = false;
foreach (webpush_openssl_config_candidates() as $configPath) {
if (openssl_pkey_export($key, $privatePem, null, ['config' => $configPath])) {
$exported = true;
break;
}
}
if (!$exported) {
return false;
}
}
return [
'public' => webpush_base64url_encode($publicRaw),
'private_pem' => $privatePem,
];
}
/**
* This installation's VAPID keypair, generating and persisting one the
* first time anything needs it.
*
* Stored on the admin row alongside the other instance-wide settings that
* already live there (smtp_*, server_url) - it identifies the Wallos
* installation as a whole to the push services it talks to, not any one
* user, the same way the instance's own SMTP identity is not per-user.
*
* @param SQLite3 $db
* @return array{public: string, private_pem: string}|false
*/
function webpush_get_vapid_keys($db)
{
$row = $db->querySingle('SELECT vapid_public_key, vapid_private_key FROM admin LIMIT 1', true);
if ($row !== false && !empty($row['vapid_public_key']) && !empty($row['vapid_private_key'])) {
return ['public' => $row['vapid_public_key'], 'private_pem' => $row['vapid_private_key']];
}
$keys = webpush_generate_vapid_keypair();
if ($keys === false) {
return false;
}
return webpush_store_vapid_keys($db, $keys);
}
/**
* Persists a freshly generated keypair, unless the installation has one by
* now, and answers with whichever pair is stored afterwards.
*
* The write has to be conditional, and the row has to be read back, because a
* push subscription is bound to the applicationServerKey the browser saw when
* it subscribed. Two first uses at once - the settings page of one household
* member and the notification cron, say - each find the columns empty, each
* generate a pair, and with an unconditional UPDATE the second write wins.
* Every device that had already subscribed with the first key is then answered
* 403 by its push service from that moment on, and 403 is not 404/410, so the
* cron prunes nothing, the settings page still lists the device, and the
* notifications simply stop with nothing anywhere to say why.
*
* @param SQLite3 $db
* @param array{public: string, private_pem: string} $keys
* @return array{public: string, private_pem: string}|false
*/
function webpush_store_vapid_keys($db, $keys)
{
$stmt = $db->prepare("UPDATE admin SET vapid_public_key = :public, vapid_private_key = :private
WHERE vapid_public_key IS NULL OR vapid_public_key = ''
OR vapid_private_key IS NULL OR vapid_private_key = ''");
if ($stmt === false) {
return false;
}
$stmt->bindValue(':public', $keys['public'], SQLITE3_TEXT);
$stmt->bindValue(':private', $keys['private_pem'], SQLITE3_TEXT);
if ($stmt->execute() === false) {
return false;
}
// Read back rather than returning what was generated: when the UPDATE
// matched nothing, the pair that matters is the one already in the row.
$row = $db->querySingle('SELECT vapid_public_key, vapid_private_key FROM admin LIMIT 1', true);
if ($row !== false && !empty($row['vapid_public_key']) && !empty($row['vapid_private_key'])) {
return ['public' => $row['vapid_public_key'], 'private_pem' => $row['vapid_private_key']];
}
return $keys;
}
/**
* Builds and signs a VAPID (RFC 8292) authorization JWT for one push
* message.
*
* @param string $endpoint The subscription's push service endpoint -
* only its scheme://host[:port] is used, as
* the "aud" claim, per RFC 8292.
* @param string $subject A mailto: or https: URL identifying this
* application server, the "sub" claim - shown
* to the push service's operator if it needs
* to reach whoever is sending it messages.
* @param string $privateKeyPem
* @return string|false
*/
function webpush_build_vapid_jwt($endpoint, $subject, $privateKeyPem)
{
$parsedEndpoint = parse_url($endpoint);
if (!$parsedEndpoint || !isset($parsedEndpoint['scheme'], $parsedEndpoint['host'])) {
return false;
}
$audience = $parsedEndpoint['scheme'] . '://' . $parsedEndpoint['host']
. (isset($parsedEndpoint['port']) ? ':' . $parsedEndpoint['port'] : '');
$header = ['typ' => 'JWT', 'alg' => 'ES256'];
$claims = [
'aud' => $audience,
// RFC 8292 caps this at 24 hours; 12 is comfortably within it and
// well past this cron's own run interval, so a slow run never signs
// a token that is already expired by the time it is used.
'exp' => time() + 12 * 3600,
'sub' => $subject,
];
$segment = webpush_base64url_encode(json_encode($header)) . '.' . webpush_base64url_encode(json_encode($claims));
$privateKey = openssl_pkey_get_private($privateKeyPem);
if ($privateKey === false) {
return false;
}
if (!openssl_sign($segment, $der, $privateKey, OPENSSL_ALGO_SHA256)) {
return false;
}
$raw = webpush_der_signature_to_raw($der, 32);
if ($raw === false) {
return false;
}
return $segment . '.' . webpush_base64url_encode($raw);
}
/**
* Encrypts one push message payload per RFC 8291 (the aes128gcm content
* coding, RFC 8188).
*
* @param string $plaintext
* @param string $p256dhB64 The subscription's own public key,
* base64url (browser-supplied).
* @param string $authB64 The subscription's auth secret,
* base64url (browser-supplied).
* @param string|null $ephemeralKeyPem Injectable only for tests to
* reproduce RFC 8291's fixed test
* vector; null generates a fresh
* one-time keypair, as production
* always must - reusing an ephemeral
* key across messages breaks the
* forward secrecy the protocol exists
* to provide.
* @param string|null $salt Injectable only for tests, for the
* same reason; null generates 16 fresh
* random bytes, as production always
* must.
* @return string|false The aes128gcm body (content-coding header followed
* by the ciphertext and its GCM tag), ready to POST as-is.
*/
function webpush_encrypt_payload($plaintext, $p256dhB64, $authB64, $ephemeralKeyPem = null, $salt = null)
{
$uaPublicRaw = webpush_base64url_decode($p256dhB64);
$authSecret = webpush_base64url_decode($authB64);
if (strlen($uaPublicRaw) !== 65 || strlen($authSecret) !== 16) {
return false;
}
$uaPublicKey = webpush_ec_public_key_from_raw($uaPublicRaw);
if ($uaPublicKey === false) {
return false;
}
if ($ephemeralKeyPem === null) {
$ephemeralKey = webpush_openssl_pkey_new([
'curve_name' => 'prime256v1',
'private_key_type' => OPENSSL_KEYTYPE_EC,
]);
if ($ephemeralKey === false) {
return false;
}
} else {
$ephemeralKey = openssl_pkey_get_private($ephemeralKeyPem);
if ($ephemeralKey === false) {
return false;
}
}
$ephemeralDetails = openssl_pkey_get_details($ephemeralKey);
if ($ephemeralDetails === false || !isset($ephemeralDetails['ec']['x'], $ephemeralDetails['ec']['y'])) {
return false;
}
$asPublicRaw = "\x04" . webpush_fixed_width($ephemeralDetails['ec']['x']) . webpush_fixed_width($ephemeralDetails['ec']['y']);
$sharedSecret = openssl_pkey_derive($uaPublicKey, $ephemeralKey, 0);
if ($sharedSecret === false) {
return false;
}
$sharedSecret = webpush_fixed_width($sharedSecret);
if ($salt === null) {
$salt = random_bytes(16);
} elseif (strlen($salt) !== 16) {
return false;
}
// RFC 8291 section 3.4: combine the ECDH secret with the subscription's
// own auth secret, so a push service that only ever sees ua_public in
// transit still cannot derive this on its own - it never sees auth.
$keyInfo = "WebPush: info\x00" . $uaPublicRaw . $asPublicRaw;
$ikm = hash_hkdf('sha256', $sharedSecret, 32, $keyInfo, $authSecret);
// RFC 8188's own key derivation from that IKM and this record's salt.
$cek = hash_hkdf('sha256', $ikm, 16, "Content-Encoding: aes128gcm\x00", $salt);
$nonce = hash_hkdf('sha256', $ikm, 12, "Content-Encoding: nonce\x00", $salt);
// A single record holds the whole payload - a push message is at most a
// few hundred bytes here, far under the 4096-byte record size declared
// below, so there is never a second record to pad between. 0x02 is RFC
// 8188's "last record" delimiter byte; nothing follows it.
$padded = $plaintext . "\x02";
$ciphertext = openssl_encrypt($padded, 'aes-128-gcm', $cek, OPENSSL_RAW_DATA, $nonce, $tag, '', 16);
if ($ciphertext === false) {
return false;
}
$recordSize = 4096;
$header = $salt . pack('N', $recordSize) . chr(strlen($asPublicRaw)) . $asPublicRaw;
return $header . $ciphertext . $tag;
}
/**
* Sends one push message to one subscription.
*
* @param array{endpoint: string, p256dh: string, auth: string} $subscription
* @param string $payload Plaintext message body.
* @param array{public: string, private_pem: string} $vapidKeys
* @param string $subject RFC 8292 "sub" claim.
* @param int $ttl Seconds the push service may hold the message for
* before giving up if the device is offline - a
* month is generous and costs nothing unused.
* @param array{host: string, ip: string, port: int}|null $ssrfPin DNS-pin
* from is_url_safe_for_ssrf()/validate_webhook_url_for_ssrf(),
* to close the DNS-rebinding gap the same way every
* other outbound channel here already does.
* @return array{success: bool, status: int|null, prune: bool, error: string|null}
* 'prune' is true only for the responses (404/410) that mean the
* push service itself has discarded this subscription - never for a
* device merely being offline, which the push service queues
* through on its own; see includes/webpush_helper.php's own comment
* above webpush_send() usage in the cron job for why.
*/
function webpush_send($subscription, $payload, $vapidKeys, $subject, $ttl = 2419200, $ssrfPin = null)
{
$body = webpush_encrypt_payload($payload, $subscription['p256dh'], $subscription['auth']);
if ($body === false) {
return ['success' => false, 'status' => null, 'prune' => false, 'error' => 'Could not encrypt the payload.'];
}
$jwt = webpush_build_vapid_jwt($subscription['endpoint'], $subject, $vapidKeys['private_pem']);
if ($jwt === false) {
return ['success' => false, 'status' => null, 'prune' => false, 'error' => 'Could not build the VAPID token.'];
}
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $subscription['endpoint']);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/octet-stream',
'Content-Encoding: aes128gcm',
'TTL: ' . (int) $ttl,
'Authorization: vapid t=' . $jwt . ', k=' . $vapidKeys['public'],
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
if ($ssrfPin !== null) {
curl_setopt($ch, CURLOPT_RESOLVE, ["{$ssrfPin['host']}:{$ssrfPin['port']}:{$ssrfPin['ip']}"]);
}
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($response === false) {
return ['success' => false, 'status' => null, 'prune' => false, 'error' => $curlError];
}
$success = $status >= 200 && $status < 300;
// 404/410: the push service has no record of this subscription any more
// (unsubscribed, cleared site data, uninstalled, or its own garbage
// collection of a very stale one) - safe to forget it. Every other
// failure - 429 rate limited, a 5xx fault, a malformed request - says
// nothing about whether the subscription itself is still good, so none
// of those prune it.
$prune = in_array($status, [404, 410], true);
return ['success' => $success, 'status' => $status, 'prune' => $prune, 'error' => $success ? null : $response];
}