]> Nokia

Bangalore Karnataka India kondtir@gmail.com

University of the Bundeswehr Munich

Neubiberg Bavaria 85577 Germany hannes.tschofenig@gmx.net

Nokia

London United Kingdom aritra.banerjee@nokia.com

Tradeverifyd

United States orie@or13.io

Self-Issued Consulting

United States michael_b_jones@hotmail.com https://self-issued.info/

Security JOSE Hybrid Public Key Encryption HPKE JSON Web Encryption JWE JSON Object Signing and Encryption JOSE Hybrid This specification defines how to use Hybrid Public Key Encryption (HPKE) with JSON Web Encryption (JWE). HPKE enables public key encryption of arbitrary-sized plaintexts to a recipient's public key, and provides security against adaptive chosen ciphertext attacks. This specification chooses a specific subset of the HPKE features to use with JWE. This specification updates RFC 7516 (JWE) to enable use of Integrated Encryption as a Key Management Mode. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the jose Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction Hybrid Public Key Encryption (HPKE) is a public key encryption (PKE) scheme that provides encryption of arbitrary-sized plaintexts to a recipient's public key. This specification enables JSON Web Encryption (JWE) to leverage HPKE, bringing support for HPKE encryption and KEMs to JWE, and the possibility of utilizing future HPKE algorithms.

Notational Conventions 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 when, and only when, they appear in all capitals, as shown here.

Terminology This specification uses the following abbreviations and terms:

• Content Encryption Key (CEK), Header Parameter, and JOSE Header, as defined in .
• Hybrid Public Key Encryption (HPKE), as defined in .
• pkR is the public key of the recipient, as defined in .
• skR is the private key of the recipient, as defined in .
• Key Encapsulation Mechanism (KEM), per .
• Key Derivation Function (KDF), per .
• Authenticated Encryption with Associated Data (AEAD); see and .
• Additional Authenticated Data (AAD); see and .

This specification defines the following terms:

Key Management Mode

A method of determining whether a Content Encryption Key (CEK) value is used and, if so, what CEK value to use. Each algorithm used for making these determinations uses a specific Key Management Mode. Key Management Modes employed by this specification are Key Encryption, Key Wrapping, Direct Key Agreement, Key Agreement with Key Wrapping, Direct Encryption, and Integrated Encryption. Of these, only Integrated Encryption is defined by this specification; the remaining modes are defined in and are included here because this specification replaces the Message Encryption and Message Decryption procedures of in their entirety.

Integrated Encryption

A Key Management Mode in which the plaintext is directly encrypted without the use of a Content Encryption Key (CEK). This mode corresponds to the Single-Shot API defined in , which is used in cases where applications encrypt only a single message to a recipient's public key. This mode is appropriate when there is exactly one recipient and no separate content encryption algorithm is required.

The definition of Key Management Mode above replaces the one in JWE .

Overview This specification defines the use of HPKE in JWE for two Key Management Modes:

• Key Encryption, and
• Integrated Encryption.

It specifies the Integrated Encryption Key Management Mode and registers the corresponding JWE algorithm identifiers for both modes. Distinct JWE algorithms are defined for Key Encryption and Integrated Encryption so that they are fully specified, as required by . Test vectors for all algorithms defined in this document are provided in . When the Key Management Mode is Integrated Encryption, HPKE is used to directly encrypt the plaintext, and the "enc" header parameter MUST NOT be included. This specification updates the definition of the "enc" header parameter in to require that it be omitted when Integrated Encryption is used. When the Key Management Mode is Key Encryption, HPKE is used to encrypt the Content Encryption Key (CEK). In this mode, the "enc" header parameter is used as specified in JWE . The HPKE AEAD encryption function used internally by HPKE is distinct from the JWE AEAD algorithm specified in "enc". In both Key Management Modes, the HPKE key encapsulation mechanism (KEM), key derivation function (KDF), and authenticated encryption with additional data (AEAD) encryption function utilized depend on the JWE algorithm used. HPKE supports two modes, which are described in Table 1 of . In this specification, both "mode_base" and "mode_psk" are supported for both Key Management Modes. When the "psk_id" header parameter is present, the HPKE mode is "mode_psk"; otherwise, the HPKE mode is "mode_base". JWE supports two kinds of serializations:

• the JWE Compact Serialization described in , and
• the JWE JSON Serialization described in .

Certain JWE features are only supported in specific serializations. For example, the JWE Compact Serialization does not support:

