Subject: [OPSAWG] IoT-DIR early review of draft-ietf-opsawg-mud-08

From: Henk Birkholz <[email-masked]>
Date: Tue, 29 Aug 2017 23:40:20 +0200

Reviewer: Henk Birkholz
Review result: Has Issues

Hi,

I am the assigned IoT-DIR reviewer for this document's early review.

Please find my comments in kramdown below.

Viele Grüße,

Henk

# IoT-DIR Early Review of I-D.ietf-opsawg-mud-08

## Draft Summary

This draft defines a canonical way to compose an URI that points to a 
specific resource called a MUD file. A MUD file is a text resource that 
contains imperative guidance in the form of YANG-based ACL policies 
represented in JSON. The imperative guidance is intended to be applied 
to things that can be identified by the segments of the MUD URI via a 
specific controller. The version of MUD is a component (segment) of the 
MUD URI and there are three examples in what to embed a MUD URI in (DHCP 
option, X.509 extension, and LLDP extension).

## Comments on General Topics

This draft could be a significant step towards to self-descriptiveness 
of things. Constrained things might require imperative guidance or 
declarative guidance in order to be managed appropriately - which in 
includes aspects, such as isolation, clustering, service/capability 
discovery/exposure, and therefore security automation in general. In a 
lot of usage scenarios, it might not be feasible to store that guidance 
on the thing itself and MUD URI could be a solution to support a lot of 
vendor supplied information, such as reference integrity measurements, 
intended composition of composite devices, etc.

### Scope of Application

On one hand, this drafts limits the potential usage of the MUD 
architecture to the use of one specific branch of YANG modules regarding 
ACL policies. There is no way to express other manufacture usage 
description "information-types" or "content-types" on a fundamental 
level and section 13 specifically states that "coupled with the fact 
that we have also chosen to leverage existing mechanisms, we are left 
with no ability to negotiate extensions and a limited desire for those 
extensions in any event."

Creating augments for the metainfo container as it is also described in 
Section 13, on the other hand, allows for virtually any kind of 
information to be expressed and conveyed via a MUD file, but on a 
semantic level that seems to be a bit perplexing.

This comment is not intended to question the feasibility of the 
technical approach - which is okay - but more taking into account the 
principle of least surprise. Hence, a strong proposal - in respect to 
the already included universal extension mechanism - to consider:

* aligning ACL content and "other" content on the same semantic level in 
the YANG module, and
* maybe indicating the corresponding semantics of the MUD file in the 
MUD URI itself.

### Intended & Allowed Representations/Formats

The assumption is that neither the MUD controller nor the server serving 
the MUD files are constrained devices. The things that the imperative 
guidance is intended to address can be constrained devices. YANG modules 
are used to create the MUD files and the representation in the MUD files 
is JSON.

In the scope of the extensibility feature highlighted, is it intended 
that every MUD file must contain content that relates to the structure 
of a YANG module (or are there other data models for data at rest 
planned for)?

Is JSON intended to be the only allowed representation used for the 
representation of content in MUD files (a question in respect to the 
CBOR-based CoMI draft in the CORE WG)?

### Segment "mud-rev"

There seems to be conflicting definitions about the semantic of the 
segment "mud-rev":

Section "5. What does a MUD URL look like?" states that a "mud-rev 
signifies the version of the manufacturer usage description file" and 
"this memo specifies "v1" of that file". The passages quoted here seem 
to imply that mud-rev is about the instance of JSON that is the content 
of the MUD file.

Section "13. Extensibility" though states "at a coarse grain, a protocol 
version is included in a MUD URL. This memo specifies MUD version 1. Any 
and all changes are entertained when this version is bumped.", which 
implies that mud-rev is intended to state the version of the MUD 
protocol and probably the respective YANG module(s).

Probably, you want both? Most certainly, this has to be clarified.

### Segment "model"

Every device typically is a composite. Similarly, the hardware 
device-model identifier is a potential composite of device-type, 
device-model & device-version (and probably even more). The text is very 
vague on this part, maybe deliberatively so because the authors do not 
want to prescribe how to compose the string that constitutes the model 
segment - but a bit more guidance on what this typically means and what 
could be caveats if you concatenate this potentially very complex 
identifier into a single string is strongly recommended.

Also, model is supposed to include in a not further specified way an 
identifier of the "version" of the software next to the "version" of the 
hardware. Even in very small things, software components can be 
composites, too. Furthermore, a software version may run on more than 
one device-model or even device-type. While it might introduce 
complexity in respect to URI composition (one/two extra segments), 
separating the hardware composite-identifier from the software/firmware 
composite-identifier will be helpful and provide more clear semantics to 
both humans and machines.

