idnits 2.17.1 draft-ietf-core-yang-cbor-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC7049]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (February 07, 2017) is 2628 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) == Missing Reference: '-2' is mentioned on line 757, but not defined -- Looks like a reference, but probably isn't: '257' on line 757 == Missing Reference: '0-9' is mentioned on line 1023, but not defined == Missing Reference: '1-9' is mentioned on line 1014, but not defined == Missing Reference: '0-4' is mentioned on line 1023, but not defined == Missing Reference: '0-5' is mentioned on line 1023, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 1022, but not defined -- Looks like a reference, but probably isn't: '01' on line 1023 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-17) exists of draft-ietf-core-comi-00 == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-00 -- Obsolete informational reference (is this intentional?): RFC 7159 (Obsoleted by RFC 8259) -- Obsolete informational reference (is this intentional?): RFC 7223 (Obsoleted by RFC 8343) -- Obsolete informational reference (is this intentional?): RFC 7277 (Obsoleted by RFC 8344) Summary: 2 errors (**), 0 flaws (~~), 9 warnings (==), 6 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: Standards Track A. Pelov, Ed. 5 Expires: August 11, 2017 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 February 07, 2017 14 CBOR Encoding of Data Modeled with YANG 15 draft-ietf-core-yang-cbor-04 17 Abstract 19 This document defines encoding rules for serializing configuration 20 data, state data, RPC input and RPC output, Action input, Action 21 output and notifications defined within YANG modules using the 22 Concise Binary Object Representation (CBOR) [RFC7049]. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on August 11, 2017. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 60 2.1. YANG Schema Item iDentifier (SID) . . . . . . . . . . . . 4 61 2.2. CBOR diagnostic notation . . . . . . . . . . . . . . . . 5 62 3. Properties of the CBOR Encoding . . . . . . . . . . . . . . . 6 63 4. Encoding of YANG Data Node Instances . . . . . . . . . . . . 7 64 4.1. The 'leaf' Data Node . . . . . . . . . . . . . . . . . . 7 65 4.2. The 'container' Data Node . . . . . . . . . . . . . . . . 7 66 4.2.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 8 67 4.2.2. Member names as keys . . . . . . . . . . . . . . . . 9 68 4.3. The 'leaf-list' Data Node . . . . . . . . . . . . . . . . 10 69 4.4. The 'list' Data Node . . . . . . . . . . . . . . . . . . 10 70 4.4.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 10 71 4.4.2. Member names as keys . . . . . . . . . . . . . . . . 13 72 4.5. The 'anydata' Data Node . . . . . . . . . . . . . . . . . 14 73 4.6. The 'anyxml' Data Node . . . . . . . . . . . . . . . . . 16 74 5. Representing YANG Data Types in CBOR . . . . . . . . . . . . 16 75 5.1. The unsigned integer Types . . . . . . . . . . . . . . . 16 76 5.2. The integer Types . . . . . . . . . . . . . . . . . . . . 17 77 5.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 17 78 5.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 17 79 5.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 18 80 5.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 18 81 5.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 19 82 5.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 20 83 5.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 20 84 5.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 21 85 5.10.1. SIDs as identityref . . . . . . . . . . . . . . . . 21 86 5.10.2. Name as identityref . . . . . . . . . . . . . . . . 22 87 5.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 22 88 5.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 23 89 5.13. The 'instance-identifier' Type . . . . . . . . . . . . . 24 90 5.13.1. SIDs as instance-identifier . . . . . . . . . . . . 24 91 5.13.2. Names as instance-identifier . . . . . . . . . . . . 27 92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 93 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 94 7.1. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 28 95 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 28 96 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 97 9.1. Normative References . . . . . . . . . . . . . . . . . . 29 98 9.2. Informative References . . . . . . . . . . . . . . . . . 29 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 101 1. Introduction 103 The specification of the YANG 1.1 data modelling language [RFC7950] 104 defines an XML encoding for data instances, i.e. contents of 105 configuration datastores, state data, RPC inputs and outputs, action 106 inputs and outputs, and event notifications. 108 A new set of encoding rules has been defined to allow the use of the 109 same data models in environments based on the JavaScript Object 110 Notation (JSON) Data Interchange Format [RFC7159]. This is 111 accomplished in the JSON Encoding of Data Modeled with YANG 112 specification [RFC7951]. 114 The aim of this document is to define a set of encoding rules for the 115 Concise Binary Object Representation (CBOR) [RFC7049]. The resulting 116 encoding is more compact compared to XML and JSON and more suitable 117 for Constrained Nodes and/or Constrained Networks as defined by 118 [RFC7228]. 120 2. Terminology and Notation 122 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 123 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 124 document are to be interpreted as described in [RFC2119]. 126 The following terms are defined in [RFC7950]: 128 o action 130 o anydata 132 o anyxml 134 o data node 136 o data tree 138 o feature 140 o identity 142 o module 144 o notification 145 o RPC 147 o schema node 149 o schema tree 151 o submodule 153 The following terms are defined in [RFC7951]: 155 o member name 157 o name of an identity 159 o namespace-qualified 161 This specification also makes use of the following terminology: 163 o child: A schema node defined within a collection such as a 164 container, a list, a case, a notification, an RPC input, an RPC 165 output, an action input, an action output. 167 o delta: Difference between the current SID and a reference SID. A 168 reference SID is defined for each context for which deltas are 169 used. 171 o item: A schema node, an identity, a module, a submodule or a 172 feature defined using the YANG modeling language. 174 o parent: The collection in which a schema node is defined. 176 o YANG Schema Item iDentifier (SID): Unsigned integer used to 177 identify different YANG items. 179 2.1. YANG Schema Item iDentifier (SID) 181 Some of the items defined in YANG [RFC7950] require the use of a 182 unique identifier. In both NETCONF [RFC6241] and RESTCONF [RFC8040], 183 these identifiers are implemented using names. To allow the 184 implementation of data models defined in YANG in constrained devices 185 and constrained networks, a more compact method to identify YANG 186 items is required. This compact identifier, called YANG Schema Item 187 iDentifier (SID), is encoded using an unsigned integer. The 188 following items are identified using SIDs: 190 o identities 192 o data nodes 193 o RPCs and associated input(s) and output(s) 195 o actions and associated input(s) and output(s) 197 o notifications and associated information 199 o YANG modules, submodules and features 201 To minimize its size, in certain positions, SIDs are represented 202 using a (signed) delta from a reference SID and the current SID. 203 Conversion from SIDs to deltas and back to SIDs are stateless 204 processes solely based on the data serialized or deserialized. 206 Mechanisms and processes used to assign SIDs to YANG items and to 207 guarantee their uniqueness is outside the scope of the present 208 specification. If SIDs are to be used, the present specification is 209 used in conjunction with a specification defining this management. 210 One example for such a specification is under development as 211 [I-D.ietf-core-sid]. 213 2.2. CBOR diagnostic notation 215 Within this document, CBOR binary contents are represented using an 216 equivalent textual form called CBOR diagnostic notation as defined in 217 [RFC7049] section 6. This notation is used strictly for 218 documentation purposes and is never used in the data serialization. 219 Table 1 below provides a summary of this notation. 221 +----------+------+--------------------------+-----------+----------+ 222 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 223 | content | type | | | encoding | 224 +----------+------+--------------------------+-----------+----------+ 225 | Unsigned | 0 | Decimal digits | 123 | 18 7b | 226 | integer | | | | | 227 | Negative | 1 | Decimal digits prefixed | -123 | 38 7a | 228 | integer | | by a minus sign | | | 229 | Byte | 2 | Hexadecimal value | h'f15c' | 42 f15c | 230 | string | | enclosed between single | | | 231 | | | quotes and prefixed by | | | 232 | | | an 'h' | | | 233 | Text | 3 | String of Unicode | "txt" | 63 | 234 | string | | characters enclosed | | 747874 | 235 | | | between double quotes | | | 236 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 237 | | | values within square | | | 238 | | | brackets | | | 239 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 240 | | | key : value pairs within | 2: 456 } | 01187b | 241 | | | curly braces | | 021901c8 | 242 | Boolean | 7/20 | false | false | f4 | 243 | | 7/21 | true | true | f5 | 244 | Null | 7/22 | null | null | f6 | 245 | Not | 7/23 | undefined | undefined | f7 | 246 | assigned | | | | | 247 +----------+------+--------------------------+-----------+----------+ 249 Table 1: CBOR diagnostic notation summary 251 The following extensions to the CBOR diagnostic notation are 252 supported: 254 o Any text within and including a pair of slashes is considered a 255 comment. 257 o Deltas are visualized as numbers preceded by a '+' or '-' sign. 258 The use of the '+' sign for positive deltas represents an 259 extension to the CBOR diagnostic notation as defined by [RFC7049] 260 section 6. 262 3. Properties of the CBOR Encoding 264 This document defines CBOR encoding rules for YANG schema trees and 265 their subtrees. 267 Basic schema nodes such as leaf, leaf-list, list, anydata and anyxml 268 can be encoded standalone. In this case, only the value of this 269 schema node is encoded in CBOR. Identification of this value needs 270 to be provided by some external means when required. 272 A collection such as container, list instance, notification, RPC 273 input, RPC output, action input and action output is serialized using 274 a CBOR map in which each child schema node is encoded using a key and 275 a value. This specification supports two type of CBOR keys; YANG 276 Schema Item iDentifier (SID) as defined in Section 2.1 and member 277 names as defined in [RFC7951]. Each of these key types is encoded 278 using a specific CBOR type which allows their interpretation during 279 the deserialization process. The end user of this mapping 280 specification (e.g. RESTCONF [RFC8040], CoMI [I-D.ietf-core-comi]) 281 can mandate the use of a specific key type. 283 In order to minimize the size of the encoded data, the proposed 284 mapping avoids any unnecessary meta-information beyond those natively 285 supported by CBOR. For instance, CBOR tags are used solely in the 286 case of anyxml data nodes and the union datatype to distinguish 287 explicitly the use of different YANG datatypes encoded using the same 288 CBOR major type. 290 4. Encoding of YANG Data Node Instances 292 Schema node instances defined using the YANG modeling language are 293 encoded using CBOR [RFC7049] based on the rules defined in this 294 section. We assume that the reader is already familiar with both 295 YANG [RFC7950] and CBOR [RFC7049]. 297 4.1. The 'leaf' Data Node 299 Leafs MUST be encoded based on the encoding rules specified in 300 Section 5. 302 4.2. The 'container' Data Node 304 Collections such as containers, list instances, notifications, RPC 305 inputs, RPC outputs, action inputs and action outputs MUST be encoded 306 using a CBOR map data item (major type 5). A map is comprised of 307 pairs of data items, with each data item consisting of a key and a 308 value. Each key within the CBOR map is set to a data node 309 identifier, each value is set to the value of this data node instance 310 according to the instance datatype. 312 This specification supports two type of CBOR keys; SID as defined in 313 Section 2.1 encoded as deltas and member names as defined in 314 [RFC7951] encoded using CBOR text strings. The use of CBOR byte 315 strings for keys is reserved for future extensions. 317 4.2.1. SIDs as keys 319 Keys implemented using SIDs MUST be encoded using a CBOR unsigned 320 integer (major type 0) or CBOR negative integer (major type 1), 321 depending on the actual value. Keys are represented as the delta of 322 the associated SID, delta values are computed as follows: 324 o The delta value is equal to the SID of the current schema node 325 minus the SID of the parent schema node. When no parent exists in 326 the context of use of this container, the delta is set to the SID 327 of the current schema node (i.e., a parent with SID equal to zero 328 is assumed). 330 o Delta values may result in a negative number, clients and servers 331 MUST support both unsigned and negative deltas. 333 The following example shows the encoding of a 'system' container 334 instance. 336 Definition example from [RFC7317]: 338 typedef date-and-time { 339 type string { 340 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 341 \d{2}:\d{2})'; 342 } 343 } 345 container clock { 346 leaf current-datetime { 347 type date-and-time; 348 } 350 leaf boot-datetime { 351 type date-and-time; 352 } 353 } 355 CBOR diagnostic notation: 357 { 358 1717 : { / clock (SID 1717) / 359 +2 : "2015-10-02T14:47:24Z-05:00", / current-datetime (SID 1719) / 360 +1 : "2015-09-15T09:12:58Z-05:00" / boot-datetime (SID 1718) / 361 } 362 } 364 CBOR encoding: 366 a1 # map(1) 367 19 06b5 # unsigned(1717) 368 a2 # map(2) 369 02 # unsigned(2) 370 78 1a # text(26) 371 323031352d31302d30325431343a34373a32345a2d30353a3030 372 01 # unsigned(1) 373 78 1a # text(26) 374 323031352d30392d31355430393a31323a35385a2d30353a3030 376 4.2.2. Member names as keys 378 Keys implemented using member names MUST be encoded using a CBOR text 379 string data item (major type 3). A namespace-qualified member name 380 MUST be used for all members of a top-level collection, and then also 381 whenever the namespaces of the schema node and its parent are 382 different. In all other cases, the simple form of the member name 383 MUST be used. Names and namespaces are defined in [RFC7951] section 384 4. 386 The following example shows the encoding of a 'system' container 387 instance using names. This example is described in Section 4.2.1. 389 CBOR diagnostic notation: 391 { 392 "ietf-system:clock" : { 393 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 394 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 395 } 396 } 398 CBOR encoding: 400 a1 # map(1) 401 71 # text(17) 402 696574662d73797374656d3a636c6f636b # "ietf-system:clock" 403 a2 # map(2) 404 70 # text(16) 405 63757272656e742d6461746574696d65 # "current-datetime" 406 78 1a # text(26) 407 323031352d31302d30325431343a34373a32345a2d30353a3030 408 6d # text(13) 409 626f6f742d6461746574696d65 # "boot-datetime" 410 78 1a # text(26) 411 323031352d30392d31355430393a31323a35385a2d30353a3030 413 4.3. The 'leaf-list' Data Node 415 A leaf-list MUST be encoded using a CBOR array data item (major type 416 4). Each entry of this array MUST be encoded using the rules defined 417 by the YANG type specified. 419 The following example shows the encoding a 'search' leaf-list 420 instance containing the two entries, "ietf.org" and "ieee.org". 422 Definition example [RFC7317]: 424 typedef domain-name { 425 type string { 426 length "1..253"; 427 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 428 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 429 )|\.'; 430 } 431 } 433 leaf-list search { 434 type domain-name; 435 ordered-by user; 436 } 438 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 440 CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267 442 4.4. The 'list' Data Node 444 A list MUST be encoded using a CBOR array data item (major type 4). 445 Each list instance within this CBOR array is encoded using a CBOR map 446 data item (major type 5) based on the same rules as a YANG container 447 as defined in Section 4.2. 449 4.4.1. SIDs as keys 451 The following example show the encoding of a 'server' list instance 452 using SIDs. It is important to note that the protocol or method 453 using this mapping may carry a parent SID or may have the knowledge 454 of this parent SID based on its context. In these cases, delta 455 encoding can be performed based on this parent SID which minimizes 456 the size of the encoded data. 458 Definition example from [RFC7317]: 460 list server { 461 key name; 463 leaf name { 464 type string; 465 } 466 choice transport { 467 case udp { 468 container udp { 469 leaf address { 470 type host; 471 mandatory true; 472 } 473 leaf port { 474 type port-number; 475 } 476 } 477 } 478 } 479 leaf association-type { 480 type enumeration { 481 enum server; 482 enum peer; 483 enum pool; 484 } 485 default server; 486 } 487 leaf iburst { 488 type boolean; 489 default false; 490 } 491 leaf prefer { 492 type boolean; 493 default false; 494 } 495 } 497 CBOR diagnostic notation: 499 [ 500 { 501 1755 : "NRC TIC server", / name (SID 1755) / 502 1757 : { / udp (SID 1757) / 503 +1 : "tic.nrc.ca", / address (SID 1758) / 504 +2 : 123 / port (SID 1759) / 505 }, 506 1753 : 0, / association-type (SID 1753) / 507 1754 : false, / iburst (SID 1754) / 508 1756 : true / prefer (SID 1756) / 509 }, 510 { 511 1755 : "NRC TAC server", / name (SID 1755) / 512 1757 : { / udp (SID 1757) / 513 +1 : "tac.nrc.ca" / address (SID 1758) / 514 } 515 } 516 ] 518 CBOR encoding: 520 82 # array(2) 521 a5 # map(5) 522 19 06db # unsigned(1755) 523 6e # text(14) 524 4e52432054494320736572766572 # "NRC TIC server" 525 19 06dd # unsigned(1757) 526 a2 # map(2) 527 01 # unsigned(1) 528 6a # text(10) 529 7469632e6e72632e6361 # "tic.nrc.ca" 530 02 # unsigned(2) 531 18 7b # unsigned(123) 532 19 06d9 # unsigned(1753) 533 00 # unsigned(0) 534 19 06da # unsigned(1754) 535 f4 # primitive(20) 536 19 06dc # unsigned(1756) 537 f5 # primitive(21) 538 a2 # map(2) 539 19 06db # unsigned(1755) 540 6e # text(14) 541 4e52432054414320736572766572 # "NRC TAC server" 542 19 06dd # unsigned(1757) 543 a1 # map(1) 544 01 # unsigned(1) 545 6a # text(10) 546 7461632e6e72632e6361 # "tac.nrc.ca" 548 4.4.2. Member names as keys 550 The following example shows the encoding of a 'server' list instance 551 using names. This example is described in Section 4.4.1. 553 CBOR diagnostic notation: 555 [ 556 { 557 "ietf-system:name" : "NRC TIC server", 558 "ietf-system:udp" : { 559 "address" : "tic.nrc.ca", 560 "port" : 123 561 }, 562 "ietf-system:association-type" : 0, 563 "ietf-system:iburst" : false, 564 "ietf-system:prefer" : true 565 }, 566 { 567 "ietf-system:name" : "NRC TAC server", 568 "ietf-system:udp" : { 569 "address" : "tac.nrc.ca" 570 } 571 } 572 ] 574 CBOR encoding: 576 82 # array(2) 577 a5 # map(5) 578 70 # text(16) 579 696574662d73797374656d3a6e616d65 # "ietf-system:name" 580 6e # text(14) 581 4e52432054494320736572766572 # "NRC TIC server" 582 6f # text(15) 583 696574662d73797374656d3a756470 # "ietf-system:udp" 584 a2 # map(2) 585 67 # text(7) 586 61646472657373 # "address" 587 6a # text(10) 588 7469632e6e72632e6361 # "tic.nrc.ca" 589 64 # text(4) 590 706f7274 # "port" 591 18 7b # unsigned(123) 592 78 1c # text(28) 593 696574662d73797374656d3a6173736f63696174696f6e2d74797065 594 00 # unsigned(0) 595 72 # text(18) 596 696574662d73797374656d3a696275727374 # "ietf-system:iburst" 597 f4 # primitive(20) 598 72 # text(18) 599 696574662d73797374656d3a707265666572 # "ietf-system:prefer" 600 f5 # primitive(21) 601 a2 # map(2) 602 70 # text(16) 603 696574662d73797374656d3a6e616d65 # "ietf-system:name" 604 6e # text(14) 605 4e52432054414320736572766572 # "NRC TAC server" 606 6f # text(15) 607 696574662d73797374656d3a756470 # "ietf-system:udp" 608 a1 # map(1) 609 67 # text(7) 610 61646472657373 # "address" 611 6a # text(10) 612 7461632e6e72632e6361 # "tac.nrc.ca" 614 4.5. The 'anydata' Data Node 616 An anydata serves as a container for an arbitrary set of schema nodes 617 that otherwise appear as normal YANG-modeled data. An anydata 618 instance is encoded using the same rules as a container, i.e., CBOR 619 map. The requirement that anydata content can be modeled by YANG 620 implies the following: 622 o Keys of any inner data nodes MUST be set to valid deltas or member 623 names. 625 o The CBOR array MUST contain either unique scalar values (as a 626 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 628 o Values MUST follow the encoding rules of one of the datatypes 629 listed in Section 5. 631 The following example shows a possible use of anydata. In this 632 example, an anydata is used to define a data node containing a 633 notification event, this data node can be part of a YANG list to 634 create an event logger. 636 Definition example: 638 anydata event; 640 This example also assumes the assistance of the following 641 notification. 643 module example-port { 644 ... 646 notification example-port-fault { # SID 2600 647 leaf port-name { # SID 2601 648 type string; 649 } 650 leaf port-fault { # SID 2601 651 type string; 652 } 653 } 654 } 656 CBOR diagnostic notation: 658 { 659 2601 : "0/4/21", / port-name / 660 2602 : "Open pin 2" / port-fault / 661 } 663 CBOR encoding: 665 a2 # map(2) 666 19 0a29 # unsigned(2601) 667 66 # text(6) 668 302f342f3231 # "0/4/21" 669 19 0a2a # unsigned(2602) 670 6a # text(10) 671 4f70656e2070696e2032 # "Open pin 2" 673 4.6. The 'anyxml' Data Node 675 An anyxml schema node is used to serialize an arbitrary CBOR content, 676 i.e., its value can be any CBOR binary object. anyxml value may 677 contain CBOR data items tagged with one of the tag listed in 678 Section 7.1, these tags shall be supported. 680 The following example shows a valid CBOR encoded instance. 682 Definition example from [RFC7951]: 684 anyxml bar; 686 CBOR diagnostic notation: [true, null, true] 688 CBOR encoding: 83 f5 f6 f5 690 5. Representing YANG Data Types in CBOR 692 The CBOR encoding of an instance of a leaf or leaf-list data node 693 depends on the built-in type of that data node. The following sub- 694 section defined the CBOR encoding of each built-in type supported by 695 YANG as listed in [RFC7950] section 4.2.4. Each subsection shows an 696 example value assigned to a data node instance of the discussed 697 built-in type. 699 5.1. The unsigned integer Types 701 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 702 a CBOR unsigned integer data item (major type 0). 704 The following example shows the encoding of a 'mtu' leaf instance set 705 to 1280 bytes. 707 Definition example from [RFC7277]: 709 leaf mtu { 710 type uint16 { 711 range "68..max"; 712 } 713 } 715 CBOR diagnostic notation: 1280 717 CBOR encoding: 19 0500 719 5.2. The integer Types 721 Leafs of type int8, int16, int32 and int64 MUST be encoded using 722 either CBOR unsigned integer (major type 0) or CBOR negative integer 723 (major type 1), depending on the actual value. 725 The following example shows the encoding of a 'timezone-utc-offset' 726 leaf instance set to -300 minutes. 728 Definition example from [RFC7317]: 730 leaf timezone-utc-offset { 731 type int16 { 732 range "-1500 .. 1500"; 733 } 734 } 736 CBOR diagnostic notation: -300 738 CBOR encoding: 39 012b 740 5.3. The 'decimal64' Type 742 Leafs of type decimal64 MUST be encoded using a decimal fraction as 743 defined in [RFC7049] section 2.4.3. 745 The following example shows the encoding of a 'my-decimal' leaf 746 instance set to 2.57. 748 Definition example from [RFC7317]: 750 leaf my-decimal { 751 type decimal64 { 752 fraction-digits 2; 753 range "1 .. 3.14 | 10 | 20..max"; 754 } 755 } 757 CBOR diagnostic notation: 4([-2, 257]) 759 CBOR encoding: c4 82 21 19 0101 761 5.4. The 'string' Type 763 Leafs of type string MUST be encoded using a CBOR text string data 764 item (major type 3). 766 The following example shows the encoding of a 'name' leaf instance 767 set to "eth0". 769 Definition example from [RFC7223]: 771 leaf name { 772 type string; 773 } 775 CBOR diagnostic notation: "eth0" 777 CBOR encoding: 64 65746830 779 5.5. The 'boolean' Type 781 Leafs of type boolean MUST be encoded using a CBOR true (major type 782 7, additional information 21) or false data item (major type 7, 783 additional information 20). 785 The following example shows the encoding of an 'enabled' leaf 786 instance set to 'true'. 788 Definition example from [RFC7317]: 790 leaf enabled { 791 type boolean; 792 } 794 CBOR diagnostic notation: true 796 CBOR encoding: f5 798 5.6. The 'enumeration' Type 800 Leafs of type enumeration MUST be encoded using a CBOR unsigned 801 integer (major type 0) or CBOR negative integer (major type 1), 802 depending on the actual value. Enumeration values are either 803 explicitly assigned using the YANG statement 'value' or automatically 804 assigned based on the algorithm defined in [RFC7950] section 9.6.4.2. 806 The following example shows the encoding of an 'oper-status' leaf 807 instance set to 'testing'. 809 Definition example from [RFC7317]: 811 leaf oper-status { 812 type enumeration { 813 enum up { value 1; } 814 enum down { value 2; } 815 enum testing { value 3; } 816 enum unknown { value 4; } 817 enum dormant { value 5; } 818 enum not-present { value 6; } 819 enum lower-layer-down { value 7; } 820 } 821 } 823 CBOR diagnostic notation: 3 825 CBOR encoding: 03 827 5.7. The 'bits' Type 829 Leafs of type bits MUST be encoded using a CBOR byte string data item 830 (major type 2). Bits position are either explicitly assigned using 831 the YANG statement 'position' or automatically assigned based on the 832 algorithm defined in [RFC7950] section 9.7.4.2. 834 Bits position 0 to 7 are assigned to the first byte within the byte 835 string, bits 8 to 15 to the second byte, and subsequent bytes are 836 assigned similarly. Within each byte, bits are assigned from least 837 to most significant. 839 The following example shows the encoding of a 'mybits' leaf instance 840 with the 'disable-nagle' and '10-Mb-only' flags set. 842 Definition example from [RFC7950]: 844 leaf mybits { 845 type bits { 846 bit disable-nagle { 847 position 0; 848 } 849 bit auto-sense-speed { 850 position 1; 851 } 852 bit 10-Mb-only { 853 position 2; 854 } 855 } 856 } 858 CBOR diagnostic notation: h'05' 859 CBOR encoding: 41 05 861 5.8. The 'binary' Type 863 Leafs of type binary MUST be encoded using a CBOR byte string data 864 item (major type 2). 866 The following example shows the encoding of an 'aes128-key' leaf 867 instance set to 0x1f1ce6a3f42660d888d92a4d8030476e. 869 Definition example: 871 leaf aes128-key { 872 type binary { 873 length 16; 874 } 875 } 877 CBOR diagnostic notation: h'1f1ce6a3f42660d888d92a4d8030476e' 879 CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e 881 5.9. The 'leafref' Type 883 Leafs of type leafref MUST be encoded using the rules of the schema 884 node referenced by the 'path' YANG statement. 886 The following example shows the encoding of an 'interface-state-ref' 887 leaf instance set to "eth1". 889 Definition example from [RFC7223]: 891 typedef interface-state-ref { 892 type leafref { 893 path "/interfaces-state/interface/name"; 894 } 895 } 897 container interfaces-state { 898 list interface { 899 key "name"; 900 leaf name { 901 type string; 902 } 903 leaf-list higher-layer-if { 904 type interface-state-ref; 905 } 906 } 907 } 909 CBOR diagnostic notation: "eth1" 911 CBOR encoding: 64 65746831 913 5.10. The 'identityref' Type 915 This specification supports two approaches for encoding identityref, 916 a YANG Schema Item iDentifier (SID) as defined in Section 2.1 or a 917 name as defined in [RFC7951] section 6.8. 919 5.10.1. SIDs as identityref 921 When schema nodes of type identityref are implemented using SIDs, 922 they MUST be encoded using a CBOR unsigned integer data item (major 923 type 0). (Note that no delta mechanism is employed for SIDs as 924 identityref.) 926 The following example shows the encoding of a 'type' leaf instance 927 set to the value 'iana-if-type:ethernetCsmacd' (SID 1180). 929 Definition example from [RFC7317]: 931 identity interface-type { 932 } 934 identity iana-interface-type { 935 base interface-type; 936 } 938 identity ethernetCsmacd { 939 base iana-interface-type; 940 } 942 leaf type { 943 type identityref { 944 base interface-type; 945 } 946 } 948 CBOR diagnostic notation: 1180 950 CBOR encoding: 19 049c 952 5.10.2. Name as identityref 954 Alternatively, an identityref may be encoded using a name as defined 955 in [RFC7951] section 6.8. When names are used, identityref MUST be 956 encoded using a CBOR text string data item (major type 3). If the 957 identity is defined in another module than the leaf node containing 958 the identityref value, the namespace-qualified form MUST be used. 959 Otherwise, both the simple and namespace-qualified forms are 960 permitted. Names and namespaces are defined in [RFC7951] section 4. 962 The following example shows the encoding of the identity 'iana-if- 963 type:ethernetCsmacd' using its name. This example is described in 964 Section 5.10.1. 966 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 968 CBOR encoding: 78 1b 969 69616e612d69662d747970653a65746865726e657443736d616364 971 5.11. The 'empty' Type 973 Leafs of type empty MUST be encoded using the CBOR null value (major 974 type 7, additional information 22). 976 The following example shows the encoding of a 'is-router' leaf 977 instance when present. 979 Definition example from [RFC7277]: 981 leaf is-router { 982 type empty; 983 } 985 CBOR diagnostic notation: null 987 CBOR encoding: f6 989 5.12. The 'union' Type 991 Leafs of type union MUST be encoded using the rules associated with 992 one of the types listed. When used in a union, the following YANG 993 datatypes are prefixed by CBOR tag to avoid confusion between 994 different YANG datatypes encoded using the same CBOR major type. 996 o bits 998 o enumeration 1000 o identityref 1002 o instance-identifier 1004 See Section 7.1 for more information about these CBOR tags. 1006 The following example shows the encoding of an 'ip-address' leaf 1007 instance when set to "2001:db8:a0b:12f0::1". 1009 Definition example from [RFC7317]: 1011 typedef ipv4-address { 1012 type string { 1013 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 1014 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 1015 \p{L}]+)?'; 1016 } 1017 } 1019 typedef ipv6-address { 1020 type string { 1021 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 1022 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 1023 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 1024 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1025 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1026 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1027 } 1028 } 1030 typedef ip-address { 1031 type union { 1032 type ipv4-address; 1033 type ipv6-address; 1034 } 1035 } 1037 leaf address { 1038 type inet:ip-address; 1039 } 1041 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1043 CBOR encoding: 74 323030313a6462383a6130623a313266303a3a31 1045 5.13. The 'instance-identifier' Type 1047 This specification supports two approaches for encoding an instance- 1048 identifier, one based on YANG Schema Item iDentifier (SID) as defined 1049 in Section 2.1 and one based on names as defined in [RFC7951] section 1050 6.11. 1052 5.13.1. SIDs as instance-identifier 1054 SIDs uniquely identify a data node. In the case of a single instance 1055 data node, a data node defined at the root of a YANG module or 1056 submodule or data nodes defined within a container, the SID is 1057 sufficient to identify this instance. 1059 In the case of a data node member of a YANG list, a SID is combined 1060 with the list key(s) to identify each instance within the YANG 1061 list(s). 1063 Single instance data nodes MUST be encoded using a CBOR unsigned 1064 integer data item (major type 0) and set to the targeted data node 1065 SID. 1067 Data nodes member of a YANG list MUST be encoded using a CBOR array 1068 data item (major type 4) containing the following entries: 1070 o The first entry MUST be encoded as a CBOR unsigned integer data 1071 item (major type 0) and set to the targeted data node SID. 1073 o The following entries MUST contain the value of each key required 1074 to identify the instance of the targeted data node. These keys 1075 MUST be ordered as defined in the 'key' YANG statement, starting 1076 from top level list, and follow by each of the subordinate 1077 list(s). 1079 *First example:* 1081 The following example shows the encoding of a leaf instance of type 1082 instance-identifier which identifies the data node "/system/contact" 1083 (SID 1737). 1085 Definition example from [RFC7317]: 1087 container system { 1089 leaf contact { 1090 type string; 1091 } 1093 leaf hostname { 1094 type inet:domain-name; 1095 } 1096 } 1098 CBOR diagnostic notation: 1737 1100 CBOR encoding: 19 06c9 1102 *Second example:* 1104 The following example shows the encoding of a leaf instance of type 1105 instance-identifier which identify the data node instance 1106 "/system/authentication/user/authorized-key/key-data" (SID 1730) for 1107 user name "bob" and authorized-key "admin". 1109 Definition example from [RFC7317]: 1111 list user { 1112 key name; 1114 leaf name { 1115 type string; 1116 } 1117 leaf password { 1118 type ianach:crypt-hash; 1119 } 1121 list authorized-key { 1122 key name; 1124 leaf name { 1125 type string; 1126 } 1127 leaf algorithm { 1128 type string; 1129 } 1130 leaf key-data { 1131 type binary; 1132 } 1133 } 1135 CBOR diagnostic notation: [1730, "bob", "admin"] 1137 CBOR encoding: 1139 83 # array(3) 1140 19 06c2 # unsigned(1730) 1141 63 # text(3) 1142 626f62 # "bob" 1143 65 # text(5) 1144 61646d696e # "admin" 1146 *Third example:* 1148 The following example shows the encoding of a leaf instance of type 1149 instance-identifier which identify the list instance 1150 "/system/authentication/user" (SID 1726) corresponding to the user 1151 name "jack". 1153 CBOR diagnostic notation: [1726, "jack"] 1154 CBOR encoding: 1156 82 # array(2) 1157 19 06be # unsigned(1726) 1158 64 # text(4) 1159 6a61636b # "jack" 1161 5.13.2. Names as instance-identifier 1163 The use of names as instance-identifier is defined in [RFC7951] 1164 section 6.11. The resulting xpath MUST be encoded using a CBOR text 1165 string data item (major type 3). 1167 *First example:* 1169 This example is described in Section 5.13.1. 1171 CBOR diagnostic notation: "/ietf-system:system/contact" 1173 CBOR encoding: 1175 78 1c 2f20696574662d73797374656d3a73797374656d2f636f6e74616374 1177 *Second example:* 1179 This example is described in Section 5.13.1. 1181 CBOR diagnostic notation: 1183 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1184 [name='admin']/key-data" 1186 CBOR encoding: 1188 78 59 1189 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1190 74696f6e2f757365725b6e616d653d27626f62275d2f617574686f72697a 1191 65642d6b65795b6e616d653d2761646d696e275d2f6b65792d64617461 1193 *Third example:* 1195 This example is described in Section 5.13.1. 1197 CBOR diagnostic notation: 1199 "/ietf-system:system/authentication/user[name='bob']" 1201 CBOR encoding: 1203 78 33 1204 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1205 74696f6e2f757365725b6e616d653d27626f62275d 1207 6. Security Considerations 1209 The security considerations of [RFC7049] and [RFC7950] apply. 1211 This document defines an alternative encoding for data modeled in the 1212 YANG data modeling language. As such, this encoding does not 1213 contribute any new security issues in addition of those identified 1214 for the specific protocol or context for which it is used. 1216 To minimize security risks, software on the receiving side SHOULD 1217 reject all messages that do not comply to the rules of this document 1218 and reply with an appropriate error message to the sender. 1220 7. IANA Considerations 1222 7.1. Tags Registry 1224 This specification requires the assignment of CBOR tags for the 1225 following YANG datatypes. These tags are added to the Tags Registry 1226 as defined in section 7.2 of [RFC7049]. 1228 +-----+---------------------+---------------------------+-----------+ 1229 | Tag | Data Item | Semantics | Reference | 1230 +-----+---------------------+---------------------------+-----------+ 1231 | 40 | bits | YANG bits datatype | RFC XXXX | 1232 | 41 | enumeration | YANG enumeration datatype | RFC XXXX | 1233 | 42 | identityref | YANG identityref datatype | RFC XXXX | 1234 | 43 | instance-identifier | YANG instance-identifier | RFC XXXX | 1235 | | | datatype | | 1236 +-----+---------------------+---------------------------+-----------+ 1238 // RFC Ed.: update Tag values using allocated tags if needed and 1239 remove this note // RFC Ed.: replace XXXX with RFC number and remove 1240 this note 1242 8. Acknowledgments 1244 This document has been largely inspired by the extensive works done 1245 by Andy Bierman and Peter van der Stok on [I-D.ietf-core-comi]. 1246 [RFC7951] has also been a critical input to this work. The authors 1247 would like to thank the authors and contributors to these two drafts. 1249 The authors would also like to acknowledge the review, feedback, and 1250 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1252 9. References 1254 9.1. Normative References 1256 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1257 Requirement Levels", BCP 14, RFC 2119, 1258 DOI 10.17487/RFC2119, March 1997, 1259 . 1261 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1262 and A. Bierman, Ed., "Network Configuration Protocol 1263 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1264 . 1266 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1267 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1268 October 2013, . 1270 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1271 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1272 . 1274 9.2. Informative References 1276 [I-D.ietf-core-comi] 1277 Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP 1278 Management Interface", draft-ietf-core-comi-00 (work in 1279 progress), January 2017. 1281 [I-D.ietf-core-sid] 1282 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1283 Minaburo, "YANG Schema Item iDentifier (SID)", draft-ietf- 1284 core-sid-00 (work in progress), October 2016. 1286 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1287 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1288 2014, . 1290 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1291 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1292 . 1294 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1295 Constrained-Node Networks", RFC 7228, 1296 DOI 10.17487/RFC7228, May 2014, 1297 . 1299 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1300 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1301 . 1303 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1304 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1305 2014, . 1307 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1308 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1309 . 1311 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1312 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1313 . 1315 Authors' Addresses 1317 Michel Veillette (editor) 1318 Trilliant Networks Inc. 1319 610 Rue du Luxembourg 1320 Granby, Quebec J2J 2V2 1321 Canada 1323 Phone: +14503750556 1324 Email: michel.veillette@trilliantinc.com 1326 Alexander Pelov (editor) 1327 Acklio 1328 2bis rue de la Chataigneraie 1329 Cesson-Sevigne, Bretagne 35510 1330 France 1332 Email: a@ackl.io 1334 Abhinav Somaraju 1335 Tridonic GmbH & Co KG 1336 Farbergasse 15 1337 Dornbirn, Vorarlberg 6850 1338 Austria 1340 Phone: +43664808926169 1341 Email: abhinav.somaraju@tridonic.com 1342 Randy Turner 1343 Landis+Gyr 1344 30000 Mill Creek Ave 1345 Suite 100 1346 Alpharetta, GA 30022 1347 US 1349 Phone: ++16782581292 1350 Email: randy.turner@landisgyr.com 1351 URI: http://www.landisgyr.com/ 1353 Ana Minaburo 1354 Acklio 1355 2bis rue de la chataigneraie 1356 Cesson-Sevigne, Bretagne 35510 1357 France 1359 Email: ana@ackl.io