HTML消息加密方法：AES128GCM详解

Web Push 消息绝非“发了就行”，而是必须严格遵循 AES-128-GCM 加密规范的硬性协议——主流浏览器（Chrome、Firefox、Edge）会直接拒绝未加密或头部不合规的推送，导致 400 错误或静默失败；其核心在于服务端必须利用客户端提供的 auth（16 字节 salt）和 p256dh（ECDH 公钥）派生出精确的 16 字节对称密钥与 12 字节 IV，并正确构造 content-encoding、encryption 和 crypto-key 三个大小写敏感、格式严苛的请求头，任何环节出错（如 salt 二次编码失误、userVisibleOnly 缺失、VAPID 配置不当）都会让加密链路断裂，最终通知无法解密显示；用 web-push 库虽可大幅简化流程，但版本差异、参数陷阱和调试细节仍需步步为营——这不是锦上添花的优化，而是 Web Push 能否真正落地的生命线。

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学习网公众号吧！