Push API Payload Encryption: Secure Implementation Guide

Web push notifications require strict end-to-end confidentiality to protect user data and prevent network interception. This guide details the exact cryptographic workflow for encrypting payloads on the server and decrypting them in the browser, aligned with RFC 8291 (Message Encryption for Web Push). For foundational context on how browsers route and queue push messages, refer to Core Protocols & Browser Implementation.

Prerequisites

• A PushSubscription with endpoint, keys.p256dh, and keys.auth captured server-side.
• A VAPID key pair supplied via process.env.VAPID_PUBLIC_KEY / process.env.VAPID_PRIVATE_KEY — never hardcoded in server code.
• An audited library (web-push for Node.js, pywebpush for Python) — do not hand-roll the cipher stack.
• A registered service worker per Service Worker Registration Patterns to receive and decrypt messages.
• Node.js 16+ (or runtime with native P-256 ECDH and HKDF-SHA-256 support).

Implementation Prerequisites (mapping):

• Extract the PushSubscription object structure: endpoint, keys.p256dh, and keys.auth
• Map all cryptographic operations to RFC 8291 specifications
• In production, use an audited library that implements RFC 8291 correctly — hand-rolling the full encryption stack is error-prone

Cryptographic Architecture & Key Derivation

Payload encryption relies on Elliptic Curve Diffie-Hellman (ECDH) over the NIST P-256 curve to establish a shared secret between the application server and the user agent. The auth secret acts as a salt input to HKDF-SHA-256, generating the Content-Encoding Key (CEK) and nonce. The final payload is encrypted using AES-128-GCM and framed as the aes128gcm content encoding.

Derivation Workflow (RFC 8291 §3.3 & §3.4):

1. Extract p256dh (client public key, base64url) and auth (16-byte auth secret, base64url) from the subscription
2. Generate an ephemeral server key pair (P-256) per-message for forward secrecy
3. Derive ecdh_secret via ECDH between ephemeral server private key and client public key
4. Compute prk = HKDF-Extract(salt=auth, IKM=ecdh_secret)
5. Compute content_encryption_key = HKDF-Expand(prk, info="Content-Encoding: aes128gcm\x00", 16 bytes)
6. Compute nonce = HKDF-Expand(prk, info="Content-Encoding: nonce\x00", 12 bytes)

const webpush = require('web-push');

// Production: let the library handle ECDH + HKDF + AES-128-GCM per RFC 8291
async function encryptAndSend(subscription, payloadObject) {
  const options = {
    vapidDetails: {
      subject:    'mailto:ops@yourdomain.com',
      publicKey:  process.env.VAPID_PUBLIC_KEY,
      privateKey: process.env.VAPID_PRIVATE_KEY
    },
    TTL: 86400
  };

  // web-push internally:
  //   1. Generates an ephemeral P-256 keypair
  //   2. Derives shared secret via ECDH with subscription.keys.p256dh
  //   3. Runs HKDF-SHA-256 to produce the CEK and nonce
  //   4. Encrypts with AES-128-GCM per RFC 8291 aes128gcm content encoding
  //   5. Attaches the VAPID Authorization header
  return webpush.sendNotification(
    subscription,
    JSON.stringify(payloadObject),
    options
  );
}

The VAPID public and private keys are read from the environment — they must never be hardcoded in server-side code. Key lifecycle for the signing pair is covered separately in VAPID Key Generation & Rotation.

Two properties of this derivation are worth internalizing because most decryption bugs trace back to violating one of them. First, the info strings passed to HKDF-Expand are exact byte sequences — "Content-Encoding: aes128gcm\x00" for the key and "Content-Encoding: nonce\x00" for the nonce — and a single wrong byte, including a missing trailing \x00, yields a key the browser cannot reproduce, so it silently fails to decrypt. Second, the ephemeral server keypair must be regenerated for every single message; reusing it across messages reuses the nonce under the same key, which not only breaks the spec’s forward-secrecy guarantee but undermines AES-GCM’s confidentiality entirely. A vetted library enforces both invariants automatically, which is the strongest argument against hand-rolling the stack.

Server-Side Encryption Workflow

Once cryptographic parameters are resolved, the plaintext payload is padded to prevent length-based fingerprinting, encrypted, and packaged into the HTTP POST body. The Content-Encoding: aes128gcm header must be explicitly set.

Packaging & Dispatch Steps:

1. Serialize JSON payload to a UTF-8 buffer
2. Apply a random padding delimiter byte (value 0x02 per RFC 8291) followed by zero or more 0x00 padding bytes to obscure content length
3. Encrypt the padded plaintext with AES-128-GCM using the derived CEK and nonce
4. Construct the aes128gcm binary record: [salt (16 bytes)][record_size (4 bytes, big-endian)][key_id_len (1 byte)][key_id][ciphertext + auth-tag (16 bytes)]
5. POST to the push endpoint with the correct headers

const webpush = require('web-push');
const crypto  = require('crypto');

/**
 * Sends an encrypted push notification using the web-push library.
 * The library handles aes128gcm framing, ECDH, HKDF, and VAPID signing.
 */
async function dispatchEncryptedPush(subscription, payload, vapidDetails) {
  const response = await webpush.sendNotification(
    subscription,
    JSON.stringify(payload),
    {
      vapidDetails,
      TTL: 86400,
      urgency: 'high',
      contentEncoding: 'aes128gcm' // default; explicit for clarity
    }
  );
  return response;
}

