Subject: [core] draft-ietf-core-resource-directory-07

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Mar 2016 13:48:26 +0200

Hi all,

I reviewed draft-ietf-core-resource-directory-07 and I have a few
comments/questions.

** Open Issues

Are the issues listed in
https://trac.tools.ietf.org/wg/core/trac/report/1, namely
* Ticket #372: https://trac.tools.ietf.org/wg/core/trac/ticket/372
* Ticket #383: https://trac.tools.ietf.org/wg/core/trac/ticket/383
still open?

The document notes that there is an open issue regarding patch (see
Section 5.6). What exactly is the question that needs to be answered?

** Terminology

* The term endpoint in this document is different from the terminology
used in the web environment. You might want to state that in the
definition since this can easily lead to confusion.

Although the CoAP RFC is referenced with regards to the definition it is
not the same definition as in the RD draft.

Furthermore, the definition of endpoint in Section 2 is different from
Section 3.

Section 2 says:

"
  Endpoint (EP) is a term used to describe a web server or client in
  [RFC7252].  In the context of this specification an endpoint is
  used to describe a web server that registers resources to the
  Resource Directory.  An endpoint is identified by its endpoint
  name, which is included during registration, and is unique within
  the associated domain of the registration.

Section 3 says:

"
  An endpoint is a web server associated with a scheme, IP address and
  port (called Context), thus a physical node may host one or more
  endpoints.
"

RFC 7252 says:

"
 An entity participating in the CoAP protocol.  Colloquially, an
 endpoint lives on a "Node", although "Host" would be more
 consistent with Internet standards usage, and is further
 identified by transport-layer multiplexing information that can
 include a UDP port number and a security association."

I don't think that Section 3 again needs to define terminology when this
was already done in Section 2.

It would be good to know why the terminology from RFC 7252 couldn't be
re-used. I suspect that there is some difference. Then, it would be good
to know whether the term refers only to a web server or also a client,
whether it applies only to CoAP or also other protocols (such as HTTP),
and how an endpoint is identified.

Regarding the term Resource Directory: The draft sometimes uses RD and
sometimes uses the term 'directory server'. I guess that these terms are
used interchangeable and for that reason I would say that in the
terminology section.

Finally, the term 'client' is not defined although it is shown in Figure
1 (architecture).

** MTI

What functionality is mandatory to implement?

For example, as it can be seen from the LWM2M section in the appendix
the OMA LWM2M protocol does not implement everything defined in this
spec and I wonder whether it is still a compliant implementation.

Another example: DNS-SD is described in the document and the reference
to DNS-SD is normative. Do I need to implement the DNS-SD part for an RD
implementation to claim conformance to this specification?

** Terminology: Installation tool vs. Commissioning Tool

Section 4.2 talks about the 'installation tool' and Appendix 12.1 calls
it 'Commissioning Tool'. I think it would be good to define the term in
Section 2 and then use the same term throughout the document.

Section 6.1 talks about a 'a management entity' even though I am not
sure it refers to the same concept as an 'installation tool' or a
'Commissioning Tool'. Later in Section 6.1 the term 'Manager' is used.

** Simple Directory Discovery

Section 1 motivates the specification and says

Section 4, however, defines a discovery technique and says:

"
   Not all endpoints hosting resources are expected to know how to
   implement the Resource Directory Function Set (see Section 5) and
   thus explicitly register with a Resource Directory (or other such
   directory server).  Instead, simple endpoints can implement the
   generic Simple Directory Discovery approach described in this
   section.  An RD implementing this specification MUST implement Simple
   Directory Discovery.  However, there may be security reasons why this
   form of directory discovery would be disabled.
"

From this text I don't understand what the differences between Section 4
and Section 5 is. As an implementer, why would I want to select the
"complex" discovery when I have a simple discovery technique that is
mandatory to implement. It would be good to say what the pros & cons are
and why this technique is there in the first place.

There are also two approaches defined:

"
   An endpoint that wants to make itself discoverable occasionally sends
   a POST request to the "/.well-known/core" URI of any candidate
   directory server that it finds.  The body of the POST request is
   either

   o  empty, in which case the directory server is encouraged by this
      POST request to perform GET requests at the requesting server's
      default discovery URI.

   or

   o  a non-empty link-format document, which indicates the specific
      services that the requesting server wants to make known to the
      directory server.
"

Why do I want to have two ways to do the same thing? Couldn't we just
pick one?

** Finding a Directory Server