### Query "extra"

While this option is included in the composition guidance of a MUD URI, 
it is not included in the text anywhere. One guess of its purpose could 
be to provide subsets of the modules via xpath or subtree expressions. 
Is that the case? Additionally, including a variable in an immutable 
container, e.g. DevID, seems to negate the intend of it being a 
variable? Maybe this should be highlighted in the upcoming section that 
illustrates what the "extra" query option is for?

### Signing MUD files

The given openssl example basically allows for every kind of 
certificate- or key-type. Is that intentional? While most individuals 
will be able to inflate "mancertfile" or "mankey" to manufacturer 
certificate and manufacturer key, respectively, I strongly recommend to 
provide more guidance here - especially in regard to command parameters 
and appropriate hash and cipher algorithms with a low footprint. 
Providing examples here will be beneficial (maybe ECDSA & EDDSA).

## Nits

What does the expression "relative to XML"  intends to convey in "JSON 
is used as a serialization for compactness and readability, relative to 
XML."?

%s/Application\/pkcs7-signature/application\/pkcs7-signature/g

---

From: Eliot Lear <[email-masked]>
Date: Wed, 30 Aug 2017 09:56:09 +0200

Hi Henk and thanks very much for your review.

Please see below.

On 8/29/17 11:40 PM, Henk Birkholz wrote:
> specific resource called a MUD file. A MUD file is a text resource
> that contains imperative guidance in the form of YANG-based ACL
> policies represented in JSON. The imperative guidance is intended to
> be applied to things that can be identified by the segments of the MUD
> URI via a specific controller. The version of MUD is a component
> (segment) of the MUD URI and there are three examples in what to embed
> a MUD URI in (DHCP option, X.509 extension, and LLDP extension).
>
> lot of usage scenarios, it might not be feasible to store that
> guidance on the thing itself and MUD URI could be a solution to
> support a lot of vendor supplied information, such as reference
> integrity measurements, intended composition of composite devices, etc.

Ok, but a cautionary note: this draft intentionally focuses NOT on
giving the Thing guidance but on giving the *network* guidance.  That
isn't to say that Things couldn't derive guidance from extensions to the
model (we'll talk about that below), but at the moment, the pain point
is protecting them.

> architecture to the use of one specific branch of YANG modules
> regarding ACL policies. There is no way to express other manufacture
> usage description "information-types" or "content-types" on a
> fundamental level and section 13 specifically states that "coupled
> with the fact that we have also chosen to leverage existing
> mechanisms, we are left with no ability to negotiate extensions and a
> limited desire for those extensions in any event."
>
> Creating augments for the metainfo container as it is also described
> in Section 13, on the other hand, allows for virtually any kind of
> * aligning ACL content and "other" content on the same semantic level
> in the YANG module, and

On the first point, that is precisely the intent of the previous reorg,
to demote, if you will, access control so that other mechanisms can be
employed.  I'll speak more to this below.

On the second point, one reason for referencing information is so that
the underlying information can change as needed without the need to
change the URL itself.  While it may be possible in some instances to
update the URL, this will not always be the case.   Consider that the
URL may be inside a signed certificate that is burned into the device. 
This having been said, we leave open the possibility that the MUD
controller may wish to modify the URI through "extras".  See below for
more details.

> The assumption is that neither the MUD controller nor the server
> serving the MUD files are constrained devices. The things that the
> imperative guidance is intended to address can be constrained devices.
> YANG modules are used to create the MUD files and the representation
> in the MUD files is JSON.
That is indeed the assumption.  The initial consumers of this
information are going to be switches and access control systems that
generally speaking can easily parse JSON.  Furthermore, at least as we
get started, it's important for humans to be able to read and debug this
stuff.
> of a YANG module (or are there other data models for data at rest

If the extension augments the YANG module then, well, yes ;-)  On the
other hand, if the extension is a reference to something else, then the
rules are up to that "something else".  Let's take an example.  Suppose
there is an extension that points to some form of WoT/schema.org-based
description.  That description could be in the form of a URN, that a
network might use to populate a CoAP resource directory, that other
Things could then retrieve.  The rules for the form of all of that would
be well outside the scope of MUD, which would be a good thing, because I
just referenced a bunch of stuff that you know a lot more about than I
do ;-)  All the encoding rules and semantics are left to you to define. 
At that point, a network management system would have to obey your
semantics if the device wants want to play.

If you like the above text, we could add something like it.

> CBOR-based CoMI draft in the CORE WG)?

Yes, for reasons given above.
> to imply that mud-rev is about the instance of JSON that is the
> content of the MUD file.

I wouldn't go that far.  The point of externalizing the version # from
JSON is so that the next version could return something else.  Many of
us have lived through ASN.1 BER/DER, SGML, HTML, XML, RDF (and numerous
other forms of XML), JSON, CBOR, and YAML in all of its looseness.  It
would be presumptuous to believe that either JSON or CBOR are the be-all
end-all, especially since we're discussing them here.  Also, one could
easily envision an entire conceptual reorganization in the next version,
but let's hope that will be down the road a bit.

Having written all of this, clearly the draft led you who are
knowledgeable in this subject to somehow believe otherwise.  If there is
a textual change that clarify that, let's make it.

>
> Section "13. Extensibility" though states "at a coarse grain, a
> protocol version is included in a MUD URL. This memo specifies MUD
> version 1. Any and all changes are entertained when this version is
> bumped.", which implies that mud-rev is intended to state the version
> of the MUD protocol and probably the respective YANG module(s).
>
> device-model & device-version (and probably even more). The text is
> very vague on this part, maybe deliberatively so because the authors
> do not want to prescribe how to compose the string that constitutes
> the model segment - but a bit more guidance on what this typically
> means and what could be caveats if you concatenate this potentially
> very complex identifier into a single string is strongly recommended.
>
> identifier of the "version" of the software next to the "version" of
> the hardware. Even in very small things, software components can be
> separating the hardware composite-identifier from the
> software/firmware composite-identifier will be helpful and provide
> more clear semantics to both humans and machines.

You've caught an important point, and we should review the text:

OLD:
> This string matches the entire MUD URL, thus covering the model that
> is unique within the context of the authority.  It may also include
> product version information.  Thus how this field is constructed is
> entirely a local matter for the manufacturer.

I propose the following to address your point:

NEW:

>
> This string matches the entire MUD URL, thus covering the model that
> is unique within the context of the authority.  It is attended to
> uniquely identify
> a particular class of device.  It may contain not only model
> information, but
> versioning information as well, and any other information that the
> manufacturer
> wishes to add.  The intended use is for devices of this precise class
> to match, to permit or
> deny communication between one another.

To make this point clearer, I also propose a change to the non-terminal
in the ABNF to avoid confusion, as well as a modest change to the text
that follows.
>
> ### Query "extra"
>
> While this option is included in the composition guidance of a MUD
> URI, it is not included in the text anywhere. One guess of its purpose
> could be to provide subsets of the modules via xpath or subtree
> expressions. Is that the case? Additionally, including a variable in
> an immutable container, e.g. DevID, seems to negate the intend of it
> being a variable? Maybe this should be highlighted in the upcoming
> section that illustrates what the "extra" query option is for?
Here I can only but agree that "extra" is under-specified, and I believe
an earlier reviewer mentioned this as well.  Here is what I have in mind
for text:

NEW:

> "extras" is intended for use by the MUD controller to provide
> additional information such as posture about the Thing to the MUD file
> server.     This field MUST not be configured on the Thing itself by a
> manufacturer - that is what "modelinfo" is for.  It is left as future
> work to define the full semantics of this field.

> certificate and manufacturer key, respectively, I strongly recommend
> to provide more guidance here - especially in regard to command
> parameters and appropriate hash and cipher algorithms with a low
> footprint. Providing examples here will be beneficial (maybe ECDSA &
> EDDSA).

Keep in mind that the signature is intended to be consumed by a MUD
controller.  This having been said, I'll examine this and see if we can
add guidance.

> is used as a serialization for compactness and readability, relative
> to XML."?

I don't know about you, but I find XML as easy to parse as binary.  I
say, relative to XML because I certainly don't want to claim that JSON
is EASIEST for humans to read.  A natural language such as English or
German is far easier.

> %s/Application\/pkcs7-signature/application\/pkcs7-signature/g

Very good.  I hope this answer addresses your issues.

Eliot

---

From: Henk Birkholz <[email-masked]>
Date: Wed, 30 Aug 2017 18:50:18 +0200

Hello Eliot,

thank you for your fast feedback! I still have some comments and 
questions for another round, though. I hope that is okay - please see 
comments in-line.

Viele Grüße,

Henk

> model (we'll talk about that below), but at the moment, the pain point

This has to be clearly stated in the abstract and the introduction, I 
think. From my point of view, filter rules that are disabler and enabler 
of communication are a very specific subset of imperative network 
guidance, which are a distinct subset of the the usage descriptions a 
manufacturer would want to provide for a thing.

To give a specific example: the passage "These devices therefore have a 
purpose to their use. By definition, therefore, all other purposes are 
NOT intended." is basically mirroring the definition of verifying if a 
thing is a Trusted System (see RFC4949), which can require, for example, 
reference integrity measurements (RIM) to enable integrity appraisal or 
Security Profiles to enable enforcement. But as you state, these are out 
of the scope of the document.

I would propose to compose an abstract and introduction that is limited 
to what MUD is intended to do - to provide ACL for a specific class of 
devices - up front. because the architecture of your solution would be 
able to address a lot of complementary requirements that are explicitly 
not in scope, as it seems.

> employed.  I'll speak more to this below.

Maybe an example on how to include a trivial non-ACL-focussed extension 
into the module via an (exemplary/bogus) augment would clarify how to 
include "other" content in a MUD file. A corresponding example of a JSON 
instance (MUD file) that then includes content defined by the augment 
would also be beneficial, I think.

Would that be okay?

> controller may wish to modify the URI through "extras".  See below for

Please also consider that the URI can be composed. Most of its parts 
(segments, etc.) are probably represented redundantly in a DevID or can 
be inferred from context (MUD controller, domain, etc.). For example, 
you could get the content of most of the segments out of the attributes 
that are already stored in the DevID and just include the "missing 
additional parts" in a specific "mud-attribute". This is possible, 
because there is a precise rule how to compose the MUD URI canonically. 
Next to "arcance content" and unnecessary verbose encoding, redundancy 
inside Identity Documents is a problem the constrained-node network 
world is struggling with.

Also, this "burning in" is only effecting content of URI path segments 
that are to be defined by the manufacturer. If there would be a 
canonical tree of paths coming after the

> "/.well-known/mud/" mud-rev "/" model

e.g. a set of paths segments/branches, such as

> "/" acl|rim|composition

then there would be no problem to provide semantic separate MUD files, 
because it would be the canonical URI where to find them - circumventing 
the "burned into the device" issue. You only need to find the "burned 
in" values to compose your canonical MUD URI. A task presumably 
conducted by the MUD controller. Would that be correct?

> get started, it's important for humans to be able to read and debug this

It was not my intention to open the box of worms that is "what is a 
readable representation" :) Having said that, I will come back to this 
at the end, anyways. I am okay with JSON in v1.

Please allow me to mention, for me (human), starting cat or openssl in 
order to read the content of a file makes no difference in respect to 
debugging.

> If you like the above text, we could add something like it.

Yes please. I actually thought that this was out-of-scope at the moment.

Please let me highlight here, the canonical composition of the MUD URI 
is the center-piece of all of this, I think.

> Yes, for reasons given above.

I am okay with JSON in v1 here, but see my reasoning below for why I 
think otherwise, in general.

> a textual change that clarify that, let's make it.

As a reader of the document, I just want to know under which conditions 
the version will change from v1 to something else. At the moment the 
text picks up on that MUD version at multiple places and in different 
ways somehow. Consolidating that into one place and illustrating the 
exact conditions in which there will be a version change, will address 
this comment, I think.

>> deny communication between one another.

I am okay with the change. It still mixes hardware and software 
identifiers, but if that is okay for the group, it is okay with me.

>> work to define the full semantics of this field.

Could you please provide an example of "posture about the Thing" that 
could be requested as an option from the MUD file server by the MUD 
controller? I am still not really sure what to make of it. If this is 
future work in the scope of this draft, we can just revisit this at a 
later point.

> controller.  This having been said, I'll examine this and see if we can

In general, the MUD controller might benefit from canonical guidance 
what signature to expect and how to verify it. Because, as it seems to 
be at the moment, the manufacturer decides on this, right? Could getting 
this information be one of the uses of the extra query?

> is EASIEST for humans to read.  A natural language such as English or

Coming back to the box of worms "easy to read" :) If I look at a raw 
JSON file without line-breaks it is "impossible" for me to read (aka I 
can, but it stresses me out). The same way I can read a DevID via a hex 
viewer (but that also stresses me out). JSON becomes easy to read for 
me, if I pipe it into jq. A DevID becomes easy to read for me, if I 
decode it with (admittedly, an appropriate version of) openssl. From a 
workflow point of view, there is no difference for me, personally.

And off-topic and most certainly not intended to be implying the 
discussed draft: sometimes, the most tedious thing for me to do, is to 
distill the actual meaning out of easy to read English or German text ;)

Viele Grüße,

Henk

---

From: Eliot Lear <[email-masked]>
Date: Thu, 31 Aug 2017 13:52:40 +0200

Hi Henk,

> questions for another round, though. I hope that is okay - please see

Soon, please.
> think. From my point of view, filter rules that are disabler and
> enabler of communication are a very specific subset of imperative
> network guidance, which are a distinct subset of the the usage
> descriptions a manufacturer would want to provide for a thing.
>

Taken together with Robert's comments, I'm proposing the following changes:

The abstract:

OLD:

> This memo specifies a component-based architecture for manufacturer
> usage descriptions (MUD). This includes two YANG modules, IPv4 and IPv6
> DHCP options, an LLDP TLV, a URL suffix specification, an X.509
> certificate
> extension and a means to sign and verify the descriptions.

NEW:

> This memo specifies a component-based architecture for manufacturer
> usage descriptions (MUD). The goal of MUD is to provide a means for
> Things to signal to the network what sort of access and network
> functionality they require to properly function.  The initial focus is
> on access control.  Later work can delve into other aspects.
>
> This memo specifies two YANG modules, IPv4 and IPv6 DHCP options, an
> LLDP TLV, a URL suffix specification, an X.509 certificate extension
> and a means to sign and verify the descriptions.

> Maybe an example on how to include a trivial non-ACL-focussed
> extension into the module via an (exemplary/bogus) augment would
> clarify how to include "other" content in a MUD file. A corresponding
> example of a JSON instance (MUD file) that then includes content
> defined by the augment would also be beneficial, I think.
>
> Would that be okay?
>

Ok, with the understanding that it is illustrative.  Someone who shall
remain nameless for just the moment talked about an indicator as to
whether DETNET is used.  I've done that, complete with serialization for
the new draft.  Ironically for brevity purposes, I will not include it
here ;-)

> (segments, etc.) are probably represented redundantly in a DevID or
> can be inferred from context (MUD controller, domain, etc.). For
> example, you could get the content of most of the segments out of the
> attributes that are already stored in the DevID and just include the
> "missing additional parts" in a specific "mud-attribute". This is
> possible, because there is a precise rule how to compose the MUD URI
> canonically. Next to "arcance content" and unnecessary verbose
> encoding, redundancy inside Identity Documents is a problem the
> constrained-node network world is struggling with.
>
> because it would be the canonical URI where to find them -
> circumventing the "burned into the device" issue. You only need to
> find the "burned in" values to compose your canonical MUD URI. A task
> presumably conducted by the MUD controller. Would that be correct?
>

Right.  We discussed this in the working group, and substantial issues
developed, mostly around versioning.  On the whole we must be very
cautious in these circumstances around composibility, especially when it
introduces either linkage or complexity.  This, to be sure, is a tradeoff.

{{json readability discussion elided}}
> Yes please. I actually thought that this was out-of-scope at the moment.

As it happens, we have something of a good example of how that might be
done, already in the draft.  It's the masa-server node.  There we don't
attempt to define all the semantics of BRSKI, but instead simply
reference the work.  One could easily do that again as an extension. 
Therefore, I propose the following text:

OLD:

> This optional leaf-list names MUD extensions that are used in the MUD
> file.
> Note that NO MUD extensions may be used in a MUD file prior to the
> extensions
> being declared.  Implementations MUST ignore any elements in this file
> that
> they do not understand.

NEW:

> This optional leaf-list names MUD extensions that are used in the MUD
> file.
> Note that NO MUD extensions may be used in a MUD file prior to the
> extensions
> being declared.  Implementations MUST ignore any node in this file that
> they do not understand. The extensions list MUST appear prior to
> extension use.
>
> Note that extensions can either extend the MUD file as described in
> the previous paragraph, or they might reference other work.  A good
> example of how this might be done is the masa-server URI that is
> defined in the base model.  We say nothing about the semantics of that
> work here, but rather leave that to the underlying specification found in
> {{I-D.anima-bootstrapping-keyinfra}}.

{{snip}}

> future work in the scope of this draft, we can just revisit this at a

Sure.  Think about NEA values as parameters (RFC 5209) as an example.
> be at the moment, the manufacturer decides on this, right? Could
> getting this information be one of the uses of the extra query?

I'm not particularly comfortable with that for a few reasons, the first
of which is that this seems like a possible downgrade attack, should the
device specify weak algorithm choices, and the second is that CMS is
already self-contained.  Again, let's ponder your original point a bit.

Eliot