Subject: [stir] Editorial comments on sections 3 and 4 of draft-ietf-stir-passport-divert-02 [was: drafts for london]

From: Christer Holmberg <[email-masked]>
Date: Tue, 6 Mar 2018 21:55:52 +0000

Hi Jon,

I see that the new version covers some of the issues that I raised previously. Thank you for that!

I did take a look at the new version (mostly focusing on Sections 3 and 4), and I have some editorial comments, mostly related to inconsistent terminology. But, there is also a couple of comments where I think we need more clarification.

(You may call some of my comments nit picking, but I personally think that fixing them would make the document easier to read)

---

Q1:

Throughout the document, you use different terminology for the claims. You at least use "claim", "array", "field".

I suggest to always use "claim", i.e., "div" claim, "dest" claim etc.

The fact that a claim might be an array is an encoding issue.

A few examples of where I identified this problem:

"occupy the "div" field in the new PASSporT."

(s/field/claim)

"...the original identifier for the called party in the "dest" array will become the "div" claim in the new PASSporT.  If the "dest" array of the original PASSporT contains multiple identifiers,..."

(s/array/claim)

"becomes the value of the "dest" array of the new PASSporT."

(s/array/claim)

---

Q2:

Throughout the document, you talk about "div" PASSporT, "div" PASSporT type, etc.

Please don't use the same name for the claim and the PASSPorT. Instead say something like "to the PASSporT carrying the "div" claim", "the diversion PASSporT", or something like that.

---

Q3:

Throughout the document, the text talks about "original PASSPorT".

Since there might be (at least in theory) multiple incoming PASSPorTs you need to define what "original" means.

---

Q4:

The text in Section 3 says:

"A PASSporT claims object containing "div""

I don't think we need to say "claims object". It is enough to just talk about PASSPorT (you do that elsewhere).

---

Q5:

The text in Section 3 says:

"These new PASSporT generated by retargeting entities MUST include the "div" PASSporT type,.."

Please explicitly indicate which header field includes the "div" type (i.e., the "ppt")

---

Q6:

The text in Section 3 says:

   "...for all PASSporTs using the "div" type the
   signature MUST be created with a credential with authority over the
   identity present in the "div" claim.  So for the example above, where
   the original "dest" is "12155551213", the signer of the new PASSporT
   object MUST have authority over that telephone number,..."

I think the text can be clarified in the following way:

   "...for all PASSporTs using the "div" type the
   signature MUST be created with a credential with authority over the
   identity present in the "div" claim, which means that the signer MUST
   have authority over the "dest" claim in the original PASSporT."

Because, I think this is a generic normative statement, not just a description of an example.
---

Q7:

The text in Section 4.1. says:

   "An authentication service only adds an Identity header field
   containing the "div" PASSporT type to an SIP request that already
   contains at least one Identity header field; it MUST NOT add a "div"
   request to an INVITE that contains no other Identity headers fields."

Is there a reason why you first say "SIP request" and then "INVITE"? Can't the "it MUST NOT add..." part be removed?

---

Q8:

In Section 4, when the new PASSPorT has been created and added to a SIP message, we need to clarify where the associated Identity header field is located in relation to other Identity header fields.

Alt A:

Identity: incoming_PASSPorT
Identity: div_PASSPorT

Alt B:

Identity: div_PASSPorT
Identity: incoming_PASSPorT

Regards,

Christer

---

From: "Peterson, Jon" <[email-masked]>
Date: Thu, 8 Mar 2018 15:52:39 +0000

Thanks for the notes Christer, this is getting down to the level of detailed review that we need.

Q1:

Throughout the document, you use different terminology for the claims. You at least use “claim”, “array”, “field”.

I suggest to always use “claim”, i.e., “div” claim, “dest” claim etc.

I do kind of like reminding people that the contents of "dest" are an array. "field" I agree isn't very helpful though. There may still be a couple times in the document where I might want to continue referring to "dest" as an array. I'll try to keep that to a minimum.

 Q2:

Throughout the document, you talk about “div” PASSporT, “div” PASSporT type, etc.

Please don’t use the same name for the claim and the PASSPorT. Instead say something like “to the PASSporT carrying the “div” claim”, “the diversion PASSporT”, or something like that.

I can do that: saying "'div' claim" and "diversion PASSporT."

Q3:

Throughout the document, the text talks about “original PASSPorT”.

Since there might be (at least in theory) multiple incoming PASSPorTs you need to define what “original” means.

Definitely the language needs to take into account that there can be multiple "original" PASSporTs. But I hesitate to just replace "original" with a synonym like "incoming." I'd like the language here to be generic enough to apply to in-band and out-of-band cases, so I don't want to define in terms like "found in the INVITE" or whatever. Terminology is tough here, I'll try to fix the language here up a bit.

 Q4:

“A PASSporT claims object containing "div"”

I don’t think we need to say “claims object”. It is enough to just talk about PASSPorT (you do that elsewhere).

I do think it is useful sometimes to distinguish between the header and the claims, but I can avoid the specific construction "claims object" if people think it is confusing. "JOSE header" and "JWT claims set" seem to be the terms used in RFC7519.

 Q5:

“These new PASSporT generated by retargeting entities MUST include the "div" PASSporT type,..”

Please explicitly indicate which header field includes the “div” type (i.e., the “ppt”)