Section 4.1 describes different ways to find a discovery server. While
it only lists them without giving any guidance on which approach would
be most useful in what situation it is reasonably easy to understand.

Section 5.1 again talks about discovery and pretty much repeats the same
approaches again. I would shorten the description. It is enough to
explain it once.

** Figure 1: Architecture

I believe the architecture diagram is incomplete. It does not show the
installer/commissioning tool, which is mentioned in various sections
throughout the document.

** Figure 2:  Resource Directory Information Hierarchy

This is a nice figure but it would be even nice if it uses some existing
notation. In UML, for example, you could use a class diagram.
The benefit of re-using existing diagram structures is that people may
have an easier time to understand what you mean and you could indicate
what the relationship between the different classes are. For example,
you can easily express that a domain consists of zero or more endpoints.

** Figures

I noticed that all figures showing message exchanges are pretty useless
for two reasons:

 a) You cannot express the necessary information in them.
 b) You always included the same information again in a non-diagram form
afterwards.

Here is an example:

"
        EP                                               RD
        |                                                 |
        | ----- GET /.well-known/core?rt=core.rd* ------> |
        |                                                 |
        |                                                 |
        | <---- 2.05 Content "</rd>;rt="core.rd"  ------- |
        |                                                 |

   Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd*

   Res: 2.05 Content
   </rd>;rt="core.rd";ct="application/link-format+cbor",
   </rd-lookup>;rt="core.rd-lookup";ct="application/link-format+cbor",
   </rd-group>;rt="core.rd-group";ct="application/link-format+cbor"
"

It would probably be easier to just do the following instead:

"
    >> EP ---- Request -----> RD

       GET coap://[ff02::1]/.well-known/core?rt=core.rd*

    >> EP <---- Response ---- RD

      2.05 Content
      </rd>;rt="core.rd";ct="application/link-format+cbor",
      </rd-lookup>;rt="core.rd-lookup";
                   ct="application/link-format+cbor",
      </rd-group>;rt="core.rd-group";
                  ct="application/link-format+cbor"

    Figure 7: Endpoint discovering an RD.
"

** Function Set

I have been confused about the strange term 'Function Set' for a while
and when I read through the document I got the impression that it is
nothing more than a REST API. Do I understand it correctly?

** Register a Group

Section 6.1 talks about ways to create a group and it says:

"
Configuration of the endpoints
   themselves is out of scope of this specification.  Such an interface
   for managing the group membership of an endpoint has been defined in
   [RFC7390].
"

What type of configuration is outside the scope?

** Lighting Installation Example

Why does this example talk about DNS? Is it possible to split the
example into two parts, one where DNS-SD is used and another one where
it isn't used?

Additionally, I have been told that luminaries in a commercial building
are installed and commissioned before a network is up and running.

I think that the lighting example could show the group concept quite
nicely and that's what it should focus on.

** Security Considerations

"
DTLS or TLS based security SHOULD be used on
   all resource directory interfaces defined in this document.
"

Why does this specification say that DTLS or TLS is optional to use? It
should mandate the use of DTLS/TLS!

The following text should be elsewhere in the document:

"
   An Endpoint is determined to be unique by an RD by the Endpoint
   identifier parameter included during Registration, and any associated
   TLS or DTLS security bindings.  An Endpoint MUST NOT be identified by
   its protocol, port or IP address as these may change over the
   lifetime of an Endpoint.
"

Why is there only a SHOULD for mutual authentication in the following
paragraph? Where in the certificate should the endpoint identifier go? I
would reference the DTLS/TLS profile document for that purpose. Why is
there only an identifier matching for the certificate-based approach
required? What about the pre-shared secret key mechanism? What about the
raw public key mechanism (where the public key is the identifier)?
(There would be the possibility to say that the endpoint is just the
fingerprint to keep it shorter.)
"
   Every operation performed by an Endpoint or Client on a resource
   directory SHOULD be mutually authenticated using Pre-Shared Key, Raw
   Public Key or Certificate based security.  Endpoints using a
   Certificate MUST include the Endpoint identifier as the Subject of
   the Certificate, and this identifier MUST be checked by a resource
   directory to match the Endpoint identifier included in the
   Registration message.
"

Why is access control optional? To me it appears that the document is
full of authorization decisions starting with the provisioning, the
registration, the lookup, and various other operations. I would at least
reference the work we do in ACE since it could be the building block
that is needed to offer an authorization story.

