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

Abierto
  • ¿Algo no está bien?
#729 0 comentarios 0 reacciones 1 asignado Ver en GitHub

Los mantenedores suelen responder en 1 día

@Spomky ya está trabajando en esto.

Desde el 12/9/2026.

  • #740 de @Spomky — abierto

Evaluación

Este issue todavía no se ha evaluado.

Descripción

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)
Lenguaje dominante
PHP
Estrellas
954
Forks
119
Merge medio
48 min
PR fusionados (30 d)
17

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de web-token/jwt-framework

Todos los issues de web-token/jwt-framework

Issues similares

Más issues de PHP

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.