• the JWE AAD value conveyed by the "aad" member,
• multiple recipients, and
• unprotected header parameters.

Key Encryption can be used with a JWE AAD value when using the JWE JSON Serialization. Single recipient Key Encryption with no JWE AAD value can be expressed in the JWE Compact Serialization.

Encapsulated Secrets HPKE encapsulated secret is defined in . When using Integrated Encryption, the JWE Encrypted Key of the sole recipient is the HPKE encapsulated secret. When using Key Encryption, each recipient's JWE Encrypted Key is the encrypted content encryption key, and the value of header parameter "ek" is the base64url encoding of the HPKE encapsulated secret.

Integrated Encryption When using Integrated Encryption with HPKE:

• The protected header MUST contain an "alg" value that is an HPKE JWE algorithm using Integrated Encryption.
• The "enc" header parameter MUST NOT be present. This is because no separate content encryption algorithm is used in this mode.
• The protected header parameter "psk_id" MAY be present.
• The header parameter "ek" MUST NOT be present.
• There MUST be exactly one recipient.
• The JWE Encrypted Key MUST be the encapsulated secret, as defined in .
• 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 HPKE aad parameter MUST be set to the "Additional Authenticated Data encryption parameter" value specified in Step 15 of .
• The HPKE info parameter defaults to the empty octet sequence; mutually known private information (a concept also utilized in ) MAY be used instead so the application can include it during key derivation.
• The JWE Ciphertext is the ciphertext from the HPKE encryption, as defined in .

Integrated Encryption Algorithms using HPKE The following JWE algorithms using HPKE are defined for use with Integrated Encryption as the Key Management Mode: Algorithms using HPKE for Integrated Encryption

"alg"	HPKE KEM	HPKE KDF	HPKE AEAD
HPKE-0	DHKEM(P-256, HKDF-SHA256)	HKDF-SHA256	AES-128-GCM
HPKE-1	DHKEM(P-384, HKDF-SHA384)	HKDF-SHA384	AES-256-GCM
HPKE-2	DHKEM(P-521, HKDF-SHA512)	HKDF-SHA512	AES-256-GCM
HPKE-3	DHKEM(X25519, HKDF-SHA256)	HKDF-SHA256	AES-128-GCM
HPKE-4	DHKEM(X25519, HKDF-SHA256)	HKDF-SHA256	ChaCha20Poly1305
HPKE-5	DHKEM(X448, HKDF-SHA512)	HKDF-SHA512	AES-256-GCM
HPKE-6	DHKEM(X448, HKDF-SHA512)	HKDF-SHA512	ChaCha20Poly1305
HPKE-7	DHKEM(P-256, HKDF-SHA256)	HKDF-SHA256	AES-256-GCM

The HPKE KEM, KDF, and AEAD values are chosen from the IANA HPKE registry .

Key Encryption When using the JWE JSON Serialization, recipients using Key Encryption with 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 (CEK). When using Key Encryption with HPKE:

• The "alg" header parameter MUST be an HPKE JWE algorithm using Key Encryption.
• The header parameter "psk_id" MAY be present.
• The header parameter "ek" MUST be present and contain the base64url-encoded HPKE encapsulated secret.
• The HPKE aad parameter defaults to the empty octet sequence.
• The HPKE info parameter is set to the value of the "Recipient_structure" defined below.
• The HPKE plaintext MUST be set to the CEK.
• The recipient's JWE Encrypted Key is the ciphertext from the HPKE Encryption, as defined in .

Recipient_structure The "Recipient_structure" used as the value of the HPKE info parameter when performing Key Encryption with HPKE provides context information used in key derivation. To ensure compactness and interoperability, this structure is encoded in a binary format. The encoding is as follows: Where:

• ASCII("JOSE-HPKE rcpt"): A fixed ASCII string identifying the context of the structure.
• BYTE(255): A separator byte (0xFF) used to delimit fields.
• ASCII(content_encryption_alg): Identifies the content encryption algorithm with which the HPKE-encrypted Content Encryption Key (CEK) is used. Its value MUST be the "enc" (encryption algorithm) header parameter value in the JOSE Header. This field provides JWE context information to the HPKE key schedule, which ensures that the encapsulated secret is bound to the selected content encryption algorithm.
• BYTE(255): A separator byte (0xFF) used to delimit fields.
• recipient_extra_info: An octet string containing additional context information that the application includes in the key derivation. Mutually known private information (a concept also utilized in ) MAY be used in this input parameter. If no additional context information is provided, this field MUST be the empty octet sequence.

