Subject: Feedback on draft-ietf-opsawg-mud-13

From: Mark Nottingham <[email-masked]>
Date: Thu, 26 Oct 2017 12:38:38 +1100

Overall, I like this specification, and am very interested to see how it is received by the market. That said, I found some significant issues that I believe need to be addressed before publication.

## Design Issues/Questions

* 1.8 Order of Operations talks about retrieving the MUD URL, but doesn't give any detail about how clients should do so. What URL schemes are acceptable? If HTTP(S) is, what headers should be sent in the GET request? Should redirects be followed? Should unsuccessful (e.g., 4xx, 5xx) responses be ignored, or trigger some other state? What level of certificate checking is required for HTTPS? Etc. It could be that your intent is "everything that the Web platform does", but that should be said explicitly.

* 3.2 and 3.3 duplicate the functionality of HTTP Last-Modified and Cache-Control. What is the benefit of doing so? Realistically, do you expect manufacturers to use protocols other than HTTPS to host MUD files?

* 3.5 systeminfo points to a URL for a human-readable description, but does not describe how it is to be localised for the administrator. E.g., should the fetch for that URL include Accept-Language? If it's HTML, how should that be presented? What versions of HTML are allowed?

* 3.6 extensions says that extensions have to be declared up-front. This is counter to common practice for most HTTP/JSON based APIs; why is it necessary? 

* 5. What does a MUD URL look like? uses a well-known URI to establish a structured name space. RFC5785 Section 1.1 explains that this is not the purpose of well-known URIs. Furthermore, it creates static structure in URLs, which is strongly discouraged by BCP190. I'm happy to work with you to help understand and meet your goals without misusing URIs.

* 12 Creating and Processing of Signed MUD files uses a separate file (at a fixed location) to host a signature. Why not just require use of HTTPS, leveraging WebPKI? Or, if there's a good reason not to do that, why not carry the signature in a response header field?

## Editorial Suggestions

* 1. Introduction needs some reworking; it meanders and has short, choppy sentences, and the voice seems off for a specification. 

* 1. Introduction uses "buy"; suggest "own", as some limited-capability devices can be made, not bought.

* 1. Introduction uses the extremely generic "object" to describe the target hosts for this specification, then switches to "Thing" with no explanation in 1.3.

* 1. Introduction waves its hands about possible quality-of-service uses of MUD. I think it'd be best to avoid making claims for features that aren't yet supported.

* 1.6 Terminology defines "Thing" as "the device emitting a MUD URL."  This is going to be confusing, because the common use of the term is much broader. Suggest "MUD Thing."

* 1.7 s/retrieve MUD files/fetch the MUD URLs in order to retrieve MUD files/

* 1.7 s/retrieves the MUD file/fetch the MUD file/

--
Mark Nottingham   https://www.mnot.net/

---

From: Eliot Lear <[email-masked]>
Date: Thu, 26 Oct 2017 15:59:34 +0200

Hi Mark,

Thanks very much for your comments (again).

Please see below.

On 10/26/17 3:38 AM, Mark Nottingham wrote:
> * 1.8 Order of Operations talks about retrieving the MUD URL, but doesn't give any detail about how clients should do so. What URL schemes are acceptable? 

This is spelled out in Section 5.  Only "https" may be used.

> If HTTP(S) is, what headers should be sent in the GET request?

I will add text that indicates that the Accept header should indicate
"application/mud+json" as described in the IANA considerations section.

>  Should redirects be followed?

Normal semantics should be observed, with the exception that .  I'll
note this in the draft in a new subsection.  However...

>  Should unsuccessful (e.g., 4xx, 5xx) responses be ignored, or trigger some other state? What level of certificate checking is required for HTTPS? Etc. It could be that your intent is "everything that the Web platform does", but that should be said explicitly.
Some amount of offline guidance is also required and should be added
(and see immediately below).
> * 3.2 and 3.3 duplicate the functionality of HTTP Last-Modified and Cache-Control. What is the benefit of doing so? Realistically, do you expect manufacturers to use protocols other than HTTPS to h…

Realistically I expect there to be a substantial amount of offline
usage, potentially including offline or alternative datastores,  and as
this is a relatively new concept, we'd like to leave open the
possibility for alternative resolution mechanisms.  I know of some who
want to create different repositories requiring different resolution
mechanisms.  I don't think that at this point we should foreclose that
possibility.

> * 3.5 systeminfo points to a URL for a human-readable description, but does not describe how it is to be localised for the administrator. E.g., should the fetch for that URL include Accept-Language…

