Use of Hybrid Public Key Encryption (HPKE) with JSON Object Signing and Encryption (JOSE)

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 22 December 2025.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

Hybrid Public Key Encryption (HPKE) [RFC9180] is a scheme that provides public key encryption of arbitrary-sized plaintexts given a recipient's public key.¶

This specification enables JSON Web Encryption (JWE) to leverage HPKE, bringing support for KEMs and the possibility of Post Quantum or Hybrid KEMs to JWE.¶

2. Conventions and Definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

3. Conventions and Terminology

This specification uses the following abbreviations and terms:¶

• Content Encryption Key (CEK), is defined in [RFC7517].¶

• Hybrid Public Key Encryption (HPKE) is defined in [RFC9180].¶

• pkR is the public key of the recipient, as defined in [RFC9180].¶

• skR is the private key of the recipient, as defined in [RFC9180].¶

• Key Encapsulation Mechanism (KEM), see [RFC9180].¶

• Key Derivation Function (KDF), see [RFC9180].¶

• Authenticated Encryption with Associated Data (AEAD), see [RFC9180].¶

• Additional Authenticated Data (AAD), see [RFC9180].¶

4. Overview

This specification defines two modes of use for HPKE in JWE:¶

• HPKE JWE Integrated Encryption, where HPKE is used to encrypt the plaintext.¶

• HPKE JWE Key Encryption, where HPKE is used to encrypt a content encryption key (CEK) and the CEK is subsequently used to encrypt the plaintext.¶

When "alg" is a JOSE-HPKE algorithm:¶

• If "enc" is "int", HPKE JWE Integrated Encryption is used.¶

• If "enc" is an AEAD algorithm, the recipient Key Management mode is Key Encryption.¶

The HPKE KEM, KDF, and AEAD used depend on the JOSE-HPKE algorithm used.¶

HPKE supports several modes, which are described in Table 1 of [RFC9180].¶

In JOSE-HPKE, only "mode_base" and "mode_psk" are supported. When "psk_id" JOSE Header parameter is present the mode is "mode_psk", otherwise the mode is "mode_base".¶

JWE supports different serializations, including Compact JWE Serialization as described in Section 3.1 of [RFC7516], General JWE JSON Serialization as described in Section 3.2 of [RFC7516].¶

Certain JWE features are only supported in specific serializations.¶

For example Compact JWE Serialization does not support the following:¶

• additional authenticated data¶

• multiple recipients¶

• unprotected headers¶

HPKE JWE Key Encryption can be used with "aad" but only when not expressed with Compact JWE Serialization.¶

Single recipient HPKE JWE Key Encryption with no "aad" can be expressed in Compact JWE Serialization, so long as the recipient and sender use the same HPKE Setup process as described in Section 5 of [RFC9180].¶

This specification updates the "enc" definition in Section 4.1.2 of [RFC7516] by allowing the "enc" value "int" when the "alg" value is a JOSE-HPKE algorithm. When "alg" is not a JOSE-HPKE algorithm and the "enc" value is "int", the input MUST be rejected.¶

5. Integrated Encryption

In HPKE JWE Integrated Encryption:¶

• The protected header MUST contain an "alg" that is JOSE-HPKE algorithm.¶

• The protected header MUST contain an "enc" with value "int". This is an explicit exception to requirement in Section 4.1.2 of [RFC7516] that "enc" must be an AEAD algorithm. This is appropriate, as HPKE will perform plaintext encryption.¶

• The protected header parameters "psk_id" MAY be present.¶

• The protected header parameter "ek" MUST NOT be present.¶

• There MUST be exactly one recipient.¶

• The JWE Encrypted Key MUST be encapsulated key, as defined in Section 5.1.1 of [RFC9180].¶

• The JWE Initialization Vector and JWE Authentication Tag MUST be the empty octet sequence.¶

• The JWE AAD MAY be present when using the JWE JSON Serialization.¶

• The JWE Ciphertext is the ciphertext defined in Section 5.2 of [RFC9180].¶

• The HPKE info parameter defaults to the empty string; mutually known private information MAY be used instead. The concept of mutually known private information is defined in [NIST.SP.800-56Ar3] as an input to the key derivation function.¶

• The HPKE aad parameter MUST be set to the "Additional Authenticated Data encryption parameter", as specified in Step 14 of Section 5.1 of [RFC7516].¶

• Then follow Steps 11-19 of Section 5.1 of [RFC7516] (Message Encryption).¶

