idnits 2.17.1 draft-ietf-core-yang-cbor-03.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 (October 31, 2016) is 2733 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 670, but not defined -- Looks like a reference, but probably isn't: '257' on line 670 == Missing Reference: '0-9' is mentioned on line 938, but not defined == Missing Reference: '1-9' is mentioned on line 929, but not defined == Missing Reference: '0-4' is mentioned on line 938, but not defined == Missing Reference: '0-5' is mentioned on line 938, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 937, but not defined -- Looks like a reference, but probably isn't: '01' on line 938 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-24) exists of draft-ietf-core-sid-00 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-10 -- 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: May 4, 2017 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 October 31, 2016 14 CBOR Encoding of Data Modeled with YANG 15 draft-ietf-core-yang-cbor-03 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 May 4, 2017. 41 Copyright Notice 43 Copyright (c) 2016 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. CBOR diagnostic notation . . . . . . . . . . . . . . . . 4 61 3. Properties of the CBOR Encoding . . . . . . . . . . . . . . . 5 62 4. Encoding of YANG Data Node Instances . . . . . . . . . . . . 6 63 4.1. The 'leaf' Data Node . . . . . . . . . . . . . . . . . . 6 64 4.2. The 'container' Data Node . . . . . . . . . . . . . . . . 6 65 4.2.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 7 66 4.2.2. Member names as keys . . . . . . . . . . . . . . . . 8 67 4.3. The 'leaf-list' Data Node . . . . . . . . . . . . . . . . 9 68 4.4. The 'list' Data Node . . . . . . . . . . . . . . . . . . 9 69 4.4.1. SIDs as keys . . . . . . . . . . . . . . . . . . . . 10 70 4.4.2. Member names as keys . . . . . . . . . . . . . . . . 13 71 4.5. The 'anydata' Data Node . . . . . . . . . . . . . . . . . 14 72 4.6. The 'anyxml' Data Node . . . . . . . . . . . . . . . . . 15 73 5. Representing YANG Data Types in CBOR . . . . . . . . . . . . 15 74 5.1. The unsigned integer Types . . . . . . . . . . . . . . . 15 75 5.2. The integer Types . . . . . . . . . . . . . . . . . . . . 15 76 5.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 16 77 5.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 16 78 5.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 17 79 5.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 17 80 5.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 18 81 5.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 18 82 5.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 19 83 5.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 19 84 5.10.1. SIDs as identityref . . . . . . . . . . . . . . . . 20 85 5.10.2. Name as identityref . . . . . . . . . . . . . . . . 20 86 5.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 21 87 5.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 21 88 5.13. The 'instance-identifier' Type . . . . . . . . . . . . . 22 89 5.13.1. SIDs as instance-identifier . . . . . . . . . . . . 22 90 5.13.2. Names as instance-identifier . . . . . . . . . . . . 25 91 6. Security Considerations . . . . . . . . . . . . . . . . . . . 26 92 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 93 7.1. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 26 94 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26 95 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 96 9.1. Normative References . . . . . . . . . . . . . . . . . . 27 97 9.2. Informative References . . . . . . . . . . . . . . . . . 27 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 100 1. Introduction 102 The specification of the YANG 1.1 data modelling language [RFC7950] 103 defines an XML encoding for data instances, i.e. contents of 104 configuration datastores, state data, RPC inputs and outputs, action 105 inputs and outputs, and event notifications. 107 A new set of encoding rules has been defined to allow the use of the 108 same data models in environments based on the JavaScript Object 109 Notation (JSON) Data Interchange Format [RFC7159]. This is 110 accomplished in the JSON Encoding of Data Modeled with YANG 111 specification [RFC7951]. 113 The aim of this document is to define a set of encoding rules for the 114 Concise Binary Object Representation (CBOR) [RFC7049]. The resulting 115 encoding is more compact compared to XML and JSON and more suitable 116 for Constrained Nodes and/or Constrained Networks as defined by 117 [RFC7228]. 119 2. Terminology and Notation 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 The following terms are defined in [RFC7950]: 127 o action 129 o anydata 131 o anyxml 133 o data node 135 o data tree 137 o module 139 o notification 141 o RPC 143 o schema node 144 o schema tree 146 o submodule 148 The following terms are defined in [RFC7951]: 150 o member name 152 o name of an identity 154 o namespace-qualified 156 This specification also makes use of the following terminology: 158 o child: A schema node defined within a collection such as a 159 container, a list, a case, a notification, an RPC input, an RPC 160 output, an action input, an action output. 162 o delta : Difference between the SID assigned to the current schema 163 node and the SID assigned to the parent. 165 o parent: The collection in which a schema node is defined. 167 o structured identifier or SID: Unsigned integer used to identify 168 different YANG items. 170 2.1. CBOR diagnostic notation 172 Within this document, CBOR binary contents are represented using an 173 equivalent textual form called CBOR diagnostic notation as defined in 174 [RFC7049] section 6. This notation is used strictly for 175 documentation purposes and is never used in the data serialization. 176 Table 1 below provides a summary of this notation. 178 +----------+------+--------------------------+-----------+----------+ 179 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 180 | content | type | | | encoding | 181 +----------+------+--------------------------+-----------+----------+ 182 | Unsigned | 0 | Decimal digits | 123 | 18 7b | 183 | integer | | | | | 184 | Negative | 1 | Decimal digits prefixed | -123 | 38 7a | 185 | integer | | by a minus sign | | | 186 | Byte | 2 | Hexadecimal value | h'f15c' | 42 f15c | 187 | string | | enclosed between single | | | 188 | | | quotes and prefixed by | | | 189 | | | an 'h' | | | 190 | Text | 3 | String of Unicode | "txt" | 63 | 191 | string | | characters enclosed | | 747874 | 192 | | | between double quotes | | | 193 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 194 | | | values within square | | | 195 | | | brackets | | | 196 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 197 | | | key : value pairs within | 2: 456 } | 01187b | 198 | | | curly braces | | 021901c8 | 199 | Boolean | 7/20 | false | false | f4 | 200 | | 7/21 | true | true | f5 | 201 | Null | 7/22 | null | null | f6 | 202 | Not | 7/23 | undefined | undefined | f7 | 203 | assigned | | | | | 204 +----------+------+--------------------------+-----------+----------+ 206 Table 1: CBOR diagnostic notation summary 208 The following extensions to the CBOR diagnostic notation are 209 supported: 211 o Comments can be added to the end of each line. Any characters 212 after a Pound sign ('#') outside of a string, up to the end of the 213 line, are treated as a comment. 215 o Deltas are represented as numbers preceded by a '+' or '-' sign. 216 The use of the '+' sign for positive deltas represents an 217 extension to the CBOR diagnostic notation as defined by [RFC7049] 218 section 6. 220 3. Properties of the CBOR Encoding 222 This document defines CBOR encoding rules for YANG schema trees and 223 their subtrees. 225 Basic schema nodes such as leaf, leaf-list, list, anydata and anyxml 226 can be encoded standalone. In this case, only the value of this 227 schema node is encoded in CBOR. Identification of this value needs 228 to be provided by some external means when required. 230 A collection such as container, list instance, notification, RPC 231 input, RPC output, action input and action output is serialized using 232 a CBOR map in which each child schema node is encoded using a key and 233 a value. This specification supports two type of keys; SID as 234 defined in [I-D.ietf-core-sid] and member names as defined in 235 [RFC7951]. Each of these key type is encoded using a specific CBOR 236 type which allows their interpretation during the deserialization 237 process. The end user of this mapping specification (e.g. RESFCONF, 238 CoMI) can mandate the use of a specific key type. 240 In order to minimize the size of the encoded data, the proposed 241 mapping avoid any unnecessary meta-information beyond those natively 242 supported by CBOR. For instance, CBOR tags are used solely in the 243 case of the union datatype to distinguish explicitly the use of 244 different YANG datatypes encoded using the same CBOR major type. 246 It is expected that application entities generating and decoding CBOR 247 contents have enough knowledge about the information processed in 248 order to perform the expected task without the need of such extra 249 meta-information. 251 4. Encoding of YANG Data Node Instances 253 Schema node instances defined using the YANG modeling language are 254 encoded using CBOR [RFC7049] based on the rules defined in this 255 section. We assume that the reader is already familiar with both 256 YANG [RFC7950] and CBOR [RFC7049]. 258 4.1. The 'leaf' Data Node 260 Leafs MUST be encoded based on the encoding rules specified in 261 Section 5. 263 4.2. The 'container' Data Node 265 Collections such as containers, list instances, notifications, RPC 266 inputs, RPC outputs, action inputs and action outputs MUST be encoded 267 using a CBOR map data item (major type 5). A map is comprised of 268 pairs of data items, with each data item consisting of a key and a 269 value. Each key within the CBOR map is set to a data node 270 identifier, each value is set to the value of this data node 271 instance. 273 This specification supports two type of keys; SID as defined in 274 [I-D.ietf-core-sid] encoded using CBOR unsigned or signed integers 275 and member names as defined in [RFC7951] encoded using CBOR text 276 strings. The use of CBOR byte strings for keys is reserved for 277 future extensions. 279 4.2.1. SIDs as keys 281 Keys implemented using SIDs MUST be encoded using a CBOR unsigned 282 integer (major type 0) or CBOR signed integer (major type 1), 283 depending on the actual value. Keys are set to the delta of the 284 associated SID, delta values are computed as follows: 286 o The delta value is equal to the SID of the current schema node 287 minus the SID of the parent schema node. When no parent exists in 288 the context of use of this container, the delta is set to the SID 289 of the current schema node (a parent with SID equal to zero is 290 assumed). 292 o Delta values may result in a negative number, clients and servers 293 MUST support negative deltas. 295 The following example shows the encoding of the 'system' container 296 using the SIDs defined in [I-D.ietf-core-sid] Appendix C. 298 Definition example from [RFC7317]: 300 typedef date-and-time { 301 type string { 302 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 303 \d{2}:\d{2})'; 304 } 305 } 307 container system { 308 leaf hostname { 309 type inet:domain-name; 311 container clock { 312 leaf current-datetime { 313 type date-and-time; 314 } 316 leaf boot-datetime { 317 type date-and-time; 318 } 319 } 320 } 321 CBOR diagnostic notation: 323 { 324 1717 : { # clock (SID 1717) 325 +2 : "2015-10-02T14:47:24Z-05:00", # current-datetime (SID 1719) 326 +1 : "2015-09-15T09:12:58Z-05:00" # boot-datetime (SID 1718) 327 } 328 } 330 CBOR encoding: 332 a1 # map(1) 333 19 06b5 # unsigned(1717) 334 a2 # map(2) 335 02 # unsigned(2) 336 78 1a # text(26) 337 323031352d31302d30325431343a34373a32345a2d30353a3030 338 01 # unsigned(1) 339 78 1a # text(26) 340 323031352d30392d31355430393a31323a35385a2d30353a3030 342 4.2.2. Member names as keys 344 Keys implemented using member names MUST be encoded using a CBOR text 345 string data item (major type 3). A namespace-qualified member name 346 MUST be used for all members of a top-level collection, and then also 347 whenever the namespaces of the schema node and its parent are 348 different. In all other cases, the simple form of the member name 349 MUST be used. Names and namespaces are defined in [RFC7951] section 350 4. 352 The following example shows the encoding of the 'system' container 353 using names. This example is described in Section 4.2.1. 355 CBOR diagnostic notation: 357 { 358 "ietf-system:clock" : { 359 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 360 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 361 } 362 } 364 CBOR encoding: 366 a1 # map(1) 367 71 # text(17) 368 696574662d73797374656d3a636c6f636b # "ietf-system:clock" 369 a2 # map(2) 370 70 # text(16) 371 63757272656e742d6461746574696d65 # "current-datetime" 372 78 1a # text(26) 373 323031352d31302d30325431343a34373a32345a2d30353a3030 374 6d # text(13) 375 626f6f742d6461746574696d65 # "boot-datetime" 376 78 1a # text(26) 377 323031352d30392d31355430393a31323a35385a2d30353a3030 379 4.3. The 'leaf-list' Data Node 381 A leaf-list MUST be encoded using a CBOR array data item (major type 382 4). Each entry of this array MUST be encoded using the rules defined 383 by the YANG type specified. 385 The following example shows the encoding the 'search' leaf-list 386 containing the two entries, "ietf.org" and "ieee.org". 388 Definition example [RFC7317]: 390 typedef domain-name { 391 type string { 392 length "1..253"; 393 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 394 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 395 )|\.'; 396 } 397 } 399 leaf-list search { 400 type domain-name; 401 ordered-by user; 402 } 404 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 406 CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267 408 4.4. The 'list' Data Node 410 A list MUST be encoded using a CBOR array data item (major type 4). 411 Each list instance within this CBOR array is encoded using a CBOR map 412 data item (major type 5) based on the same rules as a YANG container 413 as defined in Section 4.2. 415 4.4.1. SIDs as keys 417 The follwoing example show the encoding a the 'server' list using the 418 SIDs defined in [I-D.ietf-core-sid] Appendix C. It is important to 419 note that the protocol or method using this mapping may carry a 420 parent SID or may have the knowledge of this parent SID based on its 421 context. In these cases, delta encoding can be performed based on 422 this parent SID which minimizes the size of the encoded data. 424 The following example shows the encoding of the 'server' list 425 containing two enties. SIDs used in this example are defined in 426 [I-D.ietf-core-sid] Appendix C. It is important to note that the 427 protocol or method using this mapping may carry a parent SID or may 428 have the knowledge of this parent SID based on its context. In these 429 cases, delta encoding can be performed based on this parent SID which 430 minimizes the size of the encoded data. 432 Definition example from [RFC7317]: 434 list server { 435 key name; 437 leaf name { 438 type string; 439 } 440 choice transport { 441 case udp { 442 container udp { 443 leaf address { 444 type host; 445 mandatory true; 446 } 447 leaf port { 448 type port-number; 449 } 450 } 451 } 452 } 453 leaf association-type { 454 type enumeration { 455 enum server; 456 enum peer; 457 enum pool; 458 } 459 default server; 460 } 461 leaf iburst { 462 type boolean; 463 default false; 464 } 465 leaf prefer { 466 type boolean; 467 default false; 468 } 469 } 471 CBOR diagnostic notation: 473 [ 474 { 475 1755 : "NRC TIC server", # name (SID 1755) 476 1757 : { # udp (SID 1757) 477 +1 : "tic.nrc.ca", # address (SID 1758) 478 +2 : 123 # port (SID 1759) 479 }, 480 1753 : 0, # association-type (SID 1753) 481 1754 : false, # iburst (SID 1754) 482 1756 : true # prefer (SID 1756) 483 }, 484 { 485 1755 : "NRC TAC server", # name (SID 1755) 486 1757 : { # udp (SID 1757) 487 +1 : "tac.nrc.ca" # address (SID 1758) 488 } 489 } 490 ] 492 CBOR encoding: 494 82 # array(2) 495 a5 # map(5) 496 19 06db # unsigned(1755) 497 6e # text(14) 498 4e52432054494320736572766572 # "NRC TIC server" 499 19 06dd # unsigned(1757) 500 a2 # map(2) 501 01 # unsigned(1) 502 6a # text(10) 503 7469632e6e72632e6361 # "tic.nrc.ca" 504 02 # unsigned(2) 505 18 7b # unsigned(123) 506 19 06d9 # unsigned(1753) 507 00 # unsigned(0) 508 19 06da # unsigned(1754) 509 f4 # primitive(20) 510 19 06dc # unsigned(1756) 511 f5 # primitive(21) 512 a2 # map(2) 513 19 06db # unsigned(1755) 514 6e # text(14) 515 4e52432054414320736572766572 # "NRC TAC server" 516 19 06dd # unsigned(1757) 517 a1 # map(1) 518 01 # unsigned(1) 519 6a # text(10) 520 7461632e6e72632e6361 # "tac.nrc.ca" 522 4.4.2. Member names as keys 524 The following example shows the encoding of the 'server' list using 525 names. This example is described in Section 4.4.1. 527 CBOR diagnostic notation: 529 [ 530 { 531 "ietf-system:name" : "NRC TIC server", 532 "ietf-system:udp" : { 533 "address" : "tic.nrc.ca", 534 "port" : 123 535 }, 536 "ietf-system:association-type" : 0, 537 "ietf-system:iburst" : false, 538 "ietf-system:prefer" : true 539 }, 540 { 541 "ietf-system:name" : "NRC TAC server", 542 "ietf-system:udp" : { 543 "address" : "tac.nrc.ca" 544 } 545 } 546 ] 548 CBOR encoding: 550 82 # array(2) 551 a5 # map(5) 552 70 # text(16) 553 696574662d73797374656d3a6e616d65 # "ietf-system:name" 554 6e # text(14) 555 4e52432054494320736572766572 # "NRC TIC server" 556 6f # text(15) 557 696574662d73797374656d3a756470 # "ietf-system:udp" 558 a2 # map(2) 559 67 # text(7) 560 61646472657373 # "address" 561 6a # text(10) 562 7469632e6e72632e6361 # "tic.nrc.ca" 563 64 # text(4) 564 706f7274 # "port" 565 18 7b # unsigned(123) 566 78 1c # text(28) 567 696574662d73797374656d3a6173736f63696174696f6e2d74797065 568 00 # unsigned(0) 569 72 # text(18) 570 696574662d73797374656d3a696275727374 # "ietf-system:iburst" 571 f4 # primitive(20) 572 72 # text(18) 573 696574662d73797374656d3a707265666572 # "ietf-system:prefer" 574 f5 # primitive(21) 575 a2 # map(2) 576 70 # text(16) 577 696574662d73797374656d3a6e616d65 # "ietf-system:name" 578 6e # text(14) 579 4e52432054414320736572766572 # "NRC TAC server" 580 6f # text(15) 581 696574662d73797374656d3a756470 # "ietf-system:udp" 582 a1 # map(1) 583 67 # text(7) 584 61646472657373 # "address" 585 6a # text(10) 586 7461632e6e72632e6361 # "tac.nrc.ca" 588 4.5. The 'anydata' Data Node 590 An anydata serves as a container for an arbitrary set of schema nodes 591 that otherwise appear as normal YANG-modeled data. An anydata 592 instance is encoded using the same rules as a container, i.e., CBOR 593 map. The requirement that anydata content can be modeled by YANG 594 implies the following: 596 o Keys of any inner data nodes MUST be set to valid deltas or member 597 names. 599 o The CBOR array MUST contain either unique scalar values (as a 600 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 602 o Values MUST follow the encoding rules of one of the datatypes 603 listed in Section 5. 605 4.6. The 'anyxml' Data Node 607 An anyxml schema node is used to serialize an arbitrary CBOR content, 608 i.e., its value can be any CBOR binary object. 610 5. Representing YANG Data Types in CBOR 612 5.1. The unsigned integer Types 614 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 615 a CBOR unsigned integer data item (major type 0). 617 The following example shows the encoding of leaf 'mtu' set to 1280 618 bytes. 620 Definition example from [RFC7277]: 622 leaf mtu { 623 type uint16 { 624 range "68..max"; 625 } 626 } 628 CBOR diagnostic notation: 1280 630 CBOR encoding: 19 0500 632 5.2. The integer Types 634 Leafs of type int8, int16, int32 and int64 MUST be encoded using 635 either CBOR unsigned integer (major type 0) or CBOR signed integer 636 (major type 1), depending on the actual value. 638 The following example shows the encoding of leaf 'timezone-utc- 639 offset' set to -300 minutes. 641 Definition example from [RFC7317]: 643 leaf timezone-utc-offset { 644 type int16 { 645 range "-1500 .. 1500"; 646 } 647 } 649 CBOR diagnostic notation: -300 651 CBOR encoding: 39 012b 653 5.3. The 'decimal64' Type 655 Leafs of type decimal64 MUST be encoded using a decimal fraction as 656 defined in [RFC7049] section 2.4.3. 658 The following example shows the encoding of leaf 'my-decimal' set to 659 2.57. 661 Definition example from [RFC7317]: 663 leaf my-decimal { 664 type decimal64 { 665 fraction-digits 2; 666 range "1 .. 3.14 | 10 | 20..max"; 667 } 668 } 670 CBOR diagnostic notation: 4([-2, 257]) 672 CBOR encoding: c4 82 21 19 0101 674 5.4. The 'string' Type 676 Leafs of type string MUST be encoded using a CBOR text string data 677 item (major type 3). 679 The following example shows the encoding of leaf 'name' set to 680 "eth0". 682 Definition example from [RFC7223]: 684 leaf name { 685 type string; 686 } 688 CBOR diagnostic notation: "eth0" 690 CBOR encoding: 64 65746830 692 5.5. The 'boolean' Type 694 Leafs of type boolean MUST be encoded using a CBOR true (major type 695 7, additional information 21) or false data item (major type 7, 696 additional information 20). 698 The following example shows the encoding of leaf 'enabled' set to 699 'true'. 701 Definition example from [RFC7317]: 703 leaf enabled { 704 type boolean; 705 } 707 CBOR diagnostic notation: true 709 CBOR encoding: f5 711 5.6. The 'enumeration' Type 713 Leafs of type enumeration MUST be encoded using a CBOR unsigned 714 integer (major type 0) or CBOR signed integer (major type 1), 715 depending on the actual value. Enumeration values are either 716 explicitly assigned using the YANG statement 'value' or automatically 717 assigned based on the algorithm defined in [RFC7950] section 9.6.4.2. 719 The following example shows the encoding of leaf 'oper-status' set to 720 'testing'. 722 Definition example from [RFC7317]: 724 leaf oper-status { 725 type enumeration { 726 enum up { value 1; } 727 enum down { value 2; } 728 enum testing { value 3; } 729 enum unknown { value 4; } 730 enum dormant { value 5; } 731 enum not-present { value 6; } 732 enum lower-layer-down { value 7; } 733 } 734 } 736 CBOR diagnostic notation: 3 738 CBOR encoding: 03 740 5.7. The 'bits' Type 742 Leafs of type bits MUST be encoded using a CBOR byte string data item 743 (major type 2). Bits position are either explicitly assigned using 744 the YANG statement 'position' or automatically assigned based on the 745 algorithm defined in [RFC7950] section 9.7.4.2. 747 Bits position 0 to 7 are assigned to the first byte within the byte 748 string, bits 8 to 15 to the second byte, and subsequent bytes are 749 assigned similarly. Within each byte, bits are assigned from least 750 to most significant. 752 The following example shows the encoding of leaf 'mybits' with the 753 'disable-nagle' and '10-Mb-only' flags set. 755 Definition example from [RFC7950]: 757 leaf mybits { 758 type bits { 759 bit disable-nagle { 760 position 0; 761 } 762 bit auto-sense-speed { 763 position 1; 764 } 765 bit 10-Mb-only { 766 position 2; 767 } 768 } 769 } 771 CBOR diagnostic notation: h'05' 773 CBOR encoding: 41 05 775 5.8. The 'binary' Type 777 Leafs of type binary MUST be encoded using a CBOR byte string data 778 item (major type 2). 780 The following example shows the encoding of leaf 'aes128-key' set to 781 0x1f1ce6a3f42660d888d92a4d8030476e. 783 Definition example: 785 leaf aes128-key { 786 type binary { 787 length 16; 788 } 789 } 791 CBOR diagnostic notation: h'1f1ce6a3f42660d888d92a4d8030476e' 793 CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e 795 5.9. The 'leafref' Type 797 Leafs of type leafref MUST be encoded using the rules of the schema 798 node referenced by the 'path' YANG statement. 800 The following example shows the encoding of leaf 'interface-state- 801 ref' set to the value "eth1". 803 Definition example from [RFC7223]: 805 typedef interface-state-ref { 806 type leafref { 807 path "/interfaces-state/interface/name"; 808 } 809 } 811 container interfaces-state { 812 list interface { 813 key "name"; 814 leaf name { 815 type string; 816 } 817 leaf-list higher-layer-if { 818 type interface-state-ref; 819 } 820 } 821 } 823 CBOR diagnostic notation: "eth1" 825 CBOR encoding: 64 65746831 827 5.10. The 'identityref' Type 829 This specification supports two approaches for encoding identityref, 830 a SID as defined in [I-D.ietf-core-sid] or a name as defined in 831 [RFC7951] section 6.8. 833 5.10.1. SIDs as identityref 835 SIDs are globally unique and may be used as identityref. This 836 approach is both compact and simple to implement. When SIDs are 837 used, identityref MUST be encoded using a CBOR unsigned integer data 838 item (major type 0) and set to a SID allocated from a registered SID 839 range. 841 The following example shows the encoding of leaf 'type' set to the 842 value 'iana-if-type:ethernetCsmacd' (SID 1180). 844 Definition example from [RFC7317]: 846 identity interface-type { 847 } 849 identity iana-interface-type { 850 base interface-type; 851 } 853 identity ethernetCsmacd { 854 base iana-interface-type; 855 } 857 leaf type { 858 type identityref { 859 base interface-type; 860 } 861 } 863 CBOR diagnostic notation: 1180 865 CBOR encoding: 19 049c 867 5.10.2. Name as identityref 869 Alternatively, an identityref may be encoded using a name as defined 870 in [RFC7951] section 6.8. When names are used, identityref MUST be 871 encoded using a CBOR text string data item (major type 3). If the 872 identity is defined in another module than the leaf node containing 873 the identityref value, the namespace-qualified form MUST be used. 874 Otherwise, both the simple and namespace-qualified forms are 875 permitted. Names and namespaces are defined in [RFC7951] section 4. 877 The following example shows the encoding of the identity 'iana-if- 878 type:ethernetCsmacd' using its name. This example is described in 879 Section 5.10.1. 881 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 883 CBOR encoding: 78 1b 884 69616e612d69662d747970653a65746865726e657443736d616364 886 5.11. The 'empty' Type 888 Leafs of type empty MUST be encoded using the CBOR null value (major 889 type 7, additional information 22). 891 The following example shows the encoding of leaf 'is-router' when 892 present. 894 Definition example from [RFC7277]: 896 leaf is-router { 897 type empty; 898 } 900 CBOR diagnostic notation: null 902 CBOR encoding: f6 904 5.12. The 'union' Type 906 Leafs of type union MUST be encoded using the rules associated with 907 one of the types listed. When used in a union, the following YANG 908 datatypes are prefixed by CBOR tag to avoid confusion between 909 different YANG datatypes encoded using the same CBOR major type. 911 o bits 913 o enumeration 915 o identityref 917 o instance-identifier 919 See Section 7.1 for more information about these CBOR tags. 921 The following example shows the encoding of leaf 'ip-address' when 922 set to "2001:db8:a0b:12f0::1". 924 Definition example from [RFC7317]: 926 typedef ipv4-address { 927 type string { 928 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 929 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 930 \p{L}]+)?'; 931 } 932 } 934 typedef ipv6-address { 935 type string { 936 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 937 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 938 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 939 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 940 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 941 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 942 } 943 } 945 typedef ip-address { 946 type union { 947 type ipv4-address; 948 type ipv6-address; 949 } 950 } 952 leaf address { 953 type inet:ip-address; 954 } 956 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 958 CBOR encoding: 74 323030313a6462383a6130623a313266303a3a31 960 5.13. The 'instance-identifier' Type 962 This specification supports two approaches for encoding an instance- 963 identifier, one based on SIDs as defined in [I-D.ietf-core-sid] and 964 one based on names as defined in [RFC7951] section 6.11. 966 5.13.1. SIDs as instance-identifier 968 SIDs uniquely identify a data node. In the case of a single instance 969 data node, a data node defined at the root of a YANG module or 970 submodule or data nodes defined within a container, the SID is 971 sufficient to identify this instance. 973 In the case of a data node member of a YANG list, a SID is combined 974 with the list key(s) to identify each instance within the YANG 975 list(s). 977 Single instance data nodes MUST be encoded using a CBOR unsigned 978 integer data item (major type 0) and set to the targeted data node 979 SID. 981 Data nodes member of a YANG list MUST be encoded using a CBOR array 982 data item (major type 4) containing the following entries: 984 o The first entry MUST be encoded as a CBOR unsigned integer data 985 item (major type 0) and set to the targeted data node SID. 987 o The following entries MUST contain the value of each key required 988 to identify the instance of the targeted data node. These keys 989 MUST be ordered as defined in the 'key' YANG statement, starting 990 from top level list, and follow by each of the subordinate 991 list(s). 993 *First example:* 995 The following example shows the encoding of a leaf of type instance- 996 identifier which identify the data node "/system/contact" (SID 1737). 998 Definition example from [RFC7317]: 1000 container system { 1002 leaf contact { 1003 type string; 1004 } 1006 leaf hostname { 1007 type inet:domain-name; 1008 } 1009 } 1011 CBOR diagnostic notation: 1737 1013 CBOR encoding: 19 06c9 1015 *Second example:* 1017 The following example shows the encoding of a leaf of type instance- 1018 identifier which identify the data node instance 1019 "/system/authentication/user/authorized-key/key-data" (SID 1730) for 1020 user name "bob" and authorized-key "admin". 1022 Definition example from [RFC7317]: 1024 list user { 1025 key name; 1027 leaf name { 1028 type string; 1029 } 1030 leaf password { 1031 type ianach:crypt-hash; 1032 } 1034 list authorized-key { 1035 key name; 1037 leaf name { 1038 type string; 1039 } 1040 leaf algorithm { 1041 type string; 1042 } 1043 leaf key-data { 1044 type binary; 1045 } 1046 } 1048 CBOR diagnostic notation: [1730, "bob", "admin"] 1050 CBOR encoding: 1052 83 # array(3) 1053 19 06c2 # unsigned(1730) 1054 63 # text(3) 1055 626f62 # "bob" 1056 65 # text(5) 1057 61646d696e # "admin" 1059 *Third example:* 1061 The following example shows the encoding of a leaf of type instance- 1062 identifier which identify the list instance "/system/authentication/ 1063 user" (SID 1726) corresponding to the user name "jack". 1065 CBOR diagnostic notation: [1726, "jack"] 1067 CBOR encoding: 1069 82 # array(2) 1070 19 06be # unsigned(1726) 1071 64 # text(4) 1072 6a61636b # "jack" 1074 5.13.2. Names as instance-identifier 1076 The use of names as instance-identifier is defined in [RFC7951] 1077 section 6.11. The resulting xpath MUST be encoded using a CBOR text 1078 string data item (major type 3). 1080 *First example:* 1082 This example is described in Section 5.13.1. 1084 CBOR diagnostic notation: "/ietf-system:system/contact" 1086 CBOR encoding: 1088 78 1c 2f20696574662d73797374656d3a73797374656d2f636f6e74616374 1090 *Second example:* 1092 This example is described in Section 5.13.1. 1094 CBOR diagnostic notation: 1096 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1097 [name='admin']/key-data" 1099 CBOR encoding: 1101 78 59 1102 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1103 74696f6e2f757365725b6e616d653d27626f62275d2f617574686f72697a 1104 65642d6b65795b6e616d653d2761646d696e275d2f6b65792d64617461 1106 *Third example:* 1108 This example is described in Section 5.13.1. 1110 CBOR diagnostic notation: 1112 "/ietf-system:system/authentication/user[name='bob']" 1114 CBOR encoding: 1116 78 33 1117 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1118 74696f6e2f757365725b6e616d653d27626f62275d 1120 6. Security Considerations 1122 The security considerations of [RFC7049] and [RFC7950] apply. 1124 This document defines an alternative encoding for data modeled in the 1125 YANG data modeling language. As such, this encoding does not 1126 contribute any new security issues in addition of those identified 1127 for the specific protocol or context for which it is used. 1129 To minimize security risks, software on the receiving side SHOULD 1130 reject all messages that do not comply to the rules of this document 1131 and reply with an appropriate error message to the sender. 1133 7. IANA Considerations 1135 7.1. Tags Registry 1137 This specification requires the assignment of CBOR tags for the 1138 following YANG datatypes. These tags are added to the Tags Registry 1139 as defined in section 7.2 of [RFC7049]. 1141 +-----+---------------------+---------------------------+-----------+ 1142 | Tag | Data Item | Semantics | Reference | 1143 +-----+---------------------+---------------------------+-----------+ 1144 | 40 | bits | YANG bits datatype | RFC XXXX | 1145 | 41 | enumeration | YANG enumeration datatype | RFC XXXX | 1146 | 42 | identityref | YANG identityref datatype | RFC XXXX | 1147 | 43 | instance-identifier | YANG instance-identifier | RFC XXXX | 1148 | | | datatype | | 1149 +-----+---------------------+---------------------------+-----------+ 1151 // RFC Ed.: update Tag values using allocated tags if needed and 1152 remove this note // RFC Ed.: replace XXXX with RFC number and remove 1153 this note 1155 8. Acknowledgments 1157 This document has been largely inspired by the extensive works done 1158 by Andy Bierman and Peter van der Stok on [I-D.vanderstok-core-comi]. 1159 [RFC7951] has also been a critical input to this work. The authors 1160 would like to thank the authors and contributors to these two drafts. 1162 The authors would also like to acknowledge the review, feedback, and 1163 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1165 9. References 1167 9.1. Normative References 1169 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1170 Requirement Levels", BCP 14, RFC 2119, 1171 DOI 10.17487/RFC2119, March 1997, 1172 . 1174 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1175 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1176 October 2013, . 1178 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1179 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1180 . 1182 9.2. Informative References 1184 [I-D.ietf-core-sid] 1185 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1186 Minaburo, "YANG Schema Item iDentifier (SID)", draft-ietf- 1187 core-sid-00 (work in progress), October 2016. 1189 [I-D.vanderstok-core-comi] 1190 Stok, P., Bierman, A., Veillette, M., and A. Pelov, "CoAP 1191 Management Interface", draft-vanderstok-core-comi-10 (work 1192 in progress), October 2016. 1194 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1195 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1196 2014, . 1198 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1199 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1200 . 1202 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1203 Constrained-Node Networks", RFC 7228, 1204 DOI 10.17487/RFC7228, May 2014, 1205 . 1207 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1208 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1209 . 1211 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1212 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1213 2014, . 1215 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1216 RFC 7951, DOI 10.17487/RFC7951, August 2016, 1217 . 1219 Authors' Addresses 1221 Michel Veillette (editor) 1222 Trilliant Networks Inc. 1223 610 Rue du Luxembourg 1224 Granby, Quebec J2J 2V2 1225 Canada 1227 Phone: +14503750556 1228 Email: michel.veillette@trilliantinc.com 1230 Alexander Pelov (editor) 1231 Acklio 1232 2bis rue de la Chataigneraie 1233 Cesson-Sevigne, Bretagne 35510 1234 France 1236 Email: a@ackl.io 1238 Abhinav Somaraju 1239 Tridonic GmbH & Co KG 1240 Farbergasse 15 1241 Dornbirn, Vorarlberg 6850 1242 Austria 1244 Phone: +43664808926169 1245 Email: abhinav.somaraju@tridonic.com 1246 Randy Turner 1247 Landis+Gyr 1248 30000 Mill Creek Ave 1249 Suite 100 1250 Alpharetta, GA 30022 1251 US 1253 Phone: ++16782581292 1254 Email: randy.turner@landisgyr.com 1255 URI: http://www.landisgyr.com/ 1257 Ana Minaburo 1258 Acklio 1259 2bis rue de la chataigneraie 1260 Cesson-Sevigne, Bretagne 35510 1261 France 1263 Email: ana@ackl.io