Subject: [core] Chair's review of draft-ietf-core-resource-directory-19

From: Jaime Jiménez <[email-masked]>
Date: Fri, 22 Feb 2019 12:34:24 +0000

Dear authors,

below are some of the comments to the draft, they are mostly editorials with few ones that may warrant further discussion.

p1 - "Web interfaces" is often used interchangeably with "REST interfaces" it'd be better to use one only, maybe the latter.

p3 - "with limited RAM and ROM" Adding a reference to the expected RAM and ROM would be good. https://ieeexplore.ieee.org/document/6970748/ provides an estimation of <2kB of minimum RAM and <30kB of minimum ROM for common IoT OSs.

p3 p12 - I think we could move on and update the term "machine-to-machine" to "Internet of Things" throughout the document, unless there is a specific need to keep M2M still there.

p6 - RDAO is under-defined in the terminology section, expanding the acronym is too short for a definition.
p6 - the last paragraph of Section 2 "For several operations.... circumstances" could probably go before the enumeration of the terminology.
p6 - "Only information SHOULD be stored in the resource directory that can be obtained by querying ..." could be "Information SHOULD be stored in the resource directory only if it can that can be obtained by querying ..."

p8 - The Commissioning Tool (CT) should be added to the architecture on the Registration Interface.

p10 – change content-type (ct)/content-format (ct)

p15 - I wonder why there is no DHCP/DHCP6 option to discover RD defined, is there no interest by those deploying RD? If the authors find it relevant, it could be added as a new draft or as part of this one in a similar way as the RDAO option on a new section 4.2

p19 - https://github.com/core-wg/resource-directory/issues/191
"The entries for "Failure" are quite repetitive for 4.00 and 5.03. Can we factor these out a bit?
The entry "HTTP support" is surprising; maybe this item should be explained beforehand. (It seems all it is saying is that HTTP does not do multicast or /.well-known/core?)"

p20 p28 p31 p38 and others - There does not seem to be a common way to present REST interactions in the examples of the document. Please use always the same form. For example similar to:

<Interaction>: <Origin EP> -> <Destination EP>
<Request>:  <Method> <URI/PATH>
            <PAYLOAD>
<Response>: <Code>
            <PAYLOAD>

Which in markdown would look like:
~~~~
  Int: EP -> IPv6 Multicast Address (FF0X::FE) or [MCD1]
  Req: GET coap://[MCD1]/.well-known/core?rt=core.rd*
  Res: 2.05 Content
       </rd>;rt="core.rd";ct=40,
       </rd-lookup/ep>;rt="core.rd-lookup-ep";ct=40,
       </rd-lookup/res>;rt="core.rd-lookup-res";ct=40,
~~~~

p22 - Endpoint Name "mostly mandatory" is ambiguous. If the ep name is not needed to register to an RD then it is optional. If, on the other hand the RD needs an ep name and assigns one then it is mandatory ( btw if the RD assigns the ep name, shouldn't it return that information to the ep, together with the location within the rd, once the registration is successful? )
Github Issue 190 (below) raises the need to define a bit better what the ep name is supposed to contain. To me, we could keep it mandatory and add some guidelines for its creation, in OMA for example they are defined as an URN http://www.openmobilealliance.org/release/LightweightM2M/V1_1-20180710-A/HTML-Version/OMA-TS-LightweightM2M_Core-V1_1-20180710-A.html#7-3-1-0-731-Endpoint-Client-Name
p22 - https://github.com/core-wg/resource-directory/issues/190
"All we know from the draft is that it is ≤ 63 bytes. But we need to say that it is a UTF-8 string. Not entirely sure we want 😈👄👽 as an endpoint name either. Same for sector."

p23 - Sorry for asking, but why is base URI only mandatory when filled by the Commissioning Tool? Wouldn't it be better to make it always mandatory to avoid the differentiation?

p26 - Section 5.3.1 seems like could use a bit of reordering, I can explain this in another email or call with the authors.

p30 - lt, base and extra-attrs were already explained in 5.3 you might want to keep it as it is or change it by adding a reference to 5.3 and comment on the changes that the Registration Update has over the Registration.

p33 - As per the document structure, there are two interfaces: registration and lookup. Shouldn't they be at the same level in the document? Registration is 5.3, shouldn't lookup be 5.5 instead of 6?

p41 p42 - Just to clarify, is then the tuple [endpoint,sector] the way RD identifies endpoints? Or is it derived from the device's credentials?
- "A given endpoint that registers itself, needs to proof its possession of its unique (endpoint name, sector) value pair." - "An Endpoint (name, sector) pair is unique within the et of endpoints registered by the RD.  An Endpoint MUST NOT be identified by its protocol, port or IP address as these may change over the lifetime of an Endpoint."

p44 - typo address/Address

---

From: Christian M. Amsüss <[email-masked]>
Date: Thu, 28 Feb 2019 22:10:06 +0100

Hello Jaime,

thanks for the review. I've rearranged them a bit to ease further
processing, but will basically respond point-to-point:

Asking back
-----------

> p20 p28 p31 p38 and others - There does not seem to be a common way to
> present REST interactions in the examples of the document. Please use
> always the same form. For example similar to:
> 

> p23 - Sorry for asking, but why is base URI only mandatory when filled
> by the Commissioning Tool? Wouldn't it be better to make it always
> mandatory to avoid the differentiation?

That'd require the registrant to find out its currently preferred IP
address, keep track of it and serialize it -- something it may often not
need to do for any other purpose.

For example, non-TCP CoAP devices in a 6LoWPAN deployment can be sure to
never need base URIs, and don't even need to consider at runtime when to
update their base address as long as their registration lifetime is not
"long-living" in RFC6879 terms (hours or days).

Applications that talk to the device exclusively through the RD (such as
LwM2M, or the extension at [1]) need the base URI to be absent, so not
requiring the base URI also helps not conflicting with existing
deployments.

[1]: https://tools.ietf.org/html/draft-amsuess-core-resource-directory-extensions-00#section-2

> p26 - Section 5.3.1 seems like could use a bit of reordering, I can
> explain this in another email or call with the authors.

Looking forward to any suggestion.

> p22 - Endpoint Name "mostly mandatory" is ambiguous. If the ep name is
> not needed to register to an RD then it is optional. If, on the other
> hand the RD needs an ep name and assigns one then it is mandatory (
> btw if the RD assigns the ep name, shouldn't it return that
> information to the ep, together with the location within the rd, once
> the registration is successful? )

The endpoint name is mandatory in the information model, but not always
mandatory in the registration URI. As for the "mostly mandatory" phrase,
I'll try to phrase that better (together with the base URI which is also
mandatory or optional depending on some criteria).

