Subject: [jose] Comments on draft-ietf-jose-json-web-key-02

From: "Jim Schaad" <[email-masked]>
Date: Sat, 19 May 2012 15:33:34 -0700

<no hat>

My apologies for introducing you to the term algorithm families.  We don't
use it in the same way and thus I think that you should generally remove it
from the text.  To me it is a very wide term and somewhat nebulous.  Thus I
think of all of the DH algorithms as being in a family - but that family
could also include the ECDH algorithm as well as DSA depending on how one is
using it.  Thus for me an algorithm family is not restricted to a specific
instance (or small set of instances) such a DH & DSA but could be as large
as all key agreement algorithms.   As such it does not really match how you
are using it in much of the text.

Slightly more detailed:

You can define an RSA key 
You can define an RSA-OAEP key

The second one has all of the fields of the first, however it may have
additional fields defined that deal specifically with RSA-OAEP.  The
difference is going to be a question of restriction of usage of the key to a
single algorithm vs allowing for all RSA algorithms.

Here are some more comments

Abstract

1.  I am not a fan of the word enumerated in the last sentence.  This word
implies to me that the list is not expandable.  I would recommend something
along the lines of "An initial set of ... can be found in ..."

2.  JSON needs to be expanded on first use

Section 1

1.  JSON needs to be expanded on first use.  (Doing it on second use should
be fine and clearer)

2.  See enumerated comment above

3.  Don't use non-goals.  The wording "The goals of this document do not
include ..."  (Minor)

4.  It is fine to tell me what documents they are used in.  I don't know
that we need to say what the fields are.  (Minor) 

Section 2

1.  The phrase "For the purpose of this document" should be removed unless
this term is used in other ways elsewhere.

Section 4

1.  In para #2 - the use of "algorithm family" is incorrect.  They members
are going to be required for the specific key being represented not to the
family - consider the case of RSA and RSA-OAEP - these are both in the same
family, but the fields required are different.

2.  Do you believe that all of the algorithm members are defined in the JWA
document - or only for some algorithms.   Text should probably say they are
defined for the algorithms defined for the algorithms in JWA.

3.  I don't believe that para #3 is enforceable by parsers as they have been
presented to me.  Please prove me wrong.

4.  Let's look at the sentence  "If present, they MUST  be understood by
implementations using them."  I believe that this is an incorrect assertion.
(Not to mention that it is totally uncheckable.)  Consider the following
situation:

Implementation A creates a JWK and files it with Implementation B.  A does
not understand the "exist-date" property.
Implementation B adds the "exist-date" property and puts it at a URL.
Implementation C pulls the JWK from the URL, understand the "exist-date"
property.
According to the MUST, the JWK cannot be used as it is not understood by all
of the implementations. 

The only entity that you can make the requirement on is the consumer.  One
assumes that the "provider" would/might understand the field or it would not
be there but it could have been added in transit and thus that is not the
case.

5.  I find the last sentence of para #4 to be unreadable.  I would start by
breaking it into two sentences and potentially move the first one into the
JWA document (that about parameters for keys).

Section 4.1

1. Do you want to point to the JWA document or to the registry for the set
of defined algorithms?

2. In para #1 I would remove the sentence starting "Specific additional..."
as this is not part of the definition of the "alg" parameter and is covered
in section 4.0

3.  The last two sentences in para #1 can be combined together.

Section 4.2

1.  Presentation suggestion - if you use a bulleted list for the values it
will be easier to see what the list of defined values is.

2.  See point #3 in section 4.1

Section 4.3

1.  Is there a requirement that the kid be unique in a JWK Set?  I think
that the answer should be called out in text either way.

2.  Is the string case sensitive?

3.  Move the sentence "When used..." to a new paragraph.  (suggestion)

Section 6.1

1. Please make things easy for IANA - create a table with the fields across
the top and the values down the table.  This will allow them to do their job
without having to go through the entire document and for us to be able to
easily validate that they got it correct.

Section 6.2

1. Please put in a registration section for the items you are registering in
Section 4 in the JWK table.  You can refer to JWA for creation of the table.

Appendix A

1.  I am not sure why this appendix is in this document.