Subject: [Netconf] Comments on draft-ietf-netconf-restconf-14

From: [email-masked] (Dale R. Worley)
Date: Wed, 29 Jun 2016 16:30:37 -0400

These are derived from my "Comments on draft-ietf-netconf-restconf-13",
updated based on the -14 draft.

3.6

In 3.6.1 is:

   <input xmlns="https://example.com/ns/example-ops">

This means the 'input' element of an RPC body is in the namespace of
the module.  Similarly for 'output' elements.  This is not specified
anywhere.  (Errors is specified to be in "ietf-restconf" in section
7.1.)

Perhaps the way to clarify this is to change this paragraph

   If the "rpc" or "action" statement has an "input" section then
   instances of these input parameters are encoded in the module
   namespace where the "rpc" or "action" statement is defined, in an XML
   element or JSON object named "input".

into, perhaps, this

   If the "rpc" or "action" statement has an "input" section then
   instances of these input parameters are encoded in an XML element
   or JSON object named "input", which is in the module namespace
   where the "rpc" or "action" statement is defined.

The parallel change for "output" is (also correcting the typo "input"
to "output")

   If the "rpc" or "action" statement has an "output" section then
   instances of these >>output<< parameters are encoded in an XML element
   or JSON object named "output", which is in the module namespace
   where the "rpc" or "action" statement is defined.

This is just a rearrangement of the phrases of these sentences, but
they put the "input"/"output" element/object in the specified
namespace (and by implication, the input/output parameters are also).

3.6.1

   If the "rpc" or "action" statement has an "input" section, then the
   "input" node is provided in the message-body, corresponding to the
   YANG data definition statements within the "input" section.

This paragraph is an almost-clone of a paragraph in 3.6.  If
repetition is intended, it should probably be updated from the changed
wording in 3.6

3.6.2

   If the "rpc" or "action" statement has an "output" section, then the
   "output" node is provided in the message-body, corresponding to the
   YANG data definition statements within the "output" section.

This paragraph is an almost-clone of a paragraph in 3.6.  If
repetition is intended, it should probably be updated from the changed
wording in 3.6

4.3

   Note that the way that access control is applied to data resources is
   completely incompatible with HTTP caching.  The Last-Modified and
   ETag headers maintained for a data resource are not affected by
   changes to the access control rules for that data resource.  It is
   possible for the representation of a data resource that is visible to
   a particular client to be changed without detection via the Last-
   Modified or ETag values.

Note that it's possible for the client to detect changes in
configuration data that it is not allowed to read by detecting changes
in the Last-Modified/ETag values.  This probably isn't a security
problem, but the authors should be aware of it.

4.6

   Each patch mechanism needs a unique media type.  Zero or more patch
   media types MAY be supported by the server.  The media types
   supported by a server can be discovered by the client by sending an
   OPTIONS request (see Section 4.1).

To prevent the reader from making the mistake I just made, it would be
helpful to explicitly state that it is the Accept-Patch header in the
OPTIONS response, rather than an enumeration of the allowed content
types generally, that should be examined.  (An enumeration of allowed
content types generally doesn't exist in HTTP, but does in SIP.)

   A server's response to an OPTIONS request (see Section 4.1) lists
   the patch media types it supports in the Accept-Patch header.

4.6

Yang has been extended to allow non-unique key values.  The result is
that URLs may identify multiple data instances.  This seems to be
specified for GET (if JSON is used, GET can return multiple instances;
if XML is used, a 400 response is given) and DELETE (only one instance
(arbitrarily chosen) is deleted; this may be modified by query
parameters).  But PATCH does not seem to specify the behavior if
multiple instances are selected.

4.8.2

   By default, the server will include all sub-resources within a
   retrieved resource, which have the same resource type as the
   requested resource.  Only one level of sub-resources with a different
   media type than the target resource will be returned.  The exception
   is the datastore resource.  If this resource type is retrieved then
   by default the datastore and all child data resources are returned.

[Note for the -13 draft:]  Does the second sentence do anything?  The
only instance I know of of a node whose media type is different from
that of its child nodes is the the datastore resource, and that is
specifically exempted from the effect of the 2nd sentence.

With the -14 draft, there are only two media types, and which one is
used to report the contents of a resource is determined by the client,
as a choice of encoding, rather than as an attribute of the resource.
So I think this paragraph has no effect any more.

12.  Security Considerations

    The lowest NETCONF layer is the secure transport layer,
   and the mandatory-to-implement secure transport is Secure Shell
   (SSH) ^RFC6242^. The NETCONF access control model ^RFC6536^
   provides the means to restrict access for particular NETCONF users
   to a pre-configured subset of all available NETCONF protocol
   operations and content.

The formatting of this paragraph is damaged:  There is an extra space
at its beginning, and references are marked ^...^ rather than [...].

13

Who is The Space & Terrestrial Communications Directorate?  Maybe it
would add to the credit of the S&TCD by prefixing the country that
funds it ... which seems to be "United States Army".

Dale

---

From: Andy Bierman <[email-masked]>
Date: Wed, 29 Jun 2016 13:36:18 -0700

> anywhere.  (Errors is specified to be in "ietf-restconf" in section

But this would just restate normative text from YANG, right?
RESTCONF does not need to define the module namespace for the input-stmt.

Andy

> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>

---

From: [email-masked] (Dale R. Worley)
Date: Thu, 30 Jun 2016 11:38:40 -0400

> RESTCONF does not need to define the module namespace for the input-stmt.

Netconf does define the module namespace for the input schema node.  But
Restconf does *not* define that the input element in the RPC request is
an instance of that input schema node -- if you read the text exactly.
What is does say is that the *parameters* are instances of the schema
nodes, which are the children of the input schema node, but it doesn't
say anything about the input element (the parent of the parameters)

Dale

---

From: Andy Bierman <[email-masked]>
Date: Thu, 30 Jun 2016 10:41:49 -0700

> say anything about the input element (the parent of the parameters)
OK -- I think YANG sec.7.14.4 covers the issue, but it can be restated so
the "input" node is mentioned.  Seems obvious to me from the YANG RFC
this is the case.

Andy

---

From: Andy Bierman <[email-masked]>
Date: Thu, 30 Jun 2016 19:33:16 -0700

Hi,

I have made all the edits except the 2nd 4.6 below

Andy

>    where the "rpc" or "action" statement is defined.

done

> namespace (and by implication, the input/output parameters are also).
done

> repetition is intended, it should probably be updated from the changed

done; added clarification

> repetition is intended, it should probably be updated from the changed

done; added clarification

> problem, but the authors should be aware of it.

done; added security considerations note

>    the patch media types it supports in the Accept-Patch header.

done; added clarification

> multiple instances are selected.

*** not sure what the previous comment is requested... perhaps sec. #  is
wrong

> specifically exempted from the effect of the 2nd sentence.

done; 2nd sentence remoted

> So I think this paragraph has no effect any more.
Only the 2nd sentence mentioned media type, which is now removed.
It is relevant for resource types.  We don't want a GET of the entry point
to return all the data resources.

> at its beginning, and references are marked ^...^ rather than [...].
done; also caused the reference to RFC 6242 to be missed

> funds it ... which seems to be "United States Army".

done