As for the device learning the endpoint name, my expectation is that
that is bound to the security context (eg. for certificates, it can be
the certificate identifier), so registrant and RD would already agree on
it.

A registrant can use the endpoint lookup interface to retrieve the ep
name of its registration, but admittedly that's a bit intricate -- are
there applications for a registrant learning its endpoint name that'd
warrant adding mechanism to learn it more easily?

> p41 p42 - Just to clarify, is then the tuple [endpoint,sector] the way
> RD identifies endpoints? Or is it derived from the device's
> credentials?
>
> - "A given endpoint that registers itself, needs to proof its
> possession of its unique (endpoint name, sector) value pair." - "An
> Endpoint (name, sector) pair is unique within the et of endpoints
> registered by the RD.  An Endpoint MUST NOT be identified by its
> protocol, port or IP address as these may change over the lifetime of
> an Endpoint."

The tuple (endpoint name, sector) is how the RD identifies endpoints. It
may learn the registrant's endpoint name and sector from explicit
registration argumemts or from the the credentials.

> p15 - I wonder why there is no DHCP/DHCP6 option to discover RD
> defined, is there no interest by those deploying RD? If the authors
> find it relevant, it could be added as a new draft or as part of this
> one in a similar way as the RDAO option on a new section 4.2

AFAICT it just has not come up so there was no need to (given that in
6LoWPAN deployments TTBOMK the ND configuration is more prevalent). Do
you know of any interested parties or setups? Otherwise the answer is
probably still "no such option is defined at the time of writing" (but
can be added easily by anyone later).

Easy editorial fixes
--------------------

> p44 - typo address/Address

Thanks, will be fixed by the next version. [193]

Being discussed among authors
-------------------------------

The questions I don't feel comfortable answering have been put into the
authors' issue tracker.

> p3 p12 - I think we could move on and update the term "machine-to-machine" to "Internet of Things" throughout the document, unless there is a specific need to keep M2M still there.

[194] with suggestion for change

> p33 - As per the document structure, there are two interfaces: registration and lookup. Shouldn't they be at the same level in the document? Registration is 5.3, shouldn't lookup be 5.5 instead of…

[195] with suggestion for change

> p30 - lt, base and extra-attrs were already explained in 5.3 you might
> want to keep it as it is or change it by adding a reference to 5.3 and
> comment on the changes that the Registration Update has over the
> Registration.

[196], though I don't really see yet what to do about it; I'll try for
some text.

> The entry "HTTP support" is surprising; maybe this item should be explained beforehand. (It seems all it is saying is that HTTP does not do multicast or /.well-known/core?)"

[191] as you mentioned; waiting for feedback from the authors.

> "All we know from the draft is that it is ≤ 63 bytes. But we need to say that it is a UTF-8 string. Not entirely sure we want 😈👄👽 as an endpoint name either. Same for sector."

[190] as you mentioned; there's some things we'll definitely need to do
(state it's UTF-8 or ASCII); outlawing Unicode by properties is tricky,
and I wouldn't even know which ASCII characters to permit. I'm leaning
towards allowing daemon-kissing aliens, but waiting for authors'
opinions.

> p3 - "with limited RAM and ROM" Adding a reference to the expected RAM
> and ROM would be good. https://ieeexplore.ieee.org/document/6970748/
> provides an estimation of <2kB of minimum RAM and <30kB of minimum ROM
> for common IoT OSs.

[197], hoping anyone has more reliable numbers than I do.

Thanks again; I'll follow up as the referenced issues bear fruit
Christian

[190]: https://github.com/core-wg/resource-directory/issues/190
[191]: https://github.com/core-wg/resource-directory/issues/191
[193]: https://github.com/core-wg/resource-directory/issues/193
[194]: https://github.com/core-wg/resource-directory/issues/194
[195]: https://github.com/core-wg/resource-directory/issues/195
[196]: https://github.com/core-wg/resource-directory/issues/196
[197]: https://github.com/core-wg/resource-directory/issues/197

-- 
To use raw power is to make yourself infinitely vulnerable to greater powers.
  -- Bene Gesserit axiom