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 21 June 2025.¶

Copyright Notice

Copyright (c) 2024 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 describes 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" and "enc" are both present in a protected header and when "iv" and "tag" are empty, the mode is HPKE JWE Integrated Encryption.¶

When "enc" is present in a protected header and "alg" is absent, the mode is HPKE JWE Key Encryption when a valid HPKE "alg" value is present in the unprotected headers.¶

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

In JWE, the use of specific HPKE modes such as "mode_base" or "mode_auth_psk" is determined by the presence of the header parameters "psk_id" and "auth_kid".¶

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 }.¶

5. Integrated Encryption

In HPKE JWE Integrated Encryption:¶

• The protected header MUST contain an "alg" that starts with "HPKE".¶

• The protected header MUST contain an "enc" and it MUST be set to the value "dir". It updates Section 4.1.2 of [RFC7516] to clarify that in case where HPKE JWE Integrated Encryption is used, setting "enc" set to "dir" is appropriate, as both the derivation of the CEK and the encryption of the plaintext are fully handled within the HPKE encryption.¶

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

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

• The "encrypted_key" MUST be the base64url encoded encapsulated key as defined in Section 5.1.1 of [RFC9180].¶

• The "iv", "tag" and "aad" members MUST NOT be present.¶

• The "ciphertext" MUST be the base64url encoded ciphertext as defined in Section 5.2 of [RFC9180].¶

• The HPKE Setup info parameter MAY be used, and its values are not constrained by this specification. By default, it is empty unless apu or apv are present, in which case it will carry the JOSE context-specific data as defined in Section 4.6.2 of [RFC7518], i.e., the concatenation of AlgorithmID, PartyUInfo, and PartyVInfo. It does not include Z, keydatalen, SuppPubInfo, or SuppPrivInfo. AlgorithmID is structured as defined in Section 4.6.2 of [RFC7518] and the Data field in AlgorithmID will be set to the octets of the ASCII representation of the "enc" Header Parameter value.¶

eyJhbGciOiJIUEtFLVAyNTYtU0hBMjU2LUExMjhHQ00iLCJlbmMiOiJkaXIiLCJraWQiOiJ1cm46aWV0ZjpwYXJhbXM6b2F1dGg6andrLXRodW1icHJpbnQ6c2hhLTI1Njp2b2RIQ3FjVVdFbV83NUpWcXlhTjhaS1FVMjF3VEFSYzhkRzhuVU1jZlBVIn0.BCsvYxTHM4CO_OwQxL3lkJDdlw3UDjx2xN9MIXnbVzfTgFJmo_Es2xdH-fYs9EXfH_V53JgMWfUm7rBD_oE5efU..7_va6cnwClMsw7h7lqpm2tCrH9NkciM-g9UabdPWcOeIRmAf01NLYG7Wn8fFoohHlcGgd0nh7Jmo9nvHFi7sH6kOX7pplBnvLUoPrqeyW4TdXo_X8YThNKf9BFyWGyF6fjelbic5jSYClFaenMkTnjpHxFW1sWuiuZVmO1EOzrlNttWy.

{
  "protectedHeader": {
    "alg": "HPKE-0",
    "enc": "dir",
    "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:vodHCqcUWEm_75JVqyaN8ZKQU21wTARc8dG8nUMcfPU"
  },
  "payload": {
    "urn:example:claim": true,
    "iss": "urn:example:issuer",
    "aud": "urn:example:audience",
    "iat": 1729785491,
    "exp": 1729792691
  }
}

{
  "protected": "eyJhbGciOiJIUEtFLVAyNTYtU0hBMjU2LUExMjhHQ00iLCJlbmMiOiJkaXIiLCJraWQiOiJ1cm46aWV0ZjpwYXJhbXM6b2F1dGg6andrLXRodW1icHJpbnQ6c2hhLTI1NjpTNkFYZmRVXzZZZnp2dTBLRERKYjBzRnV3bklXUGs2TE1URXJZaFBiMzJzIiwicHNrX2lkIjoib3VyLXByZS1zaGFyZWQta2V5LWlkIiwiYXV0aF9raWQiOiJ1cm46aWV0ZjpwYXJhbXM6b2F1dGg6andrLXRodW1icHJpbnQ6c2hhLTI1NjpTNkFYZmRVXzZZZnp2dTBLRERKYjBzRnV3bklXUGs2TE1URXJZaFBiMzJzIn0",
  "encrypted_key": "BD7QVodtG-FwYASgb36zuTzUCc80aiYwS6JOOE-6_heUGyAZt-cU0818e4oYqP7ebBuW3KTM9EQA0vM5fWp6hj0",
  "ciphertext": "ZxqtYoomgVQGctnv1I_EBVI1NIeJ7qJw2iVtqwUw3fXa8FK-",
  "aad": "8J-PtOKAjeKYoO-4jyBiZXdhcmUgdGhlIGFhZCE"
}

{
  "protectedHeader": {
    "alg": "HPKE-0",
    "enc": "dir",
    "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
    "psk_id": "our-pre-shared-key-id",
    "auth_kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s"
  },
  "plaintext": "🖤 this plaintext!",
  "additionalAuthenticatedData": "🏴‍☠️ beware the aad!"
}

6. Key Encryption

HPKE based recipients can be added alongside existing ECDH-ES+A128KW or RSA-OAEP-384 recipients because HPKE is only used to encrypt the content encryption key, and because the protected header used in content encryption is passed to HPKE as Additional Authenticated Data.¶

