idnits 2.17.1 draft-veillette-core-cool-02.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 are 6 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The abstract seems to contain references ([I-D.ietf-core-yang-cbor], [RFC7049], [RFC7252], [I-D.ietf-netmod-RFC6020bis]), 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 == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The payload of the FETCH request carries a CBOR array of instance-identifier. The first entry MUST be set to the 'instance-identifier' of the data node instance observed. The following entries are optional and allow the selection of coincidental values, data nodes reported at the same time as the observed data node. Coincidental values are included in each notification reported, but changes to these extra data nodes MUST not trigger notification messages. -- The document date (July 18, 2016) is 2840 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1533' on line 522 -- Looks like a reference, but probably isn't: '1537' on line 628 == Unused Reference: 'I-D.vanderstok-core-etch' is defined on line 1333, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-11) exists of draft-ietf-core-coap-tcp-tls-03 == Outdated reference: A later version (-20) exists of draft-ietf-core-yang-cbor-02 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-15 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-09 -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Veillette, Ed. 3 Internet-Draft Trilliant Networks Inc. 4 Intended status: Informational A. Pelov, Ed. 5 Expires: January 19, 2017 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 July 18, 2016 14 Constrained Objects Language 15 draft-veillette-core-cool-02 17 Abstract 19 This document describes a management function set adapted to 20 constrained devices and constrained networks (e.g., low-power, 21 lossy). CoOL objects (datastores, RPCs, actions and notifications) 22 are defined using the YANG modelling language 23 [I-D.ietf-netmod-rfc6020bis]. Interactions with these objects are 24 performed using the CoAP web transfer protocol [RFC7252]. Payloads 25 are encoded using the CBOR data format [RFC7049]. The mapping 26 between YANG data models and the CBOR data format is defined in 27 [I-D.ietf-core-yang-cbor]. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 19, 2017. 46 Copyright Notice 48 Copyright (c) 2016 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 65 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 5 66 4. Resources . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 5. Operations . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.1. GET - Retrieving all data nodes of a datastore . . . . . 7 69 5.2. FETCH - Retrieving specific data nodes . . . . . . . . . 8 70 5.2.1. Example #1 - Simple data node . . . . . . . . . . . . 9 71 5.2.2. Example #2 - Data node instance within a YANG list . 11 72 5.2.3. Example #3 - YANG list . . . . . . . . . . . . . . . 12 73 5.2.4. Example #4 - YANG list instance . . . . . . . . . . . 12 74 5.2.5. Example #5 - YANG list instance filtering . . . . . . 13 75 5.2.6. Example #6 - All instances of a data node within a 76 YANG list . . . . . . . . . . . . . . . . . . . . . . 14 77 5.3. PUT - Updating all data nodes of a datastore . . . . . . 14 78 5.4. iPATCH - Updating specific data nodes . . . . . . . . . . 16 79 5.5. POST - Protocol operation . . . . . . . . . . . . . . . . 18 80 5.5.1. Example #1 - RPC . . . . . . . . . . . . . . . . . . 18 81 5.5.2. Example #2 - Action . . . . . . . . . . . . . . . . . 19 82 5.6. Event stream . . . . . . . . . . . . . . . . . . . . . . 19 83 6. Uri-Query . . . . . . . . . . . . . . . . . . . . . . . . . . 23 84 6.1. The 'a' Query Parameter . . . . . . . . . . . . . . . . . 23 85 7. CoAP compatibility . . . . . . . . . . . . . . . . . . . . . 24 86 7.1. Working with Uri-Host, Uri-Port, Uri-Path, and Uri-Query 24 87 7.2. Working with Location-Path and Location-Query . . . . . . 24 88 7.3. Working with Accept . . . . . . . . . . . . . . . . . . . 24 89 7.4. Working with Max-Age . . . . . . . . . . . . . . . . . . 24 90 7.5. Working with Proxy-Uri and Proxy-Scheme . . . . . . . . . 24 91 7.6. Working with If-Match, If-None-Match and ETag . . . . . . 24 92 7.7. Working with Size1, Size2, Block1 and Block2 . . . . . . 24 93 7.8. Working with Observe . . . . . . . . . . . . . . . . . . 24 94 7.9. Working with resource discovery . . . . . . . . . . . . . 26 95 8. Error Handling . . . . . . . . . . . . . . . . . . . . . . . 27 96 9. Security Considerations . . . . . . . . . . . . . . . . . . . 27 97 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 98 10.1. CoAP Content-Formats . . . . . . . . . . . . . . . . . . 28 99 10.2. CBOR simple value . . . . . . . . . . . . . . . . . . . 29 100 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 101 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 102 12.1. Normative References . . . . . . . . . . . . . . . . . . 29 103 12.2. Informative References . . . . . . . . . . . . . . . . . 30 104 Appendix A. File "ietf-cool.yang" . . . . . . . . . . . . . . . 32 105 Appendix B. File "ietf-cool@2016-01-01.sid" . . . . . . . . . . 38 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 40 108 1. Introduction 110 This document defines a CoAP function set for accessing YANG defined 111 resources. YANG data models are encoded in CBOR based on the mapping 112 rules defined in [I-D.ietf-core-yang-cbor]. YANG items are 113 identified using a compact identifier called Structured Identifiers 114 (SIDs) as defined in [I-D.somaraju-core-sid]. 116 The resulting protocol based on CoAP, CBOR encoded data and 117 structured identifiers (SID) has a low implementation footprint and 118 low network bandwidth requirements and is suitable for both 119 constrained devices and constrained networks as defined by [RFC7228]. 120 This protocol is applicable to the different management topology 121 options described by [I-D.ersue-constrained-mgmt]; centralized, 122 distributed and hierarchical. 124 2. Terminology and Notation 126 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 127 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 128 document are to be interpreted as described in [RFC2119]. 130 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 132 o action 134 o data node 136 o data tree 138 o module 140 o notification 141 o RPC 143 o schema node 145 o schema tree 147 o submodule 149 This specification also makes use of the following terminology: 151 o candidate configuration datastore: A configuration datastore that 152 can be manipulated without impacting the device's current 153 configuration and that can be committed to the running 154 configuration datastore. Not all devices support a candidate 155 configuration datastore. 157 o CoOL client: The originating endpoint of a request, and the 158 destination endpoint of a response. 160 o CoOL server: The destination endpoint of a request, and the 161 originating endpoint of a response. 163 o delta: Within a list, a delta represents the different between the 164 current SID and the SID of the previous entry within this list. 165 Within a collection, a delta represents the difference between the 166 SID assigned to the current schema node and the SID assigned to 167 the parent. When no previous entry or parent exist, the delta is 168 set to the absolute SID value. 170 o child: A schema node defined within a collection such as a 171 container, a list, a case, a notification, a RPC input, a RPC 172 output, an action input, an action output. 174 o datastore: Resource used to store and access information. 176 o endpoint: An entity participating in the CoOL protocol. Multiple 177 CoOL endpoints may be accessible using a single CoAP endpoint. In 178 this case, each CoOL endpoint is accessed using a distinct URI. 180 o event stream: Resource used to access notifications generated by a 181 CoOL server. Events are defined using the YANG notification 182 statement. 184 o function set: A group of well-known resources that provides a 185 particular service. 187 o object: Within CoOL, an object is a data node, an RPC or an action 188 within a datastore resource or a notification within an event 189 stream resource. 191 o parent: The collection in which a schema node is defined. 193 o resource: Content identified by a URI. 195 o running configuration datastore: A configuration datastore holding 196 the complete configuration currently active on the device. The 197 running configuration datastore always exists. 199 o Structured IDentifier (SID). Unsigned integer used to identify 200 different YANG items. 202 3. Architecture 204 The CoOL protocol is based on the client-server model. The CoOL 205 server is the provider of the datastore resource(s) and the event 206 stream resource(s). The CoOL client is the requester of these 207 resources. 209 CoOL objects are defined using the YANG modeling language [RFC6020]. 210 Interactions with these objects are performed using the Constrained 211 Application Protocol (CoAP) [RFC7252]. Payloads are encoded using 212 the Concise Binary Object Representation (CBOR) [RFC7049]. 214 This specification is applicable to any transport and security 215 protocols supported by CoAP. Implementers are free to select the 216 most appropriate transport for the targeted applications. 218 +--------------+ +----------------------------------+ 219 | CoOL client | | CoOL Server | 220 | | | - Datastore resource(s) | 221 | | | - Event stream resource(s) | 222 +--------------+ +----------------------------------+ 223 | CoAP client | <-------> | CoAP Server | 224 +--------------+ +----------------------------------+ 225 | | | | 226 | Lower layers | | Lower layers | 227 | | | | 228 +--------------+ +----------------------------------+ 230 4. Resources 232 This section lists the URIs recommended for the different CoOL 233 resources. A CoOL server MAY implement a different set of URIs. See 234 the Resource discovery section (Section 7.15) for more details on how 235 a CoOL client can discover the list of URIs supported by a CoOL 236 server using the "/.well-known/core" resource. 238 o /c - The default datastore resource 240 o /c/c - The candidate configuration datastore resource 242 o /c/r - The running configuration datastore resource 244 o /c/b - The backup configuration datastore (use to implement 245 rollbacks) 247 o /c/e - URI used to access the default event stream for this 248 device. 250 o /c/e0, /c/e1, ... - URI used to access alternate event streams. 252 o /c/0, /c/1, ... - URI used to access a specific endpoint. Each 253 end point represents a virtual device which can support any of the 254 resources listed above. 256 For example: 258 o /c/1 is the default datastore resource for endpoint 1 260 o /c/1/c is the candidate datastore resource for endpoint 1 262 o /c/1/r is the running configuration datastore resource for 263 endpoint 1 265 o /c/1/b is the backup configuration datastore resource for endpoint 266 1 268 o /c/1/e is the default event stream resource for endpoint 1 270 o /c/1/e0 is an alternate event stream resource for endpoint 1 272 All these resources are optional at the exception of the default 273 datastore resource. The CoAP response code 4.04 (Not Found) MUST be 274 returned when a CoOL client tries to access a resource that is 275 unavailable. 277 RPCs commit and cancel-commit defined in ietf-cool YANG module are 278 available to perform the following operations on datastores: 280 o Immediate or differed commit of a candidate or backup datastore. 282 o Confirmed commit 283 o Cancel of a different or confirmed commit. 285 5. Operations 287 This section defines the different interactions supported between a 288 CoOL client and a CoOL server. 290 5.1. GET - Retrieving all data nodes of a datastore 292 The GET method is used by CoOL clients to retrieve the entire 293 contents of a datastore. Implementation of this function is optional 294 and dependent of the capability of the CoOL server to transfer a 295 relatively large response. 297 To retrieve all instantiated data nodes of a datastore resource, a 298 CoOL client sends a CoAP GET request to the URI of the targeted 299 datastore. If the request is accepted by the CoOL server, a 2.05 300 (Content) response code is returned. The payload of the GET response 301 MUST carry a CBOR array containing the contents of the targeted 302 datastore. The CBOR array MUST contain a list of pairs of delta and 303 associated value. A delta represents the difference between the 304 current SID and the SID of the previous pair within the CBOR array. 305 Each value is encoded using the rules defined by 306 [I-D.ietf-core-yang-cbor]. 308 The normal behaviour of a CoOL server is to exclude from the GET 309 response, any data node currently set to its default value. When 310 this behaviour is not appropriate for the CoOL client, this client 311 can force the retrieval of all data nodes by using the 'a' Uri-Query 312 parameter, see Section 6.1 for more details. 314 If the request is rejected by the CoOL server, a 5.01 Not implemented 315 or 4.13 Request Entity Too Large response code is returned. 317 Example: 319 In this example, the CoOL server returns a datastore containing the 320 following data nodes defined in the YANG module "ietf-system" 321 [RFC7317] and YANG module 'ietf-interfaces' [RFC7223]: 323 o "/interfaces/interface" (SID 1533) 325 o "/interfaces/interface/description" (SID 1534) 327 o "/interfaces/interface/enabled" (SID 1535) 329 o "/interfaces/interface/name" (SID 1537) 330 o "/interfaces/interface/1538" (SID 1534) 332 o "/system-state/clock" (SID 1717) 334 o "/system-state/clock/boot-datetime" (SID 1718) 336 o "/system-state/clock/current-datetime" (SID 1719) 338 o "/system/clock/timezone/timezone-utc-offset/timezone-utc-offset" 339 (SID 1736) 341 CoAP Request: 343 GET /c 345 CoAP response: 347 2.05 Content Content-Format(application/cool-value-pairs+cbor) 348 [ 349 1533, # interface (SID 1533) 350 { 351 +4 : "eth0", # name (SID 1537) 352 +1 : "Ethernet adaptor", # description (SID 1534) 353 +5 : 1179, # type (SID 1538), identity ethernetCsmacd 354 +2 : true # enabled (SID 1535) 355 }, 356 +184, # clock (SID 1717) 357 { 358 +1 : "2015-02-08T14:10:08Z09:00", # boot-datetime (SID 1718) 359 +2 : "2015-04-04T09:32:51Z09:00" # current-datetime (SID 1719) 360 }, 361 +19, 60 # timezone-utc-offset (SID 1736) 362 ] 364 5.2. FETCH - Retrieving specific data nodes 366 The FETCH method is used by the CoOL client of retrieve a subset of 367 the data node instances within a datastore. 369 To retrieve a list of data node instances, the CoOL client sends a 370 CoAP FETCH request to the URI of the targeted datastore. The payload 371 of the FETCH request contains the list of data node(s) instance to be 372 retrieved. This list is encoded using a CBOR array, each entry 373 containing an 'instance-identifier' as defined by 374 [I-D.ietf-core-yang-cbor]. Within each 'instance-identifier', data 375 nodes are identified using SIDs as defined by 376 [I-D.somaraju-core-sid]. 378 SIDs within the list of 'instance-identifier' are encoded using 379 delta. A delta represents the different between the current SID and 380 the SID of the previous entry within this list. The delta of the 381 first entry within the list is set to the absolute SID value. 383 On successful processing of the CoAP request, the CoOL server MUST 384 return a CoAP response with a response code 2.05 (Content). 386 When a single data node is requested, the payload of the FETCH 387 response carries the value of the data node instance requested. When 388 multiple data nodes are requested, the payload of the FETCH response 389 carries a CBOR array containing the value of each data node 390 instance(s) requested. The number of entries in this CBOR array MUST 391 match the number of "instance-identifier" requested to allow a proper 392 interpretation of this information. The following values can be 393 returned for each 'instance-identifier' requested: 395 o If the data node requested is not implemented or not instantiated, 396 the CBOR simple value 'undefined' is returned. 398 o If the URI-Query parameter 'a' is not present in the FETCH request 399 and the value of the data node instance is equal to the default 400 value for this data node, the CBOR simple value 'default' is 401 returned. 403 o Otherwise, the data node instance is encoded using the rules 404 defined in [I-D.ietf-core-yang-cbor]. 406 The normal behaviour of a CoOL server is to exclude from containers 407 and list instances of a FETCH response, any data node currently set 408 to its default value. When this behaviour is not appropriate for the 409 CoOL client, this client can force the retrieval of all data nodes by 410 using the 'a' Uri-Query parameter, see Section 6.1 for more details. 412 5.2.1. Example #1 - Simple data node 414 In this example, a CoOL client retrieves the leaf "/system- 415 state/clock/current-datetime" (SID 1719) and the container "/system/ 416 clock" (SID 1734) containing the leaf "/system/clock/timezone/ 417 timezone-utc-offset/timezone-utc-offset" (SID 1736). These data 418 nodes are defined in the YANG module "ietf-system" [RFC7317]. 420 CoAP request: 422 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 423 [1719, +15] 425 CoAP response: 427 2.05 Content Content-Format(application/cool-value-list+cbor) 428 [ 429 "2015-10-08T14:10:08Z09:00", # current-datetime (SID 1719) 430 { # clock (SID 1734) 431 +2 : 540 # timezone-utc-offset (SID 1736) 432 } 433 ] 435 CoAP requests and responses MUST be encoded in accordance with 436 [RFC7252] or [I-D.ietf-core-coap-tcp-tls]. An encoding example is 437 shown below: 439 CoAP request: 441 0 1 2 3 442 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 443 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 444 |Ver| T | TKL | Code (0x05) | Message ID | 445 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 446 | Token (0 to 8 bytes) ... 447 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 448 | Opt Delta (12)| Opt Length (1)| na | Opt Delta (3) | 449 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 450 | Opt Length (2)| '/' | 'c' |1 1 1 1 1 1 1 1| 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 452 | 0x82 | 0x19 | 0x06 | 0xb7 | 453 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 454 | 0x0f | 455 +-+-+-+-+-+-+-+-+ 457 CoAP response: 459 0 1 2 3 460 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 461 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 462 |Ver| T | TKL | Code (0x45) | Message ID | 463 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 464 | Token (0 to 8 bytes) ... 465 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 466 | Opt Delta (12)| Opt Length (1)| na |1 1 1 1 1 1 1 1| 467 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 468 | 0x82 | 0x78 | 0x19 | 0x32 | 469 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 470 | 0x30 | 0x31 | 0x35 | 0x2d | 471 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 472 | 0x31 | 0x30 | 0x2d | 0x30 | 473 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 474 | 0x38 | 0x54 | 0x31 | 0x34 | 475 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 476 | 0x3a | 0x31 | 0x30 | 0x3a | 477 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 478 | 0x30 | 0x38 | 0x5a | 0x30 | 479 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 480 | 0x39 | 0x3a | 0x30 | 0x30 | 481 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 482 | 0xa1 | 0x02 | 0x19 | 0x02 | 483 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 484 | 0x1c | 485 +-+-+-+-+-+-+-+-+ 487 5.2.2. Example #2 - Data node instance within a YANG list 489 The data type 'instance-identifier' allows the selection of an 490 instance of a specific data node within a list. In this example, a 491 CoOL client retrieves the "/interfaces/interface/description" (SID 492 1534) leaf from the "/interfaces/interface" list. The 493 "/interfaces/interface/name" associated to this interface is equal to 494 "eth0". This example is based on the YANG module "ietf-interfaces" 495 [RFC7223]. 497 CoAP request: 499 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 500 [[1534, "eth0"]] 502 CoAP response: 504 2.05 Content Content-Format(application/cool-value+cbor) 505 "Ethernet adaptor" 507 5.2.3. Example #3 - YANG list 509 This "instance-identifier" extension allows the retrieval of all 510 instances of a YANG list. To perform this operation, the CoOL client 511 excludes from the 'instance-identifier' the key(s) of the targeted 512 list. The list returned is encoded using the rules defined in 513 [I-D.ietf-core-yang-cbor] section 4.4. 515 In this example, a CoOL client retrieves the list "/interfaces/ 516 interface" (SID 1533). The response returned contain two instances, 517 one for an Ethernet adaptor and one for a WIFI interface. 519 CoAP request: 521 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 522 [1533] 524 CoAP response: 526 2.05 Content Content-Format(application/cool-value+cbor) 527 [ 528 { 529 +4 : "eth0", # name (SID 1537) 530 +1 : "Ethernet adaptor", # description (SID 1534) 531 +5 : 1179, # type (SID 1538), identity ethernetCsmacd 532 +2 : true # enabled (SID 1535) 533 }, 534 { 535 +4 : "wlan0", # name (SID 1537) 536 +1 : "WIFI ", # description (SID 1534) 537 +5 : 1220, # type (SID 1538), identity ieee80211 538 +2 : false # enabled (SID 1535) 539 } 540 ] 542 5.2.4. Example #4 - YANG list instance 544 To retrieve a list instance, the CoOL client MUST use an 'instance- 545 identifier' with a SID set to the targeted list and the key(s) set to 546 the value(s) associated to the targeted instance. 548 In this example, the CoOL client requests the instance of the list 549 "/interfaces/interface" (SID 1533) associated to the name "eth0". 550 The response returned by the CoOL server contains the targeted list 551 instance formatted as YANG container. 553 CoAP request: 555 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 556 [[1533, "eth0"]] 558 CoAP response: 560 2.05 Content Content-Format(application/cool-value+cbor) 561 { 562 +4 : "eth0" # name (SID 1537) 563 +1 : "Ethernet adaptor" # description (SID 1534) 564 +5 : 1179 # type (SID 1538), identity ethernetCsmacd 565 +2 : true # enabled (SID 1535) 566 } 568 5.2.5. Example #5 - YANG list instance filtering 570 This 'instance-identifier' extension allows the selection of a subset 571 of data nodes within a list. This is accomplished by adding an extra 572 element to the 'instance-identifier'. This element contains the 573 subset of data nodes to be returned encoded as CBOR array. Each 574 entry within this CBOR array is set to the delta between the current 575 SID and the SID of targeted container as specified in the first entry 576 of the 'instance-identifier'. 578 CoOL servers SHOULD implement this 'instance-identifier' extension. 579 When this extension is not supported, the CoOL server MUST ignore the 580 third element of the 'instance-identifier' and return the list 581 instance as specified by the first two elements of the 'instance- 582 identifier'. 584 In this example, a CoOL client retrieves from within the 585 "/interfaces/interface" list (SID 1533) the leafs 586 "/interfaces/interface/type" (SID 1538) and "/interfaces/interface/ 587 enabled" (SID 1535). The CoOL client also includes in this request 588 the selection of the leaf "/system/hostname" (SID 1748) defined in 589 "ietf-system" [RFC7317]. 591 For example: 593 CoAP request: 595 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 596 [ [1533, "eth0", [+5, +2]], +215] 598 CoAP response: 600 2.05 Content Content-Format(application/cool-value-list+cbor) 601 [ 602 { 603 +5 : 1179, # type (SID 1538), identity ethernetCsmacd 604 +2 : true # enabled (SID 1535) 605 }, 606 "datatracker.ietf.org", # hostname (SID 1748) 607 ] 609 5.2.6. Example #6 - All instances of a data node within a YANG list 611 This 'instance-identifier' extension allows the efficient transfer of 612 all instances of a data node within a YANG list. To retrieve all 613 instances, the CoOL client excludes form the 'instance-identifier' 614 the key(s) of the list containing the targeted data node. 616 The response MUST be encoded as a CBOR ARRAY containing the available 617 instances of the requested data node. This special encoding 618 minimizes significantly this commonly used type of request. 620 In this example, a CoOL client retrieves all instances of data node 621 "/interfaces/interface/name" (SID 1537). 623 Example: 625 CoAP request: 627 FETCH /c Content-Format(application/cool-instance-id-list+cbor) 628 [1537] 630 CoAP response: 632 2.05 Content Content-Format(application/cool-value+cbor) 633 ["eth0", "eth1", "wlan0"] 635 5.3. PUT - Updating all data nodes of a datastore 637 The CoAP PUT method is used by CoOL clients to update the content of 638 a datastore. 640 The URI of the PUT request MUST be set to the URI of the targeted 641 datastore. 643 The payload of the PUT request MUST carry a CBOR array containing the 644 new content of the datastore. The CBOR array MUST contain a list of 645 pairs of delta and associated value. A delta represents the 646 different between the current SID and the SID of the previous pair 647 within the CBOR array. Each value is encoded using the rules defined 648 by [I-D.ietf-core-yang-cbor]. 650 On successful processing of the CoAP request, the CoOL server MUST 651 return a CoAP response with a response code 2.04 (Changed). 653 A PUT request MUST be processed as an atomic transaction, if any of 654 the data node transferred is rejected for any reason, the entire PUT 655 request MUST be rejected and the CoOL server MUST return an 656 appropriate error response as defined in section 6. 658 Example: 660 In this example, a CoOL client sets the default runtime datastore 661 with these data nodes: 663 o "/system/clock/timezone/timezone-utc-offset/timezone-utc-offset" 664 (SID 1736) 666 o "/system/ntp/enabled" (SID 1751) 668 o "/system/ntp/server" (SID 1752) 670 o "/system/ntp/server/name" (SID 1755) 672 o "/system/ntp/server/prefer" (SID 1756) 674 o "/system/ntp/server/transport/udp/udp" (SID 1757) 676 o "/system/ntp/server/transport/udp/udp/address" (SID 1758) 678 o "/system/ntp/server/transport/udp/udp/port" (SID 1759) 680 CoAP request: 682 PUT /c/r Content-Format(application/cool-value-pairs+cbor) 683 [ 684 1736, 540, # timezone-utc-offset (SID 1736) 685 +15, true, # enabled (SID 1751) 686 +1, [ # server (SID 1752) 687 { 688 +3 : "tic.nrc.ca", # name (SID 1755) 689 +4 : true, # prefer (SID 1756) 690 +5 : { # udp (SID 1757) 691 +1 : "132.246.11.231", # address (SID 1758) 692 +2 : 123 # port (SID 1759) 693 } 694 }, 695 { 696 +3 : "tac.nrc.ca", # name (SID 1755) 697 +4 : false, # prefer (SID 1756) 698 +5 : { # udp (SID 1757) 699 +1 : "132.246.11.232" # address (SID 1758) 700 } 701 } 702 ] 703 ] 705 CoAP response: 707 2.04 Changed 709 5.4. iPATCH - Updating specific data nodes 711 The iPATCH method is used by CoOL clients to modify a subset of a 712 datastore. 714 To modify a datastore, the CoOL client sends a CoAP PATH request to 715 the URI of the targeted datastore. The payload of the FETCH request 716 contains the list of data node instance(s) to be updated, inserted or 717 deleted. This list is encoded using a CBOR array and contains a 718 sequence of pairs of 'instance-identifier' and associated values. 720 Within each 'instance-identifier', data nodes are identified using 721 SIDs as defined by [I-D.somaraju-core-sid]. SIDs within the list are 722 encoded as delta. 724 On reception, the list is processed by the CoOL server as follows: 726 o If the targeted data instance already exists, this instance is 727 replaced by the associated value (not merged). To update only 728 some children of a collection, each child data node MUST be 729 provided individually. 731 o If the targeted data instance doesn't exist, this instance is 732 created. 734 o If the targeted data instance already exists but is associated 735 with the value 'null', this instance is deleted. 737 On successful processing of the CoAP request, the CoOL server MUST 738 return a CoAP response with a response code 2.05 (Content). 740 A iPATCH request MUST be processed as an atomic transaction, if any 741 of the data nodes transferred is rejected for any reasons, the entire 742 iPATCH request MUST be rejected and the CoOL server MUST return an 743 appropriate error response as defined in section 6. 745 Example: 747 In this example, a CoOL client performs the following operations: 749 o Set "/system/ntp/enabled" (SID 1751) to true. 751 o Remove the server "tac.nrc.ca" from the"/system/ntp/server" (SID 752 1752) list. 754 o Add the server "NTP Pool server 2" to the list "/system/ntp/ 755 server" (SID 1752). 757 o Set "/system/ntp/server/prefer" (SID 1756) to false for the server 758 "tic.nrc.ca". 760 CoAP request: 762 iPATCH /c/r Content-Format(application/cool-value-pairs+cbor) 763 [ 764 1751 , true, # enabled (1751) 765 [+1, "tac.nrc.ca"], null, # server (SID 1752) 766 +0, # server (SID 1752) 767 { 768 +3 : "NTP Pool server 2", # name (SID 1755) 769 +4 : true, # prefer (SID 1756) 770 +5 : { # udp (SID 1757) 771 +1 : "2620:10a:800f::11", # address (SID 1758) 772 } 773 } 774 [+4, "tic.nrc.ca"], false # prefer (SID 1756) 775 ] 777 CoAP response: 779 2.04 Changed 781 5.5. POST - Protocol operation 783 Protocol operations are defined using the YANG 'rpc' or YANG 'action' 784 statements. 786 To execute a protocol operation, the CoOL client sents a CoAP POST 787 request to the URI of the targeted datastore. 789 The payload of the POST request carries a CBOR array with up to two 790 entries. The first entry carries the instance-identifier identifying 791 the targeted protocol operation. The second entry carries the 792 protocol operation input(s). Input(s) are present only if defined 793 for the invoked protocol operation and used by the CoOL client. 794 Input(s) are encoded using the rules defined for a YANG container, 795 deltas are relative to the SID assigned to the protocol operation. 797 On successful completion on the protocol operation, the CoOL server 798 returns a CoAP response with the response code set to 2.05 (Content). 799 When output parameters are returned by the CoOL server, these 800 parameter(s) are carried in the CoAP response payload. Output(s) are 801 encoded using the rules defined for a YANG container, deltas are 802 relative to the SID assigned to the protocol operation. 804 5.5.1. Example #1 - RPC 806 This example is based on the 'activate-software-image' RPC defined in 807 [I-D.ietf-netmod-rfc6020bis], assuming that this RPC is assigned to 808 SID 1932, leaf image-name to SID 1933 and leaf status to SID 1934. 809 These SIDs are defined strictly for the purpose of this example. 811 rpc activate-software-image { input { leaf image-name { type string; 812 } } output { leaf status { type string; } } } 814 CoAP request: 816 POST /c Content-Format(application/cool-value-pairs+cbor) 817 [ 818 1932, 819 { 820 +1 : "acmefw-2.3" # image-name (SID 1933) 821 } 822 ] 824 CoAP response: 826 2.05 Content Content-Format(application/cool-value+cbor) 827 { 828 +2 : "installed" # status (SID 1934) 829 } 831 5.5.2. Example #2 - Action 833 This example is based on the 'reset' action defined in 834 [I-D.ietf-netmod-rfc6020bis] assuming that this action is assigned to 835 SID 1902, leaf reset-at to SID 1903 and leaf reset-finished-at to SID 836 1904. These SIDs are defined strictly for the purpose of this 837 example. 839 list server { key name; leaf name { type string; } action reset { 840 input { leaf reset-at { type yang:date-and-time; mandatory true; } } 841 output { leaf reset-finished-at { type yang:date-and-time; mandatory 842 true; } } } } 844 CoAP request: 846 POST /c Content-Format(application/cool-value-pairs+cbor) 847 [ 848 [1902, "myServer"], 849 { 850 +1 : "2016-02-08T14:10:08Z09:00" # reset-at (SID 1903) 851 } 852 ] 854 CoAP response: 856 2.05 Content Content-Format(application/cool-value+cbor) 857 { 858 +2 : "2016-08T14:10:08Z09:18" # reset-finished-at (SID 1904) 859 } 861 5.6. Event stream 862 WARNING 863 This section requires more work to address the following identified issues: 865 * Retrieval of past events (e.g. start-time, stop-time) 866 * Retrieval of specific events (e.g. filter) 867 * Configuration persistence 868 * Configuration of by a third entity (configuration tool) 869 * Support of multicast 870 * Event congestion-avoidance 871 * Transfer reliability 873 The current solution based on the observe CoAP option can be augmented 874 or completely replaced by a future version of this draft. 876 Notifications are defined using the YANG 'notification' statement. 877 Subscriptions to an event stream and notification reporting are 878 performed using an event stream resource. When multiple event stream 879 resources are supported, the list of notifications associated with 880 each stream is either pre-defined or configured in the CoOL server. 881 CoOL clients MAY subscribe to one or more event stream resources. 883 To subscribe to an event stream resource, a CoOL client MUST send a 884 CoAP GET with the Observe CoAP option set to 0. To unsubscribe, a 885 CoOL client MAY send a CoAP reset or a CoAP GET with the Observe 886 option set to 1. For more information on the observe mechanism, see 887 [RFC7641]. 889 Each notification transferred by a CoOL server to each of the 890 registered CoOL clients is carried in a CoAP response with a response 891 code set to 2.05 (Content). Each CoAP response MUST carry in its 892 payload at least one notification but MAY carry multiple. Each 893 notification is carried in a notification-payload defined in ietf- 894 cool, see Appendix A. The notification-payload supports different 895 meta-data associated to this notification, such as the notification 896 identifier, event timestamp, sequence number, severity level and 897 facility. All of these meta information are optional with the 898 exception of the notification identifier. 900 The CoAP response payload is encoded using the rules defined for the 901 PUT request. When multiple notifications are reported, the CoAP 902 response payload carries a CBOR array, with each entry containing a 903 notification. 905 This example is based on the 'link-failure' and 'interface-enabled' 906 notifications defined in [I-D.ietf-netmod-rfc6020bis] assuming the 907 following SID assignment: 909 o "/link-failure" (SID 1942) 910 o "/link-failure/if-name" (SID 1943) 912 o "/link-failure/admin-status" (SID 1944) 914 o "/interfaces/interface/interface-enabled" (SID 1538) 916 o "/interfaces/interface/interface-enabled/by-user" (SID 1539) 918 These SIDs are defined strictly for the purpose of this example. 920 notification link-failure { 921 leaf if-name { 922 type leafref { 923 path "/interface/name"; 924 } 925 } 926 leaf admin-status { 927 type leafref { 928 path "/interface[name = current()/../if-name]/admin-status"; 929 } 930 } 931 } 933 container interfaces { 934 list interface { 935 key "name"; 937 leaf name { 938 type string; 939 } 941 notification interface-enabled { 942 leaf by-user { 943 type string; 944 } 945 } 946 } 947 } 949 In this example, a CoOL client starts by registering to the default 950 event stream resource "/c/e". 952 CoAP request: 954 GET /c/e observe(0) Token(0x9372) 955 The CoOL server confirms this registration by returning a first CoAP 956 response. The payload of this CoAP response may be empty or may 957 carry the last notification reported by this server. 959 CoAP response: 961 2.05 Content Observe(52) Token(0xD937) 963 After detecting an event, the CoOL server sends its first 964 notification to the registered CoOL client. 966 CoAP response: 968 2.05 Content Observe(53) Token(0xD937) 969 Content-Format(application/cool-value-pairs+cbor) 970 [ 971 1011 , [1538, "eth0"], # _id (SID 1011) 972 +1,{ # content (SID 1012) 973 +1 : "bob" # by-user (SID 1539) 974 } 975 +5 , "2016-03-08T14:10:08Z09:00", # timestamp (SID 1016) 976 ] 978 To optimize communications or because of other constraints, the CoOL 979 server might transfer multiple notifications in a single CoAP 980 response. 982 CoAP response: 984 2.05 Content Observe(52) Token(0xD937) 985 Content-Format(application/cool-value-pairs+cbor) 986 [ 987 [ 988 1011 , [1538, "eth0"], # _id = interface-enabled (SID 1011) 989 +1,{ # content (SID 1012) 990 +1 : "jack" # by-user (SID 1539) 991 } 992 +5 , "2016-03-12T15:49:51Z09:00", # timestamp (SID 1016) 993 ], 994 [ 995 +1011 , 1942, # _id = link-failure (SID 1011) 996 +1,{ # content (SID 1011) 997 +1 : "eth0", # if-name (SID 1943) 998 +1 : 1 # admin-status = up (SID 1944) 999 } 1000 +5 , "2016-03-12T15:50:06Z09:00", # timestamp (SID 1016) 1001 ] 1002 ] 1004 6. Uri-Query 1006 6.1. The 'a' Query Parameter 1008 When performing a GET, the normal behaviour of a CoOL server is to 1009 exclude from the GET response, data nodes currently set to their 1010 default values as defined by the YANG 'default' statement. This 1011 behaviour called 'trim' is defined in [RFC6243] section 3.2. 1013 This rule also applies to the FETCH for containers and list instances 1014 but not for the root data nodes. To minimize the payload size of the 1015 FETCH responses, root data nodes are returned in a CBOR array without 1016 associated SID. To keep the symmetry between the FETCH request and 1017 the FETCH response, a CBOR content must be returned for each data 1018 node requested as follows: 1020 o a CBOR simple type 'default' is returned for each data node 1021 currently set to its default value 1023 o a CBOR simple type 'undefined value' is returned for each data 1024 node not instantiated or not supported 1026 o otherwise, the value is encoded based on the rules defined in 1027 [I-D.ietf-core-yang-cbor] 1029 There are use-cases when a CoOL client will need the default data 1030 from the server, for example: 1032 o The management application often needs a single, definitive, and 1033 complete set of configuration values that determine how the 1034 networking device works. 1036 o Documentation about default values can be unreliable or 1037 unavailable. 1039 o Some management applications might not have the capabilities to 1040 correctly parse and interpret formal data models. 1042 o Human users might want to understand the received data without 1043 consultation of the documentation. 1045 In all these cases, the CoOL client will need a mechanism to retrieve 1046 default data from a CoOL server. 1048 This is accomplished by including the 'a' Uri-Query parameter in the 1049 GET or FETCH request. This behaviour called 'report-all' is defined 1050 in [RFC6243] section 3.1. 1052 7. CoAP compatibility 1054 7.1. Working with Uri-Host, Uri-Port, Uri-Path, and Uri-Query 1056 Supported Uri-Query parameters are defined in Section 6. Uri-Host, 1057 Uri-Port and Uri-Path MUST be used as specified by [RFC6690] to 1058 target the CoOL resources as defined by section 3. 1060 7.2. Working with Location-Path and Location-Query 1062 This version of CoOL doesn't support the creation of resources 1063 (datastore or event stream). For this reason, the use of Location- 1064 Path and Location-Query is not required. 1066 7.3. Working with Accept 1068 This option is not required since this protocol don't support 1069 multiple choices of Content-Format. 1071 7.4. Working with Max-Age 1073 This option MUST be supported as specified by [RFC6690]. 1075 7.5. Working with Proxy-Uri and Proxy-Scheme 1077 This option MUST be supported as specified by [RFC6690]. 1079 7.6. Working with If-Match, If-None-Match and ETag 1081 This option MUST be supported as specified by [RFC6690]. Each ETag 1082 is associated to all schema nodes within a datastore. 1084 7.7. Working with Size1, Size2, Block1 and Block2 1086 When the UDP transport is used and a large payload need to be 1087 transferred, support of the CoAP block transfer as defined by 1088 [I-D.ietf-core-block] is recommended. 1090 7.8. Working with Observe 1092 A CoOL server MAY support state change notifications to some or all 1093 its leaf data nodes. When supported the CoOL server MUST implement 1094 the Server-Side requirements defined in [RFC7641] section 3 and the 1095 CoOL client MUST implement the Client-Side requirements defined in 1096 [RFC7641] section 4. 1098 To start observing a leaf data node, a CoOL client MUST send a CoAP 1099 FETCH with the Observe CoAP option set to 0. 1101 The payload of the FETCH request carries a CBOR array of instance- 1102 identifier. The first entry MUST be set to the 'instance-identifier' 1103 of the data node instance observed. The following entries are 1104 optional and allow the selection of coincidental values, data nodes 1105 reported at the same time as the observed data node. Coincidental 1106 values are included in each notification reported, but changes to 1107 these extra data nodes MUST not trigger notification messages. 1109 A subscription can be terminated by the CoOL client by returning a 1110 CoAP Reset message or by sending a GET request with an Observe CoAP 1111 option set to deregister (1). More details are available in 1112 [RFC7641]. 1114 Example: 1116 In this example, a CoOL client subscribes to state changes of the 1117 data node "/system/ntp/enabled" (SID = 1751) and requests that data 1118 node "/system/hostname" (SID 1748) is reported as coincidental value. 1120 A first response is immediately returned by the CoOL server to 1121 confirm the subscription and to report the current values of the 1122 requested data nodes. 1124 Subsequent responses are returned by the CoOL server each time the 1125 state of data node "/system/ntp/enabled" changes. 1127 CoAP request: 1129 FETCH /c Content-Format(application/cool-instance-id-list+cbor) Observe(0) 1130 [ [1751, "tic.nrc.ca"], -3 ] 1132 CoAP response: 1134 2.05 Content Content-Format(application/cool-value-pairs+cbor) Observe(2631) 1135 [ 1136 false, # enabled (SID 1751) 1137 "tic" # hostname (SID 1748) 1138 ] 1140 CoAP response: 1142 2.05 Content Content-Format(application/cool-value-pairs+cbor) Observe(2632) 1143 [ 1144 true, # enabled (SID 1751) 1145 "tic" # hostname (SID 1748) 1146 ] 1147 7.9. Working with resource discovery 1149 The "/.well-known/core" resource is used by CoOL clients to discover 1150 resources implemented by CoOL servers. Each CoOL server MUST have an 1151 entry in the "/.well-known/core" resource for each datastore resource 1152 and event stream resource supported. 1154 Resource discovery can be performed using a CoAP GET request. If 1155 successful, the CoAP response MUST have a response code set to 2.05 1156 (Content), a Content-Format set to "application/link-format", and a 1157 payload containing a list of web links. 1159 To enable discovery of specific resource types, the CoAP server MUST 1160 support the query string "rt". 1162 Link format and the "/.well-known/core" resource are defined in 1163 [RFC6690]. 1165 Example: 1167 CoAP request: 1169 GET /.well-known/core 1171 CoAP response: 1173 2.05 Content Content-Format(application/link-format) 1174 ;rt="cool.datastore", 1175 ;rt="cool.datastore", 1176 ;rt="cool.datastore", 1177 ;rt="cool.event-stream", 1179 In this example, a CoOL client retrieves the list of all resources 1180 available on a CoOL server. 1182 Alternatively, the CoOL client may query for a specific resource 1183 type. In this example, the CoOL client queries for resource type 1184 (rt) "cool.datastore". 1186 CoAP request: 1188 GET /.well-known/core?rt=cool.datastore 1190 CoAP response: 1192 2.05 Content Content-Format(application/link-format) 1193 ;rt="cool.datastore", 1195 8. Error Handling 1197 All CoAP response codes defined by [RFC7252] MUST be accepted and 1198 processed accordingly by CoOL clients. Optionally, client errors 1199 (CoAP response codes 4.xx) or server errors (CoAP response codes 1200 5.xx) MAY have a payload providing further information about the 1201 cause of the error. This payload contains the "error-payload" 1202 container (SID 1007) defined in the "ietf-cool" YANG module, see 1203 Appendix A. 1205 Example: 1207 CoAP response: 1209 4.00 Bad Request (Content-Format: application/cool-value-pairs+cbor) 1210 [ 1211 1007 , { # error-payload (SID 1007) 1212 +1 : 2, # error-code (SID 1008) 1213 +2 : "Unknown data node 69687" # error-text (SID 1009) 1214 } 1215 ] 1217 9. Security Considerations 1219 This application protocol relies on the lower layers to provide 1220 confidentiality, integrity, and availability. A typical approach to 1221 archive these requirements is to implement CoAP using the DTLS 1222 binding as defined in [RFC7252] section 9. Other approaches are 1223 possible to fulfill these requirements, such as the use of a network 1224 layer security mechanism as discussed in 1225 [I-D.bormann-core-ipsec-for-coap] or a link layer security mechanism 1226 for exchanges done within a single sub-network. 1228 In some applications, different access rights to objects (data nodes, 1229 protocol operations and notifications) need to be granted to 1230 different CoOL clients. Different solutions are possible, such as 1231 the implementation of Access Control Lists (ACL) using YANG module(s) 1232 or the use of an authorization certificate as defined in [RFC5755]. 1233 These access control mechanisms need to be addressed in complementary 1234 specifications. 1236 The Security Considerations section of CoAP [RFC7252] is especially 1237 relevant to this application protocol and should be reviewed 1238 carefully by implementers. 1240 10. IANA Considerations 1242 10.1. CoAP Content-Formats 1244 This draft introduces the following CoAP Content-Formats. These 1245 entries need to be registered in the CoAP Content-Formats Registry as 1246 defined in [RFC7252] section 12.3. 1248 First entry: 1250 o Media type = application/cool-instance-id-list 1252 o Encoding = CBOR 1254 o ID = 61 1256 o Reference = RFC XXXX 1258 Second entry: 1260 o Media type = application/cool-value 1262 o Encoding = CBOR 1264 o ID = 62 1266 o Reference = RFC XXXX 1268 Third entry: 1270 o Media type = application/cool-value-list 1272 o Encoding = CBOR 1274 o ID = 63 1276 o Reference = RFC XXXX 1278 Fourth entry: 1280 o Media type = application/cool-value-pairs+cbor 1282 o Encoding = CBOR 1284 o ID = 64 1286 o Reference = RFC XXXX 1287 RFC Ed.: update XXXX to the RFC number assigned to this draft, update 1288 the ID if different than the one allocated, remove this note. 1290 TO DO If this set of Content-Formats is accepted, requirements and 1291 description need to be added where appropriate. 1293 10.2. CBOR simple value 1295 This draft introduces the following CBOR simple value. This entry 1296 needs to be registered in the Simple Values Registry as defined in 1297 [RFC7049] section 7.1. 1299 o Value = 19 1301 o Semantics = Default value 1303 o Reference = RFC XXXX 1305 RFC Ed.: update XXXX to the RFC number assigned to this draft, update 1306 the value if different than the one allocated, remove this note. 1308 11. Acknowledgments 1310 This document have been largely inspired by the extensive works done 1311 by Andy Bierman and Peter van der Stok on [I-D.vanderstok-core-comi]. 1312 [I-D.ietf-netconf-restconf] have also been a critical input to this 1313 work. The authors would like to thank the authors and contributors 1314 to these two drafts. 1316 The authors would also like to thank Carsten Bormann for his help 1317 during the development of this document and his useful comments 1318 during the review process. 1320 12. References 1322 12.1. Normative References 1324 [I-D.ietf-core-block] 1325 Bormann, C. and Z. Shelby, "Block-wise transfers in CoAP", 1326 draft-ietf-core-block-21 (work in progress), July 2016. 1328 [I-D.ietf-netmod-rfc6020bis] 1329 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1330 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 1331 2016. 1333 [I-D.vanderstok-core-etch] 1334 Stok, P., Bormann, C., and A. Sehgal, "Patch and Fetch 1335 Methods for Constrained Application Protocol (CoAP)", 1336 draft-vanderstok-core-etch-00 (work in progress), March 1337 2016. 1339 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1340 Requirement Levels", BCP 14, RFC 2119, 1341 DOI 10.17487/RFC2119, March 1997, 1342 . 1344 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1345 the Network Configuration Protocol (NETCONF)", RFC 6020, 1346 DOI 10.17487/RFC6020, October 2010, 1347 . 1349 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 1350 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 1351 . 1353 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 1354 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 1355 . 1357 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1358 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1359 October 2013, . 1361 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 1362 Application Protocol (CoAP)", RFC 7252, 1363 DOI 10.17487/RFC7252, June 2014, 1364 . 1366 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1367 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1368 2014, . 1370 [RFC7641] Hartke, K., "Observing Resources in the Constrained 1371 Application Protocol (CoAP)", RFC 7641, 1372 DOI 10.17487/RFC7641, September 2015, 1373 . 1375 12.2. Informative References 1377 [I-D.bormann-core-ipsec-for-coap] 1378 Bormann, C., "Using CoAP with IPsec", draft-bormann-core- 1379 ipsec-for-coap-00 (work in progress), December 2012. 1381 [I-D.ersue-constrained-mgmt] 1382 Ersue, M., Romascanu, D., and J. Schoenwaelder, 1383 "Management of Networks with Constrained Devices: Problem 1384 Statement, Use Cases and Requirements", draft-ersue- 1385 constrained-mgmt-03 (work in progress), February 2013. 1387 [I-D.ietf-core-coap-tcp-tls] 1388 Bormann, C., Lemay, S., Tschofenig, H., Hartke, K., 1389 Silverajan, B., and B. Raymor, "CoAP (Constrained 1390 Application Protocol) over TCP, TLS, and WebSockets", 1391 draft-ietf-core-coap-tcp-tls-03 (work in progress), July 1392 2016. 1394 [I-D.ietf-core-yang-cbor] 1395 Veillette, M., Pelov, A., Somaraju, A., Turner, R., and A. 1396 Minaburo, "CBOR Encoding of Data Modeled with YANG", 1397 draft-ietf-core-yang-cbor-02 (work in progress), July 1398 2016. 1400 [I-D.ietf-netconf-restconf] 1401 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1402 Protocol", draft-ietf-netconf-restconf-15 (work in 1403 progress), July 2016. 1405 [I-D.somaraju-core-sid] 1406 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1407 Minaburo, "Structure Identifier (SID)", draft-somaraju- 1408 core-sid-01 (work in progress), July 2016. 1410 [I-D.vanderstok-core-comi] 1411 Stok, P. and A. Bierman, "CoAP Management Interface", 1412 draft-vanderstok-core-comi-09 (work in progress), March 1413 2016. 1415 [RFC5755] Farrell, S., Housley, R., and S. Turner, "An Internet 1416 Attribute Certificate Profile for Authorization", 1417 RFC 5755, DOI 10.17487/RFC5755, January 2010, 1418 . 1420 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1421 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1422 . 1424 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1425 Constrained-Node Networks", RFC 7228, 1426 DOI 10.17487/RFC7228, May 2014, 1427 . 1429 Appendix A. File "ietf-cool.yang" 1431 Module containing the different definitions required by the CoOL 1432 protocol. 1434 file "ietf-cool@2016-01-01.yang" 1435 module ietf-cool { 1436 yang-version 1.1; 1437 namespace "urn:ietf:params:xml:ns:yang:ietf-cool"; 1438 prefix cool; 1440 organization 1441 "IETF Core Working Group"; 1443 contact 1444 "Ana Minaburo 1445 1447 Abhinav Somaraju 1448 1450 Alexander Pelov 1451 1453 Michel Veillette 1454 1456 Randy Turner 1457 "; 1459 description 1460 "This module contains the different definitions required 1461 by the CoOL protocol."; 1463 revision 2016-01-01 { 1464 description 1465 "Initial revision."; 1466 reference 1467 "draft-veillette-core-cool"; 1468 } 1470 // List of useful derived YANG data types for constrained devices 1472 typedef sid { 1473 type uint32; 1474 description 1475 "Structure Identifier value (SID)."; 1476 } 1477 typedef utc-time { 1478 type uint32; 1479 description 1480 "Unsigned 32-bit value representing the number of seconds 1481 since 0 hours, 0 minutes, 0 seconds, on the 1st of January, 1482 2000 UTC (Universal Coordinated Time)."; 1483 } 1485 // Error payload 1487 container error-payload { 1488 presence "Defines the format of an error paylaod."; 1489 description 1490 "Optional payload of a client error (CoAP response 4.xx) 1491 or server error (CoAP response 5.xx)."; 1493 leaf error-code { 1494 type enumeration { 1495 enum error { 1496 value 1; 1497 description "Unspecified error."; 1498 } 1500 enum malformed { 1501 value 2; 1502 description "Malformed CBOR payload."; 1503 } 1505 enum invalid { 1506 value 3; 1507 description "The value specified in the request can't be 1508 apply to the target data node."; 1509 } 1511 enum doesNotExist { 1512 value 4; 1513 description "The target data node instance specified in 1514 the request doesn't exist."; 1515 } 1517 enum alreadyExist { 1518 value 5; 1519 description "The target data node instance specified in 1520 the request already exists."; 1521 } 1523 enum readOnly { 1524 value 6; 1525 description "Attempt to update a read-only data node."; 1526 } 1527 } 1528 mandatory true; 1529 description 1530 "Error code."; 1531 } 1533 leaf error-text { 1534 type string; 1535 description "Textual descriptions of the error."; 1536 } 1537 } 1539 // Notification payload 1541 identity facility-type { 1542 description 1543 "A facility code is used to specify the type of process that 1544 is logging the message. Notifications from different facilities 1545 may be handled differently. Other YANG module may add new 1546 facility type as needed."; 1547 } 1549 identity os { 1550 base facility-type; 1551 description 1552 "Notification generated by the operating system."; 1553 } 1555 identity protocol-stack { 1556 base facility-type; 1557 description 1558 "Notification generated by one of the layers of the IP protocol stack."; 1559 } 1561 identity security { 1562 base facility-type; 1563 description 1564 "Security related notification."; 1565 } 1567 identity hardware-monitoring { 1568 base facility-type; 1569 description 1570 "Hardware related notification."; 1571 } 1572 identity application { 1573 base facility-type; 1574 description 1575 "Notification generated by an application process."; 1576 } 1578 container notification-payload { 1579 presence "Defines the format of a notification paylaod."; 1580 description 1581 "Definition of the payload of a notification transfered using CoOL."; 1583 leaf _id { 1584 type instance-identifier; 1585 mandatory true; 1586 description 1587 "Identifier associated to the notification reported."; 1588 } 1590 leaf timestamp { 1591 type utc-time; 1592 description 1593 "Event timestamp. Support of this field is optional 1594 since its not expected that all implementations have 1595 implement a real time clock and if so, this clock is 1596 available at all time."; 1597 } 1599 leaf sequence-number { 1600 type uint32; 1601 description 1602 "Sequence number associated to each event created by CoOL 1603 server within a specific event stream."; 1604 } 1606 leaf severity-level { 1607 type enumeration { 1608 enum emergency { 1609 value 0; 1610 description 1611 "System is unusable."; 1612 } 1613 enum alert { 1614 value 1; 1615 description 1616 "Should be corrected immediately."; 1617 } 1618 enum critical { 1619 value 2; 1620 description 1621 "Critical conditions."; 1622 } 1623 enum error { 1624 value 3; 1625 description 1626 "Error conditions."; 1627 } 1628 enum warning { 1629 value 4; 1630 description 1631 "May indicate that an error will occur if action is 1632 not taken."; 1633 } 1634 enum notice { 1635 value 5; 1636 description 1637 "Events that are unusual, but not error conditions."; 1638 } 1639 enum informational { 1640 value 6; 1641 description 1642 "Normal operational messages that require no action."; 1643 } 1644 enum debug { 1645 value 7; 1646 description 1647 "Information useful to developers for debugging the 1648 application."; 1649 } 1650 } 1651 description 1652 "Severity associated with this event."; 1653 reference "RFC 5424"; 1654 } 1656 leaf facility { 1657 type identityref { 1658 base facility-type; 1659 } 1660 description 1661 "Type of process that is logging the message."; 1662 reference "RFC 5424"; 1663 } 1665 anydata content { 1666 description 1667 "Notification container as defined by the notification YANG 1668 statement."; 1669 } 1670 } 1672 rpc commit { 1673 description 1674 "Used to commit the changes present in a candidate datastore on 1675 the runtime datastore specify by the URI used to execute this 1676 operation."; 1677 input { 1678 leaf datastore { 1679 type string; 1680 description 1681 "Path of the datastore resource used as the source of the 1682 commit operation. When not present, the default candidate 1683 datastore resource is used."; 1684 } 1686 leaf commit-date-time { 1687 type utc-time; 1688 description 1689 "When specified, the commit operation is postponed at the 1690 specified date and time. When not present, the commit is 1691 performed on reception of this RPC. Supports of this feature 1692 is optional."; 1693 } 1695 leaf confirm-timeout { 1696 type string; 1697 description 1698 "When present, a confirming commit MUST be received within 1699 this period after the start of the commit process. 1700 A confirming commit is a commit RPC without the 1701 confirm-timeout field presents. Supports of this feature 1702 is optional."; 1703 } 1704 } 1705 } 1707 rpc cancel-commit { 1708 description 1709 "Cancels an ongoing scheduled or confirmed commit."; 1710 } 1711 } 1712 1713 Appendix B. File "ietf-cool@2016-01-01.sid" 1715 Following is the ".sid" file generated for the "ietf-cool" YANG 1716 module. See [I-D.somaraju-core-sid] for more details on SID and 1717 ".sid" file. 1719 { 1720 "assignment-ranges": [ 1721 { 1722 "entry-point": 1000, 1723 "size": 100 1724 } 1725 ], 1726 "module-name": "ietf-cool", 1727 "module-revision": "2016-01-01", 1728 "items": [ 1729 { 1730 "type": "Module", 1731 "label": "ietf-cool", 1732 "sid": 1000 1733 }, 1734 { 1735 "type": "identity", 1736 "label": "/facility-type", 1737 "sid": 1001 1738 }, 1739 { 1740 "type": "identity", 1741 "label": "/facility-type/application", 1742 "sid": 1002 1743 }, 1744 { 1745 "type": "identity", 1746 "label": "/facility-type/hardware-monitoring", 1747 "sid": 1003 1748 }, 1749 { 1750 "type": "identity", 1751 "label": "/facility-type/os", 1752 "sid": 1004 1753 }, 1754 { 1755 "type": "identity", 1756 "label": "/facility-type/protocol-stack", 1757 "sid": 1005 1758 }, 1759 { 1760 "type": "identity", 1761 "label": "/facility-type/security", 1762 "sid": 1006 1763 }, 1764 { 1765 "type": "node", 1766 "label": "/error-payload", 1767 "sid": 1007 1768 }, 1769 { 1770 "type": "node", 1771 "label": "/error-payload/error-code", 1772 "sid": 1008 1773 }, 1774 { 1775 "type": "node", 1776 "label": "/error-payload/error-text", 1777 "sid": 1009 1778 }, 1779 { 1780 "type": "node", 1781 "label": "/notification-payload", 1782 "sid": 1010 1783 }, 1784 { 1785 "type": "node", 1786 "label": "/notification-payload/_id", 1787 "sid": 1011 1788 }, 1789 { 1790 "type": "node", 1791 "label": "/notification-payload/content", 1792 "sid": 1012 1793 }, 1794 { 1795 "type": "node", 1796 "label": "/notification-payload/facility", 1797 "sid": 1013 1798 }, 1799 { 1800 "type": "node", 1801 "label": "/notification-payload/sequence-number", 1802 "sid": 1014 1803 }, 1804 { 1805 "type": "node", 1806 "label": "/notification-payload/severity-level", 1807 "sid": 1015 1808 }, 1809 { 1810 "type": "node", 1811 "label": "/notification-payload/timestamp", 1812 "sid": 1016 1813 }, 1814 { 1815 "type": "rpc", 1816 "label": "/cancel-commit", 1817 "sid": 1017 1818 }, 1819 { 1820 "type": "rpc", 1821 "label": "/commit", 1822 "sid": 1018 1823 }, 1824 { 1825 "type": "rpc", 1826 "label": "/commit/input/commit-date-time", 1827 "sid": 1019 1828 }, 1829 { 1830 "type": "rpc", 1831 "label": "/commit/input/confirm-timeout", 1832 "sid": 1020 1833 }, 1834 { 1835 "type": "rpc", 1836 "label": "/commit/input/datastore", 1837 "sid": 1021 1838 } 1839 ] 1840 } 1842 Authors' Addresses 1844 Michel Veillette (editor) 1845 Trilliant Networks Inc. 1846 610 Rue du Luxembourg 1847 Granby, Quebec J2J 2V2 1848 Canada 1850 Phone: +14503750556 1851 Email: michel.veillette@trilliantinc.com 1852 Alexander Pelov (editor) 1853 Acklio 1854 2bis rue de la Chataigneraie 1855 Cesson-Sevigne, Bretagne 35510 1856 France 1858 Email: a@ackl.io 1860 Abhinav Somaraju 1861 Tridonic GmbH & Co KG 1862 Farbergasse 15 1863 Dornbirn, Vorarlberg 6850 1864 Austria 1866 Phone: +43664808926169 1867 Email: abhinav.somaraju@tridonic.com 1869 Randy Turner 1870 Landis+Gyr 1871 30000 Mill Creek Ave 1872 Suite 100 1873 Alpharetta, GA 30022 1874 US 1876 Phone: ++16782581292 1877 Email: randy.turner@landisgyr.com 1878 URI: http://www.landisgyr.com/ 1880 Ana Minaburo 1881 Acklio 1882 2bis rue de la chataigneraie 1883 Cesson-Sevigne, Bretagne 35510 1884 France 1886 Email: ana@ackl.io