idnits 2.17.1 draft-ietf-core-comi-09.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-core-sid], [I-D.ietf-core-yang-cbor]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 09, 2020) is 1508 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 343 -- Looks like a reference, but probably isn't: '26' on line 344 -- Looks like a reference, but probably isn't: '57' on line 345 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-11 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-11 == Outdated reference: A later version (-03) exists of draft-ietf-core-yang-library-01 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) -- Obsolete informational reference (is this intentional?): RFC 6347 (Obsoleted by RFC 9147) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 2 errors (**), 0 flaws (~~), 4 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Standards Track P. van der Stok, Ed. 5 Expires: September 10, 2020 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 I. Petrov, Ed. 11 Acklio 12 March 09, 2020 14 CoAP Management Interface 15 draft-ietf-core-comi-09 17 Abstract 19 This document describes a network management interface for 20 constrained devices and networks, called CoAP Management Interface 21 (CoMI). The Constrained Application Protocol (CoAP) is used to 22 access datastore and data node resources specified in YANG, or SMIv2 23 converted to YANG. CoMI uses the YANG to CBOR mapping and converts 24 YANG identifier strings to numeric identifiers for payload size 25 reduction. The complete solution composed of CoMI, 26 [I-D.ietf-core-yang-cbor] and [I-D.ietf-core-sid] is called CORECONF. 27 CORECONF extends the set of YANG based protocols, NETCONF and 28 RESTCONF, with the capability to manage constrained devices and 29 networks. 31 Note 33 Discussion and suggestions for improvement are requested, and should 34 be sent to yot@ietf.org. 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at https://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on September 10, 2020. 53 Copyright Notice 55 Copyright (c) 2020 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (https://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 71 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. CoMI Architecture . . . . . . . . . . . . . . . . . . . . . . 5 73 2.1. Major differences between RESTCONF and CORECONF . . . . . 6 74 2.1.1. Differences due to CoAP and its efficient usage . . . 6 75 2.1.2. Differences due to the use of CBOR . . . . . . . . . 7 76 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 77 2.3. Instance-identifier . . . . . . . . . . . . . . . . . . . 8 78 2.4. Content-Formats . . . . . . . . . . . . . . . . . . . . . 8 79 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 80 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 81 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 82 4.1. Using the 'k' Uri-Query option . . . . . . . . . . . . . 13 83 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 14 84 4.2.1. Using the 'c' Uri-Query option . . . . . . . . . . . 14 85 4.2.2. Using the 'd' Uri-Query option . . . . . . . . . . . 15 86 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 87 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 18 88 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 19 89 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 19 90 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 91 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 92 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 21 93 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 22 94 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 23 95 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 97 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 24 98 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 25 99 4.5.2. The 'f' Uri-Query option . . . . . . . . . . . . . . 26 100 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 101 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 27 102 5. Use of Block-wise Transfers . . . . . . . . . . . . . . . . . 29 103 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 29 104 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 29 105 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 30 106 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 30 107 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 31 108 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 31 109 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 31 110 8. Security Considerations . . . . . . . . . . . . . . . . . . . 35 111 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 35 112 9.1. Resource Type (rt=) Link Target Attribute Values Registry 35 113 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 36 114 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 36 115 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 38 116 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 117 11.1. Normative References . . . . . . . . . . . . . . . . . . 38 118 11.2. Informative References . . . . . . . . . . . . . . . . . 40 119 Appendix A. ietf-comi YANG module . . . . . . . . . . . . . . . 40 120 Appendix B. ietf-comi .sid file . . . . . . . . . . . . . . . . 46 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50 123 1. Introduction 125 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 126 Machine to Machine (M2M) applications such as smart energy, smart 127 city and building control. Constrained devices need to be managed in 128 an automatic fashion to handle the large quantities of devices that 129 are expected in future installations. Messages between devices need 130 to be as small and infrequent as possible. The implementation 131 complexity and runtime resources need to be as small as possible. 133 This draft describes the CoAP Management Interface which uses CoAP 134 methods to access structured data defined in YANG [RFC7950]. This 135 draft is complementary to [RFC8040] which describes a REST-like 136 interface called RESTCONF, which uses HTTP methods to access 137 structured data defined in YANG. 139 The use of standardized data models specified in a standardized 140 language, such as YANG, promotes interoperability between devices and 141 applications from different manufacturers. 143 CORECONF and RESTCONF are intended to work in a stateless client- 144 server fashion. They use a single round-trip to complete a single 145 editing transaction, where NETCONF needs multiple round trips. 147 To promote small messages, CORECONF uses a YANG to CBOR mapping 148 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 149 to minimize CBOR payloads and URI length. 151 1.1. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 155 "OPTIONAL" in this document are to be interpreted as described in BCP 156 14 [RFC2119] [RFC8174] when, and only when, they appear in all 157 capitals, as shown here. 159 The following terms are defined in the YANG data modelling language 160 [RFC7950]: action, anydata, anyxml, client, container, data model, 161 data node, identity, instance identifier, leaf, leaf-list, list, 162 module, RPC, schema node, server, submodule. 164 The following terms are defined in [RFC6241]: configuration data, 165 datastore, state data 167 The following term is defined in [I-D.ietf-core-sid]: YANG schema 168 item identifier (SID). 170 The following terms are defined in the CoAP protocol [RFC7252]: 171 Confirmable Message, Content-Format, Endpoint. 173 The following terms are defined in this document: 175 data node resource: a CoAP resource that models a YANG data node. 177 datastore resource: a CoAP resource that models a YANG datastore. 179 event stream resource: a CoAP resource used by clients to observe 180 YANG notifications. 182 notification instance: An instance of a schema node of type 183 notification, specified in a YANG module implemented by the 184 server. The instance is generated in the server at the occurrence 185 of the corresponding event and reported by an event stream 186 resource. 188 list instance identifier: Handle used to identify a YANG data node 189 that is an instance of a YANG "list" specified with the values of 190 the key leaves of the list. 192 single instance identifier: Handle used to identify a specific data 193 node which can be instantiated only once. This includes data 194 nodes defined at the root of a YANG module and data nodes defined 195 within a container. This excludes data nodes defined within a 196 list or any children of these data nodes. 198 instance-identifier: List instance identifier or single instance 199 identifier. 201 instance-value: The value assigned to a data node instance. 202 Instance-values are serialized into the payload according to the 203 rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 205 2. CoMI Architecture 207 This section describes the CoMI architecture to use CoAP for reading 208 and modifying the content of datastore(s) used for the management of 209 the instrumented node. 211 +----------------------------------------------------------------+ 212 | SMIv2 specification (optional) (2) | 213 +----------------------------------------------------------------+ 214 | 215 V 216 +----------------------------------------------------------------+ 217 | YANG specification (1) | 218 +----------------------------------------------------------------+ 219 | | 220 Client V Server V 221 +----------------+ +-----------------------+ 222 | Request |--> CoAP request(3) -->| Indication | 223 | Confirm |<-- CoAP response(3)<--| Response (4) | 224 | | | | 225 | |<==== Security (7) ===>|+---------------------+| 226 +----------------+ || Datastore(s) (5) || 227 |+---------------------+| 228 |+---------------------+| 229 || Event stream(s) (6) || 230 |+---------------------+| 231 +-----------------------+ 233 Figure 1: Abstract CoMI architecture 235 Figure 1 is a high-level representation of the main elements of the 236 CoMI management architecture. The different numbered components of 237 Figure 1 are discussed according to component number. 239 (1) YANG specification: contains a set of named and versioned 240 modules. 242 (2) SMIv2 specification: Optional part that consists of a named 243 module which, specifies a set of variables and "conceptual 244 tables". There is an algorithm to translate SMIv2 specifications 245 to YANG specifications. 247 (3) CoAP request/response messages: The CoMI client sends request 248 messages to and receives response messages from the CoMI server. 250 (4) Request, Indication, Response, Confirm: Processes performed by 251 the CoMI clients and servers. 253 (5) Datastore: A resource used to access configuration data, state 254 data, RPCs and actions. A CoMI server may support a single 255 unified datastore or multiple datastores as those defined by 256 Network Management Datastore Architecture (NMDA) [RFC8342]. 258 (6) Event stream: A resource used to get real time notifications. A 259 CoMI server may support multiple Event streams serving different 260 purposes such as normal monitoring, diagnostic, syslog, security 261 monitoring. 263 (7) Security: The server MUST prevent unauthorized users from 264 reading or writing any CoMI resources. CoMI relies on security 265 protocols such as DTLS [RFC6347] or OSCOAP [RFC8613] to secure 266 CoAP communications. 268 2.1. Major differences between RESTCONF and CORECONF 270 CORECONF is a RESTful protocol for small devices where saving bytes 271 to transport counts. Contrary to RESTCONF, many design decisions are 272 motivated by the saving of bytes. Consequently, CORECONF is not a 273 RESTCONF over CoAP protocol, but differs more significantly from 274 RESTCONF. 276 2.1.1. Differences due to CoAP and its efficient usage 278 o CORECONF uses CoAP/UDP as transport protocol and CBOR as payload 279 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 280 transport protocol and JSON or XML as payload formats. 282 o CORECONF uses the methods FETCH and iPATCH to access multiple data 283 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 284 method GET with the "fields" Query parameter. 286 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 287 supported by CoAP. 289 o CORECONF does not support "insert" query parameter (first, last, 290 before, after) and the "point" query parameter which are supported 291 by RESTCONF. 293 o CORECONF does not support the "start-time" and "stop-time" query 294 parameters to retrieve past notifications. 296 2.1.2. Differences due to the use of CBOR 298 o CORECONF encodes YANG identifier strings as numbers, where 299 RESTCONF does not. 301 o CORECONF also differ in the handling of default values, only 302 'report-all' and 'trim' options are supported. 304 2.2. Compression of YANG identifiers 306 In the YANG specification, items are identified with a name string. 307 In order to significantly reduce the size of identifiers used in 308 CoMI, numeric identifiers called YANG Schema Item iDentifier (SID) 309 are used instead. 311 When used in a URI, SIDs are encoded using base64 encoding of the SID 312 bytes. The base64 encoding is using the URL and Filename safe 313 alphabet as defined by [RFC4648] section 5, without padding. The 314 last 6 bits encoded is always aligned with the least significant 6 315 bits of the SID represented using an unsigned integer. 'A' 316 characters (value 0) at the start of the resulting string are 317 removed. See Figure 2 for complete illustration. 319 SID in base64 = URLsafeChar[SID >> 60 & 0x3F] | 320 URLsafeChar[SID >> 54 & 0x3F] | 321 URLsafeChar[SID >> 48 & 0x3F] | 322 URLsafeChar[SID >> 42 & 0x3F] | 323 URLsafeChar[SID >> 36 & 0x3F] | 324 URLsafeChar[SID >> 30 & 0x3F] | 325 URLsafeChar[SID >> 24 & 0x3F] | 326 URLsafeChar[SID >> 18 & 0x3F] | 327 URLsafeChar[SID >> 12 & 0x3F] | 328 URLsafeChar[SID >> 6 & 0x3F] | 329 URLsafeChar[SID & 0x3F] 331 Figure 2 333 For example, SID 1721 is encoded as follow. 335 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 336 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 337 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 338 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 339 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 340 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 341 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 342 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 343 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 344 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 345 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 347 The resulting base64 representation of SID 1721 is "a5" 349 2.3. Instance-identifier 351 Instance-identifiers are used to uniquely identify data node 352 instances within a datastore. This YANG built-in type is defined in 353 [RFC7950] section 9.13. An instance-identifier is composed of the 354 data node identifier (i.e. a SID) and for data nodes within list(s) 355 the keys used to index within these list(s). 357 When part of a payload, instance-identifiers are encoded in CBOR 358 based on the rules defined in [I-D.ietf-core-yang-cbor] section 359 6.13.1. When part of a URI, the SID is appended to the URI of the 360 targeted datastore, the keys are specified using the 'k' URI-Query as 361 defined in Section 4.1. 363 2.4. Content-Formats 365 CoMI uses Content-Formats based on the YANG to CBOR mapping specified 366 in [I-D.ietf-core-yang-cbor]. 368 The following Content-formats are defined: 370 application/yang-data+cbor: This Content-Format represents a CBOR 371 YANG document containing one or multiple data node values. Each 372 data node is identified by its associated SID. 374 FORMAT: CBOR map of SID, instance-value 376 The message payload of Content-Format 'application/yang-data+cbor' 377 is encoded using a CBOR map. Each entry within the CBOR map 378 contains the data node identifier (i.e. SID) and the associated 379 instance-value. Instance-values are encoded using the rules 380 defined in [I-D.ietf-core-yang-cbor] section 4. 382 application/yang-identifiers+cbor: This Content-Format represents a 383 CBOR YANG document containing a list of instance-identifier used 384 to target specific data node instances within a datastore. 386 FORMAT: CBOR array of instance-identifier 388 The message payload of Content-Format 'application/yang- 389 identifiers+cbor' is encoded using a CBOR array. Each entry of 390 this CBOR array contain an instance-identifier encoded as defined 391 in [I-D.ietf-core-yang-cbor] section 6.13.1. 393 application/yang-instances+cbor: This Content-Format represents a 394 CBOR YANG document containing a list of data node instances. Each 395 data node instance is identified by its associated instance- 396 identifier. 398 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 399 value 401 The message payload of Content-Format 'application/yang- 402 instances+cbor' is encoded using a CBOR array. Each entry within 403 this CBOR array contains a CBOR map carrying an instance- 404 identifier and associated instance-value. Instance-identifiers 405 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 406 section 6.13.1, instance-values are encoded using the rules 407 defined in [I-D.ietf-core-yang-cbor] section 4. 409 When present in an iPATCH request payload, this Content-Format 410 carry a list of data node instances to be replaced, created, or 411 deleted. For each data node instance D, for which the instance- 412 identifier is the same as a data node instance I, in the targeted 413 datastore resource: the value of D replaces the value of I. When 414 the value of D is null, the data node instance I is removed. When 415 the targeted datastore resource does not contain a data node 416 instance with the same instance-identifier as D, a new instance is 417 created with the same instance-identifier and value as D. 419 The different Content-format usages are summarized in the table 420 below: 422 +---------------+--------------+------------------------------------+ 423 | Method | Resource | Content-Format | 424 +---------------+--------------+------------------------------------+ 425 | GET response | data node | /application/yang-data+cbor | 426 | | | | 427 | PUT request | data node | /application/yang-data+cbor | 428 | | | | 429 | POST request | data node | /application/yang-data+cbor | 430 | | | | 431 | DELETE | data node | n/a | 432 | | | | 433 | GET response | datastore | /application/yang-data+cbor | 434 | | | | 435 | PUT request | datastore | /application/yang-data+cbor | 436 | | | | 437 | POST request | datastore | /application/yang-data+cbor | 438 | | | | 439 | FETCH request | datastore | /application/yang-identifiers+cbor | 440 | | | | 441 | FETCH | datastore | /application/yang-instances+cbor | 442 | response | | | 443 | | | | 444 | iPATCH | datastore | /application/yang-instances+cbor | 445 | request | | | 446 | | | | 447 | GET response | event stream | /application/yang-instances+cbor | 448 | | | | 449 | POST request | rpc, action | /application/yang-data+cbor | 450 | | | | 451 | POST response | rpc, action | /application/yang-data+cbor | 452 +---------------+--------------+------------------------------------+ 454 2.5. Unified datastore 456 CoMI supports a simple datastore model consisting of a single unified 457 datastore. This datastore provides access to both configuration and 458 operational data. Configuration updates performed on this datastore 459 are reflected immediately or with a minimal delay as operational 460 data. 462 Alternatively, CoMI servers MAY implement a more complex datastore 463 model such as the Network Management Datastore Architecture (NMDA) as 464 defined by [RFC8342]. Each datastore supported is implemented as a 465 datastore resource. 467 Characteristics of the unified datastore are summarized in the table 468 below: 470 +-------------+-----------------------------------------------------+ 471 | Name | Value | 472 +-------------+-----------------------------------------------------+ 473 | Name | unified | 474 | | | 475 | YANG | all modules | 476 | modules | | 477 | | | 478 | YANG nodes | all data nodes ("config true" and "config false") | 479 | | | 480 | Access | read-write | 481 | | | 482 | How applied | changes applied in place immediately or with a | 483 | | minimal delay | 484 | | | 485 | Protocols | CORECONF | 486 | | | 487 | Defined in | "ietf-comi" | 488 +-------------+-----------------------------------------------------+ 490 3. Example syntax 492 CBOR is used to encode CoMI request and response payloads. The CBOR 493 syntax of the YANG payloads is specified in [RFC7049]. The payload 494 examples are notated in Diagnostic notation (defined in section 6 of 495 [RFC7049]) that can be automatically converted to CBOR. 497 SIDs in URIs are represented as a base64 number, SIDs in the payload 498 are represented as decimal numbers. 500 4. CoAP Interface 502 This note specifies a Management Interface. CoAP endpoints that 503 implement the CoMI management protocol, support at least one 504 discoverable management resource of resource type (rt): core.c.ds, 505 with example path: /c, where c is short-hand for CoMI/CORECONF. The 506 path /c is recommended, but not compulsory (see Section 6). 508 The mapping of YANG data node instances to CoMI resources is as 509 follows. Every data node of the YANG modules loaded in the CoMI 510 server represents a sub-resource of the datastore resource (e.g. /c/ 511 sid). When multiple instances of a list exist, instance selection is 512 possible as described in Section 4.1, Section 4.2.3.1, and 513 Section 4.2.4. 515 CoMI also supports event stream resources used to observe 516 notification instances. Event stream resources can be discovered 517 using resource type (rt): core.c.ev. 519 The description of the CoMI management interface is shown in the 520 table below: 522 +----------------------+------------------+-----------+ 523 | CoAP resource | Recommended path | rt | 524 +----------------------+------------------+-----------+ 525 | Datastore resource | /c | core.c.ds | 526 | | | | 527 | Data node resource | /c/SID | core.c.dn | 528 | | | | 529 | Event steam resource | /s | core.c.ev | 530 +----------------------+------------------+-----------+ 532 The path values in the table are the recommended ones. On discovery, 533 the server makes the actual path values known for these resources. 535 The methods used by CoMI are: 537 +-----------+-------------------------------------------------------+ 538 | Operation | Description | 539 +-----------+-------------------------------------------------------+ 540 | GET | Retrieve the datastore resource or a data node | 541 | | resource | 542 | | | 543 | FETCH | Retrieve specific data nodes within a datastore | 544 | | resource | 545 | | | 546 | POST | Create a datastore resource or a data node resource, | 547 | | invoke an RPC or action | 548 | | | 549 | PUT | Create or replace a datastore resource or a data node | 550 | | resource | 551 | | | 552 | iPATCH | Idem-potently create, replace, and delete data node | 553 | | resource(s) within a datastore resource | 554 | | | 555 | DELETE | Delete a datastore resource or a data node resource | 556 +-----------+-------------------------------------------------------+ 558 There is one Uri-Query option for the GET, PUT, POST, and DELETE 559 methods. 561 +------------------+----------------------------------------+ 562 | Uri-Query option | Description | 563 +------------------+----------------------------------------+ 564 | k | Select an instance within YANG list(s) | 565 +------------------+----------------------------------------+ 566 This parameter is not used for FETCH and iPATCH, because their 567 request payloads support list instance selection. 569 4.1. Using the 'k' Uri-Query option 571 The "k" (key) parameter specifies a specific instance of a data node. 572 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 573 identifies a data node, and key1, key2 are the values of the key 574 leaves that specify an instance. Lists can have multiple keys, and 575 lists can be part of lists. The order of key value generation is 576 given recursively by: 578 o For a given list, if a parent data node is a list, generate the 579 keys for the parent list first. 581 o For a given list, generate key values in the order specified in 582 the YANG module. 584 Key values are encoded using the rules defined in the following 585 table. 587 +-----------------------------+--------------------------------+ 588 | YANG datatype | Uri-Query text content | 589 +-----------------------------+--------------------------------+ 590 | uint8,uint16,unit32, uint64 | int2str(key) | 591 | | | 592 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 593 | | | 594 | decimal64 | urlSafeBase64(CBOR key) | 595 | | | 596 | string | key | 597 | | | 598 | boolean | "0" or "1" | 599 | | | 600 | enumeration | int2str(key) | 601 | | | 602 | bits | urlSafeBase64(CBORencode(key)) | 603 | | | 604 | binary | urlSafeBase64(key) | 605 | | | 606 | identityref | int2str(key) | 607 | | | 608 | union | urlSafeBase64(CBORencode(key)) | 609 | | | 610 | instance-identifier | urlSafeBase64(CBORencode(key)) | 611 +-----------------------------+--------------------------------+ 613 In this table: 615 o The method int2str() is used to convert an integer value to a 616 decimal string. For example, int2str(0x0123) return the string 617 "291". 619 o The method urlSafeBase64() is used to convert a binary string to 620 base64 using the URL and Filename safe alphabet as defined by 621 [RFC4648] section 5, without padding. For example, 622 urlSafeBase64(\xF9\x56\xA1\x3C) return the string "-VahPA". 624 o The method CBORencode() is used to convert a YANG value to CBOR as 625 specified in [I-D.ietf-core-yang-cbor] section 6. 627 The resulting key string is encoded in a Uri-Query as specified in 628 [RFC7252] section 6.5. 630 4.2. Data Retrieval 632 One or more data nodes can be retrieved by the client. The operation 633 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 634 to the FETCH method defined in section 2 of [RFC8132]. 636 There are two additional Uri-Query options for the GET and FETCH 637 methods. 639 +-------------+-----------------------------------------------------+ 640 | Uri-Query | Description | 641 | option | | 642 +-------------+-----------------------------------------------------+ 643 | c | Control selection of configuration and non- | 644 | | configuration data nodes (GET and FETCH) | 645 | | | 646 | d | Control retrieval of default values. | 647 +-------------+-----------------------------------------------------+ 649 4.2.1. Using the 'c' Uri-Query option 651 The 'c' (content) option controls how descendant nodes of the 652 requested data nodes will be processed in the reply. 654 The allowed values are: 656 +-------+-----------------------------------------------------+ 657 | Value | Description | 658 +-------+-----------------------------------------------------+ 659 | c | Return only configuration descendant data nodes | 660 | | | 661 | n | Return only non-configuration descendant data nodes | 662 | | | 663 | a | Return all descendant data nodes | 664 +-------+-----------------------------------------------------+ 666 This option is only allowed for GET and FETCH methods on datastore 667 and data node resources. A 4.02 (Bad Option) error is returned if 668 used for other methods or resource types. 670 If this Uri-Query option is not present, the default value is "a". 672 4.2.2. Using the 'd' Uri-Query option 674 The "d" (with-defaults) option controls how the default values of the 675 descendant nodes of the requested data nodes will be processed. 677 The allowed values are: 679 +-------+-----------------------------------------------------------+ 680 | Value | Description | 681 +-------+-----------------------------------------------------------+ 682 | a | All data nodes are reported. Defined as 'report-all' in | 683 | | section 3.1 of [RFC6243]. | 684 | | | 685 | t | Data nodes set to the YANG default are not reported. | 686 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 687 +-------+-----------------------------------------------------------+ 689 If the target of a GET or FETCH method is a data node that represents 690 a leaf that has a default value, and the leaf has not been given a 691 value by any client yet, the server MUST return the default value of 692 the leaf. 694 If the target of a GET method is a data node that represents a 695 container or list that has child resources with default values, and 696 these have not been given value yet, 698 The server MUST NOT return the child resource if d= 't' 700 The server MUST return the child resource if d= 'a'. 702 If this Uri-Query option is not present, the default value is 't'. 704 4.2.3. GET 706 A request to read the value of a data node instance is sent with a 707 CoAP GET message. The URI is set to the data node resource 708 requested, the 'k' Uri-Query option is added if the data node is an 709 instance of a list. 711 FORMAT: 712 GET ['k' Uri-Query option] 714 2.05 Content (Content-Format: application/yang-data+cbor) 715 CBOR map of SID, instance-value 717 The returned payload contains the CBOR encoding of the requested 718 instance-value. 720 4.2.3.1. GET Examples 722 Using for example the current-datetime leaf from module ietf-system 723 [RFC7317], a request is sent to retrieve the value of 'system- 724 state/clock/current-datetime'. The SID of 'system-state/clock/ 725 current-datetime' is 1723, encoded in base64 according to 726 Section 2.2, yields a7. The response to the request returns the CBOR 727 map with the key set to the SID of the requested data node (i.e. 728 1723) and the value encoded using a 'text string' as defined in 729 [I-D.ietf-core-yang-cbor] section 6.4. 731 REQ: GET example.com/c/a7 733 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 734 { 735 1723 : "2014-10-26T12:16:31Z" 736 } 738 The next example represents the retrieval of a YANG container. In 739 this case, the CoMI client performs a GET request on the clock 740 container (SID = 1721; base64: a5). The container returned is 741 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 742 section 4.2. 744 REQ: GET example.com/c/a5 746 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 747 { 748 1721 : { 749 2 : "2014-10-26T12:16:51Z", / current-datetime (SID 1723) / 750 1 : "2014-10-21T03:00:00Z" / boot-datetime (SID 1722) / 751 } 752 } 754 Figure 3 756 This example shows the retrieval of the /interfaces/interface YANG 757 list accessed using SID 1533 (base64: X9). The return payload is 758 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 759 section 4.4.1 containing 2 instances. 761 REQ: GET example.com/c/X9 763 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 764 { 765 1533 : [ 766 { 767 4 : "eth0", / name (SID 1537) / 768 1 : "Ethernet adaptor", / description (SID 1534) / 769 5 : 1880, / type, (SID 1538) identity / 770 / ethernetCsmacd (SID 1880) / 771 2 : true / enabled (SID 1535) / 772 }, 773 { 774 4 : "eth1", / name (SID 1537) / 775 1 : "Ethernet adaptor", / description (SID 1534) / 776 5 : 1880, / type, (SID 1538) identity / 777 / ethernetCsmacd (SID 1880) / 778 2 : false / enabled (SID 1535) / 779 } 780 ] 781 } 783 To retrieve a specific instance within the /interfaces/interface YANG 784 list, the CoMI client adds the key of the targeted instance in its 785 CoAP request using the 'k' URI-Query. The return payload containing 786 the instance requested is encoded using a CBOR array as specified by 787 [I-D.ietf-core-yang-cbor] section 4.4.1 containing the requested 788 instance. 790 REQ: GET example.com/c/X9?k="eth0" 792 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 793 { 794 1533 : [ 795 { 796 4 : "eth0", / name (SID 1537) / 797 1 : "Ethernet adaptor", / description (SID 1534) / 798 5 : 1880, / type, (SID 1538) identity / 799 / ethernetCsmacd (SID 1880) / 800 2 : true / enabled (SID 1535) / 801 } 802 ] 803 } 805 It is equally possible to select a leaf of a specific instance of a 806 list. The example below requests the description leaf (SID 1534, 807 base64: X-) within the interface list corresponding to the interface 808 name "eth0". The returned value is encoded in CBOR based on the 809 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 811 REQ: GET example.com/c/X-?k="eth0" 813 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 814 { 815 1534 : "Ethernet adaptor" 816 } 818 4.2.4. FETCH 820 The FETCH is used to retrieve multiple instance-values. The FETCH 821 request payload contains the list of instance-identifier of the data 822 node instances requested. 824 The return response payload contains a list of data node instance- 825 values in the same order as requested. A CBOR null is returned for 826 each data node requested by the client, not supported by the server 827 or not currently instantiated. 829 For compactness, indexes of the list instance identifiers returned by 830 the FETCH response SHOULD be elided, only the SID is provided. This 831 appraoch may also help reducing implementations complexity since the 832 format of each entry within the CBOR array of the FETCH response is 833 identical to the format of the corresponding GET response. 835 FORMAT: 836 FETCH 837 (Content-Format: application/yang-identifiers+cbor) 838 CBOR array of instance-identifier 840 2.05 Content (Content-Format: application/yang-instances+cbor) 841 CBOR array of CBOR map of SID, instance-value 843 4.2.4.1. FETCH examples 845 This example uses the current-datetime leaf from module ietf-system 846 [RFC7317] and the interface list from module ietf-interfaces 847 [RFC7223]. In this example the value of current-datetime (SID 1723) 848 and the interface list (SID 1533) instance identified with 849 name="eth0" are queried. 851 REQ: FETCH /c (Content-Format: application/yang-identifiers+cbor) 852 [ 853 1723, / current-datetime (SID 1723) / 854 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 855 ] 857 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 858 [ 859 { 860 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 861 }, 862 { 863 1533 : { 864 4 : "eth0", / name (SID 1537) / 865 1 : "Ethernet adaptor", / description (SID 1534) / 866 5 : 1880, / type (SID 1538), identity / 867 / ethernetCsmacd (SID 1880) / 868 2 : true / enabled (SID 1535) / 869 } 870 } 871 ] 873 4.3. Data Editing 875 CoMI allows datastore contents to be created, modified and deleted 876 using CoAP methods. 878 4.3.1. Data Ordering 880 A CoMI server MUST preserve the relative order of all user-ordered 881 list and leaf-list entries that are received in a single edit 882 request. These YANG data node types are encoded as CBOR arrays so 883 messages will preserve their order. 885 4.3.2. POST 887 The CoAP POST operation is used in CoMI for creation of data node 888 resources and the invocation of "ACTION" and "RPC" resources. Refer 889 to Section 4.6 for details on "ACTION" and "RPC" resources. 891 A request to create a data node instance is sent with a CoAP POST 892 message. The URI specifies the data node resource of the instance to 893 be created. In the case of a list instance, keys MUST be present in 894 the paylaod. 896 FORMAT: 897 POST 898 (Content-Format: application/yang-data+cbor) 899 CBOR map of SID, instance-value 901 2.01 Created 903 If the data node instance already exists, then the POST request MUST 904 fail and a "4.09 Conflict" response code MUST be returned 906 4.3.2.1. Post example 908 The example uses the interface list from module ietf-interfaces 909 [RFC7223]. This example creates a new list instance within the 910 interface list (SID = 1533): 912 REQ: POST /c/X9 (Content-Format: application/yang-data+cbor) 913 { 914 1533 : [ 915 { 916 4 : "eth5", / name (SID 1537) / 917 1 : "Ethernet adaptor", / description (SID 1534) / 918 5 : 1880, / type (SID 1538), identity / 919 / ethernetCsmacd (SID 1880) / 920 2 : true / enabled (SID 1535) / 921 } 922 ] 923 } 925 RES: 2.01 Created 927 4.3.3. PUT 929 A data node resource instance is created or replaced with the PUT 930 method. A request to set the value of a data node instance is sent 931 with a CoAP PUT message. 933 FORMAT: 934 PUT ['k' Uri-Query option] 935 (Content-Format: application/yang-data+cbor) 936 CBOR map of SID, instance-value 938 2.01 Created 940 4.3.3.1. PUT example 942 The example uses the interface list from module ietf-interfaces 943 [RFC7223]. This example updates the instance of the list interface 944 (SID = 1533) with key name="eth0": 946 REQ: PUT /c/X9?k="eth0" (Content-Format: application/yang-data+cbor) 947 { 948 1533 : [ 949 { 950 4 : "eth0", / name (SID 1537) / 951 1 : "Ethernet adaptor", / description (SID 1534) / 952 5 : 1880, / type (SID 1538), identity / 953 / ethernetCsmacd (SID 1880) / 954 2 : true / enabled (SID 1535) / 955 } 956 ] 957 } 959 RES: 2.04 Changed 961 4.3.4. iPATCH 963 One or multiple data node instances are replaced with the idempotent 964 CoAP iPATCH method [RFC8132]. 966 There are no Uri-Query options for the iPATCH method. 968 The processing of the iPATCH command is specified by Content-Format 969 'application/yang-instances+cbor'. In summary, if the CBOR patch 970 payload contains a data node instance that is not present in the 971 target, this instance is added. If the target contains the specified 972 instance, the content of this instance is replaced with the value of 973 the payload. A null value indicates the removal of an existing data 974 node instance. 976 FORMAT: 977 iPATCH 978 (Content-Format: application/yang-instances+cbor) 979 CBOR array of CBOR map of instance-identifier, instance-value 981 2.04 Changed 983 4.3.4.1. iPATCH example 985 In this example, a CoMI client requests the following operations: 987 o Set "/system/ntp/enabled" (SID 1755) to true. 989 o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID 990 1756) list. 992 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 993 server" (SID 1756). 995 REQ: iPATCH /c (Content-Format: application/yang-instances+cbor) 996 [ 997 { 998 1755 : true / enabled (SID 1755) / 999 }, 1000 { 1001 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 1002 }, 1003 { 1004 1756 : { / server (SID 1756) / 1005 3 : "tic.nrc.ca", / name (SID 1759) / 1006 4 : true, / prefer (SID 1760) / 1007 5 : { / udp (SID 1761) / 1008 1 : "132.246.11.231" / address (SID 1762) / 1009 } 1010 } 1011 } 1012 ] 1014 RES: 2.04 Changed 1016 4.3.5. DELETE 1018 A data node resource is deleted with the DELETE method. 1020 FORMAT: 1021 Delete ['k' Uri-Query option] 1023 2.02 Deleted 1025 4.3.5.1. DELETE example 1027 This example uses the interface list from module ietf-interfaces 1028 [RFC7223]. This example deletes an instance of the interface list 1029 (SID = 1533): 1031 REQ: DELETE /c/X9?k="eth0" 1033 RES: 2.02 Deleted 1035 4.4. Full datastore access 1037 The methods GET, PUT, POST, and DELETE can be used to request, 1038 replace, create, and delete a whole datastore respectively. 1040 FORMAT: 1041 GET 1043 2.05 Content (Content-Format: application/yang-data+cbor) 1044 CBOR map of SID, instance-value 1046 FORMAT: 1047 PUT 1048 (Content-Format: application/yang-data+cbor) 1049 CBOR map of SID, instance-value 1051 2.04 Changed 1053 FORMAT: 1054 POST 1055 (Content-Format: application/yang-data+cbor) 1056 CBOR map of SID, instance-value 1058 2.01 Created 1060 FORMAT: 1061 DELETE 1063 2.02 Deleted 1065 The content of the CBOR map represents the complete datastore of the 1066 server at the GET indication of after a successful processing of a 1067 PUT or POST request. 1069 4.4.1. Full datastore examples 1071 The example uses the interface list from module ietf-interfaces 1072 [RFC7223] and the clock container from module ietf-system [RFC7317]. 1073 We assume that the datastore contains two modules ietf-system (SID 1074 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1075 list (SID 1533) with one instance and the 'clock' container (SID 1076 1721). After invocation of GET, a CBOR map with data nodes from 1077 these two modules is returned: 1079 REQ: GET /c 1081 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1082 { 1083 1721 : { / Clock (SID 1721) / 1084 2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1085 1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1086 }, 1087 1533 : [ 1088 { / interface (SID 1533) / 1089 4 : "eth0", / name (SID 1537) / 1090 1 : "Ethernet adaptor", / description (SID 1534) / 1091 5 : 1880, / type (SID 1538), identity: / 1092 / ethernetCsmacd (SID 1880) / 1093 2 : true / enabled (SID 1535) / 1094 } 1095 ] 1096 } 1098 4.5. Event stream 1100 Event notification is an essential function for the management of 1101 servers. CoMI allows notifications specified in YANG [RFC5277] to be 1102 reported to a list of clients. The recommended path of the default 1103 event stream is /s. The server MAY support additional event stream 1104 resources to address different notification needs. 1106 Reception of notification instances is enabled with the CoAP Observe 1107 [RFC7641] function. Clients subscribe to the notifications by 1108 sending a GET request with an "Observe" option, specifying the /s 1109 resource when the default stream is selected. 1111 Each response payload carries one or multiple notifications. The 1112 number of notifications reported, and the conditions used to remove 1113 notifications from the reported list is left to implementers. When 1114 multiple notifications are reported, they MUST be ordered starting 1115 from the newest notification at index zero. 1117 The format of notification without any content is a null value. The 1118 format of single notification is defined in [I-D.ietf-core-yang-cbor] 1119 section 4.2.1. For multiple notifications the format is an array 1120 where each element is a single notification as described in 1121 [I-D.ietf-core-yang-cbor] section 4.2.1. 1123 FORMAT: 1124 GET Observe(0) 1126 2.05 Content (Content-Format: application/yang-instances+cbor) 1127 CBOR array of CBOR map of instance-identifier, instance-value 1129 The array of data node instances may contain identical entries which 1130 have been generated at different times. 1132 An example implementation is: 1134 Every time an event is generated, the generated notification 1135 instance is appended to the chosen stream(s). After an 1136 aggregation period, which may be limited by the maximum number of 1137 notifications supported, the content of the instance is sent to 1138 all clients observing the modified stream. 1140 4.5.1. Notify Examples 1142 Let suppose the server generates the example-port-fault event as 1143 defined below. 1145 module example-port { 1146 ... 1147 notification example-port-fault { // SID 60010 1148 description 1149 "Event generated if a hardware fault is detected"; 1150 leaf port-name { // SID 60011 1151 type string; 1152 } 1153 leaf port-fault { // SID 60012 1154 type string; 1155 } 1156 } 1157 } 1159 By executing a GET on the /s resource the client receives the 1160 following response: 1162 REQ: GET /s Observe(0) 1164 RES: 2.05 Content (Content-Format: application/yang-tree+cbor) 1165 Observe(12) 1166 [ 1167 { 1168 60010 : { / example-port-fault (SID 60010) / 1169 1 : "0/4/21", / port-name (SID 60011) / 1170 2 : "Open pin 2" / port-fault (SID 60012) / 1171 } 1172 }, 1173 { 1174 60010 : { / example-port-fault (SID 60010) / 1175 1 : "1/4/21", / port-name (SID 60011) / 1176 2 : "Open pin 5" / port-fault (SID 60012) / 1177 } 1178 } 1179 ] 1181 In the example, the request returns a success response with the 1182 contents of the last two generated events. Consecutively the server 1183 will regularly notify the client when a new event is generated. 1185 To check that the client is still alive, the server MUST send 1186 Confirmable Message periodically. When the client does not confirm 1187 the notification from the server, the server will remove the client 1188 from the list of observers [RFC7641]. 1190 4.5.2. The 'f' Uri-Query option 1192 The 'f' (filter) option is used to indicate which subset of all 1193 possible notifications is of interest. If not present, all 1194 notifications supported by the event stream are reported. 1196 When not supported by a CoMI server, this option shall be ignored, 1197 all events notifications are reported independently of the presence 1198 and content of the 'f' (filter) option. 1200 When present, this option contains a comma separated list of 1201 notification SIDs. For example, the following request returns 1202 notifications 60010 and 60020. 1204 REQ: GET /s?f=60010,60020 Observe(0) 1206 4.6. RPC statements 1208 The YANG "action" and "RPC" statements specify the execution of a 1209 Remote procedure Call (RPC) in the server. It is invoked using a 1210 POST method to an "Action" or "RPC" resource instance. 1212 The request payload contains the values assigned to the input 1213 container when specified. The response payload contains the values 1214 of the output container when specified. Both the input and output 1215 containers are encoded in CBOR using the rules defined in 1216 [I-D.ietf-core-yang-cbor] section 4.2.1. 1218 The returned success response code is 2.05 Content. 1220 FORMAT: 1221 POST ['k' Uri-Query option] 1222 (Content-Format: application/yang-data+cbor) 1223 CBOR map of SID, instance-value 1225 2.05 Content (Content-Format: application/yang-data+cbor) 1226 CBOR map of SID, instance-value 1228 4.6.1. RPC Example 1230 The example is based on the YANG action "reset" as defined in 1231 [RFC7950] section 7.15.3 and annotated below with SIDs. 1233 module example-server-farm { 1234 yang-version 1.1; 1235 namespace "urn:example:server-farm"; 1236 prefix "sfarm"; 1238 import ietf-yang-types { 1239 prefix "yang"; 1240 } 1242 list server { // SID 60000 1243 key name; 1244 leaf name { // SID 60001 1245 type string; 1246 } 1247 action reset { // SID 60002 1248 input { 1249 leaf reset-at { // SID 60003 1250 type yang:date-and-time; 1251 mandatory true; 1252 } 1253 } 1254 output { 1255 leaf reset-finished-at { // SID 60004 1256 type yang:date-and-time; 1257 mandatory true; 1258 } 1259 } 1260 } 1261 } 1262 } 1264 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1265 the server instance with name equal to "myserver". 1267 REQ: POST /c/Opq?k="myserver" 1268 (Content-Format: application/yang-data+cbor) 1269 { 1270 60002 : { 1271 1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1272 } 1273 } 1275 RES: 2.05 Content (Content-Format: application/yang-data+cbor) 1276 { 1277 60002 : { 1278 2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1279 } 1280 } 1282 5. Use of Block-wise Transfers 1284 The CoAP protocol provides reliability by acknowledging the UDP 1285 datagrams. However, when large pieces of data need to be 1286 transported, datagrams get fragmented, thus creating constraints on 1287 the resources in the client, server and intermediate routers. The 1288 block option [RFC7959] allows the transport of the total payload in 1289 individual blocks of which the size can be adapted to the underlying 1290 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1291 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1292 acknowledged to guarantee reliability. 1294 Notice that the Block mechanism splits the data at fixed positions, 1295 such that individual data fields may become fragmented. Therefore, 1296 assembly of multiple blocks may be required to process complete data 1297 fields. 1299 Beware of race conditions. Blocks are filled one at a time and care 1300 should be taken that the whole data representation is sent in 1301 multiple blocks sequentially without interruption. On the server, 1302 values are changed, lists are re-ordered, extended or reduced. When 1303 these actions happen during the serialization of the contents of the 1304 resource, the transported results do not correspond with a state 1305 having occurred in the server; or worse the returned values are 1306 inconsistent. For example: array length does not correspond with the 1307 actual number of items. It may be advisable to use Indefinite-length 1308 CBOR arrays and maps, which are foreseen for data streaming purposes. 1310 6. Application Discovery 1312 Two application discovery mechanisms are supported by CoMI, the YANG 1313 library data model as defined by [I-D.ietf-core-yang-library] and the 1314 CORE resource discovery [RFC6690]. Implementers may choose to 1315 implement one or the other or both. 1317 6.1. YANG library 1319 The YANG library data model [I-D.ietf-core-yang-library] provides a 1320 high level description of the resources available. The YANG library 1321 contains the list of modules, features and deviations supported by 1322 the CoMI server. From this information, CoMI clients can infer the 1323 list of data nodes supported and the interaction model to be used to 1324 access them. This module also contains the list of datastores 1325 implemented. 1327 As described in [RFC6690], the location of the YANG library can be 1328 found by sending a GET request to "/.well-known/core" including a 1329 resource type (RT) parameter with the value "core.c.yl". Upon 1330 success, the return payload will contain the root resource of the 1331 YANG library module. 1333 The following example assumes that the SID of the YANG library is 1334 2351 (kv encoded as specified in Section 2.2). 1336 REQ: GET /.well-known/core?rt=core.c.yl 1338 RES: 2.05 Content (Content-Format: application/link-format) 1339 ;rt="core.c.yl" 1341 6.2. Resource Discovery 1343 As some CoAP interfaces and services might not support the YANG 1344 library interface and still be interested to discover resources that 1345 are available, implementations MAY choose to support discovery of all 1346 available resources using "/.well-known/core" as defined by 1347 [RFC6690]. 1349 6.2.1. Datastore Resource Discovery 1351 The presence and location of (path to) each datastore implemented by 1352 the CoMI server can be discovered by sending a GET request to 1353 "/.well-known/core" including a resource type (RT) parameter with the 1354 value "core.c.ds". 1356 Upon success, the return payload contains the list of datastore 1357 resources. 1359 Each datastore returned is further qualified using the "ds" Link- 1360 Format attribute. This attribute is set to the SID assigned to the 1361 datastore identity. When a unified datastore is implemented, the ds 1362 attribute is set to 1029 as specified in Appendix B. For other 1363 examples of datastores, see the Network Management Datastore 1364 Architecture (NMDA) [RFC7950]. 1366 link-extension = ( "ds" "=" sid ) ) 1367 ; SID assigned to the datastore identity 1368 sid = 1*DIGIT 1370 For example: 1372 REQ: GET /.well-known/core?rt=core.c.ds 1374 RES: 2.05 Content (Content-Format: application/link-format) 1375 ; rt="core.c.ds";ds=1029 1377 6.2.2. Data node Resource Discovery 1379 If implemented, the presence and location of (path to) each data node 1380 implemented by the CoMI server are discovered by sending a GET 1381 request to "/.well-known/core" including a resource type (RT) 1382 parameter with the value "core.c.dn". 1384 Upon success, the return payload contains the SID assigned to each 1385 data node and their location. 1387 The example below shows the discovery of the presence and location of 1388 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1389 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1390 datetime' (SID 1723) are returned. 1392 REQ: GET /.well-known/core?rt=core.c.dn 1394 RES: 2.05 Content (Content-Format: application/link-format) 1395 ;rt="core.c.dn", 1396 ;rt="core.c.dn" 1398 Without additional filtering, the list of data nodes may become 1399 prohibitively long. If this is the case implementations SHOULD 1400 support a way to obtain all links using multiple GET requests (for 1401 example through some form of pagination). 1403 6.2.3. Event stream Resource Discovery 1405 The presence and location of (path to) each event stream implemented 1406 by the CoMI server are discovered by sending a GET request to 1407 "/.well-known/core" including a resource type (RT) parameter with the 1408 value "core.c.es". 1410 Upon success, the return payload contains the list of event stream 1411 resources. 1413 For example: 1415 REQ: GET /.well-known/core?rt=core.c.es 1417 RES: 2.05 Content (Content-Format: application/link-format) 1418 ;rt="core.c.es" 1420 7. Error Handling 1422 In case a request is received which cannot be processed properly, the 1423 CoMI server MUST return an error response. This error response MUST 1424 contain a CoAP 4.xx or 5.xx response code. 1426 Errors returned by a CoMI server can be broken into two categories, 1427 those associated to the CoAP protocol itself and those generated 1428 during the validation of the YANG data model constrains as described 1429 in [RFC7950] section 8. 1431 The following list of common CoAP errors should be implemented by 1432 CoMI servers. This list is not exhaustive, other errors defined by 1433 CoAP and associated RFCs may be applicable. 1435 o Error 4.01 (Unauthorized) is returned by the CoMI server when the 1436 CoMI client is not authorized to perform the requested action on 1437 the targeted resource (i.e. data node, datastore, rpc, action or 1438 event stream). 1440 o Error 4.02 (Bad Option) is returned by the CoMI server when one or 1441 more CoAP options are unknown or malformed. 1443 o Error 4.04 (Not Found) is returned by the CoMI server when the 1444 CoMI client is requesting a non-instantiated resource (i.e. data 1445 node, datastore, rpc, action or event stream). 1447 o Error 4.05 (Method Not Allowed) is returned by the CoMI server 1448 when the CoMI client is requesting a method not supported on the 1449 targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1450 node with "config" set to false). 1452 o Error 4.08 (Request Entity Incomplete) is returned by the CoMI 1453 server if one or multiple blocks of a block transfer request is 1454 missing, see [RFC7959] for more details. 1456 o Error 4.13 (Request Entity Too Large) may be returned by the CoMI 1457 server during a block transfer request, see [RFC7959] for more 1458 details. 1460 o Error 4.15 (Unsupported Content-Format) is returned by the CoMI 1461 server when the Content-Format used in the request does not match 1462 those specified in section Section 2.4. 1464 The CoMI server MUST also enforce the different constraints 1465 associated to the YANG data models implemented. These constraints 1466 are described in [RFC7950] section 8. These errors are reported 1467 using the CoAP error code 4.00 (Bad Request) and may have the 1468 following error container as payload. The YANG definition and 1469 associated .sid file are available in Appendix A and Appendix B. The 1470 error container is encoded using the encoding rules of a YANG data 1471 template as defined in [I-D.ietf-core-yang-cbor] section 5. 1473 +--rw error! 1474 +--rw error-tag identityref 1475 +--rw error-app-tag? identityref 1476 +--rw error-data-node? instance-identifier 1477 +--rw error-message? string 1479 The following 'error-tag' and 'error-app-tag' are defined by the 1480 ietf-comi YANG module, these tags are implemented as YANG identity 1481 and can be extended as needed. 1483 o error-tag 'operation-failed' is returned by the CoMI server when 1484 the operation request cannot be processed successfully. 1486 * error-app-tag 'malformed-message' is returned by the CoMI 1487 server when the payload received from the CoMI client does not 1488 contain a well-formed CBOR content as defined in [RFC7049] 1489 section 3.3 or does not comply with the CBOR structure defined 1490 within this document. 1492 * error-app-tag 'data-not-unique' is returned by the CoMI server 1493 when the validation of the 'unique' constraint of a list or 1494 leaf-list fails. 1496 * error-app-tag 'too-many-elements' is returned by the CoMI 1497 server when the validation of the 'max-elements' constraint of 1498 a list or leaf-list fails. 1500 * error-app-tag 'too-few-elements' is returned by the CoMI server 1501 when the validation of the 'min-elements' constraint of a list 1502 or leaf-list fails. 1504 * error-app-tag 'must-violation' is returned by the CoMI server 1505 when the restrictions imposed by a 'must' statement are 1506 violated. 1508 * error-app-tag 'duplicate' is returned by the CoMI server when a 1509 client tries to create a duplicate list or leaf-list entry. 1511 o error-tag 'invalid-value' is returned by the CoMI server when the 1512 CoMI client tries to update or create a leaf with a value encoded 1513 using an invalid CBOR datatype or if the 'range', 'length', 1514 'pattern' or 'require-instance' constrain is not fulfilled. 1516 * error-app-tag 'invalid-datatype' is returned by the CoMI server 1517 when CBOR encoding does not follow the rules set by the YANG 1518 Build-In type or when the value is incompatible with it (e.g. a 1519 value greater than 127 for an int8, undefined enumeration). 1521 * error-app-tag 'not-in-range' is returned by the CoMI server 1522 when the validation of the 'range' property fails. 1524 * error-app-tag 'invalid-length' is returned by the CoMI server 1525 when the validation of the 'length' property fails. 1527 * error-app-tag 'pattern-test-failed' is returned by the CoMI 1528 server when the validation of the 'pattern' property fails. 1530 o error-tag 'missing-element' is returned by the CoMI server when 1531 the operation requested by a CoMI client fails to comply with the 1532 'mandatory' constraint defined. The 'mandatory' constraint is 1533 enforced for leafs and choices, unless the node or any of its 1534 ancestors have a 'when' condition or 'if-feature' expression that 1535 evaluates to 'false'. 1537 * error-app-tag 'missing-key' is returned by the CoMI server to 1538 further qualify a missing-element error. This error is 1539 returned when the CoMI client tries to create or list instance, 1540 without all the 'key' specified or when the CoMI client tries 1541 to delete a leaf listed as a 'key'. 1543 * error-app-tag 'missing-input-parameter' is returned by the CoMI 1544 server when the input parameters of an RPC or action are 1545 incomplete. 1547 o error-tag 'unknown-element' is returned by the CoMI server when 1548 the CoMI client tries to access a data node of a YANG module not 1549 supported, of a data node associated to an 'if-feature' expression 1550 evaluated to 'false' or to a 'when' condition evaluated to 1551 'false'. 1553 o error-tag 'bad-element' is returned by the CoMI server when the 1554 CoMI client tries to create data nodes for more than one case in a 1555 choice. 1557 o error-tag 'data-missing' is returned by the CoMI server when a 1558 data node required to accept the request is not present. 1560 * error-app-tag 'instance-required' is returned by the CoMI 1561 server when a leaf of type 'instance-identifier' or 'leafref' 1562 marked with require-instance set to 'true' refers to an 1563 instance that does not exist. 1565 * error-app-tag 'missing-choice' is returned by the CoMI server 1566 when no nodes exist in a mandatory choice. 1568 o error-tag 'error' is returned by the CoMI server when an 1569 unspecified error has occurred. 1571 For example, the CoMI server might return the following error. 1573 RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor) 1574 { 1575 1024 : { 1576 4 : 1011, / error-tag (SID 1028) / 1577 / = invalid-value (SID 1011) / 1578 1 : 1018, / error-app-tag (SID 1025) / 1579 / = not-in-range (SID 1018) / 1580 2 : 1740, / error-data-node (SID 1026) / 1581 / = timezone-utc-offset (SID 1740) / 1582 3 : "maximum value exceeded" / error-message (SID 1027) / 1583 } 1584 } 1586 8. Security Considerations 1588 For secure network management, it is important to restrict access to 1589 configuration variables only to authorized parties. CoMI re-uses the 1590 security mechanisms already available to CoAP, this includes DTLS 1591 [RFC6347] for protected access to resources, as well suitable 1592 authentication and authorization mechanisms. 1594 Among the security decisions that need to be made are selecting 1595 security modes and encryption mechanisms (see [RFC7252]). 1597 In addition, mechanisms for authentication and authorization may need 1598 to be selected if not provided with the security mode. 1600 9. IANA Considerations 1602 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1604 This document adds the following resource type to the "Resource Type 1605 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1606 Environments (CoRE) Parameters" registry. 1608 +-----------+---------------------+-----------+ 1609 | Value | Description | Reference | 1610 +-----------+---------------------+-----------+ 1611 | core.c.ds | YANG datastore | RFC XXXX | 1612 | | | | 1613 | core.c.dn | YANG data node | RFC XXXX | 1614 | | | | 1615 | core.c.yl | YANG module library | RFC XXXX | 1616 | | | | 1617 | core.c.es | YANG event stream | RFC XXXX | 1618 +-----------+---------------------+-----------+ 1620 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1621 note. 1623 9.2. CoAP Content-Formats Registry 1625 This document adds the following Content-Format to the "CoAP Content- 1626 Formats", within the "Constrained RESTful Environments (CoRE) 1627 Parameters" registry. 1629 +-----------------------------------+------------+------+-----------+ 1630 | Media Type | Content | ID | Reference | 1631 | | Coding | | | 1632 +-----------------------------------+------------+------+-----------+ 1633 | application/yang-data+cbor | | TBD1 | RFC XXXX | 1634 | | | | | 1635 | application/yang-identifiers+cbor | | TBD2 | RFC XXXX | 1636 | | | | | 1637 | application/yang-instances+cbor | | TBD3 | RFC XXXX | 1638 +-----------------------------------+------------+------+-----------+ 1640 // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove 1641 this note. // RFC Ed.: replace RFC XXXX with this RFC number and 1642 remove this note. 1644 9.3. Media Types Registry 1646 This document adds the following media types to the "Media Types" 1647 registry. 1649 +-----------------------+----------------------------+-----------+ 1650 | Name | Template | Reference | 1651 +-----------------------+----------------------------+-----------+ 1652 | yang-data+cbor | application/yang-data+cbor | RFC XXXX | 1653 | | | | 1654 | yang-identifiers+cbor | application/ | RFC XXXX | 1655 | | | | 1656 | | yang-identifiers+cbor | | 1657 | | | | 1658 | yang-instances+cbor | application/ | RFC XXXX | 1659 | | | | 1660 | | yang-instances+cbor | | 1661 +-----------------------+----------------------------+-----------+ 1663 Each of these media types share the following information: 1665 o Subtype name: 1667 o Required parameters: N/A 1669 o Optional parameters: N/A 1671 o Encoding considerations: binary 1673 o Security considerations: See the Security Considerations section 1674 of RFC XXXX 1676 o Interoperability considerations: N/A 1678 o Published specification: RFC XXXX 1680 o Applications that use this media type: CoMI 1682 o Fragment identifier considerations: N/A 1684 o Additional information: 1686 * Deprecated alias names for this type: N/A 1688 * Magic number(s): N/A 1690 * File extension(s): N/A 1692 * Macintosh file type code(s): N/A 1694 o Person & email address to contact for further information: 1695 iesg&ietf.org 1697 o Intended usage: COMMON 1699 o Restrictions on usage: N/A 1701 o Author: Michel Veillette, ietf&augustcellars.com 1703 o Change Controller: IESG 1705 o Provisional registration? No 1707 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1708 note. 1710 10. Acknowledgements 1712 We are very grateful to Bert Greevenbosch who was one of the original 1713 authors of the CoMI specification. 1715 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1716 transported under SNMP. Carsten Bormann has given feedback on the 1717 use of CBOR. 1719 The draft has benefited from comments (alphabetical order) by Rodney 1720 Cummings, Dee Denteneer, Esko Dijk, Michael van Hartskamp, Tanguy 1721 Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach Shelby, Hannes 1722 Tschofenig, Michael Verschoor, and Thomas Watteyne. 1724 11. References 1726 11.1. Normative References 1728 [I-D.ietf-core-sid] 1729 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1730 iDentifier (SID)", draft-ietf-core-sid-11 (work in 1731 progress), March 2020. 1733 [I-D.ietf-core-yang-cbor] 1734 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1735 Data Modeled with YANG", draft-ietf-core-yang-cbor-11 1736 (work in progress), September 2019. 1738 [I-D.ietf-core-yang-library] 1739 Veillette, M. and I. Petrov, "Constrained YANG Module 1740 Library", draft-ietf-core-yang-library-01 (work in 1741 progress), January 2020. 1743 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1744 Requirement Levels", BCP 14, RFC 2119, 1745 DOI 10.17487/RFC2119, March 1997, 1746 . 1748 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1749 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1750 . 1752 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1753 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1754 . 1756 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1757 and A. Bierman, Ed., "Network Configuration Protocol 1758 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1759 . 1761 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1762 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1763 . 1765 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1766 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1767 October 2013, . 1769 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1770 Application Protocol (CoAP)", RFC 7252, 1771 DOI 10.17487/RFC7252, June 2014, 1772 . 1774 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1775 Application Protocol (CoAP)", RFC 7641, 1776 DOI 10.17487/RFC7641, September 2015, 1777 . 1779 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1780 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1781 . 1783 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1784 the Constrained Application Protocol (CoAP)", RFC 7959, 1785 DOI 10.17487/RFC7959, August 2016, 1786 . 1788 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1789 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1790 . 1792 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1793 FETCH Methods for the Constrained Application Protocol 1794 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1795 . 1797 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1798 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1799 May 2017, . 1801 11.2. Informative References 1803 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1804 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1805 January 2012, . 1807 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1808 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1809 . 1811 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1812 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1813 . 1815 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1816 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1817 2014, . 1819 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1820 and R. Wilton, "Network Management Datastore Architecture 1821 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1822 . 1824 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1825 "Object Security for Constrained RESTful Environments 1826 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1827 . 1829 Appendix A. ietf-comi YANG module 1831 file "ietf-comi@2019-03-28.yang" 1832 module ietf-comi { 1833 yang-version 1.1; 1835 namespace "urn:ietf:params:xml:ns:yang:ietf-comi"; 1836 prefix comi; 1838 import ietf-datastores { 1839 prefix ds; 1841 } 1843 import ietf-restconf { 1844 prefix rc; 1845 description 1846 "This import statement is required to access 1847 the yang-data extension defined in RFC 8040."; 1848 reference "RFC 8040: RESTCONF Protocol"; 1849 } 1851 organization 1852 "IETF Core Working Group"; 1854 contact 1855 "Michel Veillette 1856 1858 Alexander Pelov 1859 1861 Peter van der Stok 1862 1864 Andy Bierman 1865 "; 1867 description 1868 "This module contains the different definitions required 1869 by the CoMI protocol. 1871 Copyright (c) 2019 IETF Trust and the persons identified as 1872 authors of the code. All rights reserved. 1874 Redistribution and use in source and binary forms, with or 1875 without modification, is permitted pursuant to, and subject to 1876 the license terms contained in, the Simplified BSD License set 1877 forth in Section 4.c of the IETF Trust's Legal Provisions 1878 Relating to IETF Documents 1879 (https://trustee.ietf.org/license-info). 1881 This version of this YANG module is part of RFC XXXX; 1882 see the RFC itself for full legal notices."; 1884 revision 2019-03-28 { 1885 description 1886 "Initial revision."; 1887 reference 1888 "[I-D.ietf-core-comi] CoAP Management Interface"; 1890 } 1892 identity unified { 1893 base ds:datastore; 1894 description 1895 "Identifier of the unified configuration and operational 1896 state datastore."; 1897 } 1899 identity error-tag { 1900 description 1901 "Base identity for error-tag."; 1902 } 1904 identity operation-failed { 1905 base error-tag; 1906 description 1907 "Returned by the CoMI server when the operation request 1908 can't be processed successfully."; 1909 } 1911 identity invalid-value { 1912 base error-tag; 1913 description 1914 "Returned by the CoMI server when the CoMI client tries to 1915 update or create a leaf with a value encoded using an 1916 invalid CBOR datatype or if the 'range', 'length', 1917 'pattern' or 'require-instance' constrain is not 1918 fulfilled."; 1919 } 1921 identity missing-element { 1922 base error-tag; 1923 description 1924 "Returned by the CoMI server when the operation requested 1925 by a CoMI client fails to comply with the 'mandatory' 1926 constraint defined. The 'mandatory' constraint is 1927 enforced for leafs and choices, unless the node or any of 1928 its ancestors have a 'when' condition or 'if-feature' 1929 expression that evaluates to 'false'."; 1930 } 1932 identity unknown-element { 1933 base error-tag; 1934 description 1935 "Returned by the CoMI server when the CoMI client tries to 1936 access a data node of a YANG module not supported, of a 1937 data node associated with an 'if-feature' expression 1938 evaluated to 'false' or to a 'when' condition evaluated 1939 to 'false'."; 1940 } 1942 identity bad-element { 1943 base error-tag; 1944 description 1945 "Returned by the CoMI server when the CoMI client tries to 1946 create data nodes for more than one case in a choice."; 1947 } 1949 identity data-missing { 1950 base error-tag; 1951 description 1952 "Returned by the CoMI server when a data node required to 1953 accept the request is not present."; 1954 } 1956 identity error { 1957 base error-tag; 1958 description 1959 "Returned by the CoMI server when an unspecified error has 1960 occurred."; 1961 } 1963 identity error-app-tag { 1964 description 1965 "Base identity for error-app-tag."; 1966 } 1968 identity malformed-message { 1969 base error-app-tag; 1970 description 1971 "Returned by the CoMI server when the payload received 1972 from the CoMI client don't contain a well-formed CBOR 1973 content as defined in [RFC7049] section 3.3 or don't 1974 comply with the CBOR structure defined within this 1975 document."; 1976 } 1978 identity data-not-unique { 1979 base error-app-tag; 1980 description 1981 "Returned by the CoMI server when the validation of the 1982 'unique' constraint of a list or leaf-list fails."; 1983 } 1985 identity too-many-elements { 1986 base error-app-tag; 1987 description 1988 "Returned by the CoMI server when the validation of the 1989 'max-elements' constraint of a list or leaf-list fails."; 1990 } 1992 identity too-few-elements { 1993 base error-app-tag; 1994 description 1995 "Returned by the CoMI server when the validation of the 1996 'min-elements' constraint of a list or leaf-list fails."; 1997 } 1999 identity must-violation { 2000 base error-app-tag; 2001 description 2002 "Returned by the CoMI server when the restrictions 2003 imposed by a 'must' statement are violated."; 2004 } 2006 identity duplicate { 2007 base error-app-tag; 2008 description 2009 "Returned by the CoMI server when a client tries to create 2010 a duplicate list or leaf-list entry."; 2011 } 2013 identity invalid-datatype { 2014 base error-app-tag; 2015 description 2016 "Returned by the CoMI server when CBOR encoding is 2017 incorect or when the value encoded is incompatible with 2018 the YANG Built-In type. (e.g. value greater than 127 2019 for an int8, undefined enumeration)."; 2020 } 2022 identity not-in-range { 2023 base error-app-tag; 2024 description 2025 "Returned by the CoMI server when the validation of the 2026 'range' property fails."; 2027 } 2029 identity invalid-length { 2030 base error-app-tag; 2031 description 2032 "Returned by the CoMI server when the validation of the 2033 'length' property fails."; 2035 } 2037 identity pattern-test-failed { 2038 base error-app-tag; 2039 description 2040 "Returned by the CoMI server when the validation of the 2041 'pattern' property fails."; 2042 } 2044 identity missing-key { 2045 base error-app-tag; 2046 description 2047 "Returned by the CoMI server to further qualify a 2048 missing-element error. This error is returned when the 2049 CoMI client tries to create or list instance, without all 2050 the 'key' specified or when the CoMI client tries to 2051 delete a leaf listed as a 'key'."; 2052 } 2054 identity missing-input-parameter { 2055 base error-app-tag; 2056 description 2057 "Returned by the CoMI server when the input parameters 2058 of a RPC or action are incomplete."; 2059 } 2061 identity instance-required { 2062 base error-app-tag; 2063 description 2064 "Returned by the CoMI server when a leaf of type 2065 'instance-identifier' or 'leafref' marked with 2066 require-instance set to 'true' refers to an instance 2067 that does not exist."; 2068 } 2070 identity missing-choice { 2071 base error-app-tag; 2072 description 2073 "Returned by the CoMI server when no nodes exist in a 2074 mandatory choice."; 2075 } 2077 rc:yang-data comi-error { 2078 container error { 2079 description 2080 "Optional payload of a 4.00 Bad Request CoAP error."; 2082 leaf error-tag { 2083 type identityref { 2084 base error-tag; 2085 } 2086 mandatory true; 2087 description 2088 "The enumerated error-tag."; 2089 } 2091 leaf error-app-tag { 2092 type identityref { 2093 base error-app-tag; 2094 } 2095 description 2096 "The application-specific error-tag."; 2097 } 2099 leaf error-data-node { 2100 type instance-identifier; 2101 description 2102 "When the error reported is caused by a specific data node, 2103 this leaf identifies the data node in error."; 2104 } 2106 leaf error-message { 2107 type string; 2108 description 2109 "A message describing the error."; 2110 } 2111 } 2112 } 2113 } 2114 2116 Appendix B. ietf-comi .sid file 2118 { 2119 "assignment-ranges": [ 2120 { 2121 "entry-point": 1000, 2122 "size": 100 2123 } 2124 ], 2125 "module-name": "ietf-comi", 2126 "module-revision": "2019-03-28", 2127 "items": [ 2128 { 2129 "namespace": "module", 2130 "identifier": "ietf-comi", 2131 "sid": 1000 2132 }, 2133 { 2134 "namespace": "identity", 2135 "identifier": "bad-element", 2136 "sid": 1001 2137 }, 2138 { 2139 "namespace": "identity", 2140 "identifier": "data-missing", 2141 "sid": 1002 2142 }, 2143 { 2144 "namespace": "identity", 2145 "identifier": "data-not-unique", 2146 "sid": 1003 2147 }, 2148 { 2149 "namespace": "identity", 2150 "identifier": "duplicate", 2151 "sid": 1004 2152 }, 2153 { 2154 "namespace": "identity", 2155 "identifier": "error", 2156 "sid": 1005 2157 }, 2158 { 2159 "namespace": "identity", 2160 "identifier": "error-app-tag", 2161 "sid": 1006 2162 }, 2163 { 2164 "namespace": "identity", 2165 "identifier": "error-tag", 2166 "sid": 1007 2167 }, 2168 { 2169 "namespace": "identity", 2170 "identifier": "instance-required", 2171 "sid": 1008 2172 }, 2173 { 2174 "namespace": "identity", 2175 "identifier": "invalid-datatype", 2176 "sid": 1009 2177 }, 2178 { 2179 "namespace": "identity", 2180 "identifier": "invalid-length", 2181 "sid": 1010 2182 }, 2183 { 2184 "namespace": "identity", 2185 "identifier": "invalid-value", 2186 "sid": 1011 2187 }, 2188 { 2189 "namespace": "identity", 2190 "identifier": "malformed-message", 2191 "sid": 1012 2192 }, 2193 { 2194 "namespace": "identity", 2195 "identifier": "missing-choice", 2196 "sid": 1013 2197 }, 2198 { 2199 "namespace": "identity", 2200 "identifier": "missing-element", 2201 "sid": 1014 2202 }, 2203 { 2204 "namespace": "identity", 2205 "identifier": "missing-input-parameter", 2206 "sid": 1015 2207 }, 2208 { 2209 "namespace": "identity", 2210 "identifier": "missing-key", 2211 "sid": 1016 2212 }, 2213 { 2214 "namespace": "identity", 2215 "identifier": "must-violation", 2216 "sid": 1017 2217 }, 2218 { 2219 "namespace": "identity", 2220 "identifier": "not-in-range", 2221 "sid": 1018 2222 }, 2223 { 2224 "namespace": "identity", 2225 "identifier": "operation-failed", 2226 "sid": 1019 2228 }, 2229 { 2230 "namespace": "identity", 2231 "identifier": "pattern-test-failed", 2232 "sid": 1020 2233 }, 2234 { 2235 "namespace": "identity", 2236 "identifier": "too-few-elements", 2237 "sid": 1021 2238 }, 2239 { 2240 "namespace": "identity", 2241 "identifier": "too-many-elements", 2242 "sid": 1022 2243 }, 2244 { 2245 "namespace": "identity", 2246 "identifier": "unified", 2247 "sid": 1029 2248 }, 2249 { 2250 "namespace": "identity", 2251 "identifier": "unknown-element", 2252 "sid": 1023 2253 }, 2254 { 2255 "namespace": "data", 2256 "identifier": "/ietf-comi:error", 2257 "sid": 1024 2258 }, 2259 { 2260 "namespace": "data", 2261 "identifier": "/ietf-comi:error/error-app-tag", 2262 "sid": 1025 2263 }, 2264 { 2265 "namespace": "data", 2266 "identifier": "/ietf-comi:error/error-data-node", 2267 "sid": 1026 2268 }, 2269 { 2270 "namespace": "data", 2271 "identifier": "/ietf-comi:error/error-message", 2272 "sid": 1027 2273 }, 2274 { 2275 "namespace": "data", 2276 "identifier": "/ietf-comi:error/error-tag", 2277 "sid": 1028 2278 } 2279 ] 2280 } 2282 Authors' Addresses 2284 Michel Veillette (editor) 2285 Trilliant Networks Inc. 2286 610 Rue du Luxembourg 2287 Granby, Quebec J2J 2V2 2288 Canada 2290 Email: michel.veillette@trilliant.com 2292 Peter van der Stok (editor) 2293 consultant 2295 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2296 Email: consultancy@vanderstok.org 2297 URI: www.vanderstok.org 2299 Alexander Pelov 2300 Acklio 2301 2bis rue de la Chataigneraie 2302 Cesson-Sevigne, Bretagne 35510 2303 France 2305 Email: a@ackl.io 2307 Andy Bierman 2308 YumaWorks 2309 685 Cochran St. 2310 Suite #160 2311 Simi Valley, CA 93065 2312 USA 2314 Email: andy@yumaworks.com 2315 Ivaylo Petrov (editor) 2316 Acklio 2317 1137A avenue des Champs Blancs 2318 Cesson-Sevigne, Bretagne 35510 2319 France 2321 Email: ivaylo@ackl.io