In HPKE JWE Key Encryption:¶

• The protected header MUST NOT contain an "alg".¶

• The protected header MUST contain an "enc" that is registered in both the IANA HPKE AEAD Identifiers Registry, and the IANA JSON Web Signature and Encryption Algorithms Registry.¶

• The recipient unprotected header parameters "psk_id" and "auth_kid" MAY be present.¶

• The recipient unprotected header parameter "ek" MUST be present.¶

• The recipient unprotected header MUST contain a registered HPKE "alg" value.¶

• The "encrypted_key" MUST be the base64url encoded content encryption key as described in Step 15 in Section 5.1 of [RFC7516].¶

• The recipient "encrypted_key" is as described in Section 7.2.1 of [RFC7516].¶

• The "iv", "tag" JWE members MUST be present.¶

• The "aad" JWE member MAY be present.¶

• The "ciphertext" MUST be the base64url encoded ciphertext as described in Step 19 in Section 5.1 of [RFC7516].¶

• The HPKE Setup info parameter MAY be used, and its values are not constrained by this specification. By default, it is empty unless apu or apv are present, in which case it will carry the JOSE context-specific data as defined in Section 4.6.2 of [RFC7518], i.e., the concatenation of AlgorithmID, PartyUInfo, and PartyVInfo. It does not include Z, keydatalen, SuppPubInfo, or SuppPrivInfo. AlgorithmID is structured as defined in Section 4.6.2 of [RFC7518] and the Data field in AlgorithmID will be set to the octets of the ASCII representation of the "alg" (algorithm) Header Parameter value.¶

{
  "protected": "eyJlbmMiOiJBMTI4R0NNIn0",
  "iv": "ZL0HDvZJizA6vyTV",
  "ciphertext": "Oq26x9vppULrGNzCn2jaB_Sl-Swjv7e0AcgnhUR5AtrjEf2v6jee09WN-Ne-HIGXBgQpgJPchg0eWNmgv4Ozi5I",
  "tag": "ULnlOiJRYfCzM_r5j9sLEQ",
  "aad": "cGF1bCBhdHJlaWRlcw",
  "recipients": [
    {
      "encrypted_key": "G3HmlpOgA4H1i_RQhT44Nw7svDwUqvNR",
      "header": {
        "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:cxQC_lWt22BIjH5AWSLHCZk_f-mU3-W4Ztcu5-ZbwTk",
        "alg": "ECDH-ES+A128KW",
        "epk": {
          "kty": "EC",
          "crv": "P-256",
          "x": "JnGWSQ90hlt0H7bfcgfaw2DZE-qqv_cwA4_Dn_CkLzE",
          "y": "6jw1AC5q9-qewwBh9DK5YzUHLOogToGDSpoYAJdNo-E"
        }
      }
    },
    {
      "encrypted_key": "pn6ED0ijngCiWF8Hd_PzTyayd2OmRF7QarTVfuWj6dw",
      "header": {
        "alg": "HPKE-0",
        "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
        "psk_id": "our-pre-shared-key-id",
        "auth_kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
        "ek": "BI41YDnhTTI6jSd7T62rLwzCCt_tBqN5LFooiZ7eXJsh01O0-h-BQ6JToKX9UXDw_3ylbXTiYWmPXl2fNmr4BeQ"
      }
    }
  ]
}

{
  "plaintext": "🎵 My lungs taste the air of Time Blown past falling sands 🎵",
  "protectedHeader": {
    "enc": "A128GCM"
  },
  "unprotectedHeader": {
    "alg": "HPKE-0",
    "enc": "dir",
    "kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
    "psk_id": "our-pre-shared-key-id",
    "auth_kid": "urn:ietf:params:oauth:jwk-thumbprint:sha-256:S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
    "ek": "BI41YDnhTTI6jSd7T62rLwzCCt_tBqN5LFooiZ7eXJsh01O0-h-BQ6JToKX9UXDw_3ylbXTiYWmPXl2fNmr4BeQ"
  },
  "additionalAuthenticatedData": "paul atreides"
}

7. 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. In this case JOSE constructs like JWS and JSON Web Tokens (JWTs) can be used to add authentication. HPKE also offers modes that offer authentication.¶

HPKE relies on a source of randomness to be available on the device. In Key Agreement with Key Wrapping mode, CEK has to be randomly generated and it MUST be ensured that the guidelines in [RFC8937] for random number generations are followed.¶

8. IANA Considerations

This document adds entries to [JOSE-IANA].¶

HPKE-<KEM>-<KDF>-<AEAD>

9. References

Appendix A. Keys Used in Examples

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

{
  "kid": "S6AXfdU_6Yfzvu0KDDJb0sFuwnIWPk6LMTErYhPb32s",
  "alg": "HPKE-0",
  "kty": "EC",
  "crv": "P-256",
  "x": "wt36K06T4T4APWfGtioqDBXCvRN9evqkZjNydib9MaM",
  "y": "eupgedeE_HAmVJ62kpSt2_EOoXb6e0y2YF1JPlfr1-I",
  "d": "O3KznUTAxw-ov-9ZokwNaJ289RgP9VxQc7GJthaXzWY"
}

This pre-shared key is used in the examples:¶

{
  "kty": "oct",
  "kid": "our-pre-shared-key-id",
  "k": "anVnZW11anVnZW11Z29rb3Vub3N1cmlraXJla2FpamE"
}

Acknowledgments

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

Document History

-04¶

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

-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