Subject: [paws] AD Evaluation of draft-ietf-paws-protocol-11

From: Pete Resnick <[email-masked]>
Date: Mon, 7 Apr 2014 11:54:03 -0500

Greetings,

At long last, I completed my AD Evaluation of the protocol document to 
prepare for IETF Last Call. Below are a *large* number of comments. As I 
said with the requirements document: Don't panic. Many of these are 
editorial, are about some overuses of MUST/SHOULD/etc., or are 
clarifications to make sure the protocol requirements are separate from 
the regulatory requirements. The truly substantive issues are:

- Section 4.1 on database discovery.
- Section 9 on IANA registration policies.

I don't think either will be a big deal to solve, but they will take 
some thought.

Coincidentally, we just today received a (very late) disclosure of IPR 
regarding database discovery <https://datatracker.ietf.org/ipr/2340/>. 
Given my comments on 4.1, my general suggestion is that we think about 
making the entire discussion of database discovery clearly non-normative 
for this document, simply saying "The device needs to get a URI of the 
database, and whether that is done through pre-configuration, a Listing 
Server, or some Database Discovery mechanism, it is all outside of the 
scope of this document", and then move all discussion of this to 
whatever discovery document the WG wants to attempt. (I will separately 
chat with the chairs regarding the lateness of the disclosure and see 
what, if anything, there is to be done about that, and how the WG 
discussion of the disclosure itself should proceed.)

So, below is the list. I presume Vincent will go through all of the 
editorial or clarifying ones and tick them off. If anyone else notices 
something that you think would be a substantive change that needs 
discussion (beyond 4.1 and 9), please do make a special note of them so 
the group can address it.

pr

---

Global changes:

Change "regulatory rules" to "Ruleset".

Change "regulatory specifics" to "Ruleset specifics".

Change "regulatory-specific" to "Ruleset-specific".

Change "depends on regulatory domain" to "optional" in the tables. The 
description is sufficient to explain the dependency on regulatory 
domains. That said, throughout the descriptions of parameters, there are 
lots of places that say something like, "Some regulatory domains may 
require it." You could say something like that in a note at the top of 
the section and not have to repeat it. For any optional parameter, some 
regulatory domain might require it, even where you don't say that, so 
putting it on only some of the optional parameters is wrong, and putting 
it all of them seems silly.

In the tables where it lists "*other" parameters, you could add "optional".

2.2:

NEW
    Regulatory Domain: A location where certain rules apply to the use
       of white space spectrum, including the operation of databases and
       devices involved in its use. A regulatory domain is normally
       defined by a unit of government for a particular country, but
       the PAWS protocol is agnostic as to how a regulatory domain is
       constructed.

OLD
    Ruleset:  A set of rules that governs operations of white space
       devices and Spectrum Databases within a regulatory domain.  The
       same set of rules may be used by more than one regulatory domain.
NEW
    Ruleset:  An IANA-registered set of rules that governs operations of
       white space devices and Spectrum Databases. A regulatory authority
       can define and register its own rulesets, or can use rulesets that
       have been previously registered by others.

3.1:

    For a Master Device that supports multiple rulesets and operates with
    multiple databases in multiple regulatory domains

Strike "in multiple regulatory domains".

4:

    o  Device Registration (Section 4.3) MAY be used by the Master Device
       and MAY be implemented by the Database as a separate component or
       as part of the Available Spectrum Query (Section 4.4) component.

The second "MAY" is confusing. I think you instead mean, "and MAY be 
implemented by the Database, either as a separate component or as part 
of the Available Spectrum Query (Section 4.4) component."

    o  Device Validation (Section 4.5) MAY be used by the Master Device.

Shouldn't you add "and the Database"?

For each of the notification and validation bullets:

       Some regulatory domains mandate
       notifications, which would mandate their use by the Master Device
       and mandate their implementation by the Database.

I'd strike these from the bullets and put them in a note after the 
definitions:

    Note: Some regulatory domains mandate the use notifications and
    validation. In such cases, obviously their implementation and use
    would be necessary.

I would add a last paragraph, something like:

    The parameter tables in this section and Section 5 are for reference
    and contain the name of each parameter, the data type of each
    parameter, and whether the existence of the parameter is required for
    the protocol transaction in question. The data types are either
    defined in Section 5 or are part of the base data types specified in
    The JavaScript Object Notation (JSON) Data Interchange Format
    [RFC7159]. See Section 5 and Section 6 for more detail on data types
    and encodings.

