[stir] AD Review: draft-ietf-stir-rph-02

[Adam Roach <[e-mail]>]

I'm doing my AD review of draft-ietf-stir-rph-02. Thanks to everyone who 
has worked on this document, and the authors and chairs in particular.

The technical content here looks generally good to me. I'd like to see a 
few issues addressed before IETF LC. In short sumary:

  * The validation section needs to add a discussion of how to treat
    calls when the priority values in "rph" passports and SIP
    "Resource-Priority" header fields aren't 100% identical.
  * The examples need some adjustment.
  * There is a minor point of ambiguity in the Security Section, but
    this should be easy to fix, as long as the WG knows what was intended.
  * The IANA actions need a little bit of adjustment.
  * There are a number of minor editorial issues to be cleaned up.

Detailed comments on these points are inline in the document below. I've 
removed some portions of the document on which I have no comments.


>
> Abstract
>
>    This document extends the STIR PASSporT specification to allow the


"...the Secure Telephone Identity Revisited (STIR) Personal Assertion 
Token (PASSporT) specification defined in RFC 8122..."

(See <https://www.rfc-editor.org/materials/abbrev.expansion.txt> for 
guidance on abbreviations)


>    inclusion of cryptographically-signed assertions of authorization for
>    the values populated in the SIP 'Resource-Priority' header field,
>    which is used for communications resource prioritization.
>
> ...
>
> 1.  Introduction
>
>    PASSporT [I-D.ietf-stir-passport] is a token format based on JWT
>    [RFC7519] for conveying cryptographically-signed information about
>    the identities involved in personal communications; it is used with
>    STIR [I-D.ietf-stir-rfc4474bis] to convey a signed assertion of the
>    identity of the participants in real-time communications established
>    via a protocol like SIP.  This specification extends PASSporT to


"...like SIP [RFC3261]..."

(We want to cite SIP the first time it is mentioned)


>    allow cryptographic-signing of the SIP 'Resource-Priority' header
>    field defined in [RFC4412].
>
>    [RFC4412] defines the SIP 'Resource-Priority' header field for
>    communications Resource Priority.  As specified in [RFC4412], the
>    'Resource-Priority' header field may be used by SIP user agents
>    [RFC3261], including, Public Switched Telephone Network (PSTN)


"...including Public Switched..."

(remove the comma)


>    gateways and terminals, and SIP proxy servers to influence


"...and by SIP proxy servers, to influence..."

(add "by" and comma)


>    prioritization afforded to communication sessions,including PSTN

"...sessions, including..."

(space after comma)


>    calls.  However, the SIP 'Resource-Priority' header field could be
>    spoofed and abused by unauthorized entities.
>
>    The STIR architecture [RFC7340]assumes that an authority on the


"...STIR architecture [RFC7340] assumes..."

(space before "assumes")


>    originating side of a call provides a cryptographic assurance of the
>    validity of the calling party number in order to prevent
>    impersonation attacks.  The STIR architecture allows extension that


"...allows extensions..."


>    can be utilized by authorities supporting real-time communication
>    services using the 'Resource-Priority' header field to
>    cryptographically sign the SIP 'Resource-Priority' header field and
>    convey assertion of the authorization for 'Resource-Priority'.  For
>    example, the authority on the originating side verifying the
>    authorization of a particular communication for Resource-Priority can


Single quotes around 'Resource-Priority'.


>    use a PASSPorT claim to cryptographically-sign the SIP 'Resource-


"...cryptographically sign..."


>    Priority' header field and convey an assertion of the authorization
>    for 'Resource-Priority'.  This will allow a receiving entity
>    (including entities located in different network domains/boundaries)
>    to verify the validity of assertions authorizing Resource-Priority.


Single quotes around 'Resource-Priority'.


>    Cryptographically-signed SIP 'Resource-Priority' headers will allow a


"...cryptographically signed SIP 'Resource-Priority' header fields..."

(remove hyphen, and replace "headers" with "header fields")


>    receiving entity to verify and act on the information with confidence
>    that the information have not been spoofed or compromised.


"...has not been spoofed or compromised."


>
>    This specification documents an optional extension to PASSporT and
>    the associated STIR mechanisms to provide a function to sign the SIP
>    'Resource-Priority' header field.  This PASSporT object is used to
>    provide attestation of a calling user authorization for priority
>    communications.  This is necessary in addition to the PASSporT object
>    that is used for calling user telephone number attestation.  How the
>    optional extension to PASSporT is used for real-time communications
>    supported using SIP 'Resource-Priority' header field is defined in
>    other documents and is outside the scope of this document.


I assume these other documents are under development? If so, they should 
be cited here.


>
> 2.  Terminology
>
>    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
>    document are to be interpreted as described in RFC 2119 [RFC2119].


This document has several non-normative uses of "must", "should," and 
"may," and so it needs to use the RFC8174 boilerplate instead of the 
RFC2119 boilerplate.


>
> 3.  PASSporT 'rph' Claim
>
>    This specification defines a new JSON Web Token claim for "rph",
>    which provides an assertion for information in SIP 'Resource-
>    Priority'header.


"...Priority' header field."

(space after closing quotation mark, "header field" instead of "header")


>
>    The creator of a PASSporT object adds a "ppt" value of "rph" to the
>    header of a PASSporT object, in which case the PASSporT claims MUST
>    contain a "rph" claim, and any entities verifying the PASSporT object
>    will be required to understand the "ppt" extension in order to
>    process the PASSporT in question.  A PASSPorT header with the "ppt"
>    included will look as follows:
>
>    {  "typ":"passport",
>      "ppt":"rph",
>      "alg":"ES256",
>      "x5u":"https://www.example.org/cert.cer"}


Ideally, this would be either pretty-printed or canonicalized. Since 
it's too long to fit on a line in canonical form, I propose:

{
   "typ":"passport",
   "ppt":"rph",
   "alg":"ES256",
   "x5u":"https://www.example.org/cert.cer"
}


>
>    The "rph" claim will provide an assertion of authorization,"auth",


"...authorization, "auth", ..."

(space between comma and opening quotation mark)


>    for information in the SIP "Resource-Priority" header field (i.e.,
>    Resource-Priority: namespace "." r-priority) based on [RFC4412].


The use of the string 'namespace "." r-priority' here and elsewhere in 
the document has a detrimental impact on readability. I strongly suggest 
replacing it with "r-value" (the name of this production in RFC4412) 
everywhere.


>    Specifically, the "rph" claim includes assertion of the priority-
>    level of the user to be used for a given communication session.  The
>    value of the "rph" claim is an array containing one or more of JSON
>    objects for the content of the SIP 'Resource-Priority' header that is
>    being asserted of which one of the "rph" object, is mandatory.


This last sentence is very hard to parse; and (based on the example) the 
value is intended to be a JSON Object (curly braces) rather than a JSON 
Array (square braces). I suggest: 'The value of the "rph" claim is an 
Object with one or more keys. Each key is associated with a JSON Array. 
These arrays contain Strings that correspond to the r-values indicated 
in the SIP "Resource-Priority" header field.' (note: "header field", not 
"header")


>
>    The following is an example "rph" claim for a SIP "Resource-Priority"
>    header field with a "namespace "." r-priority" value of "ets.0" and
>    with a "namespace "." r-priority" value of "wps.0".
>
>     { "orig":{"tn":"12155551212"}
>      "dest":{["tn":"12125551213"]},
>      "iat":1443208345,
>      "rph":{"auth":["ets.0","wps.0"]}


As above, I recommend pretty-printing this. It's also missing a comma 
after the "orig" value, and the top-level structure is missing a closing 
brace. The value for "iat" needs to be enclosed in quotes.

The NANPA has allocated NPA55501xx for example use, not NPA555xxxx, much 
of which remains assignable (cf 
<https://www.nationalnanpa.com/pdf/NRUF/ATIS-0300115.pdf>).

Putting all this together, I believe what you want is:

{
   "orig":{"tn":"12155550112"},
   "dest":{["tn":"12125550113"]},
   "iat":"1443208345",
   "rph":{"auth":["ets.0","wps.0"]}
}


>
>    After the header and claims PASSporT objects have been constructed,
>    their signature is generated normally per the guidance in
>    [I-D.ietf-stir-passport] using the full form of PASSPorT.  The
>    credentials (e.g., authority responsible for authorizing Resource-
>    Priority) used to create the signature must have authority over the
>    "rph" claim and there is only one authority per claim.  The authority
>    MUST use its credentials (i.e., CERT) associated with the specific
>    service supported by the SIP namespace in the claim.
>
> 4.  'rph' in SIP
>
>    This section specifies SIP-specific usage for the "rph" claim in
>    PASSporT.
>
> 4.1.  Authentication Service Behavior
>
>    The Authentication Service will create the "rph" claim using the
>    values discussed in section 3 based on [RFC4412]. The construction
>    of "rph" claim follows the steps described in Section 4 of
>    [I-D.ietf-stir-rfc4474bis].
>
>    The resulting Identity header for "rph" might look as follows:


"...header field..."


>
> "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleUowZVhBaU9pSnd
> ZWE56Y0c5eWRDSXNEUW9pY0hCMElqb2ljbkJvSWl3TkNpSmhiR2NpT2lKRlV6STFO
> aUlzRFFvaWVEVjFJanBvZEhSd2N6b3ZMM2QzZHk1bGVHRnRjR3hsTG1OdmJTOWpaW
> EowTG1ObGNuME5DZzBLIHx84oCZLuKAmXx8IGV5QWliM0pwWnlJNmV5SjBiaUk2SW
> pFeU1UVTFOVFV4TWpFeUluME5DaUprWlhOMElqcDdXeUowYmlJNklqRXlNVEkxTlR
> VeE1qRXpJbDE5TEEwS0ltbGhkQ0k2TVRRME16SXdPRE0wTlN3TkNpSnljR2dpT25z
> aVlYVjBhQ0k2V3lKbGRITXVNQ0lzSW5kd2N5NHdJbDE5RFFvPSJ9.s37S6VC8HM6D
> l6YzJeQDsrZcwJ0lizxhUrA7f_98oWBHvo-cl-n8MIhoCr18vYYFy3blXvs3fslM_
>    oos2P2Dyw"; info= "https://www.example.org/cert.cer";alg=ES256;
>    ppt="rph"


This example has a number of issues:

  * In the Identity header field, the signed-identity-digest shouldn't
    be quoted.
  * In the Identity header field, info is enclosed in <> rather than "".
  * In the Identity header field, ppt is a token rather than a quoted
    string.
  * The signed-identity-digest header needs to indicate a "typ" of
    "passport" rather than JWT, and it needs to include both a "ppt" and
    "x5u" field.
  * The signed-identity-digest body should contain only the passport
    claim rather than a JSON object that itself contains a
    base64-encoded JWS header concatenated with a claim.
  * I believe that, even when the body is included, values in the header
    and body need to be be canonicalized (i.e., all on one line, no
    spaces, in alphabetical order, etc.)

I would also recommend following the convention of indicating that 
line-wraps are only for readability, and including the header field name 
in the example. Putting all this together, I believe what you want is:

    For example, a Identity header field for "rph" might look
    as follows (backslashes shown for line folding only):

    Identity: eyJhbGciOiJFUzI1NiIsInBwdCI6InJwaCIsInR5cCI6InBhc3Nwb3J0I \
iwieDV1IjoiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20vY2VydC5jZXIifQo.eyJkZXN0 \
Ijp7WyJ0biI6IjEyMTI1NTUwMTEzIl19LCJpYXQiOiIxNDQzMjA4MzQ1Iiwib3JpZyI \
6eyJ0biI6IjEyMTU1NTUwMTEyIn0sInJwaCI6eyJhdXRoIjpbImV0cy4wIiwid3BzLj \
AiXX19Cg.s37S6VC8HM6Dl6YzJeQDsrZcwJ0lizxhUrA7f_98oWBHvo-cl-n8MIhoCr \
18vYYFy3blXvs3fslM_oos2P2Dyw;info=<https://www.example.org/cert.cer \
    >;alg=ES256;ppt=rph

(Note: this example assumes the calling and called party numbers in the 
previous example are changed to 12155550112 and 12155550113, respectively)


>
>    A SIP authentication service typically will derive the value of "rph"
>    from the 'Resource-Priority' header field based on policy associated
>    with service specific use of the "namespace "." r-priority" values
>    based on [RFC4412].  The authentication service derives the value of
>    the PASSPorT claim by verifying the authorization for Resource-
>    Priority (i.e., verifying a calling user privilege for Resource-
>    Priority based on its identity) which might be derived from customer
>    profile data or from access to external services.
>
>    [RFC4412] allows multiple "namespace "." r-priority" pairs, either in
>    a single SIP Resource-Priority header or across multiple SIP


Single quotes around 'Resource-Priority'.

"...header field..."


>    Resource-Priority headers. However, it is not necessary to sign all


Single quotes around 'Resource-Priority'.

"...header fields..."


>    content of a SIP Resource-Priority header or all SIP Resource-


Single quotes around 'Resource-Priority'.

"...header field..."


>    Priority headers in a given SIP message.  An authority is only


Single quotes around 'Resource-Priority'.

"...header fields..."


>    responsible for signing the content of a SIP Resource-Priority header


Single quotes around 'Resource-Priority'.

"...header field..."


>    for which it has authority (e.g., a specific "namespace "."
>    r-priority").
>
> 4.2.  Verification Service Behavior
>
>    [I-D.ietf-stir-rfc4474bis] Section 6.2 Step 5 requires that
>    specifications defining "ppt" values describe any additional verifier
>    behavior.  The behavior specified for the "ppt" values of "rph" is as
>    follows:
>
>    The verification service MUST extract the value associated with the
>    "auth" key in a full form PASSPorT with a "ppt" value of "rph".  If
>    the signature validates, then the verification service can use the
>    value of the "rph" claim as validation that the calling party is
>    authorized for Resource-Priority, which would in turn be used for

Single quotes around 'Resource-Priority'.

This text is ambiguous about whether the validation indicates that the 
calling party is authorized to use the priorities indicated in the 
passport object, or the values in the SIP 'Resource-Priority' header 
field; and (taken on its face) implies the latter, when the intention 
here should clearly be the former.

"...authorized for 'Resource-Priority' indicated in the claim. This 
value would in turn be used for..."

The text also needs to say something about comparing values in the claim 
to values in the 'Resource-Priority' header field, and what a mismatch 
might mean. The document says elsewhere that the signature might only 
cover some of the r-values, which makes it entirely possible that the 
'Resource-Priority' field might contain more values than are signed. On 
the other hand, intermediaries might reasonably remove r-values as the 
call is processed. This probably means that those removed priorities 
should not be used, even if they are present in the passport. It seems 
reasonable to say that *typical* processing by a receiving party would 
be to take the *union* of all RPH passports that they trust, and 
*intersect* that with the priorities in 'Resource-Priority' header 
fields to get the actual priority or priorities to be applied to the 
call (subject to local policy).


>    priority treatment in accordance with local policy for the associated
>    communication service.
>
>    In addition, [I-D.ietf-stir-rfc4474bis] Section 6.2 Step 4 requires
>    "iat" value in "rph" claim to be verified.
>
>    The behavior of a SIP UAs upon receiving an INVITE containing a


"...of a SIP UA upon..."

or

"...of SIP UAs upon..."


>    PASSporT object with a "rph" claim will largely remain a matter of
>    implementation policy for the specific communication service.  In
>    most cases,implementations would act based on confidence in the


"...cases, implementations..."

(space after comma)


>    veracity of this information.  The use of the compact form of


Paragraph break before "The".


>    PASSporT is not specified in this document.
>
> 5.  Further Information Associated with Resource-Priority


Single quotes around 'Resource-Priority'.


>
>    There may be additional information about the calling party or the
>    call that could be relevant to authorization for Resource-Priority.


Single quotes around 'Resource-Priority'.


>    This may include information related to the device subscription of
>    the caller, or to any institutions that the caller or device is
>    associated with, or even categories of institutions.  All of these
>    data elements would benefit from the secure attestations provided by
>    the STIR and PASSporT frameworks.  The specification of the "rph"
>    claim could entail the optional presence of one or more such
>    additional information fields.
>
>    A new IANA registry has been defined to hold potential values of the
>    "rph" array; see Section 6.2.  The definition of the "rph" claim may
>    have one or more such additional information field(s).  Details of
>    such "rph" claim to encompass other data elements are left for future
>    version of this specification.
>
> 6.  IANA Considerations
>
> 6.1.  JSON Web Token Claims Registration


I think there's some confusion here. You're registering a PASSporT ppt 
value, not a new JWT claim. That is to say, you're adding an entry to 
this table:

https://www.iana.org/assignments/passport/passport.xhtml

Not to this table:

https://www.iana.org/assignments/jwt/jwt.xhtml

You would only use the second table if you had a new key to add to the 
PASSporT header -- this specification does not do that.

This section also needs some introductory text to let the IANA know 
exactly what to do; e.g. "This document registers a new value for the 
"Personal Assertion Token (PASSporT) Extensions" table.

>
>    o  ppt value: "rph"
>
>    o  Specification Document(s): Section 3 of [RFCThis]
>
> 6.2.  PASSporT 'rph' Types
>
>    This document requests that the IANA add a new entry to the PASSporT
>    Types registry for the type "rph" which is specified in [RFCThis].


There isn't an IANA table called "PASSporT Types." I presume this is the 
registration we just discussed in section 6.1, and so the above two 
lines can be removed.


>    This specification also requests that the IANA create a new registry
>    for PASSporT "rph" types.  Registration of new PASSporT "rph" types
>    shall be under the specification required policy. This registry is
>    to be initially populated with a single value for "auth" which is
>    specified in [RFCThis].


This needs to be very clear about the fields to be included in this new 
registry (e.g., "Registry entries must contain two fields: the name of 
the 'rph' type and the specification in which the type is described").


>
> 7.  Security Considerations
>
>    The security considerations discussed in [I-D.ietf-stir-rfc4474bis]
>    in Section 10 are applicable here.
>
> 7.1.  Avoidance of replay and cut and paste attacks
>
>    The PASSporT extension with a "ppt" value of "rph" MUST only be sent
>    with SIP INVITE when 'Resource-Priority' header is used to convey the


"...header field..."


>    priority of the communication as defined in [RFC4412].  To avoid the
>    replay, and cut and paste attacks, the procedures described in
>    Section 10.1 of [I-D.ietf-stir-rfc4474bis] MUST be followed.
>
> 7.2.  Solution Considerations
>
>    The use of extension to PASSporT tokens with "ppt" value "rph" based
>    on the validation of the digital signature and the associated
>    certificate requires consideration of the authentication and
>    authority or reputation of the signer to attest to the identity being
>    asserted.  The following considerations should be recognized when
>    using PASSporT extension with "ppt" value of "rph":
>
>    o  An authority (signer) is only allowed to sign the content of a SIP
>       'Resource-Priority' header for which it has the right authority.


"...header field..."


>       The authority that signs the token MUST have a secure method for
>       authentication of the end user or the device.
>
>    o  The verification of the signature MUST include means of verifying
>       that the signer is authoritative for the signed content of the SIP


It's not clear what authority is being claimed here. Is this supposed to 
mean something like "...verifying that the signer is authoritative for 
the originating tn in the PASSporT..."? Or "...authoritative for the 
resource priority namespace in the PASSporT?" Whatever the server is 
purportedly authoritative for needs to be clearly spelled out.


>       'Resource-Priority' header.


"...header field."


/a