Note that Integrated Encryption does not use the "Recipient_structure" because the JWE Protected Header and JWE AAD are included in the HPKE aad value, which binds these parameters to the ciphertext.

Recipient_structure Example The "Recipient_structure" encoded in binary as specified in , and using the field values (content_encryption_alg = "A128GCM", recipient_extra_info = ""), results in the following byte sequence: The corresponding hexadecimal representation is: This value is used as the HPKE "info" parameter when performing Key Encryption with HPKE.

Key Encryption Algorithms using HPKE The following JWE algorithms using HPKE are defined for use with Key Encryption as the Key Management Mode: Algorithms using HPKE for Key Encryption

"alg"	HPKE KEM	HPKE KDF	HPKE AEAD
HPKE-0-KE	DHKEM(P-256, HKDF-SHA256)	HKDF-SHA256	AES-128-GCM
HPKE-1-KE	DHKEM(P-384, HKDF-SHA384)	HKDF-SHA384	AES-256-GCM
HPKE-2-KE	DHKEM(P-521, HKDF-SHA512)	HKDF-SHA512	AES-256-GCM
HPKE-3-KE	DHKEM(X25519, HKDF-SHA256)	HKDF-SHA256	AES-128-GCM
HPKE-5-KE	DHKEM(X448, HKDF-SHA512)	HKDF-SHA512	AES-256-GCM
HPKE-7-KE	DHKEM(P-256, HKDF-SHA256)	HKDF-SHA256	AES-256-GCM

The HPKE KEM, KDF, and AEAD values are chosen from the IANA HPKE registry .

Producing and Consuming JWEs Sections 5.1 (Message Encryption) and 5.2 (Message Decryption) of are replaced by the following sections, which add processing rules for using Integrated Encryption as the Key Management Mode.

Message Encryption The message encryption process is as follows. The order of the steps is not significant in cases where there are no dependencies between the inputs and outputs of the steps.

1. Determine the Key Management Mode employed by the algorithm used to determine the Content Encryption Key value. (This is the algorithm recorded in the "alg" (algorithm) Header Parameter of the resulting JWE.)
2. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping is employed, generate a random CEK value to use for subsequent steps unless one was already generated for a previously processed recipient, in which case, let that be the one used for subsequent steps. See for considerations on generating random values. The CEK MUST have a length equal to that required for the content encryption algorithm.
3. When Direct Key Agreement or Key Agreement with Key Wrapping is employed, use the key agreement algorithm to compute the value of the agreed upon key. When Direct Key Agreement is employed, let the CEK be the agreed upon key. When Key Agreement with Key Wrapping is employed, the agreed upon key will be used to wrap the CEK.
4. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping is employed, encrypt the CEK to the recipient and let the result be the JWE Encrypted Key.
5. When Direct Key Agreement or Direct Encryption is employed, let the JWE Encrypted Key be the empty octet sequence.
6. When Direct Encryption is employed, let the CEK be the shared symmetric key.
7. When Integrated Encryption is employed, let the JWE Encrypted Key be as specified by the Integrated Encryption algorithm.
8. Compute the encoded key value BASE64URL(JWE Encrypted Key).
9. If the JWE JSON Serialization is being used, and there are multiple recipients, repeat this process (steps 1-8) for each recipient.
10. Generate a random JWE Initialization Vector of the correct size for the content encryption algorithm (if required for the algorithm); otherwise, let the JWE Initialization Vector be the empty octet sequence.
11. Compute the encoded Initialization Vector value BASE64URL(JWE Initialization Vector).
12. If a "zip" parameter was included, compress the plaintext using the specified compression algorithm, and let M be the octet sequence representing the compressed plaintext; otherwise, let M be the octet sequence representing the plaintext.
13. Create the JSON object(s) containing the desired set of Header Parameters, which together comprise the JOSE Header: one or more of the JWE Protected Header, the JWE Shared Unprotected Header, and the JWE Per-Recipient Unprotected Header.
14. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE Protected Header)). If the JWE Protected Header is not present (which can only happen when using the JWE JSON Serialization and no "protected" member is present), let this value be the empty string.
15. Let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header). However, if a JWE AAD value is present (which can only be the case when using the JWE JSON Serialization), instead let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)).
16. If Integrated Encryption is not being employed, encrypt M using the CEK, the JWE Initialization Vector, and the Additional Authenticated Data value using the specified content encryption algorithm to create the JWE Ciphertext value and the JWE Authentication Tag (which is the Authentication Tag output from the encryption operation).
17. If Integrated Encryption is being employed, encrypt M using the specified Integrated Encryption algorithm to create the JWE Ciphertext value. Let the JWE Authentication Tag be the empty octet sequence.
18. Compute the encoded ciphertext value BASE64URL(JWE Ciphertext).
19. Compute the encoded Authentication Tag value BASE64URL(JWE Authentication Tag).
20. If a JWE AAD value is present, compute the encoded AAD value BASE64URL(JWE AAD).
21. Create the desired serialized output. The Compact Serialization of this result is the string BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag). The JWE JSON Serialization is described in .

