HTML消息推送AES128GCM加密详解

Web Push 消息绝非简单发送即可，而是强制要求服务端使用 AES-128-GCM 加密 payload，并严格依赖客户端提供的 auth（16字节随机 salt）和 p256dh（ECC 公钥）派生密钥——不加密、密钥错、头部缺一或格式不规范（如 content-encoding 大小写错误、salt 未正确二次编码），浏览器便会直接拒绝解密，导致推送静默失败或通知无法显示；从前端订阅时必须启用 `userVisibleOnly: true` 并正确传入 Uint8Array 格式的 VAPID 公钥，到后端用 web-push 库配置 VAPID 而非废弃的 GCM Key，再到调试时逐项核验三个关键 HTTP 头的生成逻辑，每一步都踩中即崩——这是一场不容妥协的加密协议实战，稍有疏忽，你的消息就永远停在了网络请求头里。

Web Push 的 payload 必须加密，不加密会被浏览器拒绝

Chrome、Firefox、Edge 等主流浏览器强制要求 Web Push 消息体（payload）使用 AES-128-GCM 加密，且必须带 crypto-key 和 encryption 头。明文推送会直接失败，返回 400 Bad Request 或静默丢弃——不是服务端没发，是浏览器根本没解密入口。

加密不是可选项，是协议级硬性约束。关键点在于：加密用的密钥派生自客户端提供的 auth 和 p256dh 公钥，服务端不能自己生成或硬编码密钥。

• p256dh 是客户端椭圆曲线公钥（base64url 编码），用于 ECDH 密钥协商
• auth 是 16 字节随机 salt（同样 base64url 编码），用于 HKDF 派生对称密钥
• 最终 AES-128-GCM 密钥长度必须严格为 16 字节，IV（nonce）必须为 12 字节
• 加密后需将 IV、ciphertext、authentication tag 拼接为二进制 payload，并以 application/octet-stream 发送

Node.js 后端用 web-push 库最省事，但要注意版本和参数

web-push 是目前最成熟的 Node.js Web Push 封装库，它自动处理密钥协商、HKDF、AES-128-GCM 加密、头部构造等全部细节。但 v4+ 版本默认启用 payload 加密，v3 则默认不加密（需手动开），容易踩坑。

关键配置项：

• gcmAPIKey 已废弃，改用 VAPID —— 必须调用 setVapidDetails() 提供公钥/私钥对
• payload 参数传入字符串或 Buffer；若传字符串，库内部会 UTF-8 编码后再加密
• headers 中不能手动覆盖 content-encoding 或 encryption，否则加密流程中断
• 若要调试加密过程，可临时启用 debug: true，它会输出派生出的 content-encoding、encryption、crypto-key 头值

示例片段：

const webpush = require('web-push');
webpush.setVapidDetails(
  'mailto:admin@example.com',
  'BO_...public-key...', // base64url-encoded VAPID public key
  'N9_...private-key...' // base64url-encoded VAPID private key
);

webpush.sendNotification(subscription, 'Hello encrypted world', {
  TTL: 60,
  gcmAPIKey: undefined // 显式设为 undefined 防止旧配置干扰
});

前端获取 subscription 时必须启用 userVisibleOnly: true

如果 navigator.serviceWorker.register() 后调用 pushManager.subscribe() 时没传 { userVisibleOnly: true }，返回的 subscription 对象里会缺失 auth 和 p256dh 字段——这意味着服务端拿不到加密必需的材料，后续所有推送都会因缺少加密参数而失败。

这个限制是浏览器强制的，不是建议。即使你只想发后台静默消息（无 UI），也必须设为 true，否则订阅本身就不合法。

• 错误写法：pushManager.subscribe()（无参数）→ auth 和 p256dh 为空
• 正确写法：pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: urlBase64ToUint8Array(vapidPublicKey) })
• applicationServerKey 必须是 Uint8Array，不能是 base64 字符串；需用工具函数转换（atob + Uint8Array.from）
• Chrome 91+ 还要求 applicationServerKey 必须提供，否则抛 InvalidStateError

调试时抓包看三个 header 是否齐全且格式正确

真正决定推送能否解密的，是 HTTP 请求头，不是 payload 内容。用浏览器 DevTools 的 Network 标签或 curl -v 查看实际发出的请求，重点确认以下三项：

• content-encoding: aes128gcm —— 值必须小写，不能是 AES128GCM 或 aes-128-gcm
• encryption 头：格式为 keyid=p256dh; salt=xxx，其中 salt 是 auth 字段 base64url 解码后的原始字节再 base64 编码（注意不是原样复用 subscription.auth）
• crypto-key 头：包含 p256dh=xxx，值是 subscription.p256dh 原样 base64url 字符串，不可额外编码

常见失败现象：收到推送但通知不显示、控制台报 Failed to execute 'showNotification' on 'ServiceWorkerRegistration' —— 很可能是因为 header 格式错，导致浏览器解密失败，payload 变成乱码，JS 无法解析 JSON。

最容易被忽略的是 salt 的二次编码逻辑：subscription.auth 是 base64url，但 encryption 头里的 salt 是对它先 base64url 解码成字节，再按标准 base64 编码（含 +// 和填充 =）。这个转换必须由服务端完成，前端只管传原始 subscription 对象。

以上就是《HTML消息推送AES128GCM加密详解》的详细内容，更多关于的资料请关注golang学习网公众号！