The single-record framing is what distinguishes the modern aes128gcm encoding from the deprecated aesgcm scheme it replaced. In aes128gcm, the salt and the sender’s public key (the key_id) travel inside the binary record itself, so the only HTTP header the receiver needs is Content-Encoding: aes128gcm. The older aesgcm encoding carried the salt and key in separate Encryption and Crypto-Key headers, which proved fragile across proxies and is why every current implementation should emit aes128gcm exclusively. If you inherit a codebase still setting Encryption/Crypto-Key headers, that is a migration to schedule, not a configuration to preserve.

Proper service worker lifecycle management ensures encrypted messages are routed correctly, which depends heavily on established Service Worker Registration Patterns. When the browser rejects a record at the decryption stage, the aes128gcm encoding & decryption errors guide walks through each error and its root cause.

Encryption Parameter Reference

Authentication & Key Lifecycle Integration

Encryption ensures confidentiality; VAPID handles authorization. The two operate independently but must be coordinated during request construction. VAPID JWTs are signed with the application’s ECDSA P-256 private key and attached to the Authorization: WebPush <token> header. To prevent delivery failures or unauthorized access, implement automated key lifecycle policies aligned with VAPID Key Generation & Rotation, and when you must swap keys on an active install base follow rotating VAPID keys without losing subscribers.

Key Management Directives:

• Sign VAPID JWTs with explicit sub, exp (≤ 24 h), and aud claims using ES256
• Store encryption parameters (p256dh, auth) separately from VAPID signing keys in a secrets manager
• Implement cryptographic key versioning to enable seamless, zero-downtime rotation

Browser Constraints & Size Optimization

Encryption introduces overhead that reduces usable payload space. RFC 8291 aes128gcm overhead consists of: 16-byte salt, 4-byte record-size, 1-byte key-ID length field, 16-byte AES-GCM auth tag, and at least 1 padding byte — totaling roughly 38 bytes minimum plus any explicit padding you add. The overall encrypted ciphertext must fit within the push service’s per-message 4 KB payload size limit (nominally 4 KB per RFC 8030). Understanding maximum payload size limits for Chrome vs Firefox is critical for designing resilient notification architectures, and the per-engine rendering differences are catalogued in Cross-Browser Notification Quirks.

Optimization & Fallback Strategy:

• Keep plaintext JSON payloads under 3 KB to guarantee universal browser compatibility after encryption overhead
• Implement server-side payload minimization: transmit only identifiers and action metadata; fetch heavy content client-side after the notification triggers
• Validate encrypted size before dispatching to preempt 413 Payload Too Large responses

The “send an identifier, fetch the body” pattern is worth treating as the default rather than an optimization for large payloads only. A push carrying a single notification ID lets the service worker call your API on push to retrieve the current title, body, and image, which means a notification can reflect state that changed after dispatch and you never risk the 4 KB ceiling. The trade-off is that the fetch must complete inside the worker’s execution budget and must itself be wrapped in event.waitUntil(); if the network is unavailable, fall back to a generic notification rather than letting the event terminate without a visible result. Padding deserves a deliberate decision too: RFC 8291 lets you add 0x00 bytes after the 0x02 delimiter to mask the true plaintext length, which matters when the mere size of a notification could leak information (a short “approved” versus a long “declined, see details”). For most applications a small fixed pad is sufficient; for sensitive flows, pad to a constant bucket size.

Verification

Confirm the encryption path before shipping. The fastest signal is a 201 Created from the push service and a delivered notification in the target browser.

# Send a test push and observe the status code; expect 201 Created on success
node -e "require('./send-test-push.js')" && echo "dispatch returned 2xx"

In Chrome, open chrome://serviceworker-internals, push a test message, and confirm the push event fires with non-empty event.data. A decryption failure surfaces as the worker never receiving the event or event.data being null despite a 201 from the push service — that asymmetry is the canonical signature of a malformed aes128gcm record.

Error & Edge-Case Matrix

Security Compliance & Production Hardening

Encrypted payloads must comply with stringent data protection regulations. Avoid transmitting PII directly in push messages. Implement strict TLS 1.2+ enforcement for all push endpoints, log only delivery metadata (never decrypted content), and monitor for pushsubscriptionchange events to proactively renew subscriptions.

Hardening Checklist:

• Audit all payload contents for PII; replace with opaque, revocable identifiers
• Enforce HSTS and strict Content-Security-Policy on push delivery infrastructure
• Configure alerting for pushsubscriptionchange event spikes indicating mass expiration or compromise
• Conduct quarterly cryptographic dependency audits to patch vulnerabilities in underlying TLS/HKDF implementations

Related

• Maximum payload size limits for Chrome vs Firefox — exact per-engine ceilings after encryption overhead.
• aes128gcm encoding & decryption errors — diagnosing browser-side decrypt failures.
• VAPID Key Generation & Rotation — the signing key lifecycle that pairs with encryption.
• Service Worker Registration Patterns — the worker that receives and parses the decrypted payload.
• Cross-Browser Notification Quirks — rendering differences once the payload is decrypted.

Back to Core Protocols & Browser Implementation

FAQ