"
   Access control SHOULD be performed separately for the RD Function Set
   and the RD Lookup Function Set, as different endpoints may be
   authorized to register with an RD from those authorized to lookup
   endpoints from the RD.  Such access control SHOULD be performed in as
   fine-grained a level as possible.  For example access control for
   lookups could be performed either at the domain, endpoint or resource
   level.
"

Why does the DoS text talk about 'services that run over UDP
unprotected"? This section should talk about amplification attacks only
and those are related to the access control aspects. In my understanding
you cannot really run RD without DTLS/TLS security at all since it would
be very problematic from a security and privacy point of view.

Also, referencing some Cisco CVE is not really useful here.

Ciao
Hannes

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 28 Mar 2016 14:26:26 +0200

Hi Hannes,

thank you for this extremely useful review.
Many great observations, both around terminology and presentation, and
around the relationship to other efforts such as authorization.
Something to chew on for Buenos Aires...

Let me pick one item as it has a direct bearing on the meeting agenda:

> Section 5.6). What exactly is the question that needs to be answered?

The question is simply whether we will be able to finish adding the
PATCH methods to CoAP (see draft-vanderstok-core-etch) on the same
timeline as the time needed for completing the RD document.  Some of us
are optimistic that this is possible, some think the way to use PATCH
with RD should be added as a separate document.  But for the discussion
of the functionality of the RD, it makes sense to keep the PATCH
functionality in context, assuming we can always take out section 5.6
even at a late stage if we run into a problem with PATCH.
That's why it is part of -07.

Grüße, Carsten

---

From: Hannes Tschofenig <[email-masked]>
Date: Mon, 28 Mar 2016 16:48:38 +0200

Thanks, Carsten. This has helped me a lot since I have not been
following the patch debate. It sounds like a challenging task to predict
the completion date of draft-vanderstok-core-etch.

I would certainly appreciate if the RD document gets leaves the working
group at latest end of May.

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 12:25:40 -0700

These have been addressed and should be ready to be closed.

> On Mar 28, 2016, at 4:48 AM, Hannes Tschofenig <[email-masked]> wrote:
> 
> Are the issues listed in
> https://trac.tools.ietf.org/wg/core/trac/report/1 <https://trac.tools.ietf.org/wg/core/trac/report/1>, namely
> * Ticket #372: https://trac.tools.ietf.org/wg/core/trac/ticket/372 <https://trac.tools.ietf.org/wg/core/trac/ticket/372>
> * Ticket #383: https://trac.tools.ietf.org/wg/core/trac/ticket/383 <https://trac.tools.ietf.org/wg/core/trac/ticket/383>
> still open?
>

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 12:54:44 -0700

Regarding "endpoint"

I think the difference is that an RFC7252 defined endpoint may register a set of links associated with a mandatory endpoint name, which becomes in CoRE RD a representation of an "endpoint". 