When decrypting, the checks in Section 5.2 of [RFC7516], Steps 1 through 5 MUST be performed. The JWE Encrypted Key in Step 2 is the base64url-encoded encapsulated key.¶

eyJhbGciOiAiSFBLRS0wIiwgImVuYyI6ICJpbnQiLCAia2lkIjogIkc1Tl9fQ3FNdl9rSkdpZUdTRnVBdWd2bDBqclFKQ1ozeUt3Vks2c1VNNG8ifQ.BIh6I40uiBbK8-UK7nHdo3ISEfgwJ_MF3zWjQzLt00GhFF2-1VgWKHSYLXdeVeRV7AinyocYiCYmISvW0yqiDmc..Ov-llz6VUyiw8nZL0OPGLGZckLTm5UcTZFg.

6. Key Encryption

When using the JWE JSON Serialization, recipients using JOSE-HPKE can be added alongside other recipients (e.g., those using ECDH-ES+A128KW or RSA-OAEP-256), since HPKE is used to encrypt the Content Encryption Key, which is then processed as specified in JWE.¶

The encoding of the protected header remains consistent with existing JWE rules.¶

In HPKE JWE Key Encryption:¶

• The Key Management Mode is Key Encryption.¶

• When all recipients use the same HPKE algorithm to secure the Content Encryption Key, the JWE Protected Header SHOULD contain "alg". Otherwise, the JWE Protected Header (and JWE Shared Unprotected Header) MUST NOT contain "alg".¶

• JOSE Header parameter "alg" MUST be a JOSE-HPKE algorithm.¶

• JOSE Header parameter "psk_id" MAY be present.¶

• JOSE Header parameter "ek" MUST be present and contain the base64url-encoded HPKE encapsulated key.¶

• Recipient JWE Encrypted Key MUST be the ciphertext from HPKE Encryption.¶

• The HPKE info parameter defaults to the empty string; mutually known private information MAY be used instead.¶

• The HPKE AAD parameter MUST be set to the empty string.¶

• THE HPKE plaintext MUST be set to the CEK.¶

The processing of "enc", "iv", "tag", "aad", and "ciphertext" is as already defined in [RFC7516]. Implementations process these parameters as defined in [RFC7516]; no additional processing requirements are introduced by HPKE-based key encryption.¶

{
  "protected": "eyJlbmMiOiAiQTEyOEdDTSJ9",
  "ciphertext": "9AxOd65ROJY1cQ",
  "iv": "2u3NRi3CSr-x7Wuj",
  "tag": "1NKYSWVV4pw5thsq7t6m6Q",
  "recipients": [
    {
      "encrypted_key": "l9VRW1K5CA037fY2ZqVF4bDej413TaAtfjoe3k89-eI",
      "header": {
        "alg": "HPKE-0",
        "kid": "G5N__CqMv_kJGieGSFuAugvl0jrQJCZ3yKwVK6sUM4o",
        "ek": "BJl0V6KLl3HOAZbzFwiAL9eaYbFQPg7-ROmIJpluIQjNS5zultZsC4rGhGzmW1GUWG8bzJUWLQtxFF9oze0AKhU"
      }
    }
  ]
}

7. Mapping HPKE Keys to JWK for JOSE

JWKs can be used to represent JOSE-HPKE private or public keys. For the algorithms defined in this document, the valid combinations of the JWE Algorithm, "kty", and "crv" are shown in Figure 1.¶

+---------------------+-----------------+
| JWE Algorithm       | JWK |           |
|                     | kty | crv       |
+---------------------+-----+-----------+
| HPKE-0              | EC  | P-256     |
| HPKE-1              | EC  | P-384     |
| HPKE-2              | EC  | P-521     |
| HPKE-3, HPKE-4      | OKP | X25519    |
| HPKE-5, HPKE-6      | OKP | X448      |
+---------------------+-----+-----------+

When the "kty" field is "AKP" (Algorithm Key Pair [I-D.ietf-cose-dilithium]) and "alg" is a JOSE-HPKE algorithm, the public and private keys MUST be raw HPKE public and private keys (respectively) for the KEM used by HPKE.¶

{
  "kty": "OKP",
  "crv": "X25519",
  "x": "3pPHgcHYVYpOpB6ISwHdoPRB6jNgd8mM4nRyyj4H3aE",
  "d": "nWGxne0tAiV8Hk6kcy4rN0wMskjl9yND0N3Xeho9n6g",
  "kid": "recipient-key-1",
  "alg": "HPKE-3",
  "key_ops": "encrypt"
}