Yes, the intent is to allow for the use of "Accept-Language".  If you
have a recommendation about HTML versions or around language support, I
would be grateful.  The intent is also for this not to be a large file,
but very few words to describe the device, possibly with a link <a> for
more information.
> * 3.6 extensions says that extensions have to be declared up-front. This is counter to common practice for most HTTP/JSON based APIs; why is it necessary? 

This is due to an unclear statement in 3.6.  The words "prior to" should
probably be replaced by "without".  It may be an artifact of an earlier
version. The intent was to get rid of the ordering, precisely to avoid
ordering concerns.

> * 5. What does a MUD URL look like? uses a well-known URI to establish a structured name space. RFC5785 Section 1.1 explains that this is not the purpose of well-known URIs. Furthermore, it creates…

The issue here ties to above.  It's important to externalize the
versioning from the file and from the protocol.  The MUD URL is a
convenient way to do that.  We have already seen two versions of the MUD
file (XML and JSON).  Two others have already been discussed (YAML and
CBOR).  We've settled on JSON for now, but it's a sure bet that it will
change in later versions.  We have HTTP as one means for resolution.  I
expect there will be a few others, given that people have already
approached me about alternatives.  Also, see my response directly below.

> * 12 Creating and Processing of Signed MUD files uses a separate file (at a fixed location) to host a signature. Why not just require use of HTTPS, leveraging WebPKI? Or, if there's a good reason n…

See above, plus we want to make it easy for people who are really just
acquainting themselves with our technology to easily deploy MUD. 
Requiring a header field would cause them to do all sorts of web
customization.  Storing a file is already a challenge for some, not to
mention generating it.

> * 1. Introduction needs some reworking; it meanders and has short, choppy sentences, and the voice seems off for a specification. 

I'm happy to rework specific parts, if you'd like to work with me
offline on this.

> * 1. Introduction uses "buy"; suggest "own", as some limited-capability devices can be made, not bought.

Good point.  A vendor caught out ;-)
> * 1. Introduction uses the extremely generic "object" to describe the target hosts for this specification, then switches to "Thing" with no explanation in 1.3.

Good point.  The intent here was to build on the good work of Hannes,
Jari, Dave, and Danny.  I will add some bridge text.

> * 1. Introduction waves its hands about possible quality-of-service uses of MUD. I think it'd be best to avoid making claims for features that aren't yet supported.

There are two places where QoS is mentioned: in the first para, and then
one time more later on when we talk about the model structure.  We
restructured the model so that QoS could indeed be accommodated later,
as well as other uses.  Thus, I've removed the former, but the latter is
important to explain the reasoning for the model approach.

> * 1.6 Terminology defines "Thing" as "the device emitting a MUD URL."  This is going to be confusing, because the common use of the term is much broader. Suggest "MUD Thing."

I'd rather let this one lie.
> * 1.7 s/retrieve MUD files/fetch the MUD URLs in order to retrieve MUD files/
Same line as below?
> * 1.7 s/retrieves the MUD file/fetch the MUD file/
ok.

Eliot

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 27 Oct 2017 10:18:55 +1100

> On 27 Oct 2017, at 12:59 am, Eliot Lear <[email-masked]> wrote:
> 
> Hi Mark,
> 

My apologies, I missed that. It might be worth calling this out earlier.

> mechanisms.  I don't think that at this point we should foreclose that

HTTP can be used offline as well. Since adding some other resolution mechanism would almost certainly require revising the specification and/or adding extensions, why not do it then? 

> but very few words to describe the device, possibly with a link <a> for

Allowing arbitrary HTML content has a number of risks, if it's to be displayed in another context. I'd strongly recommend you specify a more constrained format.

> version. The intent was to get rid of the ordering, precisely to avoid

Right, but that doesn't impact my comment. Why do you have to declare extensions at all?

> approached me about alternatives.  Also, see my response directly below.

HTTP already has well-understood mechanisms to identify formats, and they aren't in URLs; putting it there has long and widely been known to be a bad practice. Saying that you need to do so in case one day you want to support a different protocol that doesn't enable those mechanisms isn't a good reason to violate best practice for HTTP. 

You seem to be engaging in an attempt to layer your application semantics onto multiple application protocols with a one-size-fits-all approach. I'll point you at experiences with SOAP and WS-* to illustrate how well that goes.

> See above,

I see what you did there, trying to get me into a circular reference...

> plus we want to make it easy for people who are really just

If that's your concern, we already have a wonderful specification for these technology-challenged users, the File Transfer Protocol.

