## This document is obsoleted

view source for contents

<!--
# JWS Multi Payload

## Abstract

Extends JWS with the concept of sending multiple distinct and ordered payloads. Payloads are delimited by tildes in compact encoding.

This enables:

1. Applications to utilize the concept of multiple payload values within JWS itself, without needing to define a separate container layer.
2. Newer algorithms to be created that process multiple payloads directly, rather than working on JWS Signing Input.
3. Existing algorithms can support this using a variation of the JWS signing input, very similar to how RFC 7797 (Unencoded Payload Option) defines a variation of the JWS signing input.

## Encoding
An individual payload is an octet string. Within a JWS, the payloads have an order.

Multiple payloads are indicated in JSON encoding via the 'payload' member being an array of b64u-string values

Multiple payloads are indicated in compact encoding by concatenating them into a single octet string value using tilde (~) as a separator.

It is legal for a payload to contain zero octets, which would result in being encoded as a zero-length string.

## "mp" Header Parameter

Indicating multiple payloads is accomplished with the "mp" header being specified with a "true" value. As this header changes the interpretation of the payload, it MUST only occur within the protected header.

## Changes to the JWS signing input

In this mode, the JWS signing input (which is an octet string) changes to:

  serialized-payload = B64E[payload]
  sequenced-payload = serialized-payload ("~" B64U[serialized-payload] )*
  JWS_signing_input = B64E[protected header] "." sequenced-payload

For algorithms defined by [rfc7518] (JWA), the JWS signing input will be used as input to the algorithm.

Other algorithms MAY support multi-payload mode directly, taking the protected header, payloads, and verification signature into the algorithm directly.

Algorithms MAY declare a default of multi-payload mode being true. Algorithms MAY define a failure condition if the protected header indicates a value of false.

By virtue of being a new algorithm which requires multi-payload support for implementation, the "mp" header is assumed to be understood by any JWS implementation that supports said algorithms. As such, the use of "crit" is not necessary to mandate an implementation understand the "mp" header when using algorithms that specify multi-payload behavior.

## Compatibility with single-payload algorithms

The JWS signing input is equivalent to the signing input of [rfc7797] (unencoded payload option) over the combined payload.

A JWS implementation with unencoded payload support but without multi-payload support can still verify the integrity of the combined payload. After checking integrity, another component could interpret the combined payload as multiple payloads by separating by tilde characters and B64U each component to retrieve the payload octets.

For this reason, when using algorithms without defined multiple payload support, it is encouraged to also specify "b64": false within the protected header, e.g.:

{
    "alg": "ES256",
    "b64": false,
    "mp": true,
    "crit": ["b64"]
}

If an application wishes to mandate interpretation of multiple payloads by a verifying JWS implementation when using algorithms that are otherwise not multi-payload aware, the "mp" protected header should be set to true and indicated as critical, and "b64" MUST be omitted, e.g.:

{
    "alg": "ES256",
    "mp": true,
    "crit": ["mp"]
}

## Interactions with "b64" header

Due to the "b64" header being used for compatibility behavior, as well as the challenges in defining "b64" behavior for individual payloads and the new defined meaning of the tilde "~" as a delimiter, an equivalent header is not defined for multi-payload usage.

## Interactions with detached content

Multi-payload JWS values support detached content. When an application wishes to use detached payloads, the JSON serialization would send no `payload` property, while the compact serialization would substitute a single empty string.

Applications using detached multi-payload content are expected to define their own requirements for transporting the payloads, and supplying them in order for input into signature verification. This includes any requirements around individual payload content encoding for transport, and decoding on receipt for verification.

The payloads are octet strings which are base64url encoded to form `serialized-payload` for the JWS signing input, if needed by the JWS algorithm. For algorithms which are multi-payload aware, the payloads are input into their verification algorithms as binary data.

## Selective Disclosure

Multi-payload aware algorithms *may* support selective disclosure. Both the signer and verifier applications must indicate which payloads are not disclosed to the algorithm during those steps. The JWS would represent those non-disclosed payloads identically to detached payloads, simply omitting them.
-->