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

Đang mở
  • Có gì không ổn?
#729 0 bình luận 0 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

@Spomky đang làm issue này rồi.

Từ ngày 12/9/2026.

  • #740 của @Spomky — đang mở

Đánh giá

Issue này chưa được đánh giá.

Mô tả

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)
Ngôn ngữ chính
PHP
Star
954
Fork
119
Merge trung bình
48 phút
Pull request đã merge (30 ngày)
17

Chuẩn bị môi trường

Dự án này không cung cấp dev container, Dockerfile hay hướng dẫn đóng góp, nên bạn cần tự thiết lập môi trường: hãy bắt đầu từ README và xem hướng dẫn đóng góp lần đầu của chúng tôi để biết các bước chung.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của web-token/jwt-framework

Tất cả issue của web-token/jwt-framework

Issue tương tự

Thêm issue về PHP

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.