Seriously, though, I'm sick of this argument. Adding a header is not exotic, it is not difficult. Fifteen years ago it may have been difficult to get a WordPress host to set a header for you, but we no longer live in that world; people host things on Heroko, App Engine and lots of other places that give you high-fidelity access to HTTP semantics. In 2017, people writing IoT software and deploying it on a global scale (presumably, your audience here) can set a HTTP header on a response.

Double so since here we're literally talking about setting a MIME type -- something that people can do out of the box with a file extension on most filesystem-based HTTP servers, if they choose.

> I'm happy to rework specific parts, if you'd like to work with me

Great. You wouldn't happen to have this in Github somewhere, would you?

---

From: Eliot Lear <[email-masked]>
Date: Fri, 27 Oct 2017 11:01:15 +0200

Hi Mark,

In considering my responses below, please keep in mind the following
text which is in the draft:
> In this specification we describe each of these building blocks and how
> they are intended to be used together.  However, they may also be used
> separately, independent of this specification, by local deployments
> for their own purposes.

This is a relatively new concept and we are trying to walk before we
run.  We should expect that the building blocks will be used in
different ways in different contexts, which in case of IoT really is
quite a movable feast.

Now please see below.

> My apologies, I missed that. It might be worth calling this out earlier.

Ok, what I'm proposing is the following.   Feel free to suggest better.

Processing of the MUD URL
-------------------------
MUD URLs always use the HTTPS schema.  MUD controllers that are able
to do so SHOULD resolve MUD-URLs, following the normal rules of
{{RFC3986}} and retrieve signature files via HTTP over TLS
{{RFC2818}},{{RFC7540}}.  Requests for MUD URLs should be made with an
"Accept" header containing "application/mud+json".  Normal HTTP
semantics should be observed.

If a MUD controller is not connected to the Internet, other means may
be used to import MUD files and associated signature files.  So long
as the signature of the file can be validated, the file may be used.
In such environments, controllers SHOULD warn administrators when
cache-validity expiry is approaching so that they may check for new
files.

<--snip-->

> HTTP can be used offline as well. Since adding some other resolution mechanism would almost certainly require revising the specification and/or adding extensions, why not do it then? 

One of the transfer mechanisms we anticipate being used is a file import
(e.g., USB stick).  That wouldn't really require an additional
specification.  And while other specifications may be necessary in other
contexts, they may not be here at the IETF.  A perfect example: at least
one of the plethora of IoT  transmission schemes requires only that a
device be preconfigured with a PSK, and that there be a backend database
of those PSKs.  It's a sure bet that the MUD URL itself won't be
transmitted in that case, and it's 70/20 as to whether the URL itself or
the policy in the file is stored.  In either case, for that mechanism,
the work wouldn't be performed at the IETF, although I would expect this
work to be referenced.

> Allowing arbitrary HTML content has a number of risks, if it's to be displayed in another context. I'd strongly recommend you specify a more constrained format.

What do you have in mind?  I just ask that it be previously
standardized.  If your argument is that we should stick with UTF-8 text,
perhaps that's okay as well, but the WG should get a chance to comment
on that, as it would eliminate links.

> Right, but that doesn't impact my comment. Why do you have to declare extensions at all?

The purpose of the declaration is, like other specifications, to provide
a means to unambiguously state how an extension should be interpreted. 
Also, consider this: some extensions may require parsing of other files,
rather than extending the MUD file itself.  This was something the IoT
directorate review requested in particular.

> You seem to be engaging in an attempt to layer your application semantics onto multiple application protocols with a one-size-fits-all approach. I'll point you at experiences with SOAP and WS-* to…

We would like a self-describing file (it is, in fact, so, based on
earlier review comments), but the format is likely to change, as it has
in the past.  And we need to be protocol-neutral in how that file and
its signature are processed.  That leaves us limited options, which is
how we got here.  We picked one means to do that.  Taking into account
that history if there's something we can do better, let's make a
change.  Mark, I'd be happy to take you up on your earlier offer along
those lines.
> If that's your concern, we already have a wonderful specification for these technology-challenged users, the File Transfer Protocol.

The fundamental issue here is that we should take care not to wed the
MUD files themselves to one particular transfer technology.  Keep in
mind the USB stick.  Arguably FTP is one step above that ;-) I'm
personally open to changes with that in mind, so long as they're not

> Double so since here we're literally talking about setting a MIME type -- something that people can do out of the box with a file extension on most filesystem-based HTTP servers, if they choose.

No worries about setting the mime type.  We want to be conservative. 
Not THAT conservative ;-)

> Great. You wouldn't happen to have this in Github somewhere, would you?
https://github.com/elear/mud/blob/master/drafts/draft-ietf-opsawg-mud-13.mkd

You'll see the changes we discussed in this exchange reflected in that copy.

Eliot