Subject: [sip-http-events] pre-submission check for draft-roach-sip-http-subscribe

From: "Scott Lawrence" <[email-masked]>
Date: Thu, 17 Dec 2009 12:54:36 -0500

I've been asked to serve as Document Shepherd for the submission of
draft-roach-sip-http-subscribe.  The following are review comments based
on the checklist for the proto writeup...

The draft doesn't specify an intended status.  Add category="std" to
the attributes of the <rfc> element in your xml input.

The draft uses ABNF (only once, but...), so it needs a normative
reference to RFC 5234.

RFC 2119 keyword usage.

   You use the keywords uncapitalized in a few places; the I-D nits
   checker complains about the fact that you didn't use the
   standard citation paragraph, substituting one that specifies that
   only capitalized usages of the keywords have the RFC 2119 meanings.

   Other than a couple of obviously non-normative usages in the
   introduction and one idiomatic usage in 4.4, the only uncapitalized
   uses of the keywords are:

   Section 3.0, paragraph 4:

       Because a single resource may have the ability to be monitored
via
       multiple protocols, it is perfectly legal for an HTTP response to
       contain multiple link relationships with relations that allow for
       monitoring of changes.  Implementors are cautioned to process all
       link relations to locate a one that corresponds with their
preferred
       change monitoring protocol.

     I suggest rephrasing that - it might be helpful to express it in
     terms of the monitoring services rather than the resource.  It
     would also be appropriate to provide a reference to the
     authoritative definition of the Link header here to substantiate
     the point.  I suggest something like:

       The service that provides HTTP access to a resource might
       provide monitoring of that resource using multiple protocols, so
       it is perfectly legal for an HTTP response to contain multiple
       link relationships with relations that allow for monitoring of
       changes (see [9]).  Implementors are cautioned to process all
       link relations to locate a one that corresponds with their
       preferred change monitoring protocol.

  Section 3.1 says:

       If the server supports both SIP and SIPS access, it may
       return link relations for both kinds of access.

    that 'may' should be 'MAY'.

  Section 3.2, paragraph 3:

       The monitor-group URI corresponds to an RLS service associated
with
       the HTTP server.  This RLS service MUST support subscriptions to
       request-contained resource lists, as defined in RFC 5367 [8].
This
       RLS service is not, however, required to accept URI lists that
       include monitoring URIs that are not associated with resources
served
       by its related HTTP server.  This allows RLS functionality to be
       implemented without requiring back-end subscriptions.

    The exclusion in this paragraph is important enough that it should
    be in the capitalized form.  I suggest:

       The monitor-group URI corresponds to an RLS service associated
with
       the HTTP server.  This RLS service MUST support subscriptions to
       request-contained resource lists as defined in RFC 5367 [8]; the
       RLS service is NOT REQUIRED to accept URI lists that
       include monitoring URIs that are not associated with resources
served
       by its related HTTP server.  This allows RLS functionality to be
       implemented without requiring back-end subscriptions.

    (you might also want to make that "MAY, but is NOT REQUIRED to")

  Section 3.2, paragraph 5 begins:

       If a client wishes to subscribe to the state of multiple HTTP
       resources, and has received monitor-group URIs for each of them,
it
       may use the monitor-group URIs to subscribe to multiple resources
in
       the same subscription.

    the 'may' here is easily replaced by 'can'.

  Section 4.3 says:

       Future extensions may define filter criteria to be sent in the
       SUBSCRIBE message bodies.

     Any IETF document might be extended or changed by future versions
     - it doesn't really need to be said... I'd just remove the
sentence.

  Section 4.4, last paragraph:

       This local policy may choose to take various aspects of the
monitored
       resource into account, such as its age and presumed period of
       validity.

    the 'may' here could either be capitalized or replaced with
    'might'.

  Section 4.7 paragraph 1:

      NOTIFY messages should be generated whenever the underlying
resource
      indicated by the corresponding HTTP URL has been modified.

    that 'should' either should be capitalized or (better, imho) made
    'MUST' (that's kind of the point of the whole thing).

  Section 4.7 paragraph 2:

      In the case that the notifier has insufficient information to
return
      any useful information about the underlying HTTP resource, it may
      return a message body that is zero bytes long.

    that 'may' is clearly normative and should be capitalized.

  Section 4.8 begins:

      Upon receipt of a NOTIFY message, the subscriber should use any
      information in the message/http to update its view of the
underlying
      HTTP resource.

    again, a simple rewording avoids the problem:

      Upon receipt of a NOTIFY message, the subscriber applies any
      information in the message/http to update its view of the
underlying
      HTTP resource.

  Secion 4.10 uses 'may' twice in ways that could be replaced by
  'might'.

  Section 5 uses 'It should be noted that', which could be changed to
  'Note that'.

  Section 6 (Security Considerations) ends with:

      [...] If the HTTP resource is restricted
      using some form of access control, special care must be taken to
      ensure that the SIP means of subscribing to the resource state is
      also restricted in the same way.  Otherwise, unauthorized users
may
      learn information that was intended to be confidential (including
the
      actual resource value, in some cases).

    The 'must' above should probably be capitalized.
    The 'may' can be avoided by rephrasing:

      Failure to ensure access control could expose information that
      was intended to be confidential (including the actual resource
      value, in some cases) to unauthrorized users.

One other technical comment that I didn't notice on my last review of
05... in section 4.4 you say:

   Keep in mind that the goal behind selecting
   subscription durations is to balance server load against time to
   recover in the case of a failure.

it might be better to specify the nature of the failure -
specifically, short subscriptions guard against the loss of
subscription server state.

---

From: "Scott Lawrence" <[email-masked]>
Date: Thu, 17 Dec 2009 14:27:08 -0500

> on the checklist for the proto writeup...

Sorry about the terrible formatting... here's a more legible version:

RFC 2119 keyword usage.

       Because a single resource may have the ability to be monitored via
       multiple protocols, it is perfectly legal for an HTTP response to
       contain multiple link relationships with relations that allow for
       monitoring of changes.  Implementors are cautioned to process all
       link relations to locate a one that corresponds with their preferred
       change monitoring protocol.

  Section 3.1 says:

       The monitor-group URI corresponds to an RLS service associated with
       the HTTP server.  This RLS service MUST support subscriptions to
       request-contained resource lists, as defined in RFC 5367 [8].  This
       RLS service is not, however, required to accept URI lists that
       include monitoring URIs that are not associated with resources served
       by its related HTTP server.  This allows RLS functionality to be
       implemented without requiring back-end subscriptions.

       The monitor-group URI corresponds to an RLS service associated with
       the HTTP server.  This RLS service MUST support subscriptions to
       request-contained resource lists as defined in RFC 5367 [8]; the
       RLS service is NOT REQUIRED to accept URI lists that
       include monitoring URIs that are not associated with resources served
       by its related HTTP server.  This allows RLS functionality to be
       implemented without requiring back-end subscriptions.

       If a client wishes to subscribe to the state of multiple HTTP
       resources, and has received monitor-group URIs for each of them, it
       may use the monitor-group URIs to subscribe to multiple resources in
       the same subscription.

  Section 4.3 says:

     Any IETF document might be extended or changed by future versions
     - it doesn't really need to be said... I'd just remove the sentence.

       This local policy may choose to take various aspects of the monitored
       resource into account, such as its age and presumed period of
       validity.

  Section 4.7 paragraph 1:

      NOTIFY messages should be generated whenever the underlying resource
      indicated by the corresponding HTTP URL has been modified.

  Section 4.7 paragraph 2:

      In the case that the notifier has insufficient information to return
      any useful information about the underlying HTTP resource, it may
      return a message body that is zero bytes long.

  Section 4.8 begins:

      Upon receipt of a NOTIFY message, the subscriber should use any
      information in the message/http to update its view of the underlying
      HTTP resource.

      Upon receipt of a NOTIFY message, the subscriber applies any
      information in the message/http to update its view of the underlying
      HTTP resource.

      [...] If the HTTP resource is restricted
      using some form of access control, special care must be taken to
      ensure that the SIP means of subscribing to the resource state is
      also restricted in the same way.  Otherwise, unauthorized users may
      learn information that was intended to be confidential (including the
      actual resource value, in some cases).

---

From: Adam Roach <[email-masked]>
Date: Fri, 18 Dec 2009 18:02:21 -0600

>> on the checklist for the proto writeup...

Thanks. I've generally accepted the suggested changes, except as noted 
below.

New version here:

   http://www.ietf.org/id/draft-roach-sip-http-subscribe-06.txt
   http://tools.ietf.org/rfcdiff?url2=draft-roach-sip-http-subscribe-06.txt

>      (you might also want to make that "MAY, but is NOT REQUIRED to")

"NOT REQUIRED" is not a 2119 term. "REQUIRED" is functionally equivalent 
to "MUST" -- but the equivalent of "MUST NOT" would be something like 
"REQUIRED NOT TO," which would be cumbersome, even for RFC 2119.

I'm not completely certain what "NOT REQUIRED" would mean as a normative 
statement, unless you want to define it as identical to "MAY" -- in 
which case "MAY, but is NOT REQUIRED to" is somewhat redundant.

I do see value in adding a normative MAY here, since it's not explicitly 
permitted by this text. My proposed edit is:

    The monitor-group URI corresponds to an RLS service associated with
    the HTTP server.  This RLS service MUST support subscriptions to
    request-contained resource lists, as defined in RFC 5367 [9].  This
    RLS service MAY, but is not required to, accept URI lists that
    include monitoring URIs that are not associated with resources served
    by its related HTTP server.  Not requiring such functionality allows
    the RLS to be implemented without requiring back-end subscriptions.

I recognize that this leaves the term "required" in the text in a 
non-capitalized form, and the tools will complain about that fact. 
Normally, I'd insert my rant here about the combination of 2119 and the 
tools hijacking the use of perfectly common English words and making 
them impossible to use in their original sense -- but I imagine you can 
guess how that rant goes, so I'll save you the reading.

>      'MUST' (that's kind of the point of the whole thing).

There are caveats here, though -- for example, if event rate control is 
in effect, or policy prevents notification, or filters have modified the 
content such that there is no net change, or..., or..., or...

So we can't make it "MUST."

In fact, I don't think we're talking about normatively changing what 
3265 says about notifications -- we're just defining what state 
information is conveyed in notifications. So my inclination would be to 
state it as "NOTIFY messages are generated..."

>      that 'may' is clearly normative and should be capitalized.

And, on reflection, this should be a normative MUST, not a normative 
MAY. There's no other alternative.

>    Secion 4.10 uses 'may' twice in ways that could be replaced by

#insert <rfc2119_hijacking_english_rant>

>        value, in some cases) to unauthrorized users.

#insert <rfc2119_hijacking_english_rant>

> subscription server state.

I think they're both important aspects. I've added another sentence, 
making the paragraph end:

             Keep in mind that the goal behind selecting subscription
             durations is to balance server load against time to
             recover in the case of a failure.  In particular, short
             subscription expiration times guard against the loss
             of subscription server state, albeit at the expense of
             additional load on the server.

/a