Re: [jose] Whether implementations must understand all JOSE header fields

"Manger, James H" <> Tue, 18 December 2012 12:59 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id 8EF1F21F8842 for <>; Tue, 18 Dec 2012 04:59:32 -0800 (PST)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: 0.119
X-Spam-Status: No, score=0.119 tagged_above=-999 required=5 tests=[AWL=-0.984, BAYES_00=-2.599, HELO_EQ_AU=0.377, HOST_EQ_AU=0.327, HTML_MESSAGE=0.001, RELAY_IS_203=0.994, TRACKER_ID=2.003]
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id m8dmjsBNp3MD for <>; Tue, 18 Dec 2012 04:59:31 -0800 (PST)
Received: from ( []) by (Postfix) with ESMTP id 3FC8321F87B3 for <>; Tue, 18 Dec 2012 04:59:25 -0800 (PST)
X-IronPort-AV: E=Sophos; i="4.84,309,1355058000"; d="scan'208,217"; a="108861844"
Received: from unknown (HELO ([]) by with ESMTP; 18 Dec 2012 23:59:23 +1100
X-IronPort-AV: E=McAfee;i="5400,1158,6929"; a="102746592"
Received: from ([]) by with ESMTP; 18 Dec 2012 23:59:23 +1100
Received: from ([]) by ([]) with mapi; Tue, 18 Dec 2012 23:59:22 +1100
From: "Manger, James H" <>
To: Mike Jones <>, "" <>
Date: Tue, 18 Dec 2012 23:59:19 +1100
Thread-Topic: [jose] Whether implementations must understand all JOSE header fields
Thread-Index: Ac3aJ0LgLoD5fCkEQZSpS5iQpRZ88QC6wIZg
Message-ID: <>
References: <>
In-Reply-To: <>
Accept-Language: en-US, en-AU
Content-Language: en-US
acceptlanguage: en-US, en-AU
Content-Type: multipart/alternative; boundary="_000_255B9BB34FB7D647A506DC292726F6E115040896F0WSMSG3153Vsrv_"
MIME-Version: 1.0
Subject: Re: [jose] Whether implementations must understand all JOSE header fields
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: Javascript Object Signing and Encryption <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Tue, 18 Dec 2012 12:59:32 -0000

My comments in red.

Currently the JOSE specs contain the following language declaring that all header (and some other) fields must be understood:  “Implementations MUST understand the entire contents of the header; otherwise, the … MUST be rejected.”  There's currently an open issue about whether all header fields should be required to be understood by implementations using them or whether to relax this requirement in some circumstances.  We would like the working group to consider the following potential resolutions to the issue.

1.  Maintain the current requirement that all header fields must be understood by implementations using them.

PRO:  This is a simple rule…

It is not as simple as ignoring unknown fields, which all code will do naturally.

Are the “MUST understand or reject” rules well defined? Obviously if a totally unknown field is present the JOSE message must be rejected.

How about if a defined field is in an unexpected place, eg “zip” in a JWE header? Presumably that has to be rejected so it is not sufficient for code to check any JOSE messages against one list.

How about a JWE with an “epk” field when “alg”:”RSA-OAEP”? Presumably that also has to be rejected so checking against a static list of JWE fields is not sufficient.

Does the type or value of a field need to be checked if an implementation doesn’t need to use it? For example, does an implementation that already has a given cert (so it doesn’t need to use a “x5u” value) need to confirm that the “x5u” value is a string, or is a valid URI, or actually resolves to the same cert? Probably not. I assume it is sufficient to understand that a field can be ignored, without actually understanding its actual syntax or value is a specific message.

…designed to result in secure implementations.

Secure in what way? Is this aimed specifically at preventing new fields being ignored in case they change the semantics of existing fields?

PRO: New fields are allowed to change the semantics of existing fields because implementations not understanding the changed semantics will fail-safe due to seeing an unknown field.

(or is this a CON for encouraging dangerous extensions?)

…Representations of existing JWS & JWE objects are unchanged.

CON:  Extensibility is limited to cases where all participating parties understand new fields that are introduced.

CON: Because code can successfully process JOSE message without implementing the “MUST understand or reject” rule it is hard to have confidence that it is implemented (or implemented well).

2A.  Take an alternative approach where, by default, all fields must be understood, but where an explicit list of fields can be designated as “may be ignored if not understood”.  For instance, an “ign” (may be ignored) member could be defined whose value is an array listing the member names that may be safely ignored if not understood.  An example using this field in a JWS header is:



     "notes":"This signature need not be checked when the moon is full"


(Obviously, the "ign" field MUST NOT contain the value "ign".)

PRO:  This would enable adding non-critical header fields without breaking implementations.  It would maintain the current semantics, while allowing explicit exceptions to be made in cases where the fields are not security-critical and the structure has a meaningful interpretation without them.  Representations of existing JWS & JWE objects are unchanged.

CON:  Requires coordination of field names and may-be-ignored list, adding some implementation complexity.

2B.  Take an alternative approach where instead of one header object, there would be two header objects.  Implementations would be required to understand all fields in the first header object.  Implementations would be allowed to ignore fields in the second header object if not understood.  An example of this approach, adding the second header object after the first in a JWS, would be:








The first, third, and fourth fields are from the example JWS in the current spec. The new second field is the base64url encoded representation of the string '{"notes":"This signature need not be checked when the moon is full"}'.

PRO:  May-be-ignored fields are easily distinguishable from must-be-understood fields.

CON:  Implementations must consult/merge two sets of headers to understand the meaning/structure of the object, adding some implementation complexity.  Existing JWS & JWE object representations would become invalid.

3. Have a field that indicates the semantics of the JOSE message. For instance the field could be called “!” and defined values could be “sig”, “mac”, “enc”… for signed-with-an-asymmetric-key, MACed-with-a-shared-secret, encrypted-(AEAD)-with-shared-secret…. The definition of a value for the “!” field indicates the other fields it uses. Recipients MUST ignore any unrecognized fields. Originators adding a new field that changes the semantics of a message MUST use a new value for the “!” field.

PRO: Code will implement this rule naturally, simply by switching on the “!” field value.

PRO: It is extensible. Extra fields can be defined and deployed without requiring originators and recipients to be upgraded simultaneously.

CON: Arbitrary extra data of a originator’s choosing can be included as unknown fields in messages that recipients will accept. Though this is true even with a “MUST understand or reject” rule (eg whitespace in the JSON header, junk in a “x5u” URI fragment…).

After a discussion period, we believe that it would be useful for the chairs to make two formal consensus calls of the following kind:

FIRST POLL:  Should all header fields be critical for implementations to understand?

YES – All header fields must continue to be understood by implementations or the input must be rejected.

NO – A means of listing that specific header fields may be safely ignored should be defined.

ALTERNATIVE FIRST POLL FOR EXISTING IMPLEMENTORS: Have you implemented the “MUST understand or reject” rule? Which situations do you reject (eg “foo”; “zip” in JWS; “epk” when “alg”:”RSA-OAEP”; “jku”:<non-string>; “jku”:”<invalid URI>”; …?

ALTERNATIVE SECOND POLL: How real is the risk that future groups will deliberately design & deploy new fields that change the semantics of JOSE messages depending on whether or not the new field is understood, without realizing the security consequences?

ALTERNATIVE THIRD POLL: Is JOSE so complete and stable that extensions are unlikely to be needed?

SECOND POLL:  Should the result of the first poll be "NO", which syntax would you prefer for designating the header fields that may be ignored if not understood?

A – Define a header field that explicitly lists the fields that may be safely ignored if not understood.

B – Introduce a second header, where implementations must understand all fields in the first but they may ignore not-understood fields in the second.

                                                Thanks for considering these questions,

                                                Richard Barnes, John Bradley, Mike Jones

James Manger