Subject: [stir] draft-ietf-stir-passport-08

From: Jim Schaad <[email-masked]>
Date: Sat, 8 Oct 2016 11:15:45 -0700

Here is a review of the document as a whole.

* Section 4 - para 3 - The term "key values" is potentially ambiguous.  This
could refer either to the value of the key or the value the key is pointing
to.  I would suggest making this clear.

* Section 4 - para 3 - The form you are using for encoding of claims values
has two problems.  The first is that this does not match what the JSON
document says to use "\uXXXX".  The second is that as written, it is
ambiguous.  If I have the US-ASCII string of "%ABCD" then it does not need
to be percent encoded as the string is not outside of the US-ASCII range.

  * Section 4.2.1 - General - I am having a hard time with this section
because it is not highlighting the last piece of information that I think I
need to understand for this.  From what I read, I think that dest == aud in
terms of JWT - that is the target of the statement.  Orig == iss in terms of
JWT - that is the entity that issued the statement.  I don't see anything
that is telling me what the sub of the JWT is supposed to be. 

It would also be good to say why different items are being defined that
appear to be the same thing as already exist in JWT terms. (Yes, at the core
it is because the types are different.)

* Section 4.2.X - you are not telling me that these are arrays of "some
type" rather than the "some type".

 * Section 4.2.2 - You are stating that things must occur in a specific
order.  This is not "normal" JSON behavior and not all JSON serializers may
be able to support this behavior.  I think you need some justification
someplace.

* Section 5 - I am having a hard time finding the lexicographic order and
white space rules quickly.  A pointer might be reasonable.

* Section 7 - One issue that I think you need to address in the extension
section is that signaling protocols need to identify what these new items
are so that they can be picked up and placed into the PASSporT when it is
reconstructed.  The destination does not have to understand the extension,
but it does need to understand that the extension exists.

* Section 8 - You have a problem in that there are no rules in RFC 7638 for
dealing with serialization of integers.  Given that some of the fields in
the JWT are integers this needs to be addressed.  You might want to move
this justification to the top of the document so that people are prepared
for and look for this.

* Section 8 - Wording problem with saying that "dest" and "mky" need to
follow their OWN rules.  Are these really defined elsewhere or do you just
use the standard rules recursively.

* Section 9.2 - Consider using a list structure for the asterisk leading
list in this section.

* Section 10.1.1 - Encoding Considerations - This could be 7 bit as the
value is base64 encoded for normal values and would be UTF8 if you used the
full JOSE signature structure which you do not.

* General - I was really tired when I read through this and I kept getting
tripped up on prose.  I did not write down all of the items which bothered
me and now I have read it enough that it is harder for me to locate them.
However, I would request that the authors perform some method of detailed
reading to check for this.  I frequently read the text aloud to myself for
this purpose.  Alternatively, you can just wait for the copy editors.

Jim

---

From: Chris Wendt <[email-masked]>
Date: Wed, 12 Oct 2016 15:31:29 -0400

HI Jim, 

Thanks for the comprehensive review.  I am working through some of the fixes based on your comments.
Meanwhile i have the following responses inline.

-Chris

> On Oct 8, 2016, at 2:15 PM, Jim Schaad <[email-masked]> wrote:
> 

I will use the term  “claim value” which is a RFC 7519 term.  One additional question is whether we say same thing for “claim name” as well?  I suppose we allow it.

> to be percent encoded as the string is not outside of the US-ASCII range.

Could you provide a pointer to the use of “\uXXX" specifically, we had a working group discussion on this text, but if there is something existing, i haven’t been able to find it.

> it is because the types are different.)

I don’t believe the mapping of aud and iss are appropriate here.  The “orig” and “dest” claim is specifically the asserted identity, telephone number of caller and callee, but may not correspond to the issuer/signer of the JWT, e.g. service provider. 

I can explain this in the text if that is helpful.

> type" rather than the "some type”.

sorry, i’m having trouble figuring out what you mean by this

> be able to support this behavior.  I think you need some justification

I plan to move this to the compact form section, since ordering is only really needed for compact form now.

> white space rules quickly.  A pointer might be reasonable.

same answer as above.

> but it does need to understand that the extension exists.

This will be defined in the “using protocol” specification, however i can make that clearer

> this justification to the top of the document so that people are prepared

wondering if the best way to solve this is to note it and make sure that for any passport extensions that use compact form, they specify the handling integers.

> use the standard rules recursively.

will try to clarify

> * Section 9.2 - Consider using a list structure for the asterisk leading

Yep, this was just a missed formatting problem

> full JOSE signature structure which you do not.

Ok, will look at changing this.

