idnits 2.17.1 draft-ietf-core-comi-10.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 04, 2020) is 1364 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 342 -- Looks like a reference, but probably isn't: '26' on line 343 -- Looks like a reference, but probably isn't: '57' on line 344 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-13 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-12 == Outdated reference: A later version (-03) exists of draft-ietf-core-yang-library-01 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-46) exists of draft-ietf-ace-oauth-authz-35 -- 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 (~~), 5 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: January 5, 2021 consultant 6 A. Pelov 7 Acklio 8 A. Bierman 9 YumaWorks 10 I. Petrov, Ed. 11 Acklio 12 July 04, 2020 14 CoAP Management Interface (CORECONF) 15 draft-ietf-core-comi-10 17 Abstract 19 This document describes a network management interface for 20 constrained devices and networks, called CoAP Management Interface 21 (CORECONF). The Constrained Application Protocol (CoAP) is used to 22 access datastore and data node resources specified in YANG, or SMIv2 23 converted to YANG. CORECONF uses the YANG to CBOR mapping and 24 converts YANG identifier strings to numeric identifiers for payload 25 size reduction. CORECONF extends the set of YANG based protocols, 26 NETCONF and RESTCONF, with the capability to manage constrained 27 devices and networks. 29 Note 31 Discussion and suggestions for improvement are requested, and should 32 be sent to yot@ietf.org. 34 Status of This Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at https://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on January 5, 2021. 50 Copyright Notice 52 Copyright (c) 2020 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (https://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 68 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 69 2. CORECONF Architecture . . . . . . . . . . . . . . . . . . . . 5 70 2.1. Major differences between RESTCONF and CORECONF . . . . . 6 71 2.1.1. Differences due to CoAP and its efficient usage . . . 6 72 2.1.2. Differences due to the use of CBOR . . . . . . . . . 7 73 2.2. Compression of YANG identifiers . . . . . . . . . . . . . 7 74 2.3. Instance-identifier . . . . . . . . . . . . . . . . . . . 8 75 2.4. Media-Types . . . . . . . . . . . . . . . . . . . . . . . 8 76 2.5. Unified datastore . . . . . . . . . . . . . . . . . . . . 10 77 3. Example syntax . . . . . . . . . . . . . . . . . . . . . . . 11 78 4. CoAP Interface . . . . . . . . . . . . . . . . . . . . . . . 11 79 4.1. Using the 'k' query parameter . . . . . . . . . . . . . . 13 80 4.2. Data Retrieval . . . . . . . . . . . . . . . . . . . . . 15 81 4.2.1. Using the 'c' query parameter . . . . . . . . . . . . 15 82 4.2.2. Using the 'd' query parameter . . . . . . . . . . . . 16 83 4.2.3. GET . . . . . . . . . . . . . . . . . . . . . . . . . 16 84 4.2.4. FETCH . . . . . . . . . . . . . . . . . . . . . . . . 19 85 4.3. Data Editing . . . . . . . . . . . . . . . . . . . . . . 20 86 4.3.1. Data Ordering . . . . . . . . . . . . . . . . . . . . 20 87 4.3.2. POST . . . . . . . . . . . . . . . . . . . . . . . . 20 88 4.3.3. PUT . . . . . . . . . . . . . . . . . . . . . . . . . 21 89 4.3.4. iPATCH . . . . . . . . . . . . . . . . . . . . . . . 22 90 4.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 91 4.4. Full datastore access . . . . . . . . . . . . . . . . . . 24 92 4.4.1. Full datastore examples . . . . . . . . . . . . . . . 24 93 4.5. Event stream . . . . . . . . . . . . . . . . . . . . . . 25 94 4.5.1. Notify Examples . . . . . . . . . . . . . . . . . . . 26 95 4.5.2. The 'f' query parameter . . . . . . . . . . . . . . . 27 97 4.6. RPC statements . . . . . . . . . . . . . . . . . . . . . 27 98 4.6.1. RPC Example . . . . . . . . . . . . . . . . . . . . . 28 99 5. Use of Block-wise Transfers . . . . . . . . . . . . . . . . . 30 100 6. Application Discovery . . . . . . . . . . . . . . . . . . . . 30 101 6.1. YANG library . . . . . . . . . . . . . . . . . . . . . . 30 102 6.2. Resource Discovery . . . . . . . . . . . . . . . . . . . 31 103 6.2.1. Datastore Resource Discovery . . . . . . . . . . . . 31 104 6.2.2. Data node Resource Discovery . . . . . . . . . . . . 32 105 6.2.3. Event stream Resource Discovery . . . . . . . . . . . 32 106 7. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 33 107 8. Security Considerations . . . . . . . . . . . . . . . . . . . 36 108 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 109 9.1. Resource Type (rt=) Link Target Attribute Values Registry 37 110 9.2. CoAP Content-Formats Registry . . . . . . . . . . . . . . 37 111 9.3. Media Types Registry . . . . . . . . . . . . . . . . . . 38 112 9.4. YANG Namespace Registration . . . . . . . . . . . . . . . 39 113 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 39 114 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 115 11.1. Normative References . . . . . . . . . . . . . . . . . . 40 116 11.2. Informative References . . . . . . . . . . . . . . . . . 41 117 Appendix A. ietf-coreconf YANG module . . . . . . . . . . . . . 42 118 Appendix B. ietf-coreconf .sid file . . . . . . . . . . . . . . 48 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51 121 1. Introduction 123 The Constrained Application Protocol (CoAP) [RFC7252] is designed for 124 Machine to Machine (M2M) applications such as smart energy, smart 125 city, and building control. Constrained devices need to be managed 126 in an automatic fashion to handle the large quantities of devices 127 that are expected in future installations. Messages between devices 128 need to be as small and infrequent as possible. The implementation 129 complexity and runtime resources need to be as small as possible. 131 This draft describes the CoAP Management Interface which uses CoAP 132 methods to access structured data defined in YANG [RFC7950]. This 133 draft is complementary to [RFC8040] which describes a REST-like 134 interface called RESTCONF, which uses HTTP methods to access 135 structured data defined in YANG. 137 The use of standardized data models specified in a standardized 138 language, such as YANG, promotes interoperability between devices and 139 applications from different manufacturers. 141 CORECONF and RESTCONF are intended to work in a stateless client- 142 server fashion. They use a single round-trip to complete a single 143 editing transaction, where NETCONF needs multiple round trips. 145 To promote small messages, CORECONF uses a YANG to CBOR mapping 146 [I-D.ietf-core-yang-cbor] and numeric identifiers [I-D.ietf-core-sid] 147 to minimize CBOR payloads and URI length. 149 1.1. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 153 "OPTIONAL" in this document are to be interpreted as described in BCP 154 14 [RFC2119] [RFC8174] when, and only when, they appear in all 155 capitals, as shown here. 157 The following terms are defined in the YANG data modeling language 158 [RFC7950]: action, anydata, anyxml, client, container, data model, 159 data node, identity, instance identifier, leaf, leaf-list, list, 160 module, RPC, schema node, server, submodule. 162 The following terms are defined in [RFC6241]: configuration data, 163 datastore, state data 165 The following term is defined in [I-D.ietf-core-sid]: YANG schema 166 item identifier (YANG SID, often shorten to simply SID). 168 The following terms are defined in the CoAP protocol [RFC7252]: 169 Confirmable Message, Content-Format, Endpoint. 171 The following terms are defined in this document: 173 data node resource: a CoAP resource that models a YANG data node. 175 datastore resource: a CoAP resource that models a YANG datastore. 177 event stream resource: a CoAP resource used by clients to observe 178 YANG notifications. 180 notification instance: An instance of a schema node of type 181 notification, specified in a YANG module implemented by the 182 server. The instance is generated in the server at the occurrence 183 of the corresponding event and reported by an event stream 184 resource. 186 list instance identifier: Handle used to identify a YANG data node 187 that is an instance of a YANG "list" specified with the values of 188 the key leaves of the list. 190 single instance identifier: Handle used to identify a specific data 191 node which can be instantiated only once. This includes data 192 nodes defined at the root of a YANG module and data nodes defined 193 within a container. This excludes data nodes defined within a 194 list or any children of these data nodes. 196 instance-identifier: List instance identifier or single instance 197 identifier. 199 instance-value: The value assigned to a data node instance. 200 Instance-values are serialized into the payload according to the 201 rules defined in section 4 of [I-D.ietf-core-yang-cbor]. 203 2. CORECONF Architecture 205 This section describes the CORECONF architecture to use CoAP for 206 reading and modifying the content of datastore(s) used for the 207 management of the instrumented node. 209 +----------------------------------------------------------------+ 210 | SMIv2 specification (optional) (2) | 211 +----------------------------------------------------------------+ 212 | 213 V 214 +----------------------------------------------------------------+ 215 | YANG specification (1) | 216 +----------------------------------------------------------------+ 217 | | 218 Client V Server V 219 +----------------+ +-----------------------+ 220 | Request |--> CoAP request(3) -->| Indication | 221 | Confirm |<-- CoAP response(3)<--| Response (4) | 222 | | | | 223 | |<==== Security (7) ===>|+---------------------+| 224 +----------------+ || Datastore(s) (5) || 225 |+---------------------+| 226 |+---------------------+| 227 || Event stream(s) (6) || 228 |+---------------------+| 229 +-----------------------+ 231 Figure 1: Abstract CORECONF architecture 233 Figure 1 is a high-level representation of the main elements of the 234 CORECONF management architecture. The different numbered components 235 of Figure 1 are discussed according to the component number. 237 (1) YANG specification: contains a set of named and versioned 238 modules. 240 (2) SMIv2 specification: Optional part that consists of a named 241 module which, specifies a set of variables and "conceptual 242 tables". There is an algorithm to translate SMIv2 specifications 243 to YANG specifications. 245 (3) CoAP request/response messages: The CORECONF client sends 246 request messages to and receives response messages from the 247 CORECONF server. 249 (4) Request, Indication, Response, Confirm: Processes performed by 250 the CORECONF clients and servers. 252 (5) Datastore: A resource used to access configuration data, state 253 data, RPCs, and actions. A CORECONF server may support a single 254 unified datastore or multiple datastores as those defined by 255 Network Management Datastore Architecture (NMDA) [RFC8342]. 257 (6) Event stream: A resource used to get real-time notifications. A 258 CORECONF server may support multiple Event streams serving 259 different purposes such as normal monitoring, diagnostic, syslog, 260 security monitoring. 262 (7) Security: The server MUST prevent unauthorized users from 263 reading or writing any CORECONF resources. CORECONF relies on 264 security protocols such as DTLS [RFC6347] or OSCORE [RFC8613] to 265 secure CoAP communications. 267 2.1. Major differences between RESTCONF and CORECONF 269 CORECONF is a RESTful protocol for small devices where saving bytes 270 to transport a message is very important. Contrary to RESTCONF, many 271 design decisions are motivated by the saving of bytes. Consequently, 272 CORECONF is not a RESTCONF over CoAP protocol, but differs more 273 significantly from RESTCONF. 275 2.1.1. Differences due to CoAP and its efficient usage 277 o CORECONF uses CoAP/UDP as transport protocol and CBOR as payload 278 format [I-D.ietf-core-yang-cbor]. RESTCONF uses HTTP/TCP as 279 transport protocol and JSON or XML as payload formats. 281 o CORECONF uses the methods FETCH and iPATCH to access multiple data 282 nodes. RESTCONF uses instead the HTTP method PATCH and the HTTP 283 method GET with the "fields" Query parameter. 285 o RESTCONF uses the HTTP methods HEAD, and OPTIONS, which are not 286 supported by CoAP. 288 o CORECONF does not support "insert" query parameter (first, last, 289 before, after) and the "point" query parameter which are supported 290 by RESTCONF. 292 o CORECONF does not support the "start-time" and "stop-time" query 293 parameters to retrieve past notifications. 295 2.1.2. Differences due to the use of CBOR 297 o CORECONF encodes YANG identifier strings as numbers, where 298 RESTCONF does not. 300 o CORECONF also differ in the handling of default values, only 301 'report-all' and 'trim' options are supported. 303 2.2. Compression of YANG identifiers 305 In the YANG specification, items are identified with a name string. 306 In order to significantly reduce the size of identifiers used in 307 CORECONF, numeric identifiers called YANG Schema Item iDentifier 308 (YANG SID or simply SID) are used instead. 310 When used in a URI, SIDs are encoded using base64 encoding of the SID 311 bytes. The base64 encoding is using the URL and Filename safe 312 alphabet as defined by [RFC4648] section 5, without padding. The 313 last 6 bits encoded is always aligned with the least significant 6 314 bits of the SID represented using an unsigned integer. 'A' 315 characters (value 0) at the start of the resulting string are 316 removed. See Figure 2 for complete illustration. 318 SID in base64 = URLsafeChar[SID >> 60 & 0x3F] | 319 URLsafeChar[SID >> 54 & 0x3F] | 320 URLsafeChar[SID >> 48 & 0x3F] | 321 URLsafeChar[SID >> 42 & 0x3F] | 322 URLsafeChar[SID >> 36 & 0x3F] | 323 URLsafeChar[SID >> 30 & 0x3F] | 324 URLsafeChar[SID >> 24 & 0x3F] | 325 URLsafeChar[SID >> 18 & 0x3F] | 326 URLsafeChar[SID >> 12 & 0x3F] | 327 URLsafeChar[SID >> 6 & 0x3F] | 328 URLsafeChar[SID & 0x3F] 330 Figure 2 332 For example, SID 1721 is encoded as follow. 334 URLsafeChar[1721 >> 60 & 0x3F] = URLsafeChar[0] = 'A' 335 URLsafeChar[1721 >> 54 & 0x3F] = URLsafeChar[0] = 'A' 336 URLsafeChar[1721 >> 48 & 0x3F] = URLsafeChar[0] = 'A' 337 URLsafeChar[1721 >> 42 & 0x3F] = URLsafeChar[0] = 'A' 338 URLsafeChar[1721 >> 36 & 0x3F] = URLsafeChar[0] = 'A' 339 URLsafeChar[1721 >> 30 & 0x3F] = URLsafeChar[0] = 'A' 340 URLsafeChar[1721 >> 24 & 0x3F] = URLsafeChar[0] = 'A' 341 URLsafeChar[1721 >> 18 & 0x3F] = URLsafeChar[0] = 'A' 342 URLsafeChar[1721 >> 12 & 0x3F] = URLsafeChar[0] = 'A' 343 URLsafeChar[1721 >> 6 & 0x3F] = URLsafeChar[26] = 'a' 344 URLsafeChar[1721 & 0x3F] = URLsafeChar[57] = '5' 346 The resulting base64 representation of SID 1721 is the two-character 347 string "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' query 361 parameter as defined in Section 4.1. 363 2.4. Media-Types 365 CORECONF uses Media-Types based on the YANG to CBOR mapping specified 366 in [I-D.ietf-core-yang-cbor]. 368 The following Media-Type is used as defined in [I-D.ietf-core-sid]. 370 o application/yang-data+cbor; id=sid 372 The following new Media-Types are defined in this document: 374 application/yang-identifiers+cbor: This Media-Type represents a CBOR 375 YANG document containing a list of instance-identifier used to 376 target specific data node instances within a datastore. 378 FORMAT: CBOR array of instance-identifier 380 The message payload of Media-Type 'application/yang- 381 identifiers+cbor' is encoded using a CBOR array. Each entry of 382 this CBOR array contain an instance-identifier encoded as defined 383 in [I-D.ietf-core-yang-cbor] section 6.13.1. 385 application/yang-instances+cbor: This Media-Type represents a CBOR 386 YANG document containing a list of data node instances. Each data 387 node instance is identified by its associated instance-identifier. 389 FORMAT: CBOR array of CBOR map of instance-identifier, instance- 390 value 392 The message payload of Media-Type 'application/yang- 393 instances+cbor' is encoded using a CBOR array. Each entry within 394 this CBOR array contains a CBOR map carrying an instance- 395 identifier and associated instance-value. Instance-identifiers 396 are encoded using the rules defined in [I-D.ietf-core-yang-cbor] 397 section 6.13.1, instance-values are encoded using the rules 398 defined in [I-D.ietf-core-yang-cbor] section 4. 400 When present in an iPATCH request payload, this Media-Type carry a 401 list of data node instances to be replaced, created, or deleted. 402 For each data node instance D, for which the instance-identifier 403 is the same as a data node instance I, in the targeted datastore 404 resource: the value of D replaces the value of I. When the value 405 of D is null, the data node instance I is removed. When the 406 targeted datastore resource does not contain a data node instance 407 with the same instance-identifier as D, a new instance is created 408 with the same instance-identifier and value as D. 410 The different Media-Type usages are summarized in the table below: 412 +---------------+--------------+------------------------------------+ 413 | Method | Resource | Media-Type | 414 +---------------+--------------+------------------------------------+ 415 | GET response | data node | application/yang-data+cbor; id=sid | 416 | | | | 417 | PUT request | data node | application/yang-data+cbor; id=sid | 418 | | | | 419 | POST request | data node | application/yang-data+cbor; id=sid | 420 | | | | 421 | DELETE | data node | n/a | 422 | | | | 423 | GET response | datastore | application/yang-data+cbor; id=sid | 424 | | | | 425 | PUT request | datastore | application/yang-data+cbor; id=sid | 426 | | | | 427 | POST request | datastore | application/yang-data+cbor; id=sid | 428 | | | | 429 | FETCH request | datastore | application/yang-identifiers+cbor | 430 | | | | 431 | FETCH | datastore | application/yang-instances+cbor | 432 | response | | | 433 | | | | 434 | iPATCH | datastore | application/yang-instances+cbor | 435 | request | | | 436 | | | | 437 | GET response | event stream | application/yang-instances+cbor | 438 | | | | 439 | POST request | rpc, action | application/yang-data+cbor; id=sid | 440 | | | | 441 | POST response | rpc, action | application/yang-data+cbor; id=sid | 442 +---------------+--------------+------------------------------------+ 444 2.5. Unified datastore 446 CORECONF supports a simple datastore model consisting of a single 447 unified datastore. This datastore provides access to both 448 configuration and operational data. Configuration updates performed 449 on this datastore are reflected immediately or with a minimal delay 450 as operational data. 452 Alternatively, CORECONF servers MAY implement a more complex 453 datastore model such as the Network Management Datastore Architecture 454 (NMDA) as defined by [RFC8342]. Each datastore supported is 455 implemented as a datastore resource. 457 Characteristics of the unified datastore are summarized in the table 458 below: 460 +-------------+-----------------------------------------------------+ 461 | Name | Value | 462 +-------------+-----------------------------------------------------+ 463 | Name | unified | 464 | | | 465 | YANG | all modules | 466 | modules | | 467 | | | 468 | YANG nodes | all data nodes ("config true" and "config false") | 469 | | | 470 | Access | read-write | 471 | | | 472 | How applied | changes applied in place immediately or with a | 473 | | minimal delay | 474 | | | 475 | Protocols | CORECONF | 476 | | | 477 | Defined in | "ietf-coreconf" | 478 +-------------+-----------------------------------------------------+ 480 3. Example syntax 482 CBOR is used to encode CORECONF request and response payloads. The 483 CBOR syntax of the YANG payloads is specified in [RFC7049]. The 484 payload examples are notated in Diagnostic notation (defined in 485 section 6 of [RFC7049]) that can be automatically converted to CBOR. 487 SIDs in URIs are represented as a base64 number, SIDs in the payload 488 are represented as decimal numbers. 490 4. CoAP Interface 492 This note specifies a Management Interface. CoAP endpoints that 493 implement the CORECONF management protocol, support at least one 494 discoverable management resource of resource type (rt): core.c.ds. 495 The path of the discoverable management resource is left to 496 implementers to select (see Section 6). 498 The mapping of YANG data node instances to CORECONF resources is as 499 follows. Every data node of the YANG modules loaded in the CORECONF 500 server represents a sub-resource of the datastore resource (e.g. /c/ 501 YANGSID). When multiple instances of a list exist, instance 502 selection is possible as described in Section 4.1, Section 4.2.3.1, 503 and Section 4.2.4. 505 CORECONF also supports event stream resources used to observe 506 notification instances. Event stream resources can be discovered 507 using resource type (rt): core.c.ev. 509 The description of the CORECONF management interface is shown in the 510 table below: 512 +------------------------------+--------------+-----------+ 513 | CoAP resource | Example path | rt | 514 +------------------------------+--------------+-----------+ 515 | Datastore resource | /c | core.c.ds | 516 | | | | 517 | Data node resource | /c/YANGSID | core.c.dn | 518 | | | | 519 | Default event steam resource | /s | core.c.ev | 520 +------------------------------+--------------+-----------+ 522 The path values in the table are example ones. On discovery, the 523 server makes the actual path values known for these resources. 525 The methods used by CORECONF are: 527 +-----------+-------------------------------------------------------+ 528 | Operation | Description | 529 +-----------+-------------------------------------------------------+ 530 | GET | Retrieve the datastore resource or a data node | 531 | | resource | 532 | | | 533 | FETCH | Retrieve specific data nodes within a datastore | 534 | | resource | 535 | | | 536 | POST | Create a datastore resource or a data node resource, | 537 | | invoke an RPC or action | 538 | | | 539 | PUT | Create or replace a datastore resource or a data node | 540 | | resource | 541 | | | 542 | iPATCH | Idem-potently create, replace, and delete data node | 543 | | resource(s) within a datastore resource | 544 | | | 545 | DELETE | Delete a datastore resource or a data node resource | 546 +-----------+-------------------------------------------------------+ 548 There is at most one instance of the 'k' query parameter for YANG 549 list element selection for the GET, PUT, POST, and DELETE methods. 550 Having multiple instances of that query parameter shall be treated as 551 an error. 553 +-----------------+----------------------------------------+ 554 | Query parameter | Description | 555 +-----------------+----------------------------------------+ 556 | k | Select an instance within YANG list(s) | 557 +-----------------+----------------------------------------+ 559 This parameter is not used for FETCH and iPATCH, because their 560 request payloads support list instance selection. 562 4.1. Using the 'k' query parameter 564 The 'k' (key) parameter specifies a specific instance of a data node. 565 The SID in the URI is followed by the (?k=key1,key2,...). Where SID 566 identifies a data node, and key1, key2 are the values of the key 567 leaves that specify an instance. Lists can have multiple keys, and 568 lists can be part of lists. The order of key value generation is 569 given recursively by: 571 o For a given list, if a parent data node is a list, generate the 572 keys for the parent list first. 574 o For a given list, generate key values in the order specified in 575 the YANG module. 577 Key values are encoded using the rules defined in the following 578 table. 580 +-----------------------------+--------------------------------+ 581 | YANG datatype | Uri-Query text content | 582 +-----------------------------+--------------------------------+ 583 | uint8,uint16,unit32, uint64 | int2str(key) | 584 | | | 585 | int8, int16,int32, int64 | urlSafeBase64(CBORencode(key)) | 586 | | | 587 | decimal64 | urlSafeBase64(CBOR key) | 588 | | | 589 | string | key | 590 | | | 591 | boolean | "0" or "1" | 592 | | | 593 | enumeration | int2str(key) | 594 | | | 595 | bits | urlSafeBase64(CBORencode(key)) | 596 | | | 597 | binary | urlSafeBase64(key) | 598 | | | 599 | identityref | int2str(key) | 600 | | | 601 | union | urlSafeBase64(CBORencode(key)) | 602 | | | 603 | instance-identifier | urlSafeBase64(CBORencode(key)) | 604 +-----------------------------+--------------------------------+ 606 In this table: 608 o The method int2str() is used to convert an integer value to a 609 decimal string. For example, int2str(0x0123) return the three- 610 character string "291". 612 o The boolean values false and true are represented as the single- 613 character strings "0" and "1" respectively. 615 o The method urlSafeBase64() is used to convert a binary string to 616 base64 using the URL and Filename safe alphabet as defined by 617 [RFC4648] section 5, without padding. For example, 618 urlSafeBase64(0xF956A13C) return the six-character string 619 "-VahPA". 621 o The method CBORencode() is used to convert a YANG value to CBOR as 622 specified in [I-D.ietf-core-yang-cbor] section 6. 624 The resulting key strings are joined using commas between every two 625 consecutive key values to produce the value of the 'k' parameter. 627 4.2. Data Retrieval 629 One or more data nodes can be retrieved by the client. The operation 630 is mapped to the GET method defined in section 5.8.1 of [RFC7252] and 631 to the FETCH method defined in section 2 of [RFC8132]. 633 There are two additional query parameters for the GET and FETCH 634 methods. 636 +-------------+-----------------------------------------------------+ 637 | query | Description | 638 | parameters | | 639 +-------------+-----------------------------------------------------+ 640 | c | Control selection of configuration and non- | 641 | | configuration data nodes (GET and FETCH) | 642 | | | 643 | d | Control retrieval of default values. | 644 +-------------+-----------------------------------------------------+ 646 4.2.1. Using the 'c' query parameter 648 The 'c' (content) option controls how descendant nodes of the 649 requested data nodes will be processed in the reply. 651 The allowed values are: 653 +-------+-----------------------------------------------------+ 654 | Value | Description | 655 +-------+-----------------------------------------------------+ 656 | c | Return only configuration descendant data nodes | 657 | | | 658 | n | Return only non-configuration descendant data nodes | 659 | | | 660 | a | Return all descendant data nodes | 661 +-------+-----------------------------------------------------+ 663 This option is only allowed for GET and FETCH methods on datastore 664 and data node resources. A 4.02 (Bad Option) error is returned if 665 used for other methods or resource types. 667 If this query parameter is not present, the default value is "a" (the 668 quotes are added for readability, but they are not part of the 669 payload). 671 4.2.2. Using the 'd' query parameter 673 The 'd' (with-defaults) option controls how the default values of the 674 descendant nodes of the requested data nodes will be processed. 676 The allowed values are: 678 +-------+-----------------------------------------------------------+ 679 | Value | Description | 680 +-------+-----------------------------------------------------------+ 681 | a | All data nodes are reported. Defined as 'report-all' in | 682 | | section 3.1 of [RFC6243]. | 683 | | | 684 | t | Data nodes set to the YANG default are not reported. | 685 | | Defined as 'trim' in section 3.2 of [RFC6243]. | 686 +-------+-----------------------------------------------------------+ 688 If the target of a GET or FETCH method is a data node that represents 689 a leaf that has a default value, and the leaf has not been given a 690 value by any client yet, the server MUST return the default value of 691 the leaf. 693 If the target of a GET method is a data node that represents a 694 container or list that has child resources with default values, and 695 these have not been given value yet, 697 The server MUST NOT return the child resource if d=t 699 The server MUST return the child resource if d=a. 701 If this query parameter is not present, the default value is "t" (the 702 quotes are added for readability, but they are not part of the 703 payload). 705 4.2.3. GET 707 A request to read the value of a data node instance is sent with a 708 CoAP GET message. The URI is set to the data node resource 709 requested, the 'k' query parameter is added if any of the parents of 710 the requested data node is a list node. 712 FORMAT: 713 GET ['k' Uri-Query option] 715 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 716 CBOR map of SID, instance-value 718 The returned payload contains the CBOR encoding of the requested 719 instance-value. 721 4.2.3.1. GET Examples 723 Using, for example, the current-datetime leaf from module ietf-system 724 [RFC7317], a request is sent to retrieve the value of 'system- 725 state/clock/current-datetime'. The SID of 'system-state/clock/ 726 current-datetime' is 1723, encoded in base64 according to 727 Section 2.2, yields a7. The response to the request returns the CBOR 728 map with the key set to the SID of the requested data node (i.e. 729 1723) and the value encoded using a 'text string' as defined in 730 [I-D.ietf-core-yang-cbor] section 6.4. The datastore resource path 731 /c is an example location discovered with a request similar to 732 Figure 4. 734 REQ: GET 736 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 737 { 738 1723 : "2014-10-26T12:16:31Z" 739 } 741 The next example represents the retrieval of a YANG container. In 742 this case, the CORECONF client performs a GET request on the clock 743 container (SID = 1721; base64: a5). The container returned is 744 encoded using a CBOR map as specified by [I-D.ietf-core-yang-cbor] 745 section 4.2. 747 REQ: GET 749 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 750 { 751 1721 : { 752 2 : "2014-10-26T12:16:51Z", / current-datetime (SID 1723) / 753 1 : "2014-10-21T03:00:00Z" / boot-datetime (SID 1722) / 754 } 755 } 757 Figure 3 759 This example shows the retrieval of the /interfaces/interface YANG 760 list accessed using SID 1533 (base64: X9). The return payload is 761 encoded using a CBOR array as specified by [I-D.ietf-core-yang-cbor] 762 section 4.4.1 containing 2 instances. 764 REQ: GET 766 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 767 { 768 1533 : [ 769 { 770 4 : "eth0", / name (SID 1537) / 771 1 : "Ethernet adaptor", / description (SID 1534) / 772 5 : 1880, / type, (SID 1538) identity / 773 / ethernetCsmacd (SID 1880) / 774 2 : true / enabled (SID 1535) / 775 }, 776 { 777 4 : "eth1", / name (SID 1537) / 778 1 : "Ethernet adaptor", / description (SID 1534) / 779 5 : 1880, / type, (SID 1538) identity / 780 / ethernetCsmacd (SID 1880) / 781 2 : false / enabled (SID 1535) / 782 } 783 ] 784 } 786 To retrieve a specific instance within the /interfaces/interface YANG 787 list, the CORECONF client adds the key of the targeted instance in 788 its CoAP request using the 'k' query parameter. The return payload 789 containing the instance requested is encoded using a CBOR array as 790 specified by [I-D.ietf-core-yang-cbor] section 4.4.1 containing the 791 requested instance. 793 REQ: GET 795 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 796 { 797 1533 : [ 798 { 799 4 : "eth0", / name (SID 1537) / 800 1 : "Ethernet adaptor", / description (SID 1534) / 801 5 : 1880, / type, (SID 1538) identity / 802 / ethernetCsmacd (SID 1880) / 803 2 : true / enabled (SID 1535) / 804 } 805 ] 806 } 808 It is equally possible to select a leaf of a specific instance of a 809 list. The example below requests the description leaf (SID 1534, 810 base64: X-) within the interface list corresponding to the interface 811 name "eth0". The returned value is encoded in CBOR based on the 812 rules specified by [I-D.ietf-core-yang-cbor] section 6.4. 814 REQ: GET 816 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 817 { 818 1534 : "Ethernet adaptor" 819 } 821 4.2.4. FETCH 823 The FETCH is used to retrieve multiple instance-values. The FETCH 824 request payload contains the list of instance-identifier of the data 825 node instances requested. 827 The return response payload contains a list of data node instance- 828 values in the same order as requested. A CBOR null is returned for 829 each data node requested by the client, not supported by the server 830 or not currently instantiated. 832 For compactness, indexes of the list instance identifiers returned by 833 the FETCH response SHOULD be elided, only the SID is provided. This 834 approach may also help reducing implementations complexity since the 835 format of each entry within the CBOR array of the FETCH response is 836 identical to the format of the corresponding GET response. 838 FORMAT: 839 FETCH 840 (Content-Format: application/yang-identifiers+cbor) 841 CBOR array of instance-identifier 843 2.05 Content (Content-Format: application/yang-instances+cbor) 844 CBOR array of CBOR map of SID, instance-value 846 4.2.4.1. FETCH examples 848 This example uses the current-datetime leaf from module ietf-system 849 [RFC7317] and the interface list from module ietf-interfaces 850 [RFC7223]. In this example the value of current-datetime (SID 1723) 851 and the interface list (SID 1533) instance identified with 852 name="eth0" are queried. 854 REQ: FETCH 855 (Content-Format: application/yang-identifiers+cbor) 856 [ 857 1723, / current-datetime (SID 1723) / 858 [1533, "eth0"] / interface (SID 1533) with name = "eth0" / 859 ] 861 RES: 2.05 Content (Content-Format: application/yang-instances+cbor) 862 [ 863 { 864 1723 : "2014-10-26T12:16:31Z" / current-datetime (SID 1723) / 865 }, 866 { 867 1533 : { 868 4 : "eth0", / name (SID 1537) / 869 1 : "Ethernet adaptor", / description (SID 1534) / 870 5 : 1880, / type (SID 1538), identity / 871 / ethernetCsmacd (SID 1880) / 872 2 : true / enabled (SID 1535) / 873 } 874 } 875 ] 877 4.3. Data Editing 879 CORECONF allows datastore contents to be created, modified and 880 deleted using CoAP methods. 882 4.3.1. Data Ordering 884 A CORECONF server MUST preserve the relative order of all user- 885 ordered list and leaf-list entries that are received in a single edit 886 request. These YANG data node types are encoded as CBOR arrays so 887 messages will preserve their order. 889 4.3.2. POST 891 The CoAP POST operation is used in CORECONF for the creation of data 892 node resources and the invocation of "ACTION" and "RPC" resources. 893 Refer to Section 4.6 for details on "ACTION" and "RPC" resources. 895 A request to create a data node instance is sent with a CoAP POST 896 message. The URI specifies the data node resource of the instance to 897 be created. In the case of a list instance, keys MUST be present in 898 the payload. 900 FORMAT: 901 POST 902 (Content-Format: application/yang-data+cbor; id=sid) 903 CBOR map of SID, instance-value 905 2.01 Created 907 If the data node instance already exists, then the POST request MUST 908 fail and a "4.09 Conflict" response code MUST be returned 910 4.3.2.1. Post example 912 The example uses the interface list from module ietf-interfaces 913 [RFC7223]. This example creates a new list instance within the 914 interface list (SID = 1533), while assuming the datastore resource is 915 hosted on the CoAP server with DNS name example.com and with path 916 /ds. The path /ds is an example location that is assumed to have 917 been discovered using request similar to Figure 4. 919 REQ: POST 920 (Content-Format: application/yang-data+cbor; id=sid) 921 { 922 1533 : [ 923 { 924 4 : "eth5", / name (SID 1537) / 925 1 : "Ethernet adaptor", / description (SID 1534) / 926 5 : 1880, / type (SID 1538), identity / 927 / ethernetCsmacd (SID 1880) / 928 2 : true / enabled (SID 1535) / 929 } 930 ] 931 } 933 RES: 2.01 Created 935 4.3.3. PUT 937 A data node resource instance is created or replaced with the PUT 938 method. A request to set the value of a data node instance is sent 939 with a CoAP PUT message. 941 FORMAT: 942 PUT ['k' Uri-Query option] 943 (Content-Format: application/yang-data+cbor; id=sid) 944 CBOR map of SID, instance-value 946 2.01 Created 948 4.3.3.1. PUT example 950 The example uses the interface list from module ietf-interfaces 951 [RFC7223]. This example updates the instance of the list interface 952 (SID = 1533) with key name="eth0". The example location /c is an 953 example location that is discovered using a request similar to 954 Figure 4. 956 REQ: PUT 957 (Content-Format: application/yang-data+cbor; id=sid) 958 { 959 1533 : [ 960 { 961 4 : "eth0", / name (SID 1537) / 962 1 : "Ethernet adaptor", / description (SID 1534) / 963 5 : 1880, / type (SID 1538), identity / 964 / ethernetCsmacd (SID 1880) / 965 2 : true / enabled (SID 1535) / 966 } 967 ] 968 } 970 RES: 2.04 Changed 972 4.3.4. iPATCH 974 One or multiple data node instances are replaced with the idempotent 975 CoAP iPATCH method [RFC8132]. 977 There are no query parameters for the iPATCH method. 979 The processing of the iPATCH command is specified by Media-Type 980 'application/yang-instances+cbor'. In summary, if the CBOR patch 981 payload contains a data node instance that is not present in the 982 target, this instance is added. If the target contains the specified 983 instance, the content of this instance is replaced with the value of 984 the payload. A null value indicates the removal of an existing data 985 node instance. 987 FORMAT: 988 iPATCH 989 (Content-Format: application/yang-instances+cbor) 990 CBOR array of CBOR map of instance-identifier, instance-value 992 2.04 Changed 994 4.3.4.1. iPATCH example 996 In this example, a CORECONF client requests the following operations: 998 o Set "/system/ntp/enabled" (SID 1755) to true. 1000 o Remove the server "tac.nrc.ca" from the "/system/ntp/server" (SID 1001 1756) list. 1003 o Add/set the server "NTP Pool server 2" to the list "/system/ntp/ 1004 server" (SID 1756). 1006 REQ: iPATCH 1007 (Content-Format: application/yang-instances+cbor) 1008 [ 1009 { 1010 1755 : true / enabled (SID 1755) / 1011 }, 1012 { 1013 [1756, "tac.nrc.ca"] : null / server (SID 1756) / 1014 }, 1015 { 1016 1756 : { / server (SID 1756) / 1017 3 : "tic.nrc.ca", / name (SID 1759) / 1018 4 : true, / prefer (SID 1760) / 1019 5 : { / udp (SID 1761) / 1020 1 : "132.246.11.231" / address (SID 1762) / 1021 } 1022 } 1023 } 1024 ] 1026 RES: 2.04 Changed 1028 4.3.5. DELETE 1030 A data node resource is deleted with the DELETE method. 1032 FORMAT: 1033 Delete ['k' Uri-Query option] 1035 2.02 Deleted 1037 4.3.5.1. DELETE example 1039 This example uses the interface list from module ietf-interfaces 1040 [RFC7223]. This example deletes an instance of the interface list 1041 (SID = 1533): 1043 REQ: DELETE 1045 RES: 2.02 Deleted 1047 4.4. Full datastore access 1049 The methods GET, PUT, POST, and DELETE can be used to request, 1050 replace, create, and delete a whole datastore respectively. 1052 FORMAT: 1053 GET 1055 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1056 CBOR map of SID, instance-value 1058 FORMAT: 1059 PUT 1060 (Content-Format: application/yang-data+cbor; id=sid) 1061 CBOR map of SID, instance-value 1063 2.04 Changed 1065 FORMAT: 1066 POST 1067 (Content-Format: application/yang-data+cbor; id=sid) 1068 CBOR map of SID, instance-value 1070 2.01 Created 1072 FORMAT: 1073 DELETE 1075 2.02 Deleted 1077 The content of the CBOR map represents the complete datastore of the 1078 server at the GET indication of after a successful processing of a 1079 PUT or POST request. 1081 4.4.1. Full datastore examples 1083 The example uses the interface list from module ietf-interfaces 1084 [RFC7223] and the clock container from module ietf-system [RFC7317]. 1085 We assume that the datastore contains two modules ietf-system (SID 1086 1700) and ietf-interfaces (SID 1500); they contain the 'interface' 1087 list (SID 1533) with one instance and the 'clock' container (SID 1088 1721). After invocation of GET, a CBOR map with data nodes from 1089 these two modules is returned: 1091 REQ: GET 1093 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1094 { 1095 1721 : { / Clock (SID 1721) / 1096 2: "2016-10-26T12:16:31Z", / current-datetime (SID 1723) / 1097 1: "2014-10-05T09:00:00Z" / boot-datetime (SID 1722) / 1098 }, 1099 1533 : [ 1100 { / interface (SID 1533) / 1101 4 : "eth0", / name (SID 1537) / 1102 1 : "Ethernet adaptor", / description (SID 1534) / 1103 5 : 1880, / type (SID 1538), identity: / 1104 / ethernetCsmacd (SID 1880) / 1105 2 : true / enabled (SID 1535) / 1106 } 1107 ] 1108 } 1110 4.5. Event stream 1112 Event notification is an essential function for the management of 1113 servers. CORECONF allows notifications specified in YANG [RFC5277] 1114 to be reported to a list of clients. The path for the default event 1115 stream can be discovered as described in Section 4. The server MAY 1116 support additional event stream resources to address different 1117 notification needs. 1119 Reception of notification instances is enabled with the CoAP Observe 1120 [RFC7641] function. Clients subscribe to the notifications by 1121 sending a GET request with an "Observe" option to the stream 1122 resource. 1124 Each response payload carries one or multiple notifications. The 1125 number of notifications reported, and the conditions used to remove 1126 notifications from the reported list are left to implementers. When 1127 multiple notifications are reported, they MUST be ordered starting 1128 from the newest notification at index zero. Note that this could 1129 lead to notifications being sent multiple times, which increases the 1130 probability for the client to receive them, but it might potentially 1131 lead to messages that exceed the MTU of a single CoAP packet. If 1132 such cases could arise, implementers should make sure appropriate 1133 fragmentation is available - for example the one described in 1134 Section 5. 1136 The format of notification without any content is a null value. The 1137 format of single notification is defined in [I-D.ietf-core-yang-cbor] 1138 section 4.2.1. For multiple notifications the format is an array 1139 where each element is a single notification as described in 1140 [I-D.ietf-core-yang-cbor] section 4.2.1. 1142 FORMAT: 1143 GET Observe(0) 1145 2.05 Content (Content-Format: application/yang-instances+cbor) 1146 CBOR array of CBOR map of instance-identifier, instance-value 1148 The array of data node instances may contain identical entries which 1149 have been generated at different times. 1151 An example implementation is: 1153 Every time an event is generated, the generated notification 1154 instance is appended to the chosen stream(s). After an 1155 aggregation period, which may be limited by the maximum number of 1156 notifications supported, the content of the instance is sent to 1157 all clients observing the modified stream. 1159 4.5.1. Notify Examples 1161 Let suppose the server generates the example-port-fault event as 1162 defined below. 1164 module example-port { 1165 ... 1166 notification example-port-fault { // SID 60010 1167 description 1168 "Event generated if a hardware fault is detected"; 1169 leaf port-name { // SID 60011 1170 type string; 1171 } 1172 leaf port-fault { // SID 60012 1173 type string; 1174 } 1175 } 1176 } 1178 In this example the default event stream resource path /s is an 1179 example location discovered with a request similar to Figure 5. By 1180 executing a GET with Observe 0 on the default event stream resource 1181 the client receives the following response: 1183 REQ: GET Observe(0) 1185 RES: 2.05 Content (Content-Format: application/yang-tree+cbor) 1186 Observe(12) 1187 [ 1188 { 1189 60010 : { / example-port-fault (SID 60010) / 1190 1 : "0/4/21", / port-name (SID 60011) / 1191 2 : "Open pin 2" / port-fault (SID 60012) / 1192 } 1193 }, 1194 { 1195 60010 : { / example-port-fault (SID 60010) / 1196 1 : "1/4/21", / port-name (SID 60011) / 1197 2 : "Open pin 5" / port-fault (SID 60012) / 1198 } 1199 } 1200 ] 1202 In the example, the request returns a success response with the 1203 contents of the last two generated events. Consecutively the server 1204 will regularly notify the client when a new event is generated. 1206 4.5.2. The 'f' query parameter 1208 The 'f' (filter) option is used to indicate which subset of all 1209 possible notifications is of interest. If not present, all 1210 notifications supported by the event stream are reported. 1212 When not supported by a CORECONF server, this option shall be 1213 ignored, all events notifications are reported independently of the 1214 presence and content of the 'f' (filter) option. 1216 When present, this option contains a comma-separated list of 1217 notification SIDs. For example, the following request returns 1218 notifications 60010 and 60020. 1220 REQ: GET Observe(0) 1222 4.6. RPC statements 1224 The YANG "action" and "RPC" statements specify the execution of a 1225 Remote procedure Call (RPC) in the server. It is invoked using a 1226 POST method to an "Action" or "RPC" resource instance. 1228 The request payload contains the values assigned to the input 1229 container when specified. The response payload contains the values 1230 of the output container when specified. Both the input and output 1231 containers are encoded in CBOR using the rules defined in 1232 [I-D.ietf-core-yang-cbor] section 4.2.1. 1234 The returned success response code is 2.05 Content. 1236 FORMAT: 1237 POST ['k' Uri-Query option] 1238 (Content-Format: application/yang-data+cbor; id=sid) 1239 CBOR map of SID, instance-value 1241 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1242 CBOR map of SID, instance-value 1244 4.6.1. RPC Example 1246 The example is based on the YANG action "reset" as defined in 1247 [RFC7950] section 7.15.3 and annotated below with SIDs. 1249 module example-server-farm { 1250 yang-version 1.1; 1251 namespace "urn:example:server-farm"; 1252 prefix "sfarm"; 1254 import ietf-yang-types { 1255 prefix "yang"; 1256 } 1258 list server { // SID 60000 1259 key name; 1260 leaf name { // SID 60001 1261 type string; 1262 } 1263 action reset { // SID 60002 1264 input { 1265 leaf reset-at { // SID 60003 1266 type yang:date-and-time; 1267 mandatory true; 1268 } 1269 } 1270 output { 1271 leaf reset-finished-at { // SID 60004 1272 type yang:date-and-time; 1273 mandatory true; 1274 } 1275 } 1276 } 1277 } 1278 } 1280 This example invokes the 'reset' action (SID 60002, base64: Opq), of 1281 the server instance with name equal to "myserver". 1283 REQ: POST 1284 (Content-Format: application/yang-data+cbor; id=sid) 1285 { 1286 60002 : { 1287 1 : "2016-02-08T14:10:08Z09:00" / reset-at (SID 60003) / 1288 } 1289 } 1291 RES: 2.05 Content (Content-Format: application/yang-data+cbor; id=sid) 1292 { 1293 60002 : { 1294 2 : "2016-02-08T14:10:08Z09:18" / reset-finished-at (SID 60004)/ 1295 } 1296 } 1298 5. Use of Block-wise Transfers 1300 The CoAP protocol provides reliability by acknowledging the UDP 1301 datagrams. However, when large pieces of data need to be 1302 transported, datagrams get fragmented, thus creating constraints on 1303 the resources in the client, server and intermediate routers. The 1304 block option [RFC7959] allows the transport of the total payload in 1305 individual blocks of which the size can be adapted to the underlying 1306 transport sizes such as: (UDP datagram size ~64KiB, IPv6 MTU of 1280, 1307 IEEE 802.15.4 payload of 60-80 bytes). Each block is individually 1308 acknowledged to guarantee reliability. 1310 Notice that the Block mechanism splits the data at fixed positions, 1311 such that individual data fields may become fragmented. Therefore, 1312 assembly of multiple blocks may be required to process complete data 1313 fields. 1315 Beware of race conditions. In case blocks are filled one at a time, 1316 care should be taken that the whole and consistent data 1317 representation is sent in multiple blocks sequentially without 1318 interruption. On the server, values might change, lists might get 1319 re-ordered, extended or reduced. When these actions happen during 1320 the serialization of the contents of the resource, the transported 1321 results do not correspond with a state having occurred in the server; 1322 or worse the returned values are inconsistent. For example: array 1323 length does not correspond with the actual number of items. It may 1324 be advisable to use Indefinite-length CBOR arrays and maps, which are 1325 foreseen for data streaming purposes. 1327 6. Application Discovery 1329 Two application discovery mechanisms are supported by CORECONF, the 1330 YANG library data model as defined by [I-D.ietf-core-yang-library] 1331 and the CORE resource discovery [RFC6690]. Implementers may choose 1332 to implement one or the other or both. 1334 6.1. YANG library 1336 The YANG library data model [I-D.ietf-core-yang-library] provides a 1337 high-level description of the resources available. The YANG library 1338 contains the list of modules, features, and deviations supported by 1339 the CORECONF server. From this information, CORECONF clients can 1340 infer the list of data nodes supported and the interaction model to 1341 be used to access them. This module also contains the list of 1342 datastores implemented. 1344 As described in [RFC6690], the location of the YANG library can be 1345 found by sending a GET request to "/.well-known/core" including a 1346 resource type (RT) parameter with the value "core.c.yl". Upon 1347 success, the return payload will contain the root resource of the 1348 YANG library module. 1350 The following example assumes that the SID of the YANG library is 1351 2351 (kv encoded as specified in Section 2.2) and that the server 1352 uses /c as datastore resource path. 1354 REQ: GET 1356 RES: 2.05 Content (Content-Format: application/link-format) 1357 ;rt="core.c.yl" 1359 6.2. Resource Discovery 1361 As some CoAP interfaces and services might not support the YANG 1362 library interface and still be interested to discover resources that 1363 are available, implementations MAY choose to support discovery of all 1364 available resources using "/.well-known/core" as defined by 1365 [RFC6690]. 1367 6.2.1. Datastore Resource Discovery 1369 The presence and location of (path to) each datastore implemented by 1370 the CORECONF server can be discovered by sending a GET request to 1371 "/.well-known/core" including a resource type (RT) parameter with the 1372 value "core.c.ds". 1374 Upon success, the return payload contains the list of datastore 1375 resources. 1377 Each datastore returned is further qualified using the "ds" Link- 1378 Format attribute. This attribute is set to the SID assigned to the 1379 datastore identity. When a unified datastore is implemented, the ds 1380 attribute is set to 1029 as specified in Appendix B. For other 1381 examples of datastores, see the Network Management Datastore 1382 Architecture (NMDA) [RFC7950]. 1384 link-extension = ( "ds" "=" sid ) ) 1385 ; SID assigned to the datastore identity 1386 sid = 1*DIGIT 1388 The following example assumes that the server uses /c as datastore 1389 resource path. 1391 REQ: GET 1393 RES: 2.05 Content (Content-Format: application/link-format) 1394 ; rt="core.c.ds";ds=1029 1396 Figure 4 1398 6.2.2. Data node Resource Discovery 1400 If implemented, the presence and location of (path to) each data node 1401 implemented by the CORECONF server are discovered by sending a GET 1402 request to "/.well-known/core" including a resource type (RT) 1403 parameter with the value "core.c.dn". 1405 Upon success, the return payload contains the SID assigned to each 1406 data node and their location. 1408 The example below shows the discovery of the presence and location of 1409 data nodes. Data nodes '/ietf-system:system-state/clock/boot- 1410 datetime' (SID 1722) and '/ietf-system:system-state/clock/current- 1411 datetime' (SID 1723) are returned. The example assumes that the 1412 server uses /c as datastore resource path. 1414 REQ: GET 1416 RES: 2.05 Content (Content-Format: application/link-format) 1417 ;rt="core.c.dn", 1418 ;rt="core.c.dn" 1420 Without additional filtering, the list of data nodes may become 1421 prohibitively long. If this is the case implementations SHOULD 1422 support a way to obtain all links using multiple GET requests (for 1423 example through some form of pagination). 1425 6.2.3. Event stream Resource Discovery 1427 The presence and location of (path to) each event stream implemented 1428 by the CORECONF server are discovered by sending a GET request to 1429 "/.well-known/core" including a resource type (RT) parameter with the 1430 value "core.c.es". 1432 Upon success, the return payload contains the list of event stream 1433 resources. 1435 The following example assumes that the server uses /s as the default 1436 event stream resource. 1438 REQ: GET 1440 RES: 2.05 Content (Content-Format: application/link-format) 1441 ;rt="core.c.es" 1443 Figure 5 1445 7. Error Handling 1447 In case a request is received which cannot be processed properly, the 1448 CORECONF server MUST return an error response. This error response 1449 MUST contain a CoAP 4.xx or 5.xx response code. 1451 Errors returned by a CORECONF server can be broken into two 1452 categories, those associated with the CoAP protocol itself and those 1453 generated during the validation of the YANG data model constrains as 1454 described in [RFC7950] section 8. 1456 The following list of common CoAP errors should be implemented by 1457 CORECONF servers. This list is not exhaustive, other errors defined 1458 by CoAP and associated RFCs may be applicable. 1460 o Error 4.01 (Unauthorized) is returned by the CORECONF server when 1461 the CORECONF client is not authorized to perform the requested 1462 action on the targeted resource (i.e. data node, datastore, rpc, 1463 action or event stream). 1465 o Error 4.02 (Bad Option) is returned by the CORECONF server when 1466 one or more CoAP options are unknown or malformed. 1468 o Error 4.04 (Not Found) is returned by the CORECONF server when the 1469 CORECONF client is requesting a non-instantiated resource (i.e. 1470 data node, datastore, rpc, action or event stream). 1472 o Error 4.05 (Method Not Allowed) is returned by the CORECONF server 1473 when the CORECONF client is requesting a method not supported on 1474 the targeted resource. (e.g. GET on an rpc, PUT or POST on a data 1475 node with "config" set to false). 1477 o Error 4.08 (Request Entity Incomplete) is returned by the CORECONF 1478 server if one or multiple blocks of a block transfer request is 1479 missing, see [RFC7959] for more details. 1481 o Error 4.13 (Request Entity Too Large) may be returned by the 1482 CORECONF server during a block transfer request, see [RFC7959] for 1483 more details. 1485 o Error 4.15 (Unsupported Content-Format) is returned by the 1486 CORECONF server when the Content-Format used in the request does 1487 not match those specified in section Section 2.4. 1489 The CORECONF server MUST also enforce the different constraints 1490 associated with the YANG data models implemented. These constraints 1491 are described in [RFC7950] section 8. These errors are reported 1492 using the CoAP error code 4.00 (Bad Request) and may have the 1493 following error container as payload. The YANG definition and 1494 associated .sid file are available in Appendix A and Appendix B. The 1495 error container is encoded using the encoding rules of a YANG data 1496 template as defined in [I-D.ietf-core-yang-cbor] section 5. 1498 +--rw error! 1499 +--rw error-tag identityref 1500 +--rw error-app-tag? identityref 1501 +--rw error-data-node? instance-identifier 1502 +--rw error-message? string 1504 The following 'error-tag' and 'error-app-tag' are defined by the 1505 ietf-coreconf YANG module, these tags are implemented as YANG 1506 identity and can be extended as needed. 1508 o error-tag 'operation-failed' is returned by the CORECONF server 1509 when the operation request cannot be processed successfully. 1511 * error-app-tag 'malformed-message' is returned by the CORECONF 1512 server when the payload received from the CORECONF client does 1513 not contain a well-formed CBOR content as defined in [RFC7049] 1514 section 3.3 or does not comply with the CBOR structure defined 1515 within this document. 1517 * error-app-tag 'data-not-unique' is returned by the CORECONF 1518 server when the validation of the 'unique' constraint of a list 1519 or leaf-list fails. 1521 * error-app-tag 'too-many-elements' is returned by the CORECONF 1522 server when the validation of the 'max-elements' constraint of 1523 a list or leaf-list fails. 1525 * error-app-tag 'too-few-elements' is returned by the CORECONF 1526 server when the validation of the 'min-elements' constraint of 1527 a list or leaf-list fails. 1529 * error-app-tag 'must-violation' is returned by the CORECONF 1530 server when the restrictions imposed by a 'must' statement are 1531 violated. 1533 * error-app-tag 'duplicate' is returned by the CORECONF server 1534 when a client tries to create a duplicate list or leaf-list 1535 entry. 1537 o error-tag 'invalid-value' is returned by the CORECONF server when 1538 the CORECONF client tries to update or create a leaf with a value 1539 encoded using an invalid CBOR datatype or if the 'range', 1540 'length', 'pattern' or 'require-instance' constrain is not 1541 fulfilled. 1543 * error-app-tag 'invalid-datatype' is returned by the CORECONF 1544 server when CBOR encoding does not follow the rules set by the 1545 YANG Build-In type or when the value is incompatible with it 1546 (e.g. a value greater than 127 for an int8, undefined 1547 enumeration). 1549 * error-app-tag 'not-in-range' is returned by the CORECONF server 1550 when the validation of the 'range' property fails. 1552 * error-app-tag 'invalid-length' is returned by the CORECONF 1553 server when the validation of the 'length' property fails. 1555 * error-app-tag 'pattern-test-failed' is returned by the CORECONF 1556 server when the validation of the 'pattern' property fails. 1558 o error-tag 'missing-element' is returned by the CORECONF server 1559 when the operation requested by a CORECONF client fails to comply 1560 with the 'mandatory' constraint defined. The 'mandatory' 1561 constraint is enforced for leafs and choices, unless the node or 1562 any of its ancestors have a 'when' condition or 'if-feature' 1563 expression that evaluates to 'false'. 1565 * error-app-tag 'missing-key' is returned by the CORECONF server 1566 to further qualify a missing-element error. This error is 1567 returned when the CORECONF client tries to create or list 1568 instance, without all the 'key' specified or when the CORECONF 1569 client tries to delete a leaf listed as a 'key'. 1571 * error-app-tag 'missing-input-parameter' is returned by the 1572 CORECONF server when the input parameters of an RPC or action 1573 are incomplete. 1575 o error-tag 'unknown-element' is returned by the CORECONF server 1576 when the CORECONF client tries to access a data node of a YANG 1577 module not supported, of a data node associated with an 'if- 1578 feature' expression evaluated to 'false' or to a 'when' condition 1579 evaluated to 'false'. 1581 o error-tag 'bad-element' is returned by the CORECONF server when 1582 the CORECONF client tries to create data nodes for more than one 1583 case in a choice. 1585 o error-tag 'data-missing' is returned by the CORECONF server when a 1586 data node required to accept the request is not present. 1588 * error-app-tag 'instance-required' is returned by the CORECONF 1589 server when a leaf of type 'instance-identifier' or 'leafref' 1590 marked with require-instance set to 'true' refers to an 1591 instance that does not exist. 1593 * error-app-tag 'missing-choice' is returned by the CORECONF 1594 server when no nodes exist in a mandatory choice. 1596 o error-tag 'error' is returned by the CORECONF server when an 1597 unspecified error has occurred. 1599 For example, the CORECONF server might return the following error. 1601 RES: 4.00 Bad Request (Content-Format: application/yang-data+cbor; id=sid) 1602 { 1603 1024 : { 1604 4 : 1011, / error-tag (SID 1028) / 1605 / = invalid-value (SID 1011) / 1606 1 : 1018, / error-app-tag (SID 1025) / 1607 / = not-in-range (SID 1018) / 1608 2 : 1740, / error-data-node (SID 1026) / 1609 / = timezone-utc-offset (SID 1740) / 1610 3 : "maximum value exceeded" / error-message (SID 1027) / 1611 } 1612 } 1614 8. Security Considerations 1616 For secure network management, it is important to restrict access to 1617 configuration variables only to authorized parties. CORECONF re-uses 1618 the security mechanisms already available to CoAP, this includes DTLS 1619 [RFC6347] and OSCORE [RFC8613] for protected access to resources, as 1620 well as suitable authentication and authorization mechanisms, for 1621 example those defined in ACE OAuth [I-D.ietf-ace-oauth-authz]. 1623 All the security considerations of [RFC7252], [RFC7959], [RFC8132] 1624 and [RFC7641] apply to this document as well. The use of NoSec DTLS, 1625 when OSCORE is not used, is NOT RECOMMENDED. 1627 In addition, mechanisms for authentication and authorization may need 1628 to be selected if not provided with the CoAP security mode. 1630 As [I-D.ietf-core-yang-cbor] and [RFC4648] are used for payload and 1631 SID encoding, the security considerations of those documents also 1632 need to be well-understood. 1634 9. IANA Considerations 1636 9.1. Resource Type (rt=) Link Target Attribute Values Registry 1638 This document adds the following resource type to the "Resource Type 1639 (rt=) Link Target Attribute Values", within the "Constrained RESTful 1640 Environments (CoRE) Parameters" registry. 1642 +-----------+---------------------+-----------+ 1643 | Value | Description | Reference | 1644 +-----------+---------------------+-----------+ 1645 | core.c.ds | YANG datastore | RFC XXXX | 1646 | | | | 1647 | core.c.dn | YANG data node | RFC XXXX | 1648 | | | | 1649 | core.c.yl | YANG module library | RFC XXXX | 1650 | | | | 1651 | core.c.es | YANG event stream | RFC XXXX | 1652 +-----------+---------------------+-----------+ 1654 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1655 note. 1657 9.2. CoAP Content-Formats Registry 1659 This document adds the following Content-Format to the "CoAP Content- 1660 Formats", within the "Constrained RESTful Environments (CoRE) 1661 Parameters" registry. 1663 +-----------------------------------+------------+------+-----------+ 1664 | Media Type | Content | ID | Reference | 1665 | | Coding | | | 1666 +-----------------------------------+------------+------+-----------+ 1667 | application/yang-identifiers+cbor | | TBD2 | RFC XXXX | 1668 | | | | | 1669 | application/yang-instances+cbor | | TBD3 | RFC XXXX | 1670 +-----------------------------------+------------+------+-----------+ 1672 // RFC Ed.: replace TBD1, TBD2 and TBD3 with assigned IDs and remove 1673 this note. // RFC Ed.: replace RFC XXXX with this RFC number and 1674 remove this note. 1676 9.3. Media Types Registry 1678 This document adds the following media types to the "Media Types" 1679 registry. 1681 +-----------------------+-----------------------+-----------+ 1682 | Name | Template | Reference | 1683 +-----------------------+-----------------------+-----------+ 1684 | yang-identifiers+cbor | application/ | RFC XXXX | 1685 | | | | 1686 | | yang-identifiers+cbor | | 1687 | | | | 1688 | yang-instances+cbor | application/ | RFC XXXX | 1689 | | | | 1690 | | yang-instances+cbor | | 1691 +-----------------------+-----------------------+-----------+ 1693 Each of these media types share the following information: 1695 o Subtype name: 1697 o Required parameters: N/A 1699 o Optional parameters: N/A 1701 o Encoding considerations: binary 1703 o Security considerations: See the Security Considerations section 1704 of RFC XXXX 1706 o Interoperability considerations: N/A 1708 o Published specification: RFC XXXX 1710 o Applications that use this media type: CORECONF 1712 o Fragment identifier considerations: N/A 1714 o Additional information: 1716 * Deprecated alias names for this type: N/A 1718 * Magic number(s): N/A 1720 * File extension(s): N/A 1722 * Macintosh file type code(s): N/A 1723 o Person & email address to contact for further information: 1724 iesg&ietf.org 1726 o Intended usage: COMMON 1728 o Restrictions on usage: N/A 1730 o Author: Michel Veillette, ietf&augustcellars.com 1732 o Change Controller: IESG 1734 o Provisional registration? No 1736 // RFC Ed.: replace RFC XXXX with this RFC number and remove this 1737 note. 1739 9.4. YANG Namespace Registration 1741 This document registers the following XML namespace URN in the "IETF 1742 XML Registry", following the format defined in [RFC3688]: 1744 URI: please assign urn:ietf:params:xml:ns:yang:ietf-coreconf 1746 Registrant Contact: The IESG. 1748 XML: N/A, the requested URI is an XML namespace. 1750 Reference: RFC XXXX 1752 // RFC Ed.: please replace XXXX with RFC number and remove this note 1754 10. Acknowledgments 1756 We are very grateful to Bert Greevenbosch who was one of the original 1757 authors of the CORECONF specification. 1759 Mehmet Ersue and Bert Wijnen explained the encoding aspects of PDUs 1760 transported under SNMP. Carsten Bormann has given feedback on the 1761 use of CBOR. 1763 The draft has benefited from comments (alphabetical order) by Rodney 1764 Cummings, Dee Denteneer, Esko Dijk, Klaus Hartke, Michael van 1765 Hartskamp, Tanguy Ropitault, Juergen Schoenwaelder, Anuj Sehgal, Zach 1766 Shelby, Hannes Tschofenig, Michael Verschoor, and Thomas Watteyne. 1768 11. References 1770 11.1. Normative References 1772 [I-D.ietf-core-sid] 1773 Veillette, M., Pelov, A., and I. Petrov, "YANG Schema Item 1774 iDentifier (SID)", draft-ietf-core-sid-13 (work in 1775 progress), June 2020. 1777 [I-D.ietf-core-yang-cbor] 1778 Veillette, M., Petrov, I., and A. Pelov, "CBOR Encoding of 1779 Data Modeled with YANG", draft-ietf-core-yang-cbor-12 1780 (work in progress), March 2020. 1782 [I-D.ietf-core-yang-library] 1783 Veillette, M. and I. Petrov, "Constrained YANG Module 1784 Library", draft-ietf-core-yang-library-01 (work in 1785 progress), January 2020. 1787 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1788 Requirement Levels", BCP 14, RFC 2119, 1789 DOI 10.17487/RFC2119, March 1997, 1790 . 1792 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1793 DOI 10.17487/RFC3688, January 2004, 1794 . 1796 [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data 1797 Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, 1798 . 1800 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1801 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1802 . 1804 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1805 and A. Bierman, Ed., "Network Configuration Protocol 1806 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1807 . 1809 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1810 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1811 . 1813 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1814 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1815 October 2013, . 1817 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1818 Application Protocol (CoAP)", RFC 7252, 1819 DOI 10.17487/RFC7252, June 2014, 1820 . 1822 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1823 Application Protocol (CoAP)", RFC 7641, 1824 DOI 10.17487/RFC7641, September 2015, 1825 . 1827 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1828 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1829 . 1831 [RFC7959] Bormann, C. and Z. Shelby, Ed., "Block-Wise Transfers in 1832 the Constrained Application Protocol (CoAP)", RFC 7959, 1833 DOI 10.17487/RFC7959, August 2016, 1834 . 1836 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1837 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1838 . 1840 [RFC8132] van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and 1841 FETCH Methods for the Constrained Application Protocol 1842 (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017, 1843 . 1845 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1846 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1847 May 2017, . 1849 11.2. Informative References 1851 [I-D.ietf-ace-oauth-authz] 1852 Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and 1853 H. Tschofenig, "Authentication and Authorization for 1854 Constrained Environments (ACE) using the OAuth 2.0 1855 Framework (ACE-OAuth)", draft-ietf-ace-oauth-authz-35 1856 (work in progress), June 2020. 1858 [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer 1859 Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, 1860 January 2012, . 1862 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1863 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1864 . 1866 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1867 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1868 . 1870 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1871 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1872 2014, . 1874 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1875 and R. Wilton, "Network Management Datastore Architecture 1876 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1877 . 1879 [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, 1880 "Object Security for Constrained RESTful Environments 1881 (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, 1882 . 1884 Appendix A. ietf-coreconf YANG module 1886 file "ietf-coreconf@2019-03-28.yang" 1887 module ietf-coreconf { 1888 yang-version 1.1; 1890 namespace "urn:ietf:params:xml:ns:yang:ietf-coreconf"; 1891 prefix coreconf; 1893 import ietf-datastores { 1894 prefix ds; 1895 } 1897 import ietf-restconf { 1898 prefix rc; 1899 description 1900 "This import statement is required to access 1901 the yang-data extension defined in RFC 8040."; 1902 reference "RFC 8040: RESTCONF Protocol"; 1903 } 1905 organization 1906 "IETF Core Working Group"; 1908 contact 1909 "Michel Veillette 1910 1912 Alexander Pelov 1913 1914 Peter van der Stok 1915 1917 Andy Bierman 1918 "; 1920 description 1921 "This module contains the different definitions required 1922 by the CORECONF protocol. 1924 Copyright (c) 2019 IETF Trust and the persons identified as 1925 authors of the code. All rights reserved. 1927 Redistribution and use in source and binary forms, with or 1928 without modification, is permitted pursuant to, and subject to 1929 the license terms contained in, the Simplified BSD License set 1930 forth in Section 4.c of the IETF Trust's Legal Provisions 1931 Relating to IETF Documents 1932 (https://trustee.ietf.org/license-info). 1934 This version of this YANG module is part of RFC XXXX; 1935 see the RFC itself for full legal notices."; 1937 revision 2019-03-28 { 1938 description 1939 "Initial revision."; 1940 reference 1941 "[I-D.ietf-core-comi] CoAP Management Interface"; 1942 } 1944 identity unified { 1945 base ds:datastore; 1946 description 1947 "Identifier of the unified configuration and operational 1948 state datastore."; 1949 } 1951 identity error-tag { 1952 description 1953 "Base identity for error-tag."; 1954 } 1956 identity operation-failed { 1957 base error-tag; 1958 description 1959 "Returned by the CORECONF server when the operation request 1960 can't be processed successfully."; 1961 } 1962 identity invalid-value { 1963 base error-tag; 1964 description 1965 "Returned by the CORECONF server when the CORECONF client tries to 1966 update or create a leaf with a value encoded using an 1967 invalid CBOR datatype or if the 'range', 'length', 1968 'pattern' or 'require-instance' constrain is not 1969 fulfilled."; 1970 } 1972 identity missing-element { 1973 base error-tag; 1974 description 1975 "Returned by the CORECONF server when the operation requested 1976 by a CORECONF client fails to comply with the 'mandatory' 1977 constraint defined. The 'mandatory' constraint is 1978 enforced for leafs and choices, unless the node or any of 1979 its ancestors have a 'when' condition or 'if-feature' 1980 expression that evaluates to 'false'."; 1981 } 1983 identity unknown-element { 1984 base error-tag; 1985 description 1986 "Returned by the CORECONF server when the CORECONF client tries to 1987 access a data node of a YANG module not supported, of a 1988 data node associated with an 'if-feature' expression 1989 evaluated to 'false' or to a 'when' condition evaluated 1990 to 'false'."; 1991 } 1993 identity bad-element { 1994 base error-tag; 1995 description 1996 "Returned by the CORECONF server when the CORECONF client tries to 1997 create data nodes for more than one case in a choice."; 1998 } 2000 identity data-missing { 2001 base error-tag; 2002 description 2003 "Returned by the CORECONF server when a data node required to 2004 accept the request is not present."; 2005 } 2007 identity error { 2008 base error-tag; 2009 description 2010 "Returned by the CORECONF server when an unspecified error has 2011 occurred."; 2012 } 2014 identity error-app-tag { 2015 description 2016 "Base identity for error-app-tag."; 2017 } 2019 identity malformed-message { 2020 base error-app-tag; 2021 description 2022 "Returned by the CORECONF server when the payload received 2023 from the CORECONF client don't contain a well-formed CBOR 2024 content as defined in [RFC7049] section 3.3 or don't 2025 comply with the CBOR structure defined within this 2026 document."; 2027 } 2029 identity data-not-unique { 2030 base error-app-tag; 2031 description 2032 "Returned by the CORECONF server when the validation of the 2033 'unique' constraint of a list or leaf-list fails."; 2034 } 2036 identity too-many-elements { 2037 base error-app-tag; 2038 description 2039 "Returned by the CORECONF server when the validation of the 2040 'max-elements' constraint of a list or leaf-list fails."; 2041 } 2043 identity too-few-elements { 2044 base error-app-tag; 2045 description 2046 "Returned by the CORECONF server when the validation of the 2047 'min-elements' constraint of a list or leaf-list fails."; 2048 } 2050 identity must-violation { 2051 base error-app-tag; 2052 description 2053 "Returned by the CORECONF server when the restrictions 2054 imposed by a 'must' statement are violated."; 2055 } 2057 identity duplicate { 2058 base error-app-tag; 2059 description 2060 "Returned by the CORECONF server when a client tries to create 2061 a duplicate list or leaf-list entry."; 2062 } 2064 identity invalid-datatype { 2065 base error-app-tag; 2066 description 2067 "Returned by the CORECONF server when CBOR encoding is 2068 incorect or when the value encoded is incompatible with 2069 the YANG Built-In type. (e.g. value greater than 127 2070 for an int8, undefined enumeration)."; 2071 } 2073 identity not-in-range { 2074 base error-app-tag; 2075 description 2076 "Returned by the CORECONF server when the validation of the 2077 'range' property fails."; 2078 } 2080 identity invalid-length { 2081 base error-app-tag; 2082 description 2083 "Returned by the CORECONF server when the validation of the 2084 'length' property fails."; 2085 } 2087 identity pattern-test-failed { 2088 base error-app-tag; 2089 description 2090 "Returned by the CORECONF server when the validation of the 2091 'pattern' property fails."; 2092 } 2094 identity missing-key { 2095 base error-app-tag; 2096 description 2097 "Returned by the CORECONF server to further qualify a 2098 missing-element error. This error is returned when the 2099 CORECONF client tries to create or list instance, without all 2100 the 'key' specified or when the CORECONF client tries to 2101 delete a leaf listed as a 'key'."; 2102 } 2104 identity missing-input-parameter { 2105 base error-app-tag; 2106 description 2107 "Returned by the CORECONF server when the input parameters 2108 of a RPC or action are incomplete."; 2109 } 2111 identity instance-required { 2112 base error-app-tag; 2113 description 2114 "Returned by the CORECONF server when a leaf of type 2115 'instance-identifier' or 'leafref' marked with 2116 require-instance set to 'true' refers to an instance 2117 that does not exist."; 2118 } 2120 identity missing-choice { 2121 base error-app-tag; 2122 description 2123 "Returned by the CORECONF server when no nodes exist in a 2124 mandatory choice."; 2125 } 2127 rc:yang-data coreconf-error { 2128 container error { 2129 description 2130 "Optional payload of a 4.00 Bad Request CoAP error."; 2132 leaf error-tag { 2133 type identityref { 2134 base error-tag; 2135 } 2136 mandatory true; 2137 description 2138 "The enumerated error-tag."; 2139 } 2141 leaf error-app-tag { 2142 type identityref { 2143 base error-app-tag; 2144 } 2145 description 2146 "The application-specific error-tag."; 2147 } 2149 leaf error-data-node { 2150 type instance-identifier; 2151 description 2152 "When the error reported is caused by a specific data node, 2153 this leaf identifies the data node in error."; 2155 } 2157 leaf error-message { 2158 type string; 2159 description 2160 "A message describing the error."; 2161 } 2162 } 2163 } 2164 } 2165 2167 Appendix B. ietf-coreconf .sid file 2169 { 2170 "assignment-ranges": [ 2171 { 2172 "entry-point": 1000, 2173 "size": 100 2174 } 2175 ], 2176 "module-name": "ietf-coreconf", 2177 "module-revision": "2019-03-28", 2178 "items": [ 2179 { 2180 "namespace": "module", 2181 "identifier": "ietf-coreconf", 2182 "sid": 1000 2183 }, 2184 { 2185 "namespace": "identity", 2186 "identifier": "bad-element", 2187 "sid": 1001 2188 }, 2189 { 2190 "namespace": "identity", 2191 "identifier": "data-missing", 2192 "sid": 1002 2193 }, 2194 { 2195 "namespace": "identity", 2196 "identifier": "data-not-unique", 2197 "sid": 1003 2198 }, 2199 { 2200 "namespace": "identity", 2201 "identifier": "duplicate", 2202 "sid": 1004 2204 }, 2205 { 2206 "namespace": "identity", 2207 "identifier": "error", 2208 "sid": 1005 2209 }, 2210 { 2211 "namespace": "identity", 2212 "identifier": "error-app-tag", 2213 "sid": 1006 2214 }, 2215 { 2216 "namespace": "identity", 2217 "identifier": "error-tag", 2218 "sid": 1007 2219 }, 2220 { 2221 "namespace": "identity", 2222 "identifier": "instance-required", 2223 "sid": 1008 2224 }, 2225 { 2226 "namespace": "identity", 2227 "identifier": "invalid-datatype", 2228 "sid": 1009 2229 }, 2230 { 2231 "namespace": "identity", 2232 "identifier": "invalid-length", 2233 "sid": 1010 2234 }, 2235 { 2236 "namespace": "identity", 2237 "identifier": "invalid-value", 2238 "sid": 1011 2239 }, 2240 { 2241 "namespace": "identity", 2242 "identifier": "malformed-message", 2243 "sid": 1012 2244 }, 2245 { 2246 "namespace": "identity", 2247 "identifier": "missing-choice", 2248 "sid": 1013 2249 }, 2250 { 2251 "namespace": "identity", 2252 "identifier": "missing-element", 2253 "sid": 1014 2254 }, 2255 { 2256 "namespace": "identity", 2257 "identifier": "missing-input-parameter", 2258 "sid": 1015 2259 }, 2260 { 2261 "namespace": "identity", 2262 "identifier": "missing-key", 2263 "sid": 1016 2264 }, 2265 { 2266 "namespace": "identity", 2267 "identifier": "must-violation", 2268 "sid": 1017 2269 }, 2270 { 2271 "namespace": "identity", 2272 "identifier": "not-in-range", 2273 "sid": 1018 2274 }, 2275 { 2276 "namespace": "identity", 2277 "identifier": "operation-failed", 2278 "sid": 1019 2279 }, 2280 { 2281 "namespace": "identity", 2282 "identifier": "pattern-test-failed", 2283 "sid": 1020 2284 }, 2285 { 2286 "namespace": "identity", 2287 "identifier": "too-few-elements", 2288 "sid": 1021 2289 }, 2290 { 2291 "namespace": "identity", 2292 "identifier": "too-many-elements", 2293 "sid": 1022 2294 }, 2295 { 2296 "namespace": "identity", 2297 "identifier": "unified", 2298 "sid": 1029 2299 }, 2300 { 2301 "namespace": "identity", 2302 "identifier": "unknown-element", 2303 "sid": 1023 2304 }, 2305 { 2306 "namespace": "data", 2307 "identifier": "/ietf-coreconf:error", 2308 "sid": 1024 2309 }, 2310 { 2311 "namespace": "data", 2312 "identifier": "/ietf-coreconf:error/error-app-tag", 2313 "sid": 1025 2314 }, 2315 { 2316 "namespace": "data", 2317 "identifier": "/ietf-coreconf:error/error-data-node", 2318 "sid": 1026 2319 }, 2320 { 2321 "namespace": "data", 2322 "identifier": "/ietf-coreconf:error/error-message", 2323 "sid": 1027 2324 }, 2325 { 2326 "namespace": "data", 2327 "identifier": "/ietf-coreconf:error/error-tag", 2328 "sid": 1028 2329 } 2330 ] 2331 } 2333 Authors' Addresses 2335 Michel Veillette (editor) 2336 Trilliant Networks Inc. 2337 610 Rue du Luxembourg 2338 Granby, Quebec J2J 2V2 2339 Canada 2341 Email: michel.veillette@trilliant.com 2342 Peter van der Stok (editor) 2343 consultant 2345 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 2346 Email: consultancy@vanderstok.org 2347 URI: www.vanderstok.org 2349 Alexander Pelov 2350 Acklio 2351 2bis rue de la Chataigneraie 2352 Cesson-Sevigne, Bretagne 35510 2353 France 2355 Email: a@ackl.io 2357 Andy Bierman 2358 YumaWorks 2359 685 Cochran St. 2360 Suite #160 2361 Simi Valley, CA 93065 2362 USA 2364 Email: andy@yumaworks.com 2366 Ivaylo Petrov (editor) 2367 Acklio 2368 1137A avenue des Champs Blancs 2369 Cesson-Sevigne, Bretagne 35510 2370 France 2372 Email: ivaylo@ackl.io