Hi Vince, Folks,
I am glad to see things are moving to the right direction and hopefully
soon we will finalise this work.
I just found some few not very critical issues that needs some fixing in
in my opinion:
5.11. Spectrum
Here the document talk about the FCC and OFCOM/ETSI spectral profile
presentation requirements (i.e, power levels over a set of frequency
ranges. However, there is only one type of example (OFCOM/ETSI specific)
that is provided throughout the document. I think we need to add another
set of example that is FCC specific.
Would something like this below suffice for the FCC specific example?
“resolutionBwHz”: 1e5,
“profiles”: [
{
"Hz": 5.18e8,
"Hz": 5.24e8,
“dbm”: 24
] },
6.8.3. Antenna Characteristics
We only have the AMSL and AGL as options for antenna height Types.
I don't see why we should not also list HAAT as a third option, I am
pretty sure this is/can be used in some implementations.
Kind Regards,
Luzango.
>>> Vincent Chen <[email protected]> 07/18/14 10:38 PM >>>
Barry,
Thanks again for the detailed comments. A couple issues remain
unresolved:
- How to describe JSON schema
- Usage of "parameter"
Will you be available for the PAWS session on Tues to discuss further?
I've included additional comments/answers inline.
On Mon, Jul 14, 2014 at 12:31 PM, Barry Leiba <[email protected]>
wrote:
Hey, PAWS folk.
As Pete has put the subject document on the 7 August telechat agenda,
though he still has it in "Waiting for AD Go Ahead" state, I decided
to review it now, rather than wait. I've found quite a list of
issues, from large to small, which I've sorted below into three
categories:
"DISCUSS" are those that I would put in a DISCUSS ballot during IESG
Evaluation. I think they're errors in the document that need to be
corrected, or else things that need to be discussed and resolved.
The most important in this category, and the only one I think will be
difficult to resolve, is how to specify the JSON payload formally.
"COMMENT -- substantive" are those that I would put in the
non-blocking comments, but that I think are important to deal with,
and that I'd hope we'd have a discussion about if the authors think a
discussion is necessary.
"COMMENT -- minor" are minor editorial issues that I think would be
better corrected, but that I'm not going to grump about further.
Discussion is always welcome, but should be pretty much unnecessary
for these.
I hope it's useful to get these comments earlier, rather than later.
And, so, here they are, below. I've offered suggested text where I
could, and I hope that helps as well.
Barry
======================= DISCUSS =======================
-- Section 4 --
o Device Registration (Section 4.3) MAY be used by the Master
Device
and MAY be implemented by the Database, either as a separate
component or as part of the Available Spectrum Query (Section
4.4)
component.
I don't think the first MAY is correct. If the database requires
registration, it is *not* optional for the Master Device to use it. I
think this needs some rework. The same is true with "Device
Validation".
Based on comments from our AD, we wanted to separate requirements for
the
protocol itself from database-specific and regulatory-domain
requirements. Thus, from
the protocol's perspective, it's a MAY.
Having said that, the text can be clarified a bit. Suggestion:
o Device Registration (Section 4.4) MAY be used by the Master Device
and MAY be implemented by the Database. When implementing Device
Registration, the Database MAY implement it either as a separate
component or as part of the Available Spectrum Query (Section 4.5)
component.
This list also mixes "used", "supported", and "implemented", without
making all the issu say about its use? And what's the difference between
"supported" and
"implemented"?
Agreed it's confusing. Replaced "supported" by "implemented", since
that's
what's intended. The work "supported" still exists in the doc when
referring to
"supporting a set of rules" or "rulesets". There's also an added not in
the
Terminologies section.
I strongly suggest that, if you're going to say that, you make it all
clear, as to both implementation/support and use. The note after the
list that says that some things are obvious... nah, one of it is
obvious.
-- Section 4.1 --
A Database MAY indicate that its URI will be changing by including
the URI of one or more alternate databases (See DbUpdateSpec
(Section 5.7)) in its responses to a Device. Before a Database
ceases operation, for example, it MUST include DbUpdateSpec in its
responses to notify Devices.
I don't understand how the MAY and MUST are consistent with each
other. Can you explain or fix it?
Ah, I see....MAY refers to the Database's ability to change its URI.
Reword:
A Database MAY change its URI, but before it changes its URI, it MUST
indicate so by including the URI of one or more alternate databases
(See DbUpdateSpec (Section 5.7)) in its responses to a Device.
Before a Database ceases operation, for example, it MUST include
DbUpdateSpec in its responses to notify Devices.
-- Section 4.1.1 --
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
Here's another 2119 conflict. It doesn't make sense to have a MUST
for the time period if doing it at all is a SHOULD. Please sort this
one out as well.
You're right. Changed MUST to SHOULD.
-- Section 4.2
A Master Device SHOULD use the initialization procedure to exchange
capability information with the Database whenever the Master Device
powers up or initiates communication with the Database.
But in Section 4 you said "Initialization (Section 4.2) MAY be used by
the Master Device," and now you're saying "SHOULD"? You see why I'm
on about the 2119 inconsistencies?
The MAY in Section 4 is an oversight. Changed to SHOULD.
When a Master Device is
configured manually with these parameterized-rule values, it does
not
need to use the initialization procedure.
Dos that mean that when it's not configured with them, it *does* need
to? In other words, is this really a "MUST use initialization unless
it's pre-configured with the values" thing?
Thanks. You're right. Reworded:
When a Master Device is not
configured manually with these parameterized-rule values, it MUST
use
the initialization procedure.
-- Section 4.2.1 --
deviceDesc: The DeviceDescriptor (Section 5.2) for the Device is
REQUIRED. If the Database does not support the device or any of
the rulesets specified in the device descriptor, it MUST return
an
error with the UNSUPPORTED (Table 1) code in the error response.
If the device descriptor does not contain any ruleset IDs, the
Database SHOULD return a list of RulesetInfo (Section 5.6)
parameters for each ruleset it supports at the specified
location.
What this says to me is that the Master Device uses an empty list of
rulesets to query the list of supported rulesets. So: how does this
work if the Database does not return its list of rulesets?
Presumably, the Master Device did this because it needs the list, and
then it didn't get it. What does it do now?
Also, this is worded a bit confusingly. The list is REQUIRED, so it's
not true that the Database SHOULD return a list. What you mean to
tell us is what the Database SHOULD include in the list. I think it's
really awkward to try to say that here in the query, rather than
deviceDesc: The DeviceDescriptor (Section 5.2) for the Device is
REQUIRED. If the Database does not support the device or any of
the rulesets specified in the device descriptor, it MUST return
an
error with the UNSUPPORTED (Table 1) code in the error response.
If the device descriptor does not contain any ruleset IDs, the
Database SHOULD return a list of RulesetInfo (Section 5.6)
parameters for each ruleset it supports at the specified
location.
NEW
deviceDesc: The DeviceDescriptor (Section 5.2) for the Device is
REQUIRED. If the device descriptor does not contain any ruleset
IDs, the Master Device is asking the Database to return a list of
RulesetInfo (Section 5.6) parameters for each ruleset it supports
at the specified location.
END
OLD (Section 4.2.2)
rulesetInfos: A list of RulesetInfo (Section 5.6) parameters MUST
be
included in the response. Each RulesetInfo parameter corresponds
to a ruleset supported by the Database and is applicable to the
location specified in the INIT_REQ (Section 4.2.1) message. If
the Device included a list of ruleset IDs in the DeviceDescriptor
parameter of its INIT_REQ message, each RulesetInfo parameter in
the response MUST match one of the specified ruleset IDs.
NEW
rulesetInfos: A list of RulesetInfo (Section 5.6) parameters MUST
be
included in the response. Each RulesetInfo parameter corresponds
to a ruleset supported by the Database and is applicable to the
location specified in the INIT_REQ (Section 4.2.1) message.
If the Device included a list of ruleset IDs in the
DeviceDescriptor
parameter of its INIT_REQ message, each RulesetInfo parameter in
the response MUST match one of the specified ruleset IDs.
If the DeviceDescriptor did not contain any ruleset IDs, the
Database SHOULD include in the list the RulesetInfo parameters
for
each ruleset it supports at the specified location.
If the Database does not support the device or any of the
rulesets
specified in the DeviceDescriptor, it MUST instead return an
error with the UNSUPPORTED (Table 1) code in the error response.
END
Thanks for the suggestions. Done.
-- Section 4.3.2 --
If the Database accepts the
registration for none of the rulesets it supports, the Database MUST
return the NOT_REGISTERED error (See Error Codes (Section 5.17)).
I can't follow this sentence at all. Do you mean, "If the Database
does not accept the registration for any of the rulesets" ? Or do you
mean something else? Can you re-word this, please?
Heh, I was afraid "any" is ambiguous.
"If the Database does not accept the registration for any of the
rulesets":
- Does that mean if, out of 3, one was not acceptable, it passes the
"any" test?
- Or does that mean "none of them"
Hence...the attempt at being more precise by using "none".
-- Section 5.8 --
name: The display name for a database. It MAY contain UTF-8.
What about all the other strings whose content format is unspecified?
Are they allowed to contain UTF-8? If not, what *do* they contain?
I see that the Gen-ART review mentioned this also, and the response
will be to specify that all strings are encoded in UTF-8. Good.
Done.
-- Section 6 --
How is the reference to JSON Schema [I-D.zyp-json-schema] not
normative, when the 6.x subsections quite depend upon the
understanding of the schema format that it describes?
I see that the Gen-ART review mentioned this also, but the response is
quite troubling. No, the mechanism you're using is not sufficiently
self explanatory. I understand it -- I do -- but I had to figure it
out (I decided not to go look at the Zyp draft), and we can't assume
that arbitrary implementors will get it right. We need a well defined
way to explain how JSON objects are con (which I was pushing for).
We have at least three proposals (apart from Zyp, there's Newton
(draft-newton-json-content-rules), and there's the mechanism that I
proposed, which is used in Section 6.2 of RFC 7071), but nothing
that's being taken forward as a standard yet.
I guess the 3rd option is to just describe by example. Hopefully we can
discuss this at the F2F.
-- Section 6.6.2 --
The schema is missing the optional databaseChange property.
Done
-- Section 6.7.1 --
The schema is missing the optional masterDeviceDesc property.
Done
-- Section 6.8.11 --
The schema says that both properties are optional, but Section 5.14
says that they're both required.
Done
-- Section 6.8.13 --
The schema says that rulesetInfo is optional, but Section 5.9 says
that it's required.
Done
-- Section 7 --
The Database MAY redirect a PAWS request by returning a HTTP 3xx
response (as defined by HTTP/1.1 [RFC2616]).
...
Since the Device may communicate
with a Database (which it authenticated) without user interaction,
when the response code is 301 (Moved Permanently), the Device MAY
redirect without asking a user for confirmation (note that this
represents an exception to the HTTP/1.1 [RFC2616] requirements for
HTTP POST methods).
The references to RFC2616 need to change to RFC7231, now that 2616 is
obsolete.
I see that the Gen-ART review mentioned this also, and you plan to
change the reference. This should help you get that right:
The change to 7231 also means that the note about the second citation
can change. 2616 said this about redirecting a POST:
--- RFC 2616 ---
If the 301 status code is received in response to a request other
than GET or HEAD, the user agent MUST NOT automatically redirect the
request unless it can be confirmed by the user, since this might
change the conditions under which the request was issued.
----------------
That advice has changed in 7231:
--- RFC 7231 ---
Automatic redirection needs to done with
care for methods not known to be safe, as defined in Section 4.2.1,
since the user might not wish to redirect an unsafe request.
----------------
In my view, that means that the parenthesized note in the quote above
can be removed from this document. I also suggest using a section
number in the citation, as you're citing a big document. So...
OLD
The Database MAY redirect a PAWS request by returning a HTTP 3xx
response (as defined by HTTP/1.1 [RFC2616]).
NEW
The Database MAY redirect a PAWS request by returning a HTTP 3xx
response (as defined by HTTP/1.1 Semantics and Content [RFC7231],
Section 6.4).
END
OLD
Since the Device may communicate
with a Database (which it authenticated) without user interaction,
when the response code is 301 (Moved Permanently), the Device MAY
redirect without asking a user for confirmation (note that this
represents an exception to the HTTP/1.1 [RFC2616] requirements for
HTTP POST methods).
NEW
Since the Device may communicate
with a Database (which it authenticated) without user interaction,
when the response code is 301 (Moved Permanently), the Device MAY
redirect without asking a user for confirmation, even though it
is in response to an HTTP POST request.
END
Done for the above.
-- Section 8.2 --
The parameter name SHOULD be lowerCamelCase.
Why "SHOULD"? How does it affect interoperability? Wouldn't
"Parameter names use lowerCamelCase by convention." work fine?
Agreed. Changed.
-- Section 9 --
First, and most importantly, the IANA review interpreted your text to
say that the registration policies are Expert Review; I interpret your
text to say that they're Specification Required. Yet Vince replied to
the IANA review without correcting that. Which policy do you intend?
If it is Specification Required, you need to clear that up with IANA.
Or just deal with my othe
The text in this section seems to be commonly copied from somewhere.
Perhaps you could tell me whence you copied it, so we can make an
effort to stop people from doing that.
I don't remember precisely, but I recall I was reviewing some OAUTH docs
at the time.
RFC6749
The first paragraph is entirely unnecessary: please just remove it.
Done
The second paragraph and the list is fine, and the third is mostly OK,
except for the URI. You'll need to ask IANA how they want to receive
requests (by email or through a web URI), and specify that in
paragraph 3 instead of what's there now.
FYI. From http://www.iana.org, you can navigate to a "Protocol
Registration Forms" page to submit requests
for new assignments.
The fourth paragraph really needs to be entirely re-thought: it is not
how IANA does expert review in the first place, and we shouldn't be
telling IANA how to run their process in the second place.
The fourth paragraph should say that all registries use the
Specification Required policy [RFC5226], with a Designated Expert
appointed by the IESG. It should note that instructions to the DE as
to what she should look for and consider in evaluating a request are
given below in the descriptions of each registry. It should say that
the DE should take advice from the community through the designated
mailing list, and that is why the registrant should post to the
mailing list before formally requesting the registration from IANA.
All the rest of the mechanics are part of IANA's process, and should
not be specified here.
Thanks. Proposed text:
All registries use the Specification Required policy [RFC5226], with
a Designated Expert appointed by the IESG. Specific criteria that
the Designated Expert should use in assessing registrations are
given
below in the description of each registry. The Designated Expert
should take advice from the community through the [email protected]
mailing list, and the registrant is encouraged to post to the
mailing
list before formally requesting the registration from IANA. The
intention is that new registrations will be accompanied by a
published specification. But in order to allow for the allocation
of
values prior to publication of the specification, the Designated
Expert can approve allocations once it seems clear that the
specification will be published.
Is the last part (about allocation before publication of spec) also
process that should be omitted?
Or are they instructions to the DE?
One question: does it make sense for the review list to be a separate
list, or couldn't the WG mailing list be reused for that purpose?
I don't think there's a reason not to. Just didn't know the process.
Will propose just to use [email protected].
======================= COMMENT -- substantive =======================
General:
You appear to sometimes use "parameter" to refer to a structure (such
as GeoLocation) and also the fields within the parameter (see Section
5.1, for example). I find this confusing, and suggest that you do not
use the same term for both.
You're right. Perhaps, when referring to a structure, I should use
"object" in the JSON sense?
-- Section 3 --
In step 4, should this not say a word or two about what message it
responds with? Might it respond, "To be, or not to be; that is the
question?" Or is there an expected sort of response?
Changed.
Step 5 is the first mention of registration. A reference to where
that process is explained would be useful here (as this step doesn't
seem to fit into the flow).
In step 7, this is the first mention of a Slave Device, so referring
to "the Slave Device" doesn't make sense. Maybe you want something
like, "If a Slave Device has made a request to the Master Device, the
Master Device may verify..." ?
It's not clear how step 7 relates to steps 6 and 8.
Thanks. Reworded these steps:
6. The the Database. The message may be on behalf of a Slave
Device
that made a request to the Master Device.
7. If the Master Device is making a request on behalf of a Slave
Device, the Master Device may verify with the Database that the
Slave Device is valid.
8. The Database responds with an available-spectrum response
message in the body of the HTTP response.
In step 10, might it also send an error, refusal, or whatever? Or are
those all considered acknowledgment messages?
This should be considered a notification (fire and forget) call from the
Device.
Suggested rewording:
9. The Master Device may send a spectrum-usage notification message
to the Database. The notification is purely informational.
10. If the Database receives a spectrum-usage notification message,
it responds by sending the Master Device a spectrum-usage
acknowledgement message. Since the notification is purely
informational, the Master Device does not need to process the
Database response.
Hm, it seems that steps 5 and 7 are actually explained in the
paragraph after the numbered steps. So do they really belong in the
numbered steps at all?
The numbered steps are supposed to correspond to the order in which
these steps
happen, so I think it's important to leave them there.
-- Section 5.1 --
point: If present, it indicates that the GeoLocation represents a
point.
...
region: If present, it indicates that the GeoLocation represents a
region.
These make it sound as though these are boolean. It took me a bit to
realize that the values of each of these is actually a structure. I
think you mean this:
NEW
point: If present, it specifies the GeoLocation as a point.
...
region: If present, it specifies the GeoLocation as a region.
END
Done.
-- Section 8.3 --
Please get rid of the MAY in the first sentence.
Done.
If an
appropriate category does not exist, it can use values in a
different
range.
What is the antecedent for "it"? It looks like it's "an appropriate
category", but that's clearly not right. Please fix.
Done. Rewording:
If an
appropriate category does not exist, a value from a different range
may be used.
======================= COMMENT -- minor =======================
A small point in the header:
"iconectiv (formerly Telcordia Interconnection Solutions)"
I think it's fine to put that in the "Authors' Addresses" section, but
the header should just say "iconectiv". I realize that takes a little
inconvenient massaging of the XML, and probably isn't worth the
trouble for the I-D. Might just put that in an RFC Editor note....
I'll take a look later :)
General:
I like that your citations include the document names, as well as the
RFC numbers; thanks! It would be better if you put quotation marks
around the document names, to distinguish them from being part of your
text.
Done.
-- Section 1 --
The document describes the use of HTTP/TLS as
transport for the protocol.
This hits what's rather a peeve of mine: HTTP is not a transport
protocol; the transport protocol you're using is TCP.
I'd be happier if you said something like this:
OLD
This specification defines an extensible protocol to obtain
available
spectrum from a geospatial database by a device with geo-location
capability.
NEW
This specification defines an extensible protocol, built on top of
HTTP and TLS, to obtain available spectrum from a geospatial
database
by a device with geo-location capability.
END
...and then eliminate that last sentence. See also comments on
Section 4 and Section 7.
Done.
-- Section 2.2 --
I suggest this:
OLD
EIRP: Effective isotropically radiated power
ETSI: European Telecommunications Standards Institute
FCC: Federal Communications Commission
NEW
... and then in Section 9.2.2.7, spell out EIRP, as it's only used in
that one place.
Done.
-- Section 3 --
Little grammar nit:
1. The Master Device obtains (statically or dynamically) the URI
for a Database appropriate for its location to send subsequent
PAWS messages.
Make it "location, to which to send".
Done.
-- Section 3.1 --
These
requirements may be complex and involve device behavior that are not
easily parameterized.
"Device behaviour" is singular, so "that is not", please.
Done.
-- Section 4 --
Usage pet peeve: please change "comprise" to "compose", in the one
place it's used.
HTTPS Binding (Section 7) describes the use of
HTTPS (HTTP Over TLS [RFC2818]) for transporting PAWS messages and
optional device authentication.
Please use "transferring", instead of "transporting", to avoid calling
HTTP a transport.
Done.
-- Section 4.1.1 --
TBD Define message format
You missed something here. Jus' sayin'.
Acknowledged.
-- Section 4.4.1 --
Rulesets may mandate that it be the Device's
current location or allow it to be an anticipated location.
This is probably as good a place as any to ask this: is there any
validation of the geo-location at all? If not, can such a mandate
have any real teeth? What is this *really* saying?
There is no requirement for Database to validate. Devices typically go
through
separate certification (e.g., FCC) to ensure they conform to the rules.
Likewise,
Databases may also need to be certified, depending on regulatory
requirements.
-- Section 4.4.5 --
The table says that "location" is required, but the text says it's not
always required. The table should say "see description".
Done.
-- Section 4.5 --
Typically, a Slave Device needs a Master Device to ask the Database
on its behalf for available spectrum
"Typically"? Isn't that the *definition* of a Slave Device?
Oops. Done.
-- Section 5.5 --
All contact information MUST be expressed using the structure
defined
by the vCard Format Specification [RFC6350].
I think it's best to include both references here, like this:
NEW
All contact information MUST be expressed using the structure
defined
by the vCard Format Specification [RFC6350], encoded in JSON [RFC
7095].
END
Done.
-- Section 5.7 --
The subsections explain what additional "data" field each error might
use, but there are only sections for the ones that use the "data"
field. One has to assume that the absence of a subsection means that
the "data" field is not used for that error. It would be better to
say that in the table. I suggest adding one sentence to each error
description in the table except for -104, -105, and -201, as follows:
"This error does not use any additional data."
Done.
-- Section 5.11 --
The third table should be labelled "SpectrumProfilePoint".
Done.
-- Section 5.12 --
The second table should be labelled "SpectrumProfilePoint".
Done.
-- Section 5.17.1 --
When the error code is OUTSIDE_COVERAGE, the Database MAY include an
ErrorData element within its as the "data" field
You're missing the words "Error response" after "within its".
Done.
-- Section 7 --
This section describes the use of HTTP over TLS (HTTPS) HTTP Over
TLS
[RFC2818] as the transport mechanism for the PAWS protocol.
As I've noted earlier, please say "as the transfer mechanism". Also,
it's really weird to describe the document in the same words as the
document title. I suggest just deleting the document title in this
case. This also applies to Section 10.1.
Done.
-- Section 9.1.2 --
The first paragraph was obviously written before the ETSI info was
added. Please adjust it accordingly. (I see that the Gen-ART review
mentioned this too, and it will be fixed.)
Done.
You might add instructions to the DE with starting with "fcc". Or perhaps
with the initials of an organization
that hasn't yet registered anything, but reasonably might.
Done.
-- Section 10.1 --
The doubled "HTTP over TLS" comment applies here. Also, it's not at
all clear, when you say "these checks MAY be omitted," exactly what
checks you're saying may be omitted.
Verification of the SANs. Added some text.
In particular, the
validation path of the certificate must end in one of the client's
trust anchors, even if that trust anchor is the Database certificate
itself. A Master Device should allow for the fact that a Database
can change its certificate authorities (CAs) over time.
Just a question here: did the WG consider DANE at all?
It was brought up, but not discussed further.
Another question: is it really necessary to cover this stuff here?
Isn't it in 2818?
I believe the WG thought it would be good to restate.
-- Section 10.3 --
Using HTTP over TLS, messages protected by appropriate cypher suites
are also protected from eavesdropping or otherwise access by
unauthorized parties en route.
What does "or otherwise access" mean? Apart from the grammar problem:
it would be better to say something substantive here, rather than
something vague.
Changed to "or otherwise unrestricted reading".
-- Section 11 --
I wouldn't usually comment on a "Contributors" section, but it seems
odd to me to cite abandoned and long-expired drafts as references. It
might be better just to include the draft names, without making them
references. No? You're not actually suggesting that people read
them, just thanking the authors for their contributions.
Done.
==============================================
_______________________________________________
paws mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/paws
--
-vince
--
This message is subject to the CSIR's copyright terms and conditions, e-mail
legal notice, and implemented Open Document Format (ODF) standard.
The full disclaimer details can be found at
http://www.csir.co.za/disclaimer.html.
This message has been scanned for viruses and dangerous content by MailScanner,
and is believed to be clean.
Please consider the environment before printing this email.
_______________________________________________
paws mailing list
[email protected]
https://www.ietf.org/mailman/listinfo/paws