Message Decryption The message decryption process is the reverse of the encryption process. The order of the steps is not significant in cases where there are no dependencies between the inputs and outputs of the steps. If any of these steps fail, the encrypted content cannot be validated. When there are multiple recipients, it is an application decision which of the recipients' encrypted content must successfully validate for the JWE to be accepted. In some cases, encrypted content for all recipients must successfully validate or the JWE will be considered invalid. In other cases, only the encrypted content for a single recipient needs to be successfully validated. However, in all cases, the encrypted content for at least one recipient MUST successfully validate or the JWE MUST be considered invalid.

1. Parse the JWE representation to extract the serialized values for the components of the JWE. When using the JWE Compact Serialization, these components are the base64url-encoded representations of the JWE Protected Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE Ciphertext, and the JWE Authentication Tag. When using the JWE JSON Serialization, these components also include the base64url-encoded representation of the JWE AAD, along with the unencoded JWE Shared Unprotected Header and JWE Per-Recipient Unprotected Header values. When using the JWE Compact Serialization, the JWE Protected Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE Ciphertext, and the JWE Authentication Tag are represented as base64url-encoded values in that order, with each value being separated from the next by a single period ('.') character, resulting in exactly four delimiting period characters being used. The JWE JSON Serialization is described in .
2. Base64url decode the encoded representations of the JWE Protected Header, the JWE Encrypted Key, the JWE Initialization Vector, the JWE Ciphertext, the JWE Authentication Tag, and the JWE AAD, following the restriction that no line breaks, whitespace, or other additional characters have been used.
3. Verify that the octet sequence resulting from decoding the encoded JWE Protected Header is a UTF-8-encoded representation of a completely valid JSON object conforming to ; let the JWE Protected Header be this JSON object.
4. If using the JWE Compact Serialization, let the JOSE Header be the JWE Protected Header. Otherwise, when using the JWE JSON Serialization, let the JOSE Header be the union of the members of the JWE Protected Header, the JWE Shared Unprotected Header and the corresponding JWE Per-Recipient Unprotected Header, all of which must be completely valid JSON objects. During this step, verify that the resulting JOSE Header does not contain duplicate Header Parameter names. When using the JWE JSON Serialization, this restriction includes that the same Header Parameter name also MUST NOT occur in distinct JSON object values that together comprise the JOSE Header.
5. Verify that the implementation understands and can process all fields that it is required to support, whether required by this specification, by the algorithms being used, or by the "crit" Header Parameter value, and that the values of those parameters are also understood and supported.
6. Determine the Key Management Mode employed by the algorithm specified by the "alg" (algorithm) Header Parameter.
7. If using Integrated Encryption, Direct Encryption, or Direct Key Agreement, verify that there is exactly one recipient.
8. Verify that the JWE uses a key known to the recipient.
9. When Direct Key Agreement or Key Agreement with Key Wrapping is employed, use the key agreement algorithm to compute the value of the agreed upon key. When Direct Key Agreement is employed, let the CEK be the agreed upon key. When Key Agreement with Key Wrapping is employed, the agreed upon key will be used to decrypt the JWE Encrypted Key.
10. When Key Wrapping, Key Encryption, or Key Agreement with Key Wrapping is employed, decrypt the JWE Encrypted Key to produce the CEK. The CEK MUST have a length equal to that required for the content encryption algorithm. Note that when there are multiple recipients, each recipient will only be able to decrypt JWE Encrypted Key values that were encrypted to a key in that recipient's possession. It is therefore normal to only be able to decrypt one of the per-recipient JWE Encrypted Key values to obtain the CEK value. Also, see for security considerations on mitigating timing attacks.
11. When Direct Key Agreement or Direct Encryption is employed, verify that the JWE Encrypted Key value is an empty octet sequence.
12. When Direct Encryption is employed, let the CEK be the shared symmetric key.
13. If Integrated Encryption is not being employed, record whether the CEK could be successfully determined for this recipient or not.
14. If the JWE JSON Serialization is being used and there are multiple recipients, repeat this process (steps 4-13) for each recipient contained in the representation.
15. Compute the Encoded Protected Header value BASE64URL(UTF8(JWE Protected Header)). If the JWE Protected Header is not present (which can only happen when using the JWE JSON Serialization and no "protected" member is present), let this value be the empty string.
16. Let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header). However, if a JWE AAD value is present (which can only be the case when using the JWE JSON Serialization), instead let the Additional Authenticated Data encryption parameter be ASCII(Encoded Protected Header || '.' || BASE64URL(JWE AAD)).
17. If Integrated Encryption is not being employed, decrypt the JWE Ciphertext using the CEK, the JWE Initialization Vector, the Additional Authenticated Data value, and the JWE Authentication Tag (which is the Authentication Tag input to the calculation) using the content encryption algorithm specified in the "enc" header parameter, returning the decrypted plaintext and validating the JWE Authentication Tag in the manner specified for the algorithm, rejecting the input without emitting any decrypted output if the JWE Authentication Tag is incorrect.
18. If Integrated Encryption is being employed, verify that no "enc" header parameter is present.
19. If Integrated Encryption is being employed, decrypt the JWE Ciphertext using the specified Integrated Encryption algorithm, returning the decrypted plaintext in the manner specified for the algorithm, rejecting the input without emitting any decrypted output if the decryption fails.
20. If a "zip" parameter was included, uncompress the decrypted plaintext using the specified compression algorithm.
21. If there was no recipient for which all of the decryption steps succeeded, then the JWE MUST be considered invalid. Otherwise, output the plaintext. In the JWE JSON Serialization case, also return a result to the application indicating for which of the recipients the decryption succeeded and failed.