In CoRE RD an endpoint is that entity described by the attribute "ep". It has a default associated server address, unless the links are registered with an explicit context attribute (e.g. registering the link </temp>;con=coap://[2002::17]:5683;rt=temp rd-lookup could return the link  <coap://[2002::17]:5683/temp>;rt=temp)

I agree that we can make this a lot clearer and have one normative reference, which is used consistently thereafter.

An endpoint is associated with a client, which is the entity that POSTs the links to the rd resource to register itself. RD is expected to infer the server address of the registered links from the network address of the registering client, unless explicitly overridden by the "con" link attribute.

Maybe the confusion it that there is a registering client that is associated with the endpoint (ep=<endpoint identifier>) being registered, and there are other clients that do lookup operations. The client interacting with rd-lookup is not an endpoint wrt. the lookup operation, but may be associated with some registered endpoint.

Also, there is nothing prohibiting a client from registering any number of "endpoints" with different sets of links in them, each representing some different exposed set of capabilities. They are only required to have unique endpoint identifiers. So maybe there is too much implication of a one-to-one correspondence with a server name or network address. There isn't any such constraint. An endpoint identifier in CoRE RE only identifies a link bundle that is registered, but does have a default server address.

Another thing that may need clarification is how a RD uses the IP address of a registering client to provide the complete URL to the rd-lookup interface. If the context of a link is registered (using the con attribute) it sould be used as in the above example.

This seems like a particularly difficult concept and I hope the only problem is bad descriptive text. If this is the case, we can fix it now.

Maybe we should create an issue for this and make a good description of the problem?

Best regards,

Michael

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:03:29 -0700

Yes, this is not well specified. 

rd-group and rd-lookup could be considered optional since they are defined as function sets. 

I believe that a single default domain should be specified with optionally more than one named domain, since the "d" parameter is optional on registration. 

I think these 2 clarifications would allow an implementation like LWM2M to use only the rd function set.

DNSSD should not be mandatory.

So here we should create an issue to track and resolve.

Michael

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:06:15 -0700

OK, that seems reasonable. The commissioning tool is a sort of proxy client for RD operations.
We could settle on one term for this.

Again, create an issue so we can track resolution ?

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:07:24 -0700

I agree with this. The flow diagrams are also inconsistent with the text for the same example

>   Req: GET coap://[ff02::1]/.well-known/core?rt=core.rd* <coap://[ff02::1]/.well-known/core?rt=core.rd*>
> 
>   Res: 2.05 Content
>       GET coap://[ff02::1]/.well-known/core?rt=core.rd* <coap://[ff02::1]/.well-known/core?rt=core.rd*>
> 
>

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:14:34 -0700

It's definitely confusing as it is. 

Maybe section 4 could focus on discovery of RD services only, and this could be removed from the function set definition of section 5. Section 4 could be about how to fine an RD, and section 5 could be about how to use an RD.

Another issue to track?

Michael

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:29:48 -0700

Yes, a function set is a form of REST API definition. It defines the expected requests, responses, options, and formats of messages to effect particular operations and state changes on resources. It is a structured way we (Shelby? Vial?) defined to represent such information in some IETF drafts. 

The idea is there is a resource like /rd for registering and another resource like /rd-lookup for discovery and another /rd-group for group functions. Each of these represents different functions and the name "function set" was chosen.

Is function set too much new conceptual language for something we already know? Is there a suggestion for a better way to describe it, like maybe "this is the REST API for registering things in RD", and "This is the REST API for looking up things in an RD"?

BTW, some more formal descriptive alternatives are WADL, Hydra, RAML, RESTdesc, HAL, JSON Hyper-Schema, Siren, UBER and some other less well known languages. Each of these has a targeted use case that is a little different from what we are doing, but could be adapted. We try to use WADL in CoRE Interfaces...

Best regards,

Michael

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 13:33:19 -0700

DNSSD is not important to the use of RD, but we were asked to show an example if integration of DNSSD with CoRE RD.

I agree this example goes a little to deep into resource discovery using DNSSD as an alternative to RD, and could be more focused on the use of DNSSD to find RDs and endpoints, but then make much more use of rd-lookup to discover resources.

Michael

---

From: Michael Koster <[email-masked]>
Date: Mon, 28 Mar 2016 14:10:44 -0700

The Security Consideration section here could be augmented by a security policy section.

It seems like we should define security policy for Resource Directories, Registration, and Discovery. This is a recurring question in other bodies as well, like W3C WoT IG. There may be some fundamental patterns to consider in a broader use case context. Who is registering and who is discovering, and what is the relationship that can be managed through RD?

Are there use cases in ACE or other groups that would inform this?

MIchael

---

From: peter van der Stok <[email-masked]>
Date: Tue, 29 Mar 2016 14:18:20 +0200

+1
Peter

Hannes Tschofenig schreef op 2016-03-28 16:48:
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: peter van der Stok <[email-masked]>
Date: Tue, 29 Mar 2016 15:08:03 +0200

Hi Hannes,

thanks for the comments, see below.

> implementation to claim conformance to this specification?

Good question.
I think the extra attributes of section 8 are part of the 
implementation.
The DNS-SD mapping that uses them can be RECOMMENDED.

> 'Commissioning Tool'. Later in Section 6.1 the term 'Manager' is used.

YEP, good catch.

> What type of configuration is outside the scope?

Managing group membership and their MC addresses.

> are installed and commissioned before a network is up and running.

The example tries to remove any suspicion that it describes the one and 
only way of setting up.
The purpose is to show a number of aspects.

> nicely and that's what it should focus on.

How is the group concept in the example unclear?

About a year ago you started the discussion about the the scope of the 
example, but regrettably we did not come to a conclusion.

For the moment I really want this RD going to its conclusion.
Do you think the example would benefit when sections 12.1.1 and 12.1.3 
are removed?
That can be done rather quickly.
Nevertheless, I will regret removing the part of the example describing 
the use of the ins and exp format attributes, because at the moment of 
writing there was a strong wish for it, but I can live without that part 
of the example.

Peter