8. Security Considerations

This specification is based on HPKE and the security considerations of [RFC9180] are therefore applicable also to this specification.¶

HPKE assumes the sender is in possession of the public key of the recipient and HPKE JOSE makes the same assumptions. Hence, some form of public key distribution mechanism is assumed to exist but outside the scope of this document.¶

HPKE in Base mode does not offer authentication as part of the HPKE KEM.¶

HPKE relies on a source of randomness being available on the device. In Key Agreement with Key Wrapping mode, the CEK has to be randomly generated. The guidance on randomness in [RFC4086] applies.¶

9. Ciphersuite Registration

This specification registers a number of ciphersuites for use with HPKE. A ciphersuite is a group of algorithms, often sharing component algorithms such as hash functions, targeting a security level. A JOSE-HPKE algorithm makes choices for the following HPKE parameters:¶

• KEM Algorithm¶

• KDF Algorithm¶

• AEAD Algorithm¶

The "KEM", "KDF", and "AEAD" values are chosen from the IANA HPKE registry [IANA.HPKE].¶

All JOSE-HPKE algorithm identifiers registered by this specification begin with the string "HPKE-". Future JOSE-HPKE ciphersuite names registered MUST also follow this convention.¶

10. IANA Considerations

11. References

Appendix A. Keys Used in Examples

This private key and its implied public key are used the examples:¶

{
  "kty": "EC",
  "use": "enc",
  "alg": "HPKE-0",
  "kid": "G5N__CqMv_kJGieGSFuAugvl0jrQJCZ3yKwVK6sUM4o",
  "crv": "P-256",
  "x": "gixQJ0qg4Ag-6HSMaIEDL_zbDhoXavMyKlmdn__AQVE",
  "y": "ZxTgRLWaKONCL_GbZKLNPsW9EW6nBsN4AwQGEFAFFbM",
  "d": "g2DXtKapi2oN2zL_RCWX8D4bWURHCKN2-ZNGC05ZaR8"
}

Acknowledgments

This specification leverages text from [I-D.ietf-cose-hpke]. We would like to thank Matt Chanda, Ilari Liusvaara, Neil Madden, Aaron Parecki, Filip Skokan, and Sebastian Stenzel for their contributions to the specification.¶

Document History

-10¶

• Addressed WGLC review comments by Neil Madden and Sebastian Stenzel.¶

-09¶

• Corrected examples.¶

-08¶

• Use "enc":"int" for integrated encryption.¶

• Described reasons for excluding authenticated HPKE.¶

• Stated that mutually known private information MAY be used as the HPKE info value.¶

-07¶

• Clarifications¶

-06¶

• Remove auth mode and auth_kid from the specification.¶

• HPKE AAD for JOSE HPKE Key Encryption is now empty.¶

-05¶

• Removed incorrect text about HPKE algorithm names.¶

• Fixed #21: Comply with NIST SP 800-227 Recommendations for Key-Encapsulation Mechanisms.¶

• Fixed #19: Binding the Application Context.¶

• Fixed #18: Use of apu and apv in Recipient context.¶

• Added new Section 7.1 (Authentication using an Asymmetric Key).¶

• Updated Section 7.2 (Key Management) to prevent cross-protocol attacks.¶

• Updated HPKE Setup info parameter to be empty.¶

• Added details on HPKE AEAD AAD, compression and decryption for HPKE Integrated Encryption.¶

-04¶

• Fixed #8: Use short algorithm identifiers, per the JOSE naming conventions.¶

-03¶

• Added new section 7.1 to discuss Key Management.¶

• HPKE Setup info parameter is updated to carry JOSE context-specific data for both modes.¶

-02¶

• Fixed #4: HPKE Integrated Encryption "enc: dir".¶

• Updated text on the use of HPKE Setup info parameter.¶

• Added Examples in Sections 5.1, 5.2 and 6.1.¶

• Use of registered HPKE "alg" value in the recipient unprotected header for Key Encryption.¶

-01¶

• Apply feedback from call for adoption.¶

• Provide examples of auth and psk modes for JSON and Compact Serializations¶

• Simplify description of HPKE modes¶

• Adjust IANA registration requests¶

• Remove HPKE Mode from named algorithms¶

• Fix AEAD named algorithms¶

-00¶

• Created initial working group version from draft-rha-jose-hpke-encrypt-07¶

Authors' Addresses