Finally, note that it is an application decision which algorithms may be used in a given context. Even if a JWE can be successfully decrypted, unless the algorithms used in the JWE are acceptable to the application, it SHOULD consider the JWE to be invalid.

Distinguishing Between JWS and JWE Objects is updated to delete the last bullet, which says:

• The JOSE Header for a JWS can also be distinguished from the JOSE Header for a JWE by determining whether an "enc" (encryption algorithm) member exists. If the "enc" member exists, it is a JWE; otherwise, it is a JWS.

The deleted test no longer works when Integrated Encryption is used. The other methods of distinguishing between JSON Web Signature (JWS) and JSON Web Encryption (JWE) objects continue to work.

JWK Representations for JWE HPKE Keys The JSON Web Key (JWK) representations for keys used with the JWE algorithms defined in this specification are as follows. The valid combinations of the "alg", "kty", and "crv" in the JWK are shown in . JWK Types and Curves for JWE HPKE Ciphersuites

"alg" values	"kty"	"crv"
HPKE-0, HPKE-0-KE, HPKE-7, HPKE-7-KE	EC	P-256
HPKE-1, HPKE-1-KE	EC	P-384
HPKE-2, HPKE-2-KE	EC	P-521
HPKE-3, HPKE-3-KE, HPKE-4	OKP	X25519
HPKE-5, HPKE-5-KE, HPKE-6	OKP	X448

Examples of JWKs for each algorithm are provided in .

Security Considerations This specification uses HPKE, and the security considerations of are therefore applicable. HPKE assumes the sender is in possession of the public key of the recipient and HPKE JOSE makes the same assumption. Hence, some form of public key distribution mechanism is assumed to exist but is outside the scope of this document. HPKE in Base mode does not provide proof of sender origin as part of the HPKE KEM. PSK mode authenticates the sender as a holder of the pre-shared key (see ). This specification relies on a source of randomness being available on the device. When used, the CEK has to be randomly generated. Likewise, when used, the JWE Initialization Vector has to be randomly generated. In both cases, the guidance on randomness in applies.

