feat(encryption): HPKE for JWE (draft-ietf-jose-hpke-encrypt, awaiting AD go-ahead)

未关闭
  • 哪里不对？
#729 0 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

维护者通常 1 天内回复

@Spomky 已经在做这个了。

开始于 2026年9月12日。

  • #740 来自 @Spomky —— 未关闭

评估

这个 Issue 还没有评估数据。

描述

Compliance feature
Context

draft-ietf-jose-hpke-encrypt (-22, July 2026) is in "Waiting for AD Go-Ahead" — the last step before the RFC Editor queue, so an RFC number is a matter of months. It brings HPKE (RFC 9180) to JWE with fourteen alg values and two header parameters:

  • Integrated encryption (HPKE does everything, no enc): HPKE-0 … HPKE-7.
  • Key encryption (HPKE wraps the CEK, enc as usual): HPKE-0-KE, -1-KE, -2-KE, -3-KE, -5-KE, -7-KE.
  • Suites: 0 DHKEM(P-256)/HKDF-SHA256/AES-128-GCM, 1 P-384/HKDF-SHA384/AES-256-GCM, 2 P-521/HKDF-SHA512/AES-256-GCM, 3 X25519/HKDF-SHA256/AES-128-GCM, 4 X25519/HKDF-SHA256/ChaCha20-Poly1305, 5 X448/HKDF-SHA512/AES-256-GCM, 6 X448/HKDF-SHA512/ChaCha20-Poly1305, 7 P-256/HKDF-SHA256/AES-256-GCM.
  • Headers: ek (base64url encapsulated key) and psk_id; alg and ek are bound into the HPKE info / AAD as the draft specifies, which is what makes the integrated mode safe against header tampering.

It is the first key-management addition to JWE since RFC 7518, and the JOSE path to post-quantum encryption (draft-ietf-jose-hpke-pq-pqt and draft-ietf-jose-pqc-kem build on it). The library has nothing HPKE-related; there is no HPKE in PHP core.

Backend: paragonie/hpke implements RFC 9180 in PHP (DHKEM P-256, P-521, X25519, ML-KEM; HKDF-SHA256/512; AES-128/256-GCM, ChaCha20-Poly1305) but has neither P-384 nor X448 KEMs at the time of writing — suites 1, 5 and 6 would be missing. To decide: depend on it and contribute the two KEMs upstream, or carry a minimal HPKE (base mode + PSK is all the draft needs) inside the library, which has all the primitives (ECDH through AbstractECDH, HKDF in ConcatKDF's neighbourhood, AES-GCM and ChaCha20 content encryption). cose-lib does not implement COSE-HPKE either, so a shared spomky-labs/hpke would serve both.

This issue is opened now so the design and the backend question are settled when the RFC lands; the implementation is not to be merged before the RFC number exists (identifiers can still change in AUTH48).

Scope
  • Integrated mode: a new Jose\Component\Encryption\Algorithm\KeyEncryption kind, since HPKE replaces both key management and content encryption — JWEBuilder / JWEDecrypter need a branch where enc is absent and the ciphertext / tag come from HPKE Seal; check how RecipientSpec and the compact serializer behave with an empty encrypted_key and no iv / tag.
  • Key-encryption mode: fits KeyEncryption as it is — HPKE Seal on the CEK, ek set on the per-recipient header, and multi-recipient JSON serialization works as for ECDH-ES+A*KW.
  • ek and psk_id known to the header machinery; psk supplied out of band to the algorithm (constructor or JWK-shaped secret, to design).
  • Recipient keys are the existing EC (P-256/384/521) and OKP (X25519 / X448 — X448 requires the OKP work of #724) JWKs; sender ephemeral key generated by the KEM.
  • Bundle registration for the fourteen aliases; docs (algorithm table, a dedicated HPKE page explaining integrated vs key-encryption and the PSK option); changelog.
Out of scope
  • Auth / AuthPSK HPKE modes (the draft uses base and PSK only).
  • Post-quantum and hybrid KEMs (draft-ietf-jose-hpke-pq-pqt, draft-ietf-jose-pqc-kem): separate issues once those drafts stabilise.
  • Merging before the RFC is published.
Acceptance criteria
  • The draft's Appendix test vectors (integrated and key-encryption, compact and JSON) decrypt and re-encrypt with the vector's ephemeral material.
  • Round-trip for the eight integrated and six key-encryption identifiers with generated keys, single and multiple recipients where the mode allows it; ChaCha20 suites gated on ext-sodium / OpenSSL availability like C20P today.
  • Tampering with alg or ek in the protected header makes decryption fail (the info / AAD binding).
  • A HPKE-* recipient in a JWE that also carries enc (integrated mode) is rejected; a HPKE-*-KE without enc is rejected.
References
  • draft-ietf-jose-hpke-encrypt-22 (identifiers, ek / psk_id, info and AAD construction, test vectors)
  • RFC 9180 (HPKE), RFC 7516 §4.1.2 (enc)
  • paragonie/hpke — https://github.com/paragonie/hpke-php
  • draft-ietf-jose-hpke-pq-pqt, draft-ietf-jose-pqc-kem (follow-ups)
主要语言
PHP
星标
954
派生
119
平均合并
48 分钟
30 天内合并 PR
17

环境准备

这个项目没有提供开发容器、Dockerfile 或贡献指南，环境需要你自己搭建：先看它的 README，通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

web-token/jwt-framework 的其他 Issue

查看 web-token/jwt-framework 的全部 Issue

相似的 Issue

更多 PHP Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。