---

From: Jim Schaad <[email-masked]>
Date: Wed, 12 Oct 2016 18:44:42 -0700

> -----Original Message-----
> From: Chris Wendt [mailto:[email-masked]]
> Sent: Wednesday, October 12, 2016 12:31 PM
> To: Jim Schaad <[email-masked]>
> Cc: [email-masked]; [email-masked]
> Subject: Re: draft-ietf-stir-passport-08
> 
> HI Jim,
> 
> > * Section 4 - para 3 - The term "key values" is potentially ambiguous.
> > This could refer either to the value of the key or the value the key
> > is pointing to.  I would suggest making this clear.
> 
> I will use the term  “claim value” which is a RFC 7519 term.  One additional
> question is whether we say same thing for “claim name” as well?  I suppose we
> allow it

As long as it is clear what is a key and what is a value for the purposes of JSON, I don't think it makes any difference.  My problem with the term was that it had both terms so yes "claim name" or "claim key" would seem to make sense.  However both the JSON document and JWT both seem to prefer "name" to "key".  I will note that JWT seems to prefer prefixing claim to both name and value. 
.
> 
> >
> > * Section 4 - para 3 - The form you are using for encoding of claims
> > values has two problems.  The first is that this does not match what
> > the JSON document says to use "\uXXXX".  The second is that as
> > written, it is ambiguous.  If I have the US-ASCII string of "%ABCD"
> > then it does not need to be percent encoded as the string is not outside of the
> US-ASCII range.
> 
> Could you provide a pointer to the use of “\uXXX" specifically, we had a working
> group discussion on this text, but if there is something existing, i haven’t been
> able to find it.

This is from the JSON document 7159 section 7 (Strings).  Thus it should be the default behavior for JSON serialization code.

> > because it is not highlighting the last piece of information that I
> > think I need to understand for this.  From what I read, I think that
> > dest == aud in terms of JWT - that is the target of the statement.
> > Orig == iss in terms of JWT - that is the entity that issued the
> > statement.  I don't see anything that is telling me what the sub of the JWT is
> supposed to be.
> >
> > It would also be good to say why different items are being defined
> > that appear to be the same thing as already exist in JWT terms. (Yes,
> > at the core it is because the types are different.)
> 
> I don’t believe the mapping of aud and iss are appropriate here.  The “orig” and
> “dest” claim is specifically the asserted identity, telephone number of caller and
> callee, but may not correspond to the issuer/signer of the JWT, e.g. service
> provider.
> 

I am more worried about the fact that when I read the document, I thought that 'orig' was associated with the entity making the claim - i.e. the service provider and not with the call originator than I am about the question of equivalence to the existing JWT claims.  

> 
> >
> > * Section 4.2.X - you are not telling me that these are arrays of
> > "some type" rather than the "some type”.
> 

I can understand some of your confusion and I got it partly wrong - I was looking at 4.2.2 not 4.2.1 when I wrote the text.

4.2.1 contains the text "The "orig" JSON object MUST only have one key value pair representing
   the asserted identity of any type (currently either "tn" or "uri") of
   the originator of the personal communications signaling." 

The above is the only place that I can see that says that "orig" is a JSON object.  Separating this into two different sentences would make it clear that 1) it is and object and 2) the object can only have one name/value pair.

In section 4.2.2 - I did not see any clear text before getting to the example about the array/object question for the "mky" name.   Looking at just the one example, I would not see that there is a distinction between having a single value and having multiple values as it is not clearly highlighted.  It might be good to break the first paragraph into multiple ones each dealing with different parts of the constructed item.  Simple language makes things easier to understand.

> > order.  This is not "normal" JSON behavior and not all JSON
> > serializers may be able to support this behavior.  I think you need
> > some justification someplace.
> 

I need to look; however, memory says that only the PASSporT compact form was allowed.  

> 
> >
> > * Section 5 - I am having a hard time finding the lexicographic order
> > and white space rules quickly.  A pointer might be reasonable.
> 
> same answer as above.
> 
> >
> > * Section 7 - One issue that I think you need to address in the
> > extension section is that signaling protocols need to identify what
> > these new items are so that they can be picked up and placed into the
> > PASSporT when it is reconstructed.  The destination does not have to
> > understand the extension, but it does need to understand that the extension
> exists.
> 
> > * Section 8 - You have a problem in that there are no rules in RFC
> > 7638 for dealing with serialization of integers.  Given that some of
> > the fields in the JWT are integers this needs to be addressed.  You
> > might want to move this justification to the top of the document so
> > that people are prepared for and look for this.
> 
> wondering if the best way to solve this is to note it and make sure that for any
> passport extensions that use compact form, they specify the handling integers.

That would be the base specification with the "iat" claim.  This is a NumericDate - that is an integer since.   Canonicalization is not a problem for JWT as the claim is transported so the form is fixed.

> 
> >
> > * Section 8 - Wording problem with saying that "dest" and "mky" need
> > to follow their OWN rules.  Are these really defined elsewhere or do
> > you just use the standard rules recursively.
> 
> will try to clarify
> 
> >
> > * General - I was really tired when I read through this and I kept
> > getting tripped up on prose.  I did not write down all of the items
> > which bothered me and now I have read it enough that it is harder for me to
> locate them.
> > However, I would request that the authors perform some method of
> > detailed reading to check for this.  I frequently read the text aloud
> > to myself for this purpose.  Alternatively, you can just wait for the copy
> editors.
> >
> > Jim
> >
> >
> >

---

From: Jim Schaad <[email-masked]>
Date: Thu, 13 Oct 2016 13:54:22 -0700

I went back to re-read the document and figure out where my confusion was on the issue of who the 'orig' and 'dest' referred to.  This is what I find.

Origination in the context of PASSporT and for a given application's use of PASSporT is the point in the network that has the authority to assert the caller identity.

The text then goes on to talk about certificates, which I made the assumption referred to the same certificate as appears in the JWT header under the ‘x5u’ name.

I think from this is it not unreasonable that I made the assumption that the ‘orig’ field referred not the caller originator but to the issuer of the PASSporT.

jim

> Thanks for the comprehensive review.  I am working through some of the fixes

> based on your comments.

> > On Oct 8, 2016, at 2:15 PM, Jim Schaad < <mailto:[email-masked]> [email-masked]> wrote:

> allow it.

> I plan to move this to the compact form section, since ordering is only really

> needed for compact form now.

> This will be defined in the “using protocol” specification, however i can make

> that clearer

> > * Section 9.2 - Consider using a list structure for the asterisk

> > leading list in this section.

> > * Section 10.1.1 - Encoding Considerations - This could be 7 bit as

> > the value is base64 encoded for normal values and would be UTF8 if you

> > used the full JOSE signature structure which you do not.

---

From: Chris Wendt <[email-masked]>
Date: Thu, 13 Oct 2016 22:29:35 -0400

Hi Jim,  Thanks for the clarifications.  Answers inline.

> On Oct 12, 2016, at 9:44 PM, Jim Schaad <[email-masked]> wrote:
> 
> 
> 

good, will also make sure this is consistent in the full document.

> This is from the JSON document 7159 section 7 (Strings).  Thus it should be the default behavior for JSON serialization code.

Ok, so i will say "Any claim name or claim values outside the US-ASCII range should follow the default JSON serialization defined in [RFC7519] Section 7."

> I am more worried about the fact that when I read the document, I thought that 'orig' was associated with the entity making the claim - i.e. the service provider and not with the call originator th…

I will review the text and see if i can make that more clear, however i think we are stuck with a concept that is a bit unintuitive by default unfortunately.

> The above is the only place that I can see that says that "orig" is a JSON object.  Separating this into two different sentences would make it clear that 1) it is and object and 2) the object can o…

Got it thanks for the clarification

> In section 4.2.2 - I did not see any clear text before getting to the example about the array/object question for the "mky" name.   Looking at just the one example, I would not see that there is a…

good, will clarify that

> I need to look; however, memory says that only the PASSporT compact form was allowed.  

No, we support both, but would be good to make that clear.

> That would be the base specification with the "iat" claim.  This is a NumericDate - that is an integer since.   Canonicalization is not a problem for JWT as the claim is transported so the form is…

Right, for “iat” i think we are good.

---

From: Chris Wendt <[email-masked]>
Date: Thu, 13 Oct 2016 22:33:24 -0400

Hi Jim,

The certificate used for the signature does represent the issuer and is indicated in the x5u.

But i think i get your confusion about what ‘orig’ represents as stated in your last message and will see if there is any more clarity i can provide.

Thanks again!

-Chris

> On Oct 13, 2016, at 4:54 PM, Jim Schaad <[email-masked]> wrote:
> 
> > From: Chris Wendt [mailto:[email-masked] <mailto:[email-masked]>]
> > To: Jim Schaad <[email-masked] <mailto:[email-masked]>>
> > Cc: [email-masked] <mailto:[email-masked]>; [email-masked] <mailto:[email-masked]>
> > > On Oct 8, 2016, at 2:15 PM, Jim Schaad <[email-masked] <mailto:[email-masked]>> wrote:
> > >