Re: [OAUTH-WG] WGLC on JSON Web Token (JWT)

Mike Jones <Michael.Jones@microsoft.com> Mon, 17 March 2014 18:04 UTC

Return-Path: <Michael.Jones@microsoft.com>
X-Original-To: oauth@ietfa.amsl.com
Delivered-To: oauth@ietfa.amsl.com
Received: from localhost (ietfa.amsl.com [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id E70E91A0449 for <oauth@ietfa.amsl.com>; Mon, 17 Mar 2014 11:04:19 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -3.901
X-Spam-Level:
X-Spam-Status: No, score=-3.901 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, GB_I_LETTER=-2, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001] autolearn=ham
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id Hr9ZgXX7F2TW for <oauth@ietfa.amsl.com>; Mon, 17 Mar 2014 11:04:14 -0700 (PDT)
Received: from na01-bn1-obe.outbound.protection.outlook.com (mail-bn1lp0140.outbound.protection.outlook.com [207.46.163.140]) by ietfa.amsl.com (Postfix) with ESMTP id 351AD1A02F2 for <oauth@ietf.org>; Mon, 17 Mar 2014 11:04:12 -0700 (PDT)
Received: from BL2PR03CA020.namprd03.prod.outlook.com (10.141.66.28) by BL2PR03MB163.namprd03.prod.outlook.com (10.255.230.147) with Microsoft SMTP Server (TLS) id 15.0.898.11; Mon, 17 Mar 2014 18:04:03 +0000
Received: from BN1AFFO11FD043.protection.gbl (2a01:111:f400:7c10::158) by BL2PR03CA020.outlook.office365.com (2a01:111:e400:c1b::28) with Microsoft SMTP Server (TLS) id 15.0.898.11 via Frontend Transport; Mon, 17 Mar 2014 18:04:03 +0000
Received: from mail.microsoft.com (131.107.125.37) by BN1AFFO11FD043.mail.protection.outlook.com (10.58.52.190) with Microsoft SMTP Server (TLS) id 15.0.898.8 via Frontend Transport; Mon, 17 Mar 2014 18:04:02 +0000
Received: from TK5EX14MBXC286.redmond.corp.microsoft.com ([169.254.1.240]) by TK5EX14HUBC103.redmond.corp.microsoft.com ([157.54.86.9]) with mapi id 14.03.0181.007; Mon, 17 Mar 2014 18:03:17 +0000
From: Mike Jones <Michael.Jones@microsoft.com>
To: "Manger, James" <James.H.Manger@team.telstra.com>, "oauth@ietf.org WG" <oauth@ietf.org>
Thread-Topic: [OAUTH-WG] WGLC on JSON Web Token (JWT)
Thread-Index: AQHOk09MPVTXxCf600aHih1/kI1D/ZmLZ98AgUVpnFCADWIk8IAIrL4w
Date: Mon, 17 Mar 2014 18:03:16 +0000
Message-ID: <4E1F6AAD24975D4BA5B16804296739439A0EEC5E@TK5EX14MBXC286.redmond.corp.microsoft.com>
References: <5202113B.1020505@gmx.net> <255B9BB34FB7D647A506DC292726F6E1152869AC01@WSMSG3153V.srv.dir.telstra.com> <4E1F6AAD24975D4BA5B16804296739439A0A9521@TK5EX14MBXC286.redmond.corp.microsoft.com> <255B9BB34FB7D647A506DC292726F6E11540251D0A@WSMSG3153V.srv.dir.telstra.com>
In-Reply-To: <255B9BB34FB7D647A506DC292726F6E11540251D0A@WSMSG3153V.srv.dir.telstra.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach:
X-MS-TNEF-Correlator:
x-originating-ip: [157.54.51.35]
Content-Type: multipart/alternative; boundary="_000_4E1F6AAD24975D4BA5B16804296739439A0EEC5ETK5EX14MBXC286r_"
MIME-Version: 1.0
X-EOPAttributedMessage: 0
X-Forefront-Antispam-Report: =?us-ascii?Q?CIP:131.107.125.37; CTRY:US; IPV:NLI; EFV:NLI; SFV:NSPM; SFS:(100?= =?us-ascii?Q?09001)(438001)(51914003)(199002)(189002)(52604005)(51704005)?= =?us-ascii?Q?(377454003)(53754006)(13464003)(15202345003)(97736001)(92726?= =?us-ascii?Q?001)(93516002)(94946001)(97336001)(87266001)(83072002)(93136?= =?us-ascii?Q?001)(16297215004)(77982001)(79102001)(74366001)(59766001)(74?= =?us-ascii?Q?876001)(74706001)(85852003)(81542001)(94316002)(86612001)(92?= =?us-ascii?Q?566001)(95416001)(97186001)(95666003)(2656002)(87936001)(193?= =?us-ascii?Q?00405004)(56816005)(90146001)(69226001)(81816001)(80976001)(?= =?us-ascii?Q?46102001)(6806004)(86362001)(77096001)(76796001)(76786001)(8?= =?us-ascii?Q?5306002)(20776003)(63696002)(85806002)(47446002)(84676001)(7?= =?us-ascii?Q?4662001)(84326002)(31966008)(76482001)(81686001)(19580395003?= =?us-ascii?Q?)(19580405001)(44976005)(74502001)(33656001)(83322001)(49866?= =?us-ascii?Q?001)(66066001)(54316002)(71186001)(55846006)(512874002)(5677?= =?us-ascii?Q?6001)(15975445006)(53806001)(54356001)(4396001)(50986001)(47?= =?us-ascii?Q?736001)(81342001)(16236675002)(47976001)(80022001)(65816001)?= =?us-ascii?Q?(579004); DIR:OUT; SFP:1101; SCL:1; SRVR:BL2PR03MB163; H:mail.mic?= =?us-ascii?Q?rosoft.com; FPR:ED3EFDE5.8CFA9345.39F3F17B.82AACA42.2091C; MLV?= =?us-ascii?Q?:sfv; PTR:InfoDomainNonexistent; A:1; MX:1; LANG:en; ?=
X-O365ENT-EOP-Header: Message processed by - O365_ENT: Allow from ranges (Engineering ONLY)
X-Forefront-PRVS: 0153A8321A
Received-SPF: Pass (: domain of microsoft.com designates 131.107.125.37 as permitted sender) receiver=; client-ip=131.107.125.37; helo=mail.microsoft.com;
X-OriginatorOrg: microsoft.onmicrosoft.com
Archived-At: http://mailarchive.ietf.org/arch/msg/oauth/OFIHPmhN7_FfdmlDx0ueX2hTgdw
Subject: Re: [OAUTH-WG] WGLC on JSON Web Token (JWT)
X-BeenThere: oauth@ietf.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: OAUTH WG <oauth.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/oauth>, <mailto:oauth-request@ietf.org?subject=unsubscribe>
List-Archive: <http://www.ietf.org/mail-archive/web/oauth/>
List-Post: <mailto:oauth@ietf.org>
List-Help: <mailto:oauth-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/oauth>, <mailto:oauth-request@ietf.org?subject=subscribe>
X-List-Received-Date: Mon, 17 Mar 2014 18:04:20 -0000

Hi James,

Per your point 1 below, actually, the JOSE docs already *do* specify that JOSE objects can be either JWSs or JWEs and say how to distinguish them – see http://tools.ietf.org/html/draft-ietf-jose-json-web-encryption-23#section-9 on Distinguishing between JWS and JWE Objects.

Per your point 2, JOSE *does* define the “cty” (content type) header parameter to enable describing the type of the payload of a JOSE object.  Nesting is simply a special case of this more general capability to describe the content type of the payload.  The JWT spec defines a specific content type value to be used to indicate that the payload is a JWT, which is used as the “cty” value in this case.  Other applications would similarly use other application-specific content types to indicate that that application’s data is the JOSE payload.

Your point about whether nesting is mandatory-to-implement is well taken.  (I don’t think that had been pointed out before.)  I can add a statement saying that it is application-dependent whether support for nesting is required or not.  (Just like encryption support is already explicitly optional, it should made clear that support for nesting is optional, unless the application specifies otherwise.)

You may not love the text about collision-resistant names, but the alternatives would be worse in practice – for instance, requiring that all non-registered names come from a single specific collision-resistant namespace, such as OIDS, URLs, URNs, GUIDs, IP addresses, etc.  Yes, there’s a theoretical possibility of a collision between a name that’s an OID with four numbers and a numeric IPv4 address representation, but is that actually a real issue?  Do you really expect people to use both numeric IPv4 addresses and OIDs in the same application context?  These specs have tried to take a pragmatic and practical approach throughout, and allowing the use of application-chosen collision-resistant names without registration is one such case.

                                                            -- Mike

From: Manger, James [mailto:James.H.Manger@team.telstra.com]
Sent: Tuesday, March 11, 2014 10:42 PM
To: Mike Jones; oauth@ietf.org WG; Hannes Tschofenig
Subject: RE: [OAUTH-WG] WGLC on JSON Web Token (JWT)

Thanks for talking the time to reply to the individual comments, Mike.


The structure of the JWT doc is still flawed. The root cause is that JWT tries to do three tasks:

1.      Describe how a JOSE message can be a JWE or a JWS.

2.      Describe how JOSE messages can nest (eg JWS in a JWE; JWE in a JWS; JWS in a JWE in a JWS in a JWE).

3.      Describe a JSON object representing a collection of claims; including iss, sub, aud, exp, nbf, iat, jti members.

#1 and #2 are not specific to JWT. They shouldn’t be specified in JWT; they certainly shouldn’t use a JWT-specific value ("cty":"JWT") to indicate when nesting is occurring; and they shouldn’t require introducing JWT-specific terminology (eg “JWT Header”).
The JWT doc has this problem because the JOSE specs don’t define a JOSE message, they only specify JWS and JWE separately. That JOSE omission has propagated up the stack to substantially complicate the JWT doc, and presumably that complication has to be repeated for every other specification of an application like JWT that want to use JOSE messages.


Curiously, for all the text about nested JOSE messages, the JWT doc still isn’t specific about what combinations MUST be supported for interoperability. I wouldn’t expect many JWT-compliant receivers to accept claims-in-a-JWS-in-a-JWE-in-another-JWE-in-another-JWS, but I cannot tell which nesting will or will not work widely.



The text about collision-resistant names is still silly since you lose the collision-resistance when you combine multiple namespaces (domain names, OIDs, etc).

--
James Manger

From: Mike Jones [mailto:Michael.Jones@microsoft.com]
Sent: Tuesday, 4 March 2014 9:22 AM
To: Manger, James; oauth@ietf.org<mailto:oauth@ietf.org> WG
Subject: RE: [OAUTH-WG] WGLC on JSON Web Token (JWT)


Thanks for taking the time to send in the comments, James.  I am sending you this to describe the changes that were made in response to your comments (mostly in -13 but also a few in -18).  See individual responses inline.



                                                            -- Mike



-----Original Message-----
From: oauth-bounces@ietf.org<mailto:oauth-bounces@ietf.org> [mailto:oauth-bounces@ietf.org] On Behalf Of Manger, James H
Sent: Thursday, August 08, 2013 7:55 AM
To: oauth@ietf.org<mailto:oauth@ietf.org> WG
Subject: Re: [OAUTH-WG] WGLC on JSON Web Token (JWT)



Comments on draft-ietf-oauth-json-web-token-11:



1. Should JWT really go to WGLC before the JOSE docs that it depends on so heavily (JWS/JWE/...)? Even if the "bytes-on-the-wire" are fairly stable, JWT repeats a lot of text from JWS/JWE some of which is likely to change. Finishing WGLC now and queuing the doc to be auto-published when JWS/JWE are published would be bad (unless the duplicate text is removed).



In practice, it seems that JWT has waited for JOSE (and I’ve kept them fully in sync).  At this point, I expect them proceed through the rest of the approval steps in parallel.



2. The JWT doc would be so much more readable if it could refer to a "JOSE message", "JOSE header", and "JOSE compact serialization"; instead of having to explicitly talk about JWS and JWE every time even when talking about aspects common to both. It would also avoid introducing "JWT Header", "Encoded JWT Header", "Nested JWT", "Plaintext JWT" etc as though these are new items, when in fact they are just additional names for JOSE items. For instance, "JWT Header" is effectively shorthand for "JWS or JWE header" but it is presented as a JWT-specific thing.



I think this really only shows up in a few places – primarily when discussing that the JWT Header is either a JWS Header or a JWE header.  Given that these are actually distinct but related data structures, making it evident that they are different is arguably a good thing.



3. The doc should not repeat definitions from JWS and JWE.



The duplication has been substantially reduced, both within the JOSE docs, and within this doc.  That being said, there’s a stylistic tension between saying things in exactly one place and making each document easier to read without constantly having to flip back and forth between them.  In this case, I believe that the small amount of duplication aids developers who might not recursively read everything referenced in full detail.



For instance, the whole first paragraph of section 5 "JWT Header" (JSON object; describes crypto ops; unique names; reject duplicates or use last) is an almost identical copy of paragraphs from JWS and JWE. The duplication (often triplication) adds confusion (eg what is the difference between a JWT Header and JWS Header?) and gets subtly out of sync (eg "cty" either "declares structural information about the JWT" or "declares the type of the secured/encrypted content (the payload/Plaintext) in an application-specific manner").



The description of JWT’s use of “cty” is not out of sync – it is intentionally more specific than the fully general, application-independent descriptions in JWS and JWE.  In this case, JWT is the application of JWS and JWE, and needs to specify its requirements about how it uses this header parameter.



Other examples of unnecessarily duplicated text include: section 7 steps 3 & 4 (creating) and steps 1-8 (validating); section 7.1 text about comparing "alg" values; parts of the last 2 paragraphs of section 3 "JWT overview"; 1st and 3rd paragraphs of section 5.2 "cty"; 1st, 2nd, and 4th sentence of section 5.1 "typ".



Step 4 of creation was removed because it truly was a duplicate.  (3 is more specific than the corresponding JWS and JWE steps, and so was not removed.)



The validating steps are necessary because JWT adds two things beyond JWS and JWE:  First, the contents can be either a JWS or JWE, and so there’s logic described for the slightly different actions taken in the two cases.  Second, the JWT can be nested, so the logic for nesting and detecting nested JWTs is defined.  It *does* just rely on JWS and JWE for the creation and verification aspects of the JWS and JWE aspects of JWTs.



Both “typ” and “cty” were reworked when their values where changed to MIME types, reducing duplication.



4. Hardly anyone pronounces JWT as "jot" -- it is usually spelt out -- so drop the sentence in the abstract suggesting the "jot" pronunciation.



Your experience may vary, but in in-person conversations, it’s usually pronounced “jot” in my experience.  (It’s a lot easier to say than “J W T” or “JSON Web Token” and people tend to like short names to say.)



5. Collision Resistant Namespace (section 2 "Terminology") mentions domain names, OIDs, and UUIDs as examples, but fails to mention URIs, which is a likely choice. Domain names will start colliding with "reserved" names soon with all the new top-level domains. Should UUIDs use a "urn:uuid:" prefix, or "uuid:", or no prefix? Should UUIDs only use lower-case hex digits (otherwise duplicate UUIDs will look like distinct JSON names)? Should an OID be "2.5.4.3" or "oid:2.5.4.3" or "URN:OID:2.5.4.3" or "commonName" or "cn"? Collision resistant namespaces lose collision-resistance when you combine namespaces as is done here.



As you suggested, domain names are now the first example mentioned.  This was also rewritten with input from Jim Schaad.



Could the reserved/public/private mess be simplified by saying (at the end of section 4 "JWT Claims"):



  A claim name can be any string. Using URIs as claim names is one

  way to ensure claim names are unambiguous. Claim names that are

  not URIs SHOULD be registered in the IANA Claims registry [section 9.1]



Then drop the last paragraph of section 4 "JWT claims" that starts "there are three classes of JT Claim Names"; drop section 4.2 "Public claim names"; drop section 4.3 "Private claim names"; drop the "collision resistant namespace" term.



Calling out that there are three distinct classes of names has been valuable in helping developers think about how to use claim names, in practice.  In particular, it lets us describe the benefits and drawbacks of each, helping developers and deployers make reasonable choices for their application contexts.



At Jim Schaad’s suggestion, “public” was changed to “registered” and the description changed to talk about this class of names being in the IANA registry.



6. The docs says including a "typ" field is OPTIONAL. Even when present "typ" can have any value since the two suggestions in the doc ("JWT" or "urn:ietf:params:oauth:token-type:jwt") are only RECOMMENDED. Given this, there doesn't seem to be anything a JWT recipient can usefully do with "typ". If it tries to use "typ" it will just be incompatible with compliant JWT senders that either omit "typ" or use another value. It would be better to drop section 5.1 "Type Header Parameter" entirely -- leaving any "typ" value definitions to profiles that actually define processing for such values.



The description has been reworked to mostly just refer to the JWS and JWE definitions.  The URN usage was removed when “typ” and “cty” values were made MIME type values.



7. The doc redefines the "cty" header parameter, which is already defined in JWS and JWE (slightly differently in all 3 cases - argh). JWT uses "cty" to indicate nested JOSE messages, which should be a JOSE feature as it is not specific to JWT (hence "cty":"jwt" is a poor choice).



The description has been reworked to mostly just refer to the JWS and JWE definitions.  “cty” is not redefined; it’s use by JWT is specified.



8. [Editorial] "JWA signing algorithm" and "JWA encryption algorithms" are the wrong phrases. These are JWS signing algs and JWE encryption algs that happen to be specified in JWA.



The phrases "JWA signing algorithms" and "JWA encryption algorithms" were removed.



9. Including a short description for each claim name in the registry would be useful. Just a 3-letter abbreviation is not helpful enough. Eg add a Claim description field:

  Claim name: "nbf"

  Claim description: not before

  Change controller: IETF

  Specification document: section 4.1.5. of [[ this doc ]]



This was done – both here and in the JOSE documents.  Thanks for the useful suggestion.







--

James Manger



> ----------

> Sent: Wednesday, 7 August 2013 7:20 PM

> Subject: [OAUTH-WG] WGLC on JSON Web Token (JWT)

>

> Hi all,

>

> this is a working group last call for the JSON Web Token (JWT).

>

> Here is the document:

> http://tools.ietf.org/html/draft-ietf-oauth-json-web-token-11

>

> Please send you comments to the OAuth mailing list by August 21, 2013.

>

> Ciao

> Hannes & Derek



_______________________________________________

OAuth mailing list

OAuth@ietf.org<mailto:OAuth@ietf.org>

https://www.ietf.org/mailman/listinfo/oauth