Key Management A KEM key pair used with HPKE is intended for use with a specific mode and HPKE algorithm suite. Using the same KEM key pair with multiple modes or multiple HPKE algorithm suites in parallel is NOT RECOMMENDED. In principle, such use could be supported by the HPKE key schedule, since it takes both the suite_id variable, which encodes the full ciphersuite, and the mode byte as inputs, ensuring that cryptographically distinct keys are derived for each combination of ciphersuite and mode. However, there is no formal proof of security for this at the time of writing; see . Likewise,the same key SHOULD NOT be used with both HPKE and non-HPKE algorithms (e.g., "ECDH-ES" or "ECDH-ES+A128KW"). When using Key Encryption in a multi-recipient scenario, the security of the content is limited by the weakest algorithm used to encrypt the CEK.

JWT Best Current Practices The guidance in about encryption is also pertinent to this specification. RFC Editor Note: If draft-ietf-oauth-8725bis has been published as an RFC by the time this document is processed, please update the reference from to the published RFC for draft-ietf-oauth-8725bis.

IANA Considerations

JSON Web Signature and Encryption Algorithms The following entries are added to the IANA "JSON Web Signature and Encryption Algorithms" registry established by :

HPKE-0

• Algorithm Name: HPKE-0
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(P-256, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-128-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-1

• Algorithm Name: HPKE-1
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(P-384, HKDF-SHA384) KEM, HKDF-SHA384 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-2

• Algorithm Name: HPKE-2
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(P-521, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-3

• Algorithm Name: HPKE-3
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(X25519, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-128-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-4

• Algorithm Name: HPKE-4
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(X25519, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and ChaCha20Poly1305 AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-5

• Algorithm Name: HPKE-5
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(X448, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-6

• Algorithm Name: HPKE-6
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(X448, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and ChaCha20Poly1305 AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-7

• Algorithm Name: HPKE-7
• Algorithm Description: Integrated Encryption with HPKE using DHKEM(P-256, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-0-KE

• Algorithm Name: HPKE-0-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(P-256, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-128-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-1-KE

• Algorithm Name: HPKE-1-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(P-384, HKDF-SHA384) KEM, HKDF-SHA384 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-2-KE

• Algorithm Name: HPKE-2-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(P-521, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-3-KE

• Algorithm Name: HPKE-3-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(X25519, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-128-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-5-KE

• Algorithm Name: HPKE-5-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(X448, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

HPKE-7-KE

• Algorithm Name: HPKE-7-KE
• Algorithm Description: Key Encryption with HPKE using DHKEM(P-256, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and AES-256-GCM AEAD
• Algorithm Usage Location(s): "alg"
• JOSE Implementation Requirements: Optional
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]
• Algorithm Analysis Documents(s):

JSON Web Signature and Encryption Header Parameters The following entries are added to the IANA "JSON Web Signature and Encryption Header Parameters" registry :

ek

• Header Parameter Name: "ek"
• Header Parameter Description: A base64url-encoded encapsulated secret, as defined in
• Header Parameter Usage Location(s): JWE
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]

psk_id

• Header Parameter Name: "psk_id"
• Header Parameter Description: A base64url-encoded key identifier (kid) for the pre-shared key, as defined in
• Header Parameter Usage Location(s): JWE
• Change Controller: IETF
• Specification Document(s): of [[ this specification ]]

Summary of Updates to RFC 7516 (JWE) This specification updates JSON Web Encryption (JWE) to enable the use of Integrated Encryption. The specific updates made are as follows:

• Adds the Integrated Encryption Key Management Mode and correspondingly updates the Key Management Mode definition ().
• Updates the "enc" header parameter to be absent when Integrated Encryption is used in ().
• Replaces the Message Encryption procedure (), adding Integrated Encryption.
• Replaces the Message Decryption procedure (), adding Integrated Encryption.
• Updates the methods for distinguishing between JWS and JWE objects () because Integrated Encryption does not use the "enc" header parameter.

References Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Cisco Inria Inria This document describes a scheme for hybrid public key encryption (HPKE). This scheme provides a variant of public key encryption of arbitrary-sized plaintexts for a recipient public key. It also includes a variant that authenticates possession of a pre-shared key. HPKE works for any combination of an asymmetric Key Encapsulation Mechanism (KEM), key derivation function (KDF), and authenticated encryption with additional data (AEAD) encryption function. We provide instantiations of the scheme using widely used and efficient primitives, such as Elliptic Curve Diffie-Hellman (ECDH) key agreement, HMAC-based key derivation function (HKDF), and SHA2. JSON Web Encryption (JWE) represents encrypted content using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries defined by that specification. Related digital signature and Message Authentication Code (MAC) capabilities are described in the separate JSON Web Signature (JWS) specification. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. This specification also defines a JWK Set JSON data structure that represents a set of JWKs. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and IANA registries established by that specification. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. Randomness is a crucial ingredient for Transport Layer Security (TLS) and related security protocols. Weak or predictable "cryptographically secure" pseudorandom number generators (CSPRNGs) can be abused or exploited for malicious purposes. An initial entropy source that seeds a CSPRNG might be weak or broken as well, which can also lead to critical and systemic security problems. This document describes a way for security protocol implementations to augment their CSPRNGs using long-term private keys. This improves randomness from broken or otherwise subverted CSPRNGs. This document is a product of the Crypto Forum Research Group (CFRG) in the IRTF. Informative References This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content. JSON Web Signature (JWS) represents content secured with digital signatures or Message Authentication Codes (MACs) using JSON-based data structures. Cryptographic algorithms and identifiers for use with this specification are described in the separate JSON Web Algorithms (JWA) specification and an IANA registry defined by that specification. Related encryption capabilities are described in the separate JSON Web Encryption (JWE) specification. This specification registers cryptographic algorithms and identifiers to be used with the JSON Web Signature (JWS), JSON Web Encryption (JWE), and JSON Web Key (JWK) specifications. It defines several IANA registries for these identifiers. This specification refers to cryptographic algorithm identifiers that fully specify the cryptographic operations to be performed, including any curve, key derivation function (KDF), and hash functions, as being "fully specified". It refers to cryptographic algorithm identifiers that require additional information beyond the algorithm identifier to determine the cryptographic operations to be performed as being "polymorphic". This specification creates fully-specified algorithm identifiers for registered JSON Object Signing and Encryption (JOSE) and CBOR Object Signing and Encryption (COSE) polymorphic algorithm identifiers, enabling applications to use only fully-specified algorithm identifiers. It deprecates those polymorphic algorithm identifiers. This specification updates RFCs 7518, 8037, and 9053. It deprecates polymorphic algorithms defined by RFCs 8037 and 9053 and provides fully-specified replacements for them. It adds to the instructions to designated experts in RFCs 7518 and 9053. University of the Bundeswehr Munich Self-Issued Consulting Tradeverifyd bibital LLC Security Theory LLC This specification defines hybrid public-key encryption (HPKE) for use with CBOR Object Signing and Encryption (COSE). HPKE offers a variant of public-key encryption of arbitrary-sized plaintexts for a recipient public key. HPKE is a general encryption framework utilizing an asymmetric key encapsulation mechanism (KEM), a key derivation function (KDF), and an Authenticated Encryption with Associated Data (AEAD) algorithm. This document defines the use of HPKE with COSE. Authentication for HPKE in COSE is provided by COSE-native security mechanisms or by the pre-shared key authenticated variant of HPKE. IANA n.d. IANA n.d. National Institute of Standards and Technology

Test Vectors This appendix provides test vectors for each algorithm defined in this document. For each algorithm, a private JWK, a Flattened JWE JSON Serialization example with Additional Authenticated Data, and a JWE Compact Serialization example are provided. Long lines in the examples are folded using the single backslash strategy from . Before using a folded example as a test vector, remove the RFC 8792 header and unfold the lines according to that strategy. The complete unfolded vector set is available as examples/jose-vectors.json in the repository for this document.

HPKE-0

HPKE-0 Private JWK

HPKE-0 Flattened JWE JSON Serialization

HPKE-0 JWE Compact Serialization

HPKE-0-KE

HPKE-0-KE Private JWK

HPKE-0-KE Flattened JWE JSON Serialization

HPKE-0-KE JWE Compact Serialization

HPKE-1

HPKE-1 Private JWK

HPKE-1 Flattened JWE JSON Serialization

HPKE-1 JWE Compact Serialization

HPKE-1-KE

HPKE-1-KE Private JWK

HPKE-1-KE Flattened JWE JSON Serialization

HPKE-1-KE JWE Compact Serialization

HPKE-2

HPKE-2 Private JWK

HPKE-2 Flattened JWE JSON Serialization

HPKE-2 JWE Compact Serialization

HPKE-2-KE

HPKE-2-KE Private JWK

HPKE-2-KE Flattened JWE JSON Serialization

HPKE-2-KE JWE Compact Serialization

HPKE-3

HPKE-3 Private JWK

HPKE-3 Flattened JWE JSON Serialization

HPKE-3 JWE Compact Serialization

HPKE-3-KE

HPKE-3-KE Private JWK

HPKE-3-KE Flattened JWE JSON Serialization

HPKE-3-KE JWE Compact Serialization

HPKE-4

HPKE-4 Private JWK

HPKE-4 Flattened JWE JSON Serialization

HPKE-4 JWE Compact Serialization

HPKE-5

HPKE-5 Private JWK

HPKE-5 Flattened JWE JSON Serialization

HPKE-5 JWE Compact Serialization

HPKE-5-KE

HPKE-5-KE Private JWK

HPKE-5-KE Flattened JWE JSON Serialization

HPKE-5-KE JWE Compact Serialization

HPKE-6

HPKE-6 Private JWK

HPKE-6 Flattened JWE JSON Serialization

HPKE-6 JWE Compact Serialization

HPKE-7

HPKE-7 Private JWK

HPKE-7 Flattened JWE JSON Serialization

HPKE-7 JWE Compact Serialization

HPKE-7-KE

HPKE-7-KE Private JWK

HPKE-7-KE Flattened JWE JSON Serialization

HPKE-7-KE JWE Compact Serialization

Acknowledgments This specification leverages text from . We would like to thank Richard Barnes, Mike Bishop, Brian Campbell, Matt Chanda, Deb Cooley, David Dong, Christopher Inacio, Paul Kyzivat, Ilari Liusvaara, Neil Madden, Aaron Parecki, Filip Skokan, Sebastian Stenzel, �ric Vyncke, and Peter Yee for their contributions to the specification.

Document History -22

• Removed HPKE-4-KE and HPKE-6-KE at the request of Deb Cooley. They were:
  • HPKE-4-KE: Key Encryption with HPKE using DHKEM(X25519, HKDF-SHA256) KEM, HKDF-SHA256 KDF, and ChaCha20Poly1305 AEAD
  • HPKE-6-KE: Key Encryption with HPKE using DHKEM(X448, HKDF-SHA512) KEM, HKDF-SHA512 KDF, and ChaCha20Poly1305 AEAD

-21

• Addressed review comments by Mike Bishop and Christopher Inacio.

-20

• Added a complete set of test vectors.
• Cleaned up presentation of tables and examples.
• Corrected text referring to the IANA "JSON Web Signature and Encryption Header Parameters" registry.
• Corrected text referring to the "aad" JWE parameter.

-19

• Applied editorial improvements suggested by Peter Yee.

-18

• Rewrote Key Management guidance in Security Considerations section.

-17

• Clarified in Section 3 that only Integrated Encryption is newly defined; other Key Management Modes are from .
• Added explanation that Integrated Encryption corresponds to the Single-Shot API in .
• Renamed "Flattened JWE JSON Serialization Example" to "JWE JSON Serialization Example".
• Added note explaining HPKE-7/HPKE-7-KE pairing rationale.
• Added qualifying clause to step 9 of Message Encryption and step 13 of Message Decryption regarding multiple recipients.
• Updated authentication wording in Security Considerations to use HPKE spec terminology "proof of sender origin".
• Replaced RFC4086 with .
• Upgraded SHOULD NOT to MUST NOT for key reuse across Key Encryption and Integrated Encryption modes.
• Added RFC Editor note regarding draft-ietf-oauth-8725bis.
• Updated Algorithm Analysis field in IANA registrations to point to specific sections of .
• Moved IANA.JOSE and IANA.HPKE to informative references.

-16

• Change uses of Key Establishment Mode to Key Management Mode to align with JWE terminology.

-15

• Defined the Integrated Encryption Key Establishment Mode and updated JWE to enable its use.
• Specified distinct algorithms for use with Key Encryption and Integrated Encryption so that they are fully-specified.
• Updated the Message Encryption and Message Decryption procedures from JWE.
• Said that JWS and JWE objects can no longer be distinguished by the presence of an "enc" header parameter.
• Many editorial improvements.

-14

• Added HPKE-7.
• Update to Recipient_structure.
• Removed text related to apu and apv.
• Updated description of mutually known private information.

-13

• Removed orphan text about AKP kty field
• Fixed bug in "include-fold" syntax
• Switched reference from RFC 9180 to draft-ietf-hpke-hpke
• Editorial improvements to abstract and introduction.
• Removed Section 8.2 "Static Asymmetric Authentication in HPKE"

-12

• Added the Recipient_structure

-11

• Fix too long lines

-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