4.1: The first paragraph and three bullets seem completely unnecessary 
and I think they should be removed. Then, rewrite the "Preconfiguration" 
as follows:

    Preconfiguration

    The Master Device can be provisioned statically with the URI of one
    or more Databases.  For example, in a particular regulatory domain
    there may be a number of certified databases that any device
    operating in that domain is permitted to connect to, and those URIs
    can be provisioned in the device. Alternatively, a Master Device can
    be provisioned statically with the URI of a Database Listing Server,
    from which it can retrieve URIs of available Databases.

(However, see comments on 4.1.1.)

There should probably be a non-normative reference to the bootstrapping 
draft in this section.

Last sentence: Change "regulators" to "regulatory domains".

4.1.1:

I'm a little concerned about the discussion of Listing Servers, 
especially the last sentence of this section. Are we saying that we are 
not defining the Listing Server protocol at all? That is, as a device, I 
might be handed a URI for a Listing Server, but this document gives me 
no protocol with which to communicate with the Listing Server? The 
protocol is completely out-of-band? That's not interoperable, and if 
left this way, I think the discussion of Listing Servers might have to 
be completely removed from the document.

If we are going to discuss Listing Servers, there's still work to be 
done on this section. I think the first paragraph needs a total rewrite. 
There's no need to talk about the mandates of regulators here. Here's my 
suggestion:

    The use of a Database Listing Server allows the Device to determine
    the URIs of available databases.  When a Listing Server is used, the
    Device can save the database list and SHOULD contact the Database
    Listing Server periodically to update its list. The time between such
    updates MUST be no longer than one week, although the update interval
    can be shorter (for example, when required by the applicable
    regulatory domain).

Strike the last sentence of the second paragraph.

The last sentence needs to be replaced with the way to get information 
out of the Listing Server.

4.2: Strike "regulatory-dependent".

4.4:

In item 4:

OLD
        It MUST return an error with appropriate error code (Table 1), if
        validation fails.
NEW
        If validation fails, the Database returns an appropriate error
        code (Table 1).

Also, I suggest changing the name of the "REQUIRED" error code to 
"MISSING" or "MISSING_PARAM" to avoid confusing it with the 2119 
terminology.

In item 5:

OLD
        the Database MUST indicate so in the response message.
NEW
        the Database will indicate so in the response message.

In item 6: What happens if there is a request for spectrum-usage in the 
available-spectrum response but the Master Device never sends the 
spectrum-usage notification? Does the database send back an unsolicited 
error? Is this a *protocol level* violation, or just a regulatory one? 
If it's just regulatory, change "MUST send" to "will send" or "sends".

4.4.1:

deviceDesc and location - In the table, change "optional" to "see 
description". There are times where it is *protocol* required.

requestType is of type "string", but there are no particular limits 
(either length or characters) on what can be in it. You can define it 
here or in section 5 if you like, but some indication of what can go in 
there seems important.

Change "regulatory specifics" to "Ruleset specifics".

4.4.2:

"SHOULD be sorted in increasing time": Why? If there's a good reason, 
what are the exceptions when you might not do it?

Change "This SHOULD be used by the Device" to "This can be used by the 
Device".

"...is REQUIRED and MUST include at least one entry" seems redundant. I 
think you can strike "is REQUIRED and".

4.4.3:

OLD
    The Database MUST interpret each
    location in the batch request as if it were an independent request
    and MUST return results consistent with multiple individual
    AVAIL_SPECTRUM_REQ (Section 4.4.1) requests.  The request message for
NEW
    The Database interprets each
    location in the batch request as if it were an independent request
    and returns results consistent with multiple individual
    AVAIL_SPECTRUM_REQ (Section 4.4.1) requests, but returns these
    results in a batched response (Section 4.4.4).  The request message
    for

deviceDesc: Change to "optional" to "see description".

4.4.4:

geoSpectrumSpecs: I think this is "optional". See below.

Change "This SHOULD be used by the Device" to "This can be used by the 
Device".

Change "The Device MUST NOT make any assumptions on the order of the 
entries in the list and..." to "The order of the entries in the list is 
not significant and the Device..."

4.4.5:

OLD
    The spectrum-use notification message MUST contain the geo-location
    of the Device.  Some regulatory domains may mandate additional
    parameters.