While I don't think this is confusing in the text, no harm in saying that explicitly.

 Q6:

   “…for all PASSporTs using the "div" type the
   signature MUST be created with a credential with authority over the
   identity present in the "div" claim.  So for the example above, where
   the original "dest" is "12155551213", the signer of the new PASSporT
   object MUST have authority over that telephone number,…”

   “…for all PASSporTs using the "div" type the
   signature MUST be created with a credential with authority over the
   identity present in the "div" claim, which means that the signer MUST
   have authority over the “dest” claim in the original PASSporT.”

Agreed it is a blunder to have a normative statement in an example. I think we still do want an example and a normative statement, I'll separate them out.

Q7:

   “An authentication service only adds an Identity header field
   containing the "div" PASSporT type to an SIP request that already
   contains at least one Identity header field; it MUST NOT add a "div"
   request to an INVITE that contains no other Identity headers fields.”

Is there a reason why you first say “SIP request” and then “INVITE”? Can’t the “it MUST NOT add…” part be removed?

Agreed that "INVITE" there should be the more generic "request." The previous statement is not normative, though, so I'd hesitate to remove the normative statement entirely.

Q8:

Alt A:

Alt B:

Identity: div_PASSPorT

Hmm. Do we think that intermediaries will always preserve the order of these headers? I guess we could order them in the hopes that they will. But again, I think we should provide a means that lets verification services look at the PASSporTs associated with a request and figure out how they are related. That discussion is how we ended up with nesting in the first place. Right now we only RECOMMEND that implementations use nesting for in-band, until we get some more input on the header size question, but we need to do something here to make it clear how PASSporTs are ordered. Maybe "iat" helps? A few possibilities.

Thanks!

Jon Peterson
Neustar, Inc.

---

From: Christer Holmberg <[email-masked]>
Date: Thu, 8 Mar 2018 19:04:45 +0000

Hi Jon,

Please see inline.

>>I suggest to always use "claim", i.e., "div" claim, "dest" claim etc. 
 >>
> I do kind of like reminding people that the contents of "dest" are an array. "field" I agree isn't very helpful though. There 
> may still be a couple times in the document where I might want to continue referring to "dest" as an array. I'll try to keep
> that to a minimum.

My suggestion would be to use "dest" claim, but somewhere point out that it is an array.

---

Q2:
 
>> Please don't use the same name for the claim and the PASSPorT. Instead say something like "to the PASSporT 
>> carrying the "div" claim", "the diversion PASSporT", or something like that.
>

Sounds good :)

---

Q3:
 
> Definitely the language needs to take into account that there can be multiple "original" PASSporTs. But I hesitate to just 
> replace "original" with a synonym like "incoming." I'd like the language here to be generic enough to apply to in-band 
> and out-of-band cases, so I don't want to define in terms like "found in the INVITE" or whatever. Terminology is tough
> here, I'll try to fix the language here up a bit.

My suggestion is not to replace "original" with "incoming". The issue is that, if there are multiple incoming PASSporTs, which of them is the "original".

I do agree that we sould not talk about INVITEs etc in Section 3 (we can define the SIP specific details in Section 4).

---

 Q4:
 
> I do think it is useful sometimes to distinguish between the header and the claims, but I can avoid the specific 
> construction "claims object" if people think it is confusing. "JOSE header" and "JWT claims set" seem to be the terms used in RFC7519.

Yes. If you need to be explicit of whether you refer to the header or the claims, we can use those words.

But, in general, if are e.g., talking about a claim, you don't need to say that it is the "JWT claims set". That is defined in the base PASSporT specification.

---

> While I don't think this is confusing in the text, no harm in saying that explicitly.

Alternatively, based on Q2, you can say "new diversion PASSporT generated by the retargeting entities...". Then it is implicit that the type is "div", because that is specified elsewhere.

---

Q6:
 
>>   ".for all PASSporTs using the "div" type the
>>   object MUST have authority over that telephone number,."
>> 
>>  ".for all PASSporTs using the "div" type the
> Agreed it is a blunder to have a normative statement in an example. I think we still do want an example 
> and a normative statement, I'll separate them out.

Thanks!

---

Q7:
 
>> Is there a reason why you first say "SIP request" and then "INVITE"? Can't the "it MUST NOT add." part be removed?
>
> Agreed that "INVITE" there should be the more generic "request." The previous statement is not normative, though, so I'd hesitate 
> to remove the normative statement entirely.

Ok.

---

Q8:
 
>> In Section 4, when the new PASSPorT has been created and added to a SIP message, we need to clarify where the 
>> associated Identity header field is located in relation to other Identity header fields.
>> 
>> Alt A:
>>
> Hmm. Do we think that intermediaries will always preserve the order of these headers?
> I guess we could order them in the hopes that they will. But again, I think we should provide a means that lets verification 
> services look at the PASSporTs associated with a request and figure out how they are related. That discussion is how we ended 
> up with nesting in the first place. Right now we only RECOMMEND that implementations use nesting for in-band, until we get 
> some more input on the header size question, but we need to do something here to make it clear how PASSporTs are ordered. 
> Maybe "iat" helps? A few possibilities.

My assumption has been that the order MUST be preserved (similar to Record-Route, Route etc), but that we need to specify where new Identity header fields are placed in relation to the existing headers. Because, if we at some point come up with a use-case where the order matters, we could end up with problem. 

Regarding nesting, if there are multiple incoming Identity header fields, the text needs to be clear which of them (or all of them) are nested, and how it is done. The text currently says that the "original" PASSporT is nested, so I assume this is related to my question on which PASSporT (if multiple) "original" refers to.

Regards,

Christer