< draft-ietf-core-comi-05.txt   draft-ietf-core-comi-06.txt >
CoRE M. Veillette, Ed. CoRE M. Veillette, Ed.
Internet-Draft Trilliant Networks Inc. Internet-Draft Trilliant Networks Inc.
Intended status: Standards Track P. van der Stok, Ed. Intended status: Standards Track P. van der Stok, Ed.
Expires: November 16, 2019 consultant Expires: January 10, 2020 consultant
A. Pelov A. Pelov
Acklio Acklio
A. Bierman A. Bierman
YumaWorks YumaWorks
May 15, 2019 I. Petrov, Ed.
Acklio
July 09, 2019
CoAP Management Interface CoAP Management Interface
draft-ietf-core-comi-05 draft-ietf-core-comi-06
Abstract Abstract
This document describes a network management interface for This document describes a network management interface for
constrained devices and networks, called CoAP Management Interface constrained devices and networks, called CoAP Management Interface
(CoMI). The Constrained Application Protocol (CoAP) is used to (CoMI). The Constrained Application Protocol (CoAP) is used to
access datastore and data node resources specified in YANG, or SMIv2 access datastore and data node resources specified in YANG, or SMIv2
converted to YANG. CoMI uses the YANG to CBOR mapping and converts converted to YANG. CoMI uses the YANG to CBOR mapping and converts
YANG identifier strings to numeric identifiers for payload size YANG identifier strings to numeric identifiers for payload size
reduction. The complete solution composed of CoMI, reduction. The complete solution composed of CoMI,
skipping to change at page 2, line 4 skipping to change at page 2, line 6
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on November 16, 2019.
This Internet-Draft will expire on January 10, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 27 skipping to change at page 2, line 30
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Major differences between RESTCONF and CoMI . . . . . . . 6 2.1. Major differences between RESTCONF and CoMI . . . . . . . 6
2.1.1. Differences due to CoAP and its efficient usage . . . 6
2.1.2. Differences due to the use of CBOR . . . . . . . . . 7
2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7
2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8 2.3. Instance identifier . . . . . . . . . . . . . . . . . . . 8
2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8
2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10
3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11
4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13
4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14
4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15
skipping to change at page 2, line 47 skipping to change at page 3, line 4
4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19
4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19
4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 19 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 20 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21
4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22
4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23
4.4.1. Full datastore examples . . . . . . . . . . . . . . . 23 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 23
4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24
4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25
4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26 4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26
4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27
4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27
5. Use of Block-wise Transfers . . . . . . . . . . . . . . . . . 29
5. Use of Block . . . . . . . . . . . . . . . . . . . . . . . . 29
6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29
6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29
6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30
6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30
6.2.2. Data node Resource Discovery . . . . . . . . . . . . 30 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 30
6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31
7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31
8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35
9.1. Resource Type (rt=) Link Target Attribute Values Registry 35 9.1. Resource Type (rt=) Link Target Attribute Values Registry 35
skipping to change at page 3, line 50 skipping to change at page 4, line 9
structured data defined in YANG. structured data defined in YANG.
The use of standardized data models specified in a standardized The use of standardized data models specified in a standardized
language, such as YANG, promotes interoperability between devices and language, such as YANG, promotes interoperability between devices and
applications from different manufacturers. applications from different manufacturers.
CoMI and RESTCONF are intended to work in a stateless client-server CoMI and RESTCONF are intended to work in a stateless client-server
fashion. They use a single round-trip to complete a single editing fashion. They use a single round-trip to complete a single editing
transaction, where NETCONF needs multiple round trips. transaction, where NETCONF needs multiple round trips.
To promote small messges, CoMI uses a YANG to CBOR mapping To promote small messges, CORECONF uses a YANG to CBOR mapping
[I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid]
to minimize CBOR payloads and URI length. to minimize CBOR payloads and URI length.
1.1. Terminology 1.1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in [RFC2119]. "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
The following terms are defined in the YANG data modelling language The following terms are defined in the YANG data modelling language
[RFC7950]: action, anydata, anyxml, client, container, data model, [RFC7950]: action, anydata, anyxml, client, container, data model,
data node, identity, instance identifier, leaf, leaf-list, list, data node, identity, instance identifier, leaf, leaf-list, list,
module, RPC, schema node, server, submodule. module, RPC, schema node, server, submodule.
The following terms are defined in [RFC6241]: configuration data, The following terms are defined in [RFC6241]: configuration data,
datastore, state data datastore, state data
The following term is defined in [I-D.ietf-core-sid]: YANG schema The following term is defined in [I-D.ietf-core-sid]: YANG schema
skipping to change at page 5, line 16 skipping to change at page 5, line 25
Schema node values are serialized into the payload according to Schema node values are serialized into the payload according to
the rules defined in section 4 of [I-D.ietf-core-yang-cbor]. the rules defined in section 4 of [I-D.ietf-core-yang-cbor].
2. CoMI Architecture 2. CoMI Architecture
This section describes the CoMI architecture to use CoAP for reading This section describes the CoMI architecture to use CoAP for reading
and modifying the content of datastore(s) used for the management of and modifying the content of datastore(s) used for the management of
the instrumented node. the instrumented node.
+----------------------------------------------------------------+ +----------------------------------------------------------------+
| SMIv2 specification (2) | | SMIv2 specification (optional) (2) |
+----------------------------------------------------------------+ +----------------------------------------------------------------+
| |
V V
+----------------------------------------------------------------+ +----------------------------------------------------------------+
| YANG specification (1) | | YANG specification (1) |
+----------------------------------------------------------------+ +----------------------------------------------------------------+
| | | |
Client V Server V Client V Server V
+----------------+ +-----------------------+ +----------------+ +-----------------------+
| Request |--> CoAP request(3) -->| Indication | | Request |--> CoAP request(3) -->| Indication |
skipping to change at page 5, line 46 skipping to change at page 6, line 8
Figure 1: Abstract CoMI architecture Figure 1: Abstract CoMI architecture
Figure 1 is a high-level representation of the main elements of the Figure 1 is a high-level representation of the main elements of the
CoMI management architecture. The different numbered components of CoMI management architecture. The different numbered components of
Figure 1 are discussed according to component number. Figure 1 are discussed according to component number.
(1) YANG specification: contains a set of named and versioned (1) YANG specification: contains a set of named and versioned
modules. modules.
(2) SMIv2 specification: A named module specifies a set of variables (2) SMIv2 specification: Optional part that consists of a named
and "conceptual tables". There is an algorithm to translate SMIv2 module which, specifies a set of variables and "conceptual
specifications to YANG specifications. tables". There is an algorithm to translate SMIv2 specifications
to YANG specifications.
(3) CoAP request/response messages: The CoMI client sends request (3) CoAP request/response messages: The CoMI client sends request
messages to and receives response messages from the CoMI server. messages to and receives response messages from the CoMI server.
(4) Request, Indication, Response, Confirm: Processes performed by (4) Request, Indication, Response, Confirm: Processes performed by
the CoMI clients and servers. the CoMI clients and servers.
(5) Datastore: A resource used to access configuration data, state (5) Datastore: A resource used to access configuration data, state
data, RPCs and actions. A CoMI server may support a single data, RPCs and actions. A CoMI server may support a single
unified datastore or multiple datastores as those defined by unified datastore or multiple datastores as those defined by
skipping to change at page 6, line 28 skipping to change at page 6, line 39
(7) Security: The server MUST prevent unauthorized users from (7) Security: The server MUST prevent unauthorized users from
reading or writing any CoMI resources. CoMI relies on security reading or writing any CoMI resources. CoMI relies on security
protocols such as DTLS [RFC6347] to secure CoAP communications. protocols such as DTLS [RFC6347] to secure CoAP communications.
2.1. Major differences between RESTCONF and CoMI 2.1. Major differences between RESTCONF and CoMI
CoMI is a RESTful protocol for small devices where saving bytes to CoMI is a RESTful protocol for small devices where saving bytes to
transport counts. Contrary to RESTCONF, many design decisions are transport counts. Contrary to RESTCONF, many design decisions are
motivated by the saving of bytes. Consequently, CoMI is not a motivated by the saving of bytes. Consequently, CoMI is not a
RESTCONF over CoAP protocol, but differs more significantly from RESTCONF over CoAP protocol, but differs more significantly from
RESTCONF. Some major differences are cited below: RESTCONF.
2.1.1. Differences due to CoAP and its efficient usage
o CoMI uses CoAP/UDP as transport protocol and CBOR as payload o CoMI uses CoAP/UDP as transport protocol and CBOR as payload
format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as
transport protocol and JSON or XML as payload formats. transport protocol and JSON or XML as payload formats.
o CoMI encodes YANG identifier strings as numbers, where RESTCONF
does not.
o CoMI uses the methods FETCH and iPATCH to access multiple data o CoMI uses the methods FETCH and iPATCH to access multiple data
nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP
method GET with the "fields" Query parameter. method GET with the "fields" Query parameter.
o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not
supported by CoAP. supported by CoAP.
o CoMI does not support "insert" query parameter (first, last, o CoMI does not support "insert" query parameter (first, last,
before, after) and the "point" query parameter which are supported before, after) and the "point" query parameter which are supported
by RESTCONF. by RESTCONF.
o CoMI does not support the "start-time" and "stop-time" query o CoMI does not support the "start-time" and "stop-time" query
parameters to retrieve past notifications. parameters to retrieve past notifications.
o CoMI does not support the "filter" query parameters to observe a o CoMI does not support the "filter" query parameters to observe a
specific set of notifications. specific set of notifications.
2.1.2. Differences due to the use of CBOR
o CoMI encodes YANG identifier strings as numbers, where RESTCONF
does not.
o CoMI also differ in the handling of default values, only 'report- o CoMI also differ in the handling of default values, only 'report-
all' and 'trip' options are supported. all' and 'trip' options are supported.
2.2. Compression of YANG identifiers 2.2. Compression of YANG identifiers
In the YANG specification, items are identified with a name string. In the YANG specification, items are identified with a name string.
In order to significantly reduce the size of identifiers used in In order to significantly reduce the size of identifiers used in
CoMI, numeric identifiers are used instead of these strings. YANG CoMI, numeric identifiers are used instead of these strings. YANG
Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor] Schema Item iDentifier (SID) is defined in [I-D.ietf-core-yang-cbor]
section 2.1. section 2.1.
When used in a URI, SIDs are encoded in based64 using the URL and When used in a URI, SIDs are encoded in base64 using the URL and
Filename safe alphabet as defined by [RFC4648] section 5. The last 6 Filename safe alphabet as defined by [RFC4648] section 5, without
bits encoded is always aligned with the least significant 6 bits of padding. The last 6 bits encoded is always aligned with the least
the SID represented using an unsigned integer. 'A' characters (value significant 6 bits of the SID represented using an unsigned integer.
0) at the start of the resulting string are removed. 'A' characters (value 0) at the start of the resulting string are
removed.
SID in basae64 = URLsafeChar[SID >> 60 & 0x3F] | SID in base64 = URLsafeChar[SID >> 60 & 0x3F] |
URLsafeChar[SID >> 54 & 0x3F] | URLsafeChar[SID >> 54 & 0x3F] |
URLsafeChar[SID >> 48 & 0x3F] | URLsafeChar[SID >> 48 & 0x3F] |
URLsafeChar[SID >> 42 & 0x3F] | URLsafeChar[SID >> 42 & 0x3F] |
URLsafeChar[SID >> 36 & 0x3F] | URLsafeChar[SID >> 36 & 0x3F] |
URLsafeChar[SID >> 30 & 0x3F] | URLsafeChar[SID >> 30 & 0x3F] |
URLsafeChar[SID >> 24 & 0x3F] | URLsafeChar[SID >> 24 & 0x3F] |
URLsafeChar[SID >> 18 & 0x3F] | URLsafeChar[SID >> 18 & 0x3F] |
URLsafeChar[SID >> 12 & 0x3F] | URLsafeChar[SID >> 12 & 0x3F] |
URLsafeChar[SID >> 6 & 0x3F] | URLsafeChar[SID >> 6 & 0x3F] |
URLsafeChar[SID & 0x3F] URLsafeChar[SID & 0x3F]
skipping to change at page 8, line 21 skipping to change at page 8, line 35
the keys used to index within these list(s). the keys used to index within these list(s).
When part of a payload, instance identifiers are encoded in CBOR When part of a payload, instance identifiers are encoded in CBOR
based on the rules defined in [I-D.ietf-core-yang-cbor] section based on the rules defined in [I-D.ietf-core-yang-cbor] section
6.13.1. When part of a URI, the SID is appended to the URI of the 6.13.1. When part of a URI, the SID is appended to the URI of the
targeted datastore, the keys are specified using the 'k' URI-Query as targeted datastore, the keys are specified using the 'k' URI-Query as
defined in Section 4.1. defined in Section 4.1.
2.4. Content-Formats 2.4. Content-Formats
ComI uses Content-Formats based on the YANG to CBOR mapping specified CoMI uses Content-Formats based on the YANG to CBOR mapping specified
in [I-D.ietf-core-yang-cbor]. in [I-D.ietf-core-yang-cbor].
The following Content-formats are defined: The following Content-formats are defined:
application/yang-data+cbor: This Content-Format represents a CBOR application/yang-data+cbor: This Content-Format represents a CBOR
YANG document containing one or multiple data node values. Each YANG document containing one or multiple data node values. Each
data node is identified by its associated SID. data node is identified by its associated SID.
FORMAT: CBOR map of SID, instance-value FORMAT: CBOR map of SID, instance-value
The message payload of Content-Format 'application/yang-data+cbor' The message payload of Content-Format 'application/yang-data+cbor'
is encoded using a CBOR map. Each entry of this CBOR map is is encoded using a CBOR map. Each entry of this CBOR map is
composed of a key and a value. CBOR map keys are set to the SID composed of a key and a value. CBOR map keys are set to the SID
assigned to the data nodes, CBOR map values are set to the or SID deltas associated with the data nodes as defined in
instance value as defined in [I-D.ietf-core-yang-cbor] section 4. [I-D.ietf-core-yang-cbor] section 4, CBOR map values are set to
the instance value as defined in [I-D.ietf-core-yang-cbor] section
4.
application/yang-identifiers+cbor: This Content-Format represents a application/yang-identifiers+cbor: This Content-Format represents a
CBOR YANG document containing a list of instance identifier used CBOR YANG document containing a list of instance identifier used
to target specific data node instances within a datastore. to target specific data node instances within a datastore.
FORMAT: CBOR array of instance-identifier FORMAT: CBOR array of instance-identifier
The message payload of Content-Format 'application/yang- The message payload of Content-Format 'application/yang-
identifiers+cbor' is encoded using a CBOR array. Each entry of identifiers+cbor' is encoded using a CBOR array. Each entry of
this CBOR array contain an instance identifier encoded as defined this CBOR array contain an instance identifier encoded as defined
skipping to change at page 10, line 40 skipping to change at page 10, line 40
| GET response | event stream | /application/yang-instances+cbor | | GET response | event stream | /application/yang-instances+cbor |
| | | | | | | |
| POST request | rpc, action | /application/yang-data+cbor | | POST request | rpc, action | /application/yang-data+cbor |
| | | | | | | |
| POST response | rpc, action | /application/yang-data+cbor | | POST response | rpc, action | /application/yang-data+cbor |
+---------------+--------------+------------------------------------+ +---------------+--------------+------------------------------------+
2.5. Unified datastore 2.5. Unified datastore
CoMI supports a simple datastore model consisting of a single unified CoMI supports a simple datastore model consisting of a single unified
datastore. This datasore provides access to both configuration and datastore. This datastore provides access to both configuration and
operational data. Configuration updates performed on this datastore operational data. Configuration updates performed on this datastore
are reflected immediately or with a minimal delay as operational are reflected immediately or with a minimal delay as operational
data. data.
Alternatively, CoMI servers MAY implement a more complex datastore Alternatively, CoMI servers MAY implement a more complex datastore
model such as the Network Management Datastore Architecture (NMDA) as model such as the Network Management Datastore Architecture (NMDA) as
defined by [RFC8342]. Each datastore supported is implemented as a defined by [RFC8342]. Each datastore supported is implemented as a
datastore resource. datastore resource.
Characteristics of the unified datastore are summarized in the table Characteristics of the unified datastore are summarized in the table
skipping to change at page 11, line 50 skipping to change at page 11, line 50
with example path: /c, where c is short-hand for CoMI. The path /c with example path: /c, where c is short-hand for CoMI. The path /c
is recommended, but not compulsory (see Section 6). is recommended, but not compulsory (see Section 6).
The mapping of YANG data node instances to CoMI resources is as The mapping of YANG data node instances to CoMI resources is as
follows. Every data node of the YANG modules loaded in the CoMI follows. Every data node of the YANG modules loaded in the CoMI
server represents a sub-resource of the datastore resource (e.g. /c/ server represents a sub-resource of the datastore resource (e.g. /c/
sid). When multiple instances of a list exist, instance selection is sid). When multiple instances of a list exist, instance selection is
possible as described in Section 4.1, Section 4.2.3.1, and possible as described in Section 4.1, Section 4.2.3.1, and
Section 4.2.4. Section 4.2.4.
CoMI also supports event stream resourced used to observe CoMI also supports event stream resources used to observe
notification instances. Event stream resources can be discovered notification instances. Event stream resources can be discovered
using resource type (rt): core.c.ev. using resource type (rt): core.c.ev.
The description of the CoMI management interface is shown in the The description of the CoMI management interface is shown in the
table below: table below:
+-------------+------------------+-----------+ +-------------+------------------+-----------+
| Function | Recommended path | rt | | Function | Recommended path | rt |
+-------------+------------------+-----------+ +-------------+------------------+-----------+
| Datastore | /c | core.c.ds | | Datastore | /c | core.c.ds |
| | | | | | | |
| Data node | /c/SID | core.c.dn | | Data node | /c/SID | core.c.dn |
| | | | | | | |
| Event steam | /s | core.c.ev | | Event steam | /s | core.c.ev |
+-------------+------------------+-----------+ +-------------+------------------+-----------+
The path values are example values. On discovery, the server makes The path values in the table are the recommended ones. On discovery,
the actual path values known for these resources. the server makes the actual path values known for these resources.
The methods used by CoMI are: The methods used by CoMI are:
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| Operation | Description | | Operation | Description |
+-----------+-------------------------------------------------------+ +-----------+-------------------------------------------------------+
| GET | Retrieve the datastore resource or a data node | | GET | Retrieve the datastore resource or a data node |
| | resource | | | resource |
| | | | | |
| FETCH | Retrieve specific data nodes within a datastore | | FETCH | Retrieve specific data nodes within a datastore |
skipping to change at page 14, line 6 skipping to change at page 14, line 6
| identityref | int2str(key) | | identityref | int2str(key) |
| | | | | |
| union | urlSafeBase64(CBORencode(key)) | | union | urlSafeBase64(CBORencode(key)) |
| | | | | |
| instance-identifier | urlSafeBase64(CBORencode(key)) | | instance-identifier | urlSafeBase64(CBORencode(key)) |
+-----------------------------+--------------------------------+ +-----------------------------+--------------------------------+
In this table: In this table:
o The method int2str() is used to convert an integer value to a o The method int2str() is used to convert an integer value to a
string. For example, int2str(0x0123) return the string "291". decimal string. For example, int2str(0x0123) return the string
"291".
o The method urlSafeBase64() is used to convert a binary string to o The method urlSafeBase64() is used to convert a binary string to
base64 using the URL and Filename safe alphabet as defined by base64 using the URL and Filename safe alphabet as defined by
[RFC4648] section 5. For example, urlSafeBase64(\xF9\x56\xA1\x3C) [RFC4648] section 5, without padding. For example,
return the string "-VahPA". urlSafeBase64(\xF9\x56\xA1\x3C) return the string "-VahPA".
o The method CBORencode() is used to convert a YANG value to CBOR as o The method CBORencode() is used to convert a YANG value to CBOR as
specified in [I-D.ietf-core-yang-cbor] section 6. specified in [I-D.ietf-core-yang-cbor] section 6.
The resulting key string is encoded in a Uri-Query as specified in The resulting key string is encoded in a Uri-Query as specified in
[RFC7252] section 6.5. [RFC7252] section 6.5.
4.2. Data Retrieval 4.2. Data Retrieval
One or more data nodes can be retrieved by the client. The operation One or more data nodes can be retrieved by the client. The operation
skipping to change at page 15, line 47 skipping to change at page 15, line 47
If the target of a GET or FETCH method is a data node that represents If the target of a GET or FETCH method is a data node that represents
a leaf that has a default value, and the leaf has not been given a a leaf that has a default value, and the leaf has not been given a
value by any client yet, the server MUST return the default value of value by any client yet, the server MUST return the default value of
the leaf. the leaf.
If the target of a GET method is a data node that represents a If the target of a GET method is a data node that represents a
container or list that has child resources with default values, and container or list that has child resources with default values, and
these have not been given value yet, these have not been given value yet,
The server MUST not return the child resource if d= 't' The server MUST NOT return the child resource if d= 't'
The server MUST return the child resource if d= 'a'. The server MUST return the child resource if d= 'a'.
If this Uri-Query option is not present, the default value is 't'. If this Uri-Query option is not present, the default value is 't'.
4.2.3. GET 4.2.3. GET
A request to read the values of a data node instance is sent with a A request to read the values of a data node instance is sent with a
CoAP GET message. An instance identifier is specified in the URI CoAP GET message. A base64-encoded instance-identifier in SID-form
path prefixed with the example path /c. is specified in the URI path prefixed with the example path /c.
FORMAT: FORMAT:
GET /c/instance-identifier GET /c/instance-identifier
2.05 Content (Content-Format: application/yang-data+cbor) 2.05 Content (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
The returned payload contains the CBOR encoding of the specified data The returned payload contains the CBOR encoding of the specified data
node instance value. node instance value.
skipping to change at page 20, line 7 skipping to change at page 20, line 7
resources and the invocation of "ACTION" and "RPC" resources. Refer resources and the invocation of "ACTION" and "RPC" resources. Refer
to Section 4.6 for details on "ACTION" and "RPC" resources. to Section 4.6 for details on "ACTION" and "RPC" resources.
A request to create a data node resource is sent with a CoAP POST A request to create a data node resource is sent with a CoAP POST
message. The URI specifies the data node to be instantiated at the message. The URI specifies the data node to be instantiated at the
exception of list instances. In this case, for compactness, the URI exception of list instances. In this case, for compactness, the URI
specifies the list for which an instance is created. specifies the list for which an instance is created.
FORMAT: FORMAT:
POST /c/<instance identifier> POST /c/<instance identifier>
(Content-Format :application/yang-data+cbor) (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.01 Created 2.01 Created
If the data node resource already exists, then the POST request MUST If the data node resource already exists, then the POST request MUST
fail and a "4.09 Conflict" response code MUST be returned fail and a "4.09 Conflict" response code MUST be returned
4.3.2.1. Post example 4.3.2.1. Post example
The example uses the interface list from module ietf-interfaces The example uses the interface list from module ietf-interfaces
skipping to change at page 20, line 44 skipping to change at page 20, line 44
RES: 2.01 Created RES: 2.01 Created
4.3.3. PUT 4.3.3. PUT
A data node resource instance is created or replaced with the PUT A data node resource instance is created or replaced with the PUT
method. A request to set the value of a data node instance is sent method. A request to set the value of a data node instance is sent
with a CoAP PUT message. with a CoAP PUT message.
FORMAT: FORMAT:
PUT /c/<instanceidentifier> PUT /c/<instanceidentifier>
(Content-Format :application/yang-data+cbor) (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.01 Created 2.01 Created
4.3.3.1. PUT example 4.3.3.1. PUT example
The example uses the interface list from module ietf-interfaces The example uses the interface list from module ietf-interfaces
[RFC7223]. Example updates the instance of the list interface (SID = [RFC7223]. Example updates the instance of the list interface (SID =
1533) with key name="eth0": 1533) with key name="eth0":
skipping to change at page 21, line 42 skipping to change at page 21, line 42
The processing of the iPATCH command is specified by Content-Format The processing of the iPATCH command is specified by Content-Format
'application/yang-instances+cbor'. In summary, if the CBOR patch 'application/yang-instances+cbor'. In summary, if the CBOR patch
payload contains a data node instance that is not present in the payload contains a data node instance that is not present in the
target, this instance is added. If the target contains the specified target, this instance is added. If the target contains the specified
instance, the content of this instance is replaced with the value of instance, the content of this instance is replaced with the value of
the payload. A null value indicates the removal of an existing data the payload. A null value indicates the removal of an existing data
node instance. node instance.
FORMAT: FORMAT:
iPATCH /c (Content-Format: application/yang-instances+cbor) iPATCH /c (Content-Format: application/yang-instances+cbor)
CBOR array of CBOR map of instance-identifier, instance-value CBOR array of CBOR map of instance-identifier, instance-value
2.04 Changed 2.04 Changed
4.3.4.1. iPATCH example 4.3.4.1. iPATCH example
In this example, a CoMI client requests the following operations: In this example, a CoMI client requests the following operations:
o Set "/system/ntp/enabled" (SID 1755) to true. o Set "/system/ntp/enabled" (SID 1755) to true.
o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID
1756) list. 1756) list.
o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ o Add/set the server "NTP Pool server 2" to the list "/system/ntp/
server" (SID 1756). server" (SID 1756).
REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) REQ: iPATCH /c (Content-Format: application/yang-instances+cbor)
[ [
{ {
1755 : true / enabled (SID 1755) / 1755 : true / enabled (SID 1755) /
}, },
skipping to change at page 25, line 10 skipping to change at page 25, line 10
Every time an event is generated, the generated notification Every time an event is generated, the generated notification
instance is appended to the chosen stream(s). After an instance is appended to the chosen stream(s). After an
aggregation period, which may be adjusted using an exclusion delay aggregation period, which may be adjusted using an exclusion delay
and limited by the maximum number of notifications supported, the and limited by the maximum number of notifications supported, the
content of the instance is sent to all clients observing the content of the instance is sent to all clients observing the
modified stream. modified stream.
FORMAT: FORMAT:
GET /<stream-resource> Observe(0) GET /<stream-resource> Observe(0)
2.05 Content (Content-Format :application/yang-instances+cbor) 2.05 Content (Content-Format: application/yang-instances+cbor)
CBOR array of CBOR map of instance-identifier, instance-value CBOR array of CBOR map of instance-identifier, instance-value
The array of data node instances may contain identical entries which The array of data node instances may contain identical entries which
have been generated at different times. have been generated at different times.
4.5.1. Notify Examples 4.5.1. Notify Examples
Let suppose the server generates the example-port-fault event as Let suppose the server generates the example-port-fault event as
defined below. defined below.
skipping to change at page 26, line 5 skipping to change at page 26, line 5
} }
leaf port-fault { // SID 60012 leaf port-fault { // SID 60012
type string; type string;
} }
} }
} }
By executing a GET on the /s resource the client receives the By executing a GET on the /s resource the client receives the
following response: following response:
REQ: GET /s Observe(0) Token(0x93) REQ: GET /s Observe(0)
RES: 2.05 Content (Content-Format :application/yang-tree+cbor) RES: 2.05 Content (Content-Format: application/yang-tree+cbor)
Observe(12) Token(0x93) Observe(12)
[ [
{ {
60010 : { / example-port-fault (SID 60010) / 60010 : { / example-port-fault (SID 60010) /
+1 : "0/4/21", / port-name (SID 60011) / +1 : "0/4/21", / port-name (SID 60011) /
+2 : "Open pin 2" / port-fault (SID 60012) / +2 : "Open pin 2" / port-fault (SID 60012) /
} }
}, },
{ {
60010 : { / example-port-fault (SID 60010) / 60010 : { / example-port-fault (SID 60010) /
+1 : "1/4/21", / port-name (SID 60011) / +1 : "1/4/21", / port-name (SID 60011) /
skipping to change at page 26, line 47 skipping to change at page 26, line 47
notifications supported by the event stream are reported. notifications supported by the event stream are reported.
When not supported by a CoMI server, this option shall be ignored, When not supported by a CoMI server, this option shall be ignored,
all events notifications are reported independently of the presence all events notifications are reported independently of the presence
and content of the 'f' (filter) option. and content of the 'f' (filter) option.
When present, this option contains a comma separated list of When present, this option contains a comma separated list of
notification SIDs. For example, the following request returns notification SIDs. For example, the following request returns
notifications 60010 and 60020. notifications 60010 and 60020.
REQ: GET /s?f=60010,60020 Observe(0) Token(0x241) REQ: GET /s?f=60010,60020 Observe(0)
4.6. RPC statements 4.6. RPC statements
The YANG "action" and "RPC" statements specify the execution of a The YANG "action" and "RPC" statements specify the execution of a
Remote procedure Call (RPC) in the server. It is invoked using a Remote procedure Call (RPC) in the server. It is invoked using a
POST method to an "Action" or "RPC" resource instance. POST method to an "Action" or "RPC" resource instance.
The request payload contains the values assigned to the input The request payload contains the values assigned to the input
container when specified. The response payload contains the values container when specified. The response payload contains the values
of the output container when specified. Both the input and output of the output container when specified. Both the input and output
containers are encoded in CBOR using the rules defined in containers are encoded in CBOR using the rules defined in
[I-D.ietf-core-yang-cbor] section 4.2.1. [I-D.ietf-core-yang-cbor] section 4.2.1.
The returned success response code is 2.05 Content. The returned success response code is 2.05 Content.
FORMAT: FORMAT:
POST /c/<instance identifier> POST /c/<instance identifier>
(Content-Format :application/yang-data+cbor) (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
2.05 Content (Content-Format :application/yang-data+cbor) 2.05 Content (Content-Format: application/yang-data+cbor)
CBOR map of SID, instance-value CBOR map of SID, instance-value
4.6.1. RPC Example 4.6.1. RPC Example
The example is based on the YANG action reset as defined in [RFC7950] The example is based on the YANG action "reset" as defined in
section 7.15.3 and annotated below with SIDs. [RFC7950] section 7.15.3 and annotated below with SIDs.
module example-server-farm { module example-server-farm {
yang-version 1.1; yang-version 1.1;
namespace "urn:example:server-farm"; namespace "urn:example:server-farm";
prefix "sfarm"; prefix "sfarm";
import ietf-yang-types { import ietf-yang-types {
prefix "yang"; prefix "yang";
} }
skipping to change at page 28, line 40 skipping to change at page 28, line 40
} }
} }
} }
} }
} }
This example invokes the 'reset' action (SID 60002, base64: Opq), of This example invokes the 'reset' action (SID 60002, base64: Opq), of
the server instance with name equal to "myserver". the server instance with name equal to "myserver".
REQ: POST /c/Opq?k="myserver" REQ: POST /c/Opq?k="myserver"
(Content-Format :application/yang-data+cbor) (Content-Format: application/yang-data+cbor)
{ {
60002 : { 60002 : {
+1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / +1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) /
} }
} }
RES: 2.05 Content (Content-Format :application/yang-data+cbor) RES: 2.05 Content (Content-Format: application/yang-data+cbor)
{ {
60002 : { 60002 : {
+2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ +2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/
} }
} }
5. Use of Block 5. Use of Block-wise Transfers
The CoAP protocol provides reliability by acknowledging the UDP The CoAP protocol provides reliability by acknowledging the UDP
datagrams. However, when large pieces of data need to be datagrams. However, when large pieces of data need to be
transported, datagrams get fragmented, thus creating constraints on transported, datagrams get fragmented, thus creating constraints on
the resources in the client, server and intermediate routers. The the resources in the client, server and intermediate routers. The
block option [RFC7959] allows the transport of the total payload in block option [RFC7959] allows the transport of the total payload in
individual blocks of which the size can be adapted to the underlying individual blocks of which the size can be adapted to the underlying
transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280,
IEEE 802.15.4 payload of 60-80 bytes). Each block is individually IEEE 802.15.4 payload of 60-80 bytes). Each block is individually
acknowledged to guarantee reliability. acknowledged to guarantee reliability.
skipping to change at page 30, line 10 skipping to change at page 30, line 10
datastores implemented. datastores implemented.
The location of the YANG library can be found by sending a GET The location of the YANG library can be found by sending a GET
request to "/.well-known/core" including a resource type (RT) request to "/.well-known/core" including a resource type (RT)
parameter with the value "core.c.yl". Upon success, the return parameter with the value "core.c.yl". Upon success, the return
payload will contain the root resource of the YANG library module. payload will contain the root resource of the YANG library module.
REQ: GET /.well-known/core?rt=core.c.yl REQ: GET /.well-known/core?rt=core.c.yl
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</c/kv >;rt="core.c.yl" </c/kv>;rt="core.c.yl"
6.2. Resource Discovery 6.2. Resource Discovery
Even if the YANG library provides all the information needed for Even if the YANG library provides all the information needed for
application discovery, the implementation of Resource discovery as application discovery once it is itself discovered, other types of
defined by [RFC6690] can be desirable for a seamless integration with resources could be discovered using the implementation of Resource
other CoAP interfaces and services. discovery as defined by [RFC6690]. This can be desirable for a
seamless integration with other CoAP interfaces and services.
6.2.1. Datastore Resource Discovery 6.2.1. Datastore Resource Discovery
The presence and location of (path to) each datastore implemented by The presence and location of (path to) each datastore implemented by
the CoMI server can be discovered by sending a GET request to the CoMI server can be discovered by sending a GET request to
"/.well-known/core" including a resource type (RT) parameter with the "/.well-known/core" including a resource type (RT) parameter with the
value "core.c.ds". value "core.c.ds".
Upon success, the return payload contains the list of datastore Upon success, the return payload contains the list of datastore
resources. resources.
skipping to change at page 31, line 19 skipping to change at page 31, line 21
data nodes. Data nodes '/ietf-system:system-state/clock/boot- data nodes. Data nodes '/ietf-system:system-state/clock/boot-
datetime' (SID 1722) and '/ietf-system:system-state/clock/current- datetime' (SID 1722) and '/ietf-system:system-state/clock/current-
datetime' (SID 1723) are returned. datetime' (SID 1723) are returned.
REQ: GET /.well-known/core?rt=core.c.dn REQ: GET /.well-known/core?rt=core.c.dn
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</c/a6>;rt="core.c.dn", </c/a6>;rt="core.c.dn",
</c/a7>;rt="core.c.dn" </c/a7>;rt="core.c.dn"
The list of data nodes may become prohibitively long. Without additional filtering, the list of data nodes may become
Implementations MAY return a subset of this list or can rely solely prohibitively long. Implementations MAY return a subset of this list
on the YANG library. or can rely solely on the YANG library.
6.2.3. Event stream Resource Discovery 6.2.3. Event stream Resource Discovery
The presence and location of (path to) each event stream implemented The presence and location of (path to) each event stream implemented
by the CoMI server are discovered by sending a GET request to by the CoMI server are discovered by sending a GET request to
"/.well-known/core" including a resource type (RT) parameter with the "/.well-known/core" including a resource type (RT) parameter with the
value "core.c.es". value "core.c.es".
Upon success, the return payload contains the list of event stream Upon success, the return payload contains the list of event stream
resources. resources.
skipping to change at page 31, line 43 skipping to change at page 31, line 45
For example: For example:
REQ: GET /.well-known/core?rt=core.c.es REQ: GET /.well-known/core?rt=core.c.es
RES: 2.05 Content (Content-Format: application/link-format) RES: 2.05 Content (Content-Format: application/link-format)
</s>;rt="core.c.es" </s>;rt="core.c.es"
7. Error Handling 7. Error Handling
In case a request is received which cannot be processed properly, the In case a request is received which cannot be processed properly, the
CoMI server MUST return an error message. This error message MUST CoMI server MUST return an error response. This error response MUST
contain a CoAP 4.xx or 5.xx response code. contain a CoAP 4.xx or 5.xx response code.
Errors returned by a CoMI server can be broken into two categories, Errors returned by a CoMI server can be broken into two categories,
those associated to the CoAP protocol itself and those generated those associated to the CoAP protocol itself and those generated
during the validation of the YANG data model constrains as described during the validation of the YANG data model constrains as described
in [RFC7950] section 8. in [RFC7950] section 8.
The following list of common CoAP errors should be implemented by The following list of common CoAP errors should be implemented by
CoMI servers. This list is not exhaustive, other errors defined by CoMI servers. This list is not exhaustive, other errors defined by
CoAP and associated RFCs may be applicable. CoAP and associated RFCs may be applicable.
skipping to change at page 32, line 35 skipping to change at page 32, line 35
o Error 4.08 (Request Entity Incomplete) is returned by the CoMI o Error 4.08 (Request Entity Incomplete) is returned by the CoMI
server if one or multiple blocks of a block transfer request is server if one or multiple blocks of a block transfer request is
missing, see [RFC7959] for more details. missing, see [RFC7959] for more details.
o Error 4.13 (Request Entity Too Large) may be returned by the CoMI o Error 4.13 (Request Entity Too Large) may be returned by the CoMI
server during a block transfer request, see [RFC7959] for more server during a block transfer request, see [RFC7959] for more
details. details.
o Error 4.15 (Unsupported Content-Format) is returned by the CoMI o Error 4.15 (Unsupported Content-Format) is returned by the CoMI
server when the Content-Format used in the request don't match server when the Content-Format used in the request does not match
those specified in section Section 2.4. those specified in section Section 2.4.
CoMI server MUST also enforce the different constraints associated to CoMI server MUST also enforce the different constraints associated to
the YANG data models implemented. These constraints are described in the YANG data models implemented. These constraints are described in
[RFC7950] section 8. These errors are reported using the CoAP error [RFC7950] section 8. These errors are reported using the CoAP error
code 4.00 (Bad Request) and may have the following error container as code 4.00 (Bad Request) and may have the following error container as
payload. The YANG definition and associated .sid file are available payload. The YANG definition and associated .sid file are available
in Appendix A and Appendix B. The error container is encoded using in Appendix A and Appendix B. The error container is encoded using
the encoding rules of a YANG data template as defined in the encoding rules of a YANG data template as defined in
[I-D.ietf-core-yang-cbor] section 5. [I-D.ietf-core-yang-cbor] section 5.
skipping to change at page 33, line 13 skipping to change at page 33, line 13
+--rw error-message? string +--rw error-message? string
The following 'error-tag' and 'error-app-tag' are defined by the The following 'error-tag' and 'error-app-tag' are defined by the
ietf-comi YANG module, these tags are implemented as YANG identity ietf-comi YANG module, these tags are implemented as YANG identity
and can be extended as needed. and can be extended as needed.
o error-tag 'operation-failed' is returned by the CoMI server when o error-tag 'operation-failed' is returned by the CoMI server when
the operation request cannot be processed successfully. the operation request cannot be processed successfully.
* error-app-tag 'malformed-message' is returned by the CoMI * error-app-tag 'malformed-message' is returned by the CoMI
server when the payload received from the CoMI client don't server when the payload received from the CoMI client does not
contain a well-formed CBOR content as defined in [RFC7049] contain a well-formed CBOR content as defined in [RFC7049]
section 3.3 or don't comply with the CBOR structure defined section 3.3 or does not comply with the CBOR structure defined
within this document. within this document.
* error-app-tag 'data-not-unique' is returned by the CoMI server * error-app-tag 'data-not-unique' is returned by the CoMI server
when the validation of the 'unique' constraint of a list or when the validation of the 'unique' constraint of a list or
leaf-list fails. leaf-list fails.
* error-app-tag 'too-many-elements' is returned by the CoMI * error-app-tag 'too-many-elements' is returned by the CoMI
server when the validation of the 'max-elements' constraint of server when the validation of the 'max-elements' constraint of
a list or leaf-list fails. a list or leaf-list fails.
skipping to change at page 33, line 43 skipping to change at page 33, line 43
* error-app-tag 'duplicate' is returned by the CoMI server when a * error-app-tag 'duplicate' is returned by the CoMI server when a
client tries to create a duplicate list or leaf-list entry. client tries to create a duplicate list or leaf-list entry.
o error-tag 'invalid-value' is returned by the CoMI server when the o error-tag 'invalid-value' is returned by the CoMI server when the
CoMI client tries to update or create a leaf with a value encoded CoMI client tries to update or create a leaf with a value encoded
using an invalid CBOR datatype or if the 'range', 'length', using an invalid CBOR datatype or if the 'range', 'length',
'pattern' or 'require-instance' constrain is not fulfilled. 'pattern' or 'require-instance' constrain is not fulfilled.
* error-app-tag 'invalid-datatype' is returned by the CoMI server * error-app-tag 'invalid-datatype' is returned by the CoMI server
when CBOR encoding don't follow the rules set by or when the when CBOR encoding does not follow the rules set by or when the
value is incompatible with the YANG Built-In type. (e.g. a value is incompatible with the YANG Built-In type (e.g. a value
value greater than 127 for an int8, undefined enumeration) greater than 127 for an int8, undefined enumeration)
* error-app-tag 'not-in-range' is returned by the CoMI server * error-app-tag 'not-in-range' is returned by the CoMI server
when the validation of the 'range' property fails. when the validation of the 'range' property fails.
* error-app-tag 'invalid-length' is returned by the CoMI server * error-app-tag 'invalid-length' is returned by the CoMI server
when the validation of the 'length' property fails. when the validation of the 'length' property fails.
* error-app-tag 'pattern-test-failed' is returned by the CoMI * error-app-tag 'pattern-test-failed' is returned by the CoMI
server when the validation of the 'pattern' property fails. server when the validation of the 'pattern' property fails.
o error-tag 'missing-element' is returned by the CoMI server when o error-tag 'missing-element' is returned by the CoMI server when
the operation requested by a CoMI client fail to comply with the the operation requested by a CoMI client fails to comply with the
'mandatory' constraint defined. The 'mandatory' constraint is 'mandatory' constraint defined. The 'mandatory' constraint is
enforced for leafs and choices, unless the node or any of its enforced for leafs and choices, unless the node or any of its
ancestors have a 'when' condition or 'if-feature' expression that ancestors have a 'when' condition or 'if-feature' expression that
evaluates to 'false'. evaluates to 'false'.
* error-app-tag 'missing-key' is returned by the CoMI server to * error-app-tag 'missing-key' is returned by the CoMI server to
further qualify a missing-element error. This error is further qualify a missing-element error. This error is
returned when the CoMI client tries to create or list instance, returned when the CoMI client tries to create or list instance,
without all the 'key' specified or when the CoMI client tries without all the 'key' specified or when the CoMI client tries
to delete a leaf listed as a 'key'. to delete a leaf listed as a 'key'.
skipping to change at page 35, line 5 skipping to change at page 35, line 5
instance that does not exist. instance that does not exist.
* error-app-tag 'missing-choice' is returned by the CoMI server * error-app-tag 'missing-choice' is returned by the CoMI server
when no nodes exist in a mandatory choice. when no nodes exist in a mandatory choice.
o error-tag 'error' is returned by the CoMI server when an o error-tag 'error' is returned by the CoMI server when an
unspecified error has occurred. unspecified error has occurred.
For example, the CoMI server might return the following error. For example, the CoMI server might return the following error.
RES: 4.00 Bad Request (Content-Format :application/yang-data+cbor) RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor)
{ {
1024 : { 1024 : {
+4 : 1011, / error-tag (SID 1028) / +4 : 1011, / error-tag (SID 1028) /
/ = invalid-value (SID 1011) / / = invalid-value (SID 1011) /
+1 : 1018, / error-app-tag (SID 1025) / +1 : 1018, / error-app-tag (SID 1025) /
/ = not-in-range (SID 1018) / / = not-in-range (SID 1018) /
+2 : 1740, / error-data-node (SID 1026) / +2 : 1740, / error-data-node (SID 1026) /
/ = timezone-utc-offset (SID 1740) / / = timezone-utc-offset (SID 1740) /
+3 : "maximum value exceeded" / error-message (SID 1027) / +3 : "maximum value exceeded" / error-message (SID 1027) /
} }
skipping to change at page 35, line 29 skipping to change at page 35, line 29
For secure network management, it is important to restrict access to For secure network management, it is important to restrict access to
configuration variables only to authorized parties. CoMI re-uses the configuration variables only to authorized parties. CoMI re-uses the
security mechanisms already available to CoAP, this includes DTLS security mechanisms already available to CoAP, this includes DTLS
[RFC6347] for protected access to resources, as well suitable [RFC6347] for protected access to resources, as well suitable
authentication and authorization mechanisms. authentication and authorization mechanisms.
Among the security decisions that need to be made are selecting Among the security decisions that need to be made are selecting
security modes and encryption mechanisms (see [RFC7252]). This security modes and encryption mechanisms (see [RFC7252]). This
requires a trade-off, as the NoKey mode gives no protection at all, requires a trade-off, as the NoKey mode gives no protection at all,
but is easy to implement, whereas the X.509 mode is quite secure, but but is easy to implement, whereas the Certificate mode is quite
may be too complex for constrained devices. secure, but may be too complex for constrained devices.
In addition, mechanisms for authentication and authorization may need In addition, mechanisms for authentication and authorization may need
to be selected. to be selected in case NoKey is used.
CoMI avoids defining new security mechanisms as much as possible.
However, some adaptations may still be required, to cater for CoMI's
specific requirements.
9. IANA Considerations 9. IANA Considerations
9.1. Resource Type (rt=) Link Target Attribute Values Registry 9.1. Resource Type (rt=) Link Target Attribute Values Registry
This document adds the following resource type to the "Resource Type This document adds the following resource type to the "Resource Type
(rt=) Link Target Attribute Values", within the "Constrained RESTful (rt=) Link Target Attribute Values", within the "Constrained RESTful
Environments (CoRE) Parameters" registry. Environments (CoRE) Parameters" registry.
+-----------+---------------------+-----------+ +-----------+---------------------+-----------+
skipping to change at page 36, line 26 skipping to change at page 36, line 26
// RFC Ed.: replace RFC XXXX with this RFC number and remove this // RFC Ed.: replace RFC XXXX with this RFC number and remove this
note. note.
9.2. CoAP Content-Formats Registry 9.2. CoAP Content-Formats Registry
This document adds the following Content-Format to the "CoAP Content- This document adds the following Content-Format to the "CoAP Content-
Formats", within the "Constrained RESTful Environments (CoRE) Formats", within the "Constrained RESTful Environments (CoRE)
Parameters" registry. Parameters" registry.
+-----------------------------------+-------------+-----------+ +-----------------------------------+------------+------+-----------+
| Media Type | Encoding ID | Reference | | Media Type | Content | ID | Reference |
+-----------------------------------+-------------+-----------+ | | Coding | | |
| application/yang-data+cbor | XXX | RFC XXXX | +-----------------------------------+------------+------+-----------+
| | | | | application/yang-data+cbor | | TBD1 | RFC XXXX |
| application/yang-identifiers+cbor | XXX | RFC XXXX | | | | | |
| | | | | application/yang-identifiers+cbor | | TBD2 | RFC XXXX |
| application/yang-instances+cbor | XXX | RFC XXXX | | | | | |
+-----------------------------------+-------------+-----------+ | application/yang-instances+cbor | | TBD3 | RFC XXXX |
+-----------------------------------+------------+------+-----------+
// RFC Ed.: replace XXX with assigned IDs and remove this note. // // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove
RFC Ed.: replace RFC XXXX with this RFC number and remove this note. this note. // RFC Ed.: replace RFC XXXX with this RFC number and
remove this note.
9.3. Media Types Registry 9.3. Media Types Registry
This document adds the following media types to the "Media Types" This document adds the following media types to the "Media Types"
registry. registry.
+-----------------------+----------------------------+-----------+ +-----------------------+----------------------------+-----------+
| Name | Template | Reference | | Name | Template | Reference |
+-----------------------+----------------------------+-----------+ +-----------------------+----------------------------+-----------+
| yang-data+cbor | application/yang-data+cbor | RFC XXXX | | yang-data+cbor | application/yang-data+cbor | RFC XXXX |
skipping to change at page 38, line 38 skipping to change at page 38, line 38
Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy
Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes
Tschofenig, Michael Verschoor, and Thomas Watteyne. Tschofenig, Michael Verschoor, and Thomas Watteyne.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-core-sid] [I-D.ietf-core-sid]
Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item
iDentifier (SID)", draft-ietf-core-sid-06 (work in iDentifier (SID)", draft-ietf-core-sid-07 (work in
progress), March 2019. progress), July 2019.
[I-D.ietf-core-yang-cbor] [I-D.ietf-core-yang-cbor]
Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of
Data Modeled with YANG", draft-ietf-core-yang-cbor-10 Data Modeled with YANG", draft-ietf-core-yang-cbor-10
(work in progress), April 2019. (work in progress), April 2019.
[I-D.veillette-core-yang-library] [I-D.veillette-core-yang-library]
Veillette, M. and I. Petrov, "Constrained YANG Module Veillette, M. and I. Petrov, "Constrained YANG Module
Library", draft-veillette-core-yang-library-04 (work in Library", draft-veillette-core-yang-library-04 (work in
progress), March 2019. progress), March 2019.
skipping to change at page 40, line 10 skipping to change at page 40, line 10
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>. <https://www.rfc-editor.org/info/rfc8040>.
[RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
FETCH Methods for the Constrained Application Protocol FETCH Methods for the Constrained Application Protocol
(CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
<https://www.rfc-editor.org/info/rfc8132>. <https://www.rfc-editor.org/info/rfc8132>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
11.2. Informative References 11.2. Informative References
[RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer
Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347,
January 2012, <https://www.rfc-editor.org/info/rfc6347>. January 2012, <https://www.rfc-editor.org/info/rfc6347>.
[RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link
Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, Format", RFC 6690, DOI 10.17487/RFC6690, August 2012,
<https://www.rfc-editor.org/info/rfc6690>. <https://www.rfc-editor.org/info/rfc6690>.
skipping to change at line 2259 skipping to change at page 50, line 27
Email: a@ackl.io Email: a@ackl.io
Andy Bierman Andy Bierman
YumaWorks YumaWorks
685 Cochran St. 685 Cochran St.
Suite #160 Suite #160
Simi Valley, CA 93065 Simi Valley, CA 93065
USA USA
Email: andy@yumaworks.com Email: andy@yumaworks.com
Ivaylo Petrov (editor)
Acklio
1137A avenue des Champs Blancs
Cesson-Sevigne, Bretagne 35510
France
Email: ivaylo@ackl.io
 End of changes. 56 change blocks. 
88 lines changed or deleted 107 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/