NEW
    The spectrum-use notification message indicates the spectrum
    anticipated to be used by the device.

(The discussion of what's required is below and needn't be mentioned 
here. In any event, the geo-location is not always required -- i.e., for 
a Slave Device -- so the sentence is wrong.)

In spectra, it says "SHOULD match". This doesn't sound like an 
interoperability requirement to me; if it's a SHOULD, the Database still 
has to deal with a different resolution than the one from the 
AVAIL_SPECTRUM_RESP. If this is needed for interoperability, you should 
change it to a MUST. If not, I'd drop this.

4.5: Typo: Change "and entry" to "an entry".

5.1:

For "point" and "region" in the table, change "optional" to "see 
description".

Change "the orientation MUST be interpreted as 0" to "the default value 
is 0".

Change "its value MUST be interpreted as 95" to "the default value is 95".

5.2:

Change "regulatory-specific ID" to "manufacturer's ID".

This section mentions 3 parameters that "MUST NOT exceed 64 characters". 
If these were limited to US-ASCII, that would also mean 64 octets, but 
64 characters is not necessarily 64 octets. Some definition is probably 
needed for what can specifically go in each one. You could even put in 
the ABNF for each. For example:

    serialNumber = 1*64name-char
    name-char = ALPHA / DIGIT / "_"

Obviously you can limit them as you see fit. If you want 
internationalization, I would obviously limit it to UTF-8.

OLD
       This SHOULD represent the
       name of the device manufacturer, SHOULD be consistent across all
       devices from the same manufacturer, and SHOULD be distinct from
       that of other manufacturers.
NEW
       This represents the name of the device manufacturer, and therefore
       ought to be consistent across all devices from the same
       manufacturer and distinct from that of other manufacturers.

5.3: If AGL is default, then why is heightType REQUIRED if height is 
provided?

5.4:

Change "Each FrequencyRange element MUST contain" to "Each 
FrequencyRange element contains".

Why is it SHOULD NOT instead of MUST NOT return frequencies outside of 
the range?

5.6:

Are you sure you want to limit authority to 2-letter country codes in 
the protocol with a MUST? I could imagine in the future authority being 
a different political entity (e.g., maybe there will be an EU authority 
some day). Instead of MUST, would "will normally" make sense here?

A reference to 8.2 for rulesetID would be helpful here.

For "maxLocationChange" and "maxPollingSecs" in the table, change 
"optional" to "see description".

5.8: You need to define length and content limits for name and uri if 
applicable.

5.9:

"SHOULD be sorted in increasing time": Why? If there's a good reason, 
what are the exceptions when you might not do it?

Change "MUST be interpreted by the Device as" to "are".

"When specified, it SHOULD correspond to the frequency ranges governed 
by the ruleset." I don't know what that means. Please explain.

Change "which the Device MUST treat as the same as a false value" to "in 
which case the default value is false".

For the following:

       If this parameter is present and its
       value is true, the Device MUST send a SPECTRUM_USE_NOTIFY
       (Section 4.4.5) message to the Database

Again, what happens if there is a request for spectrum-usage in the 
available-spectrum response but the Master Device never sends the 
spectrum-usage notification? Does the database send back an unsolicited 
error? Is this a *protocol level* violation, or just a regulatory one? 
If it's just regulatory, change "MUST send" to "will send" or "sends".

5.11:

"such that the Device MUST satisfy all the conditions" seems wrong. 
Don't you just mean, "such that the spectrum satisfies all of the 
conditions"?

Change "MUST cover" to "covers".

Why is it "SHOULD be ordered in non-decreasing frequency value" instead 
of MUST?

Change "is REQUIRED to define" to "defines".

Change "is REQUIRED to specify" to "specifies".

5.15:

Change "is REQUIRED to identify" to "identifies".

5.16:

You define the length in terms of characters for "reason", but don't 
indicate what contents it might have. If this can contain UTF-8, you'll 
want to say that, and say what the octet limit is instead of the 
character count.

5.17:

Change "optional" to "see description" for data.

"message" is another string that requires further definition.

In "data", mention that any required additional data is described in 
Table 1.

As mentioned above, probably best to change the name of the "REQUIRED" 
error code.

A mention of the IANA registry in this section would be useful.

5.17.1:

Change "MAY include" to "contains".

5.17.2:

Change "MUST include" to "contains".

5.17.3:

As mentioned above, probably best to change the name of the "REQUIRED" 
error code.

Instead of "SHOULD be expressed using dotted notation", don't you just 
mean "is expressed using dotted notation"?

6: Was a review of all of the schema descriptions and examples done by a 
JSON expert?

6.8.13:

Change "regulatory-domain ruleset" to "ruleset".

Why "SHOULD be sorted"? (See 5.9)

8.1:

Change param-name to:

    param-name = 1*64name-char

8.2:

OLD
    The form of a Ruleset ID value SHOULD be guided by the following:
    o  The value SHOULD describe the set of rules that allow a device to
       operate within one or more regulatory domains.  For example, it
       MAY include the name of a regulatory body or a certification
       process
    o  The value SHOULD include version information, such as a year
       and/or version number
    o  The value MUST NOT exceed 64 characters
NEW
    When defining a Ruleset ID:
    o  It can be useful for the identifier to be descriptive of the set
       of rules  that allow a device to operate within one or more
       regulatory domains.  For example, it might include the name of a
       regulatory body or a certification process
    o  The identifier SHOULD include some sort of version information,
       such as a year and/or version number.
    o  The identifier MUST NOT exceed 64 characters

8.3:

Change "MUST be registered" (x2) to "are registered".

Change "SHOULD be" to "is".

Change "it MAY use" to "it can use".

9.1, 9.2, and 9.3:

    are registered through the Specification
    Required [RFC5226] process, after a two-week review period on the
    [email-masked] mailing list, on the advice of one or more
    Designated Experts.  To allow for the allocation of values prior to
    publication, the Designated Expert(s) may approve registration once
    they are satisfied that such a specification will be published.

    Registration requests must be sent to the [email-masked]
    mailing list for review and comment, with an appropriate subject
    (e.g., "Request for parameter: example").

    Within the review period, the Designated Expert(s) will either
    approve or deny the registration request, communicating this decision
    to the review list and IANA.  Denials should include an explanation
    and, if applicable, suggestions as to how to make the request
    successful.

    IANA must only accept registry updates from the Designated Expert(s),
    and should direct all requests for registration to the review mailing
    list.

First of all, I think this is the wrong way to set up the process. 
Submitting to the list will leave an unclosed loop. Instead, submissions 
of registrations should go to IANA. That will either happen by way of 
Last Call, if the specification is an RFC, or by direct submission if 
it's a different kind of specification. Then let IANA contact the 
Designated Expert(s) to do their review. This document can specify that 
the DEs can/will post the request to a list for wider community review, 
but that should be part of the instructions to the DEs in this document. 
After the DEs approve, they send the message to IANA (who can poke them 
if they're late), and IANA notifies the registrant and does the 
registration. So the order should be:

Registrant->IANA->DE(s)->list->DE(s)->IANA->Registrant

Set up this way, IANA will be tracking the progress of the registration 
from beginning to end.

Second, I think this needs specific instruction to the DEs on what basis 
they should accept or reject registration requests. Can they only do it 
based on completeness of the application? Can they reject if the 
registration is somehow duplicative with an existing registration? For 
early allocation requests, should the DEs be reviewing the draft 
specification for completeness? Each section should provide an 
explanation of criteria that the DEs should be using to evaluate 
registration requests.

Finally, for ease of reading, I'd ask that you swap sections 9.1 and 
9.2. Describing FCC parameters before defining the FCC ruleset ID seemed 
weird.

9.2.2:

I think the second column of the table should be subdivided: For each 
parameter, it should specify the parameter name, its type, and whether 
it is required or optional.

I'm not sure the description of DeviceOwner is clear enough that IANA 
will know how to put that into the table.

11: I'm a bit concerned about everyone but Vincent being listed in the 
Author's section rather than the Contributor's section. The Author's 
section includes the folks that must sign off on the document during RFC 
Editor AUTH48. I'd rather not require 5 people to have to do that. The 
Contributor's section indicates that each person was an instrumental 
contributor of text to the document, so I think that's a reasonable 
place to put those folks.

13.1:

I think X.520 can be Informative instead of Normative.

13.2:

I think JSON-RPC is going to have to be Normative.

RFC 2818 is definitely normative.

Appendix A: You should note that the RFC Editor should remove this 
section before publication.

-- 
Pete Resnick<http://www.qualcomm.com/~presnick/>
Qualcomm Technologies, Inc. - +1 (858)651-4478