idnits 2.17.1 draft-ietf-core-yang-cbor-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 : ---------------------------------------------------------------------------- ** 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 (July 08, 2016) is 2842 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: '0-9' is mentioned on line 948, but not defined == Missing Reference: '1-9' is mentioned on line 939, but not defined == Missing Reference: '0-4' is mentioned on line 948, but not defined == Missing Reference: '0-5' is mentioned on line 948, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 947, but not defined -- Looks like a reference, but probably isn't: '01' on line 948 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-01) exists of draft-somaraju-core-sid-00 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-09 -- 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 (~~), 8 warnings (==), 5 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: January 9, 2017 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 July 08, 2016 14 CBOR Encoding of Data Modeled with YANG 15 draft-ietf-core-yang-cbor-02 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 January 9, 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 103 [I-D.ietf-netmod-rfc6020bis] defines an XML encoding for data 104 instances, i.e. contents of configuration datastores, state data, RPC 105 inputs and outputs, action inputs and outputs, and event 106 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 [I-D.ietf-netmod-yang-json]. 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 [I-D.ietf-netmod-rfc6020bis]: 128 o action 130 o anydata 132 o anyxml 134 o data node 136 o data tree 138 o module 140 o notification 142 o RPC 144 o schema node 145 o schema tree 147 o submodule 149 The following terms are defined in [I-D.ietf-netmod-yang-json]: 151 o member name 153 o name of an identity 155 o namespace-qualified 157 This specification also makes use of the following terminology: 159 o child: A schema node defined within a collection such as a 160 container, a list, a case, a notification, an RPC input, an RPC 161 output, an action input, an action output. 163 o delta : Difference between the SID assigned to the current schema 164 node and the SID assigned to the parent. 166 o parent: The collection in which a schema node is defined. 168 o structured identifier or SID: Unsigned integer used to identify 169 different YANG items. 171 2.1. CBOR diagnostic notation 173 Within this document, CBOR binary contents are represented using an 174 equivalent textual form called CBOR diagnostic notation as defined in 175 [RFC7049] section 6. This notation is used strictly for 176 documentation purposes and is never used in the data serialization. 177 Table 1 below provides a summary of this notation. 179 +----------+------+--------------------------+-----------+----------+ 180 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 181 | content | type | | | encoding | 182 +----------+------+--------------------------+-----------+----------+ 183 | Unsigned | 0 | Decimal digits | 123 | 18 7b | 184 | integer | | | | | 185 | Negative | 1 | Decimal digits prefixed | -123 | 38 7a | 186 | integer | | by a minus sign | | | 187 | Byte | 2 | Hexadecimal value | h'f15c' | 42 f15c | 188 | string | | enclosed between single | | | 189 | | | quotes and prefixed by | | | 190 | | | an 'h' | | | 191 | Text | 3 | String of Unicode | "txt" | 63 | 192 | string | | characters enclosed | | 747874 | 193 | | | between double quotes | | | 194 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 195 | | | values within square | | | 196 | | | brackets | | | 197 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 198 | | | key : value pairs within | 2: 456 } | 01187b | 199 | | | curly braces | | 021901c8 | 200 | Boolean | 7/20 | false | false | f4 | 201 | | 7/21 | true | true | f5 | 202 | Null | 7/22 | null | null | f6 | 203 | Not | 7/23 | undefined | undefined | f7 | 204 | assigned | | | | | 205 +----------+------+--------------------------+-----------+----------+ 207 Table 1: CBOR diagnostic notation summary 209 The following extensions to the CBOR diagnostic notation are 210 supported: 212 o Comments can be added to the end of each line. Any characters 213 after a Pound sign ('#') outside of a string, up to the end of the 214 line, are treated as a comment. 216 o Deltas are represented as numbers preceded by a '+' or '-' sign. 217 The use of the '+' sign for positive deltas represents an 218 extension to the CBOR diagnostic notation as defined by [RFC7049] 219 section 6. 221 3. Properties of the CBOR Encoding 223 This document defines CBOR encoding rules for YANG schema trees and 224 their subtrees. 226 Basic schema nodes such as leaf, leaf-list, list, anydata and anyxml 227 can be encoded standalone. In this case, only the value of this 228 schema node is encoded in CBOR. Identification of this value needs 229 to be provided by some external means when required. 231 A collection such as container, list instance, notification, RPC 232 input, RPC output, action input and action output is serialized using 233 a CBOR map in which each child schema node is encoded using a key and 234 a value. This specification supports two type of keys; SID as 235 defined in [I-D.somaraju-core-sid] and member names as defined in 236 [I-D.ietf-netmod-yang-json]. Each of these key type is encoded using 237 a specific CBOR type which allows their interpretation during the 238 deserialization process. The end user of this mapping specification 239 can mandate the use of a specific key type or a specific subset of 240 key types. 242 In order to minimize the size of the encoded data, the proposed 243 mapping avoid any unnecessary meta-information beyond those natively 244 supported by CBOR. For instance, CBOR tags are used sorely in the 245 case of the union datatype to distinguish explicitly the use of 246 different YANG datatypes encoded using the same CBOR major type. 248 It is expected that application entities generating and decoding CBOR 249 contents have enough knowledge about the information processed in 250 order to perform the expected task without the need of such extra 251 meta-information. 253 4. Encoding of YANG Data Node Instances 255 Schema node instances defined using the YANG modeling language are 256 encoded using CBOR [RFC7049] based on the rules defined in this 257 section. We assume that the reader is already familiar with both 258 YANG [I-D.ietf-netmod-rfc6020bis] and CBOR [RFC7049]. 260 4.1. The 'leaf' Data Node 262 Leafs MUST be encoded based on the encoding rules specified in 263 Section 5. 265 4.2. The 'container' Data Node 267 Collections such as containers, list instances, notifications, RPC 268 inputs, RPC outputs, action inputs and action outputs MUST be encoded 269 using a CBOR map data item (major type 5). A map is comprised of 270 pairs of data items, with each data item consisting of a key and a 271 value. Each key within the CBOR map is set to a data node 272 identifier, each value is set to the value of this data node 273 instance. 275 This specification supports two type of keys; SID as defined in 276 [I-D.somaraju-core-sid] encoded using CBOR unsigned or signed 277 integers and member names as defined in [I-D.ietf-netmod-yang-json] 278 encoded using CBOR text strings. The use of CBOR byte strings for 279 keys is reserved for future extensions. 281 4.2.1. SIDs as keys 283 Keys implemented using SIDs MUST be encoded using a CBOR unsigned 284 integer (major type 0) or CBOR signed integer (major type 1), 285 depending on the actual value. Keys are set to the delta of the 286 associated SID, delta values are computed as follows: 288 o The delta value is equal to the SID of the current schema node 289 minus the SID of the parent schema node. When no parent exists in 290 the context of use of this container, the delta is set to the SID 291 of the current schema node (a parent with SID equal to zero is 292 assumed). 294 o Delta values may result in a negative number, clients and servers 295 MUST support negative deltas. 297 The following example shows the encoding of the 'system' container 298 using the SIDs defined in [I-D.somaraju-core-sid] Appendix C. 300 Definition example from [RFC7317]: 302 typedef date-and-time { 303 type string { 304 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 305 \d{2}:\d{2})'; 306 } 307 } 309 container system { 310 leaf hostname { 311 type inet:domain-name; 313 container clock { 314 leaf current-datetime { 315 type date-and-time; 316 } 318 leaf boot-datetime { 319 type date-and-time; 320 } 321 } 322 } 323 CBOR diagnostic notation: 325 { 326 1717 : { # clock (SID 1717) 327 +2 : "2015-10-02T14:47:24Z-05:00", # current-datetime (SID 1719) 328 +1 : "2015-09-15T09:12:58Z-05:00" # boot-datetime (SID 1718) 329 } 330 } 332 CBOR encoding: 334 a1 # map(1) 335 19 06b5 # unsigned(1717) 336 a2 # map(2) 337 02 # unsigned(2) 338 78 1a # text(26) 339 323031352d31302d30325431343a34373a32345a2d30353a3030 340 01 # unsigned(1) 341 78 1a # text(26) 342 323031352d30392d31355430393a31323a35385a2d30353a3030 344 4.2.2. Member names as keys 346 Keys implemented using member names MUST be encoded using a CBOR text 347 string data item (major type 3). A namespace-qualified member name 348 MUST be used for all members of a top-level collection, and then also 349 whenever the namespaces of the schema node and its parent are 350 different. In all other cases, the simple form of the member name 351 MUST be used. Names and namespaces are defined in 352 [I-D.ietf-netmod-yang-json] section 4. 354 The following example shows the encoding of the the 'system' 355 container using names. This example is described in Section 4.2.1. 357 CBOR diagnostic notation: 359 { 360 "ietf-system:clock" : { 361 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 362 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 363 } 364 } 366 CBOR encoding: 368 a1 # map(1) 369 71 # text(17) 370 696574662d73797374656d3a636c6f636b # "ietf-system:clock" 371 a2 # map(2) 372 70 # text(16) 373 63757272656e742d6461746574696d65 # "current-datetime" 374 78 1a # text(26) 375 323031352d31302d30325431343a34373a32345a2d30353a3030 376 6d # text(13) 377 626f6f742d6461746574696d65 # "boot-datetime" 378 78 1a # text(26) 379 323031352d30392d31355430393a31323a35385a2d30353a3030 381 4.3. The 'leaf-list' Data Node 383 A leaf-list MUST be encoded using a CBOR array data item (major type 384 4). Each entry of this array MUST be encoded using the rules defined 385 by the YANG type specified. 387 The following example shows the encoding the 'search' leaf-list 388 containing the two entries, "ietf.org" and "ieee.org". 390 Definition example [RFC7317]: 392 typedef domain-name { 393 type string { 394 length "1..253"; 395 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 396 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 397 )|\.'; 398 } 399 } 401 leaf-list search { 402 type domain-name; 403 ordered-by user; 404 } 406 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 408 CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267 410 4.4. The 'list' Data Node 412 A list MUST be encoded using a CBOR array data item (major type 4). 413 Each list instance within this CBOR array is encoded using a CBOR map 414 data item (major type 5) based on the same rules as a YANG container 415 as defined in Section 4.2. 417 4.4.1. SIDs as keys 419 The follwoing example show the encoding a the 'server' list using the 420 SIDs defined in [I-D.somaraju-core-sid] Appendix C. It is important 421 to note that the protocol or method using this mapping may carry a 422 parent SID or may have the knowledge of this parent SID based on its 423 context. In these cases, delta encoding can be performed based on 424 this parent SID which minimizes the size of the encoded data. 426 The following example shows the encoding of the 'server' list 427 containing two enties. SIDs used in this example are defined in 428 [I-D.somaraju-core-sid] Appendix C. It is important to note that the 429 protocol or method using this mapping may carry a parent SID or may 430 have the knowledge of this parent SID based on its context. In these 431 cases, delta encoding can be performed based on this parent SID which 432 minimizes the size of the encoded data. 434 Definition example from [RFC7317]: 436 list server { 437 key name; 439 leaf name { 440 type string; 441 } 442 choice transport { 443 case udp { 444 container udp { 445 leaf address { 446 type host; 447 mandatory true; 448 } 449 leaf port { 450 type port-number; 451 } 452 } 453 } 454 } 455 leaf association-type { 456 type enumeration { 457 enum server; 458 enum peer; 459 enum pool; 460 } 461 default server; 462 } 463 leaf iburst { 464 type boolean; 465 default false; 466 } 467 leaf prefer { 468 type boolean; 469 default false; 470 } 471 } 473 CBOR diagnostic notation: 475 [ 476 { 477 1755 : "NRC TIC server", # name (SID 1755) 478 1757 : { # udp (SID 1757) 479 +1 : "tic.nrc.ca", # address (SID 1758) 480 +2 : 123 # port (SID 1759) 481 }, 482 1753 : 0, # association-type (SID 1753) 483 1754 : false, # iburst (SID 1754) 484 1756 : true # prefer (SID 1756) 485 }, 486 { 487 1755 : "NRC TAC server", # name (SID 1755) 488 1757 : { # udp (SID 1757) 489 +1 : "tac.nrc.ca" # address (SID 1758) 490 } 491 } 492 ] 494 CBOR encoding: 496 82 # array(2) 497 a5 # map(5) 498 19 06db # unsigned(1755) 499 6e # text(14) 500 4e52432054494320736572766572 # "NRC TIC server" 501 19 06dd # unsigned(1757) 502 a2 # map(2) 503 01 # unsigned(1) 504 6a # text(10) 505 7469632e6e72632e6361 # "tic.nrc.ca" 506 02 # unsigned(2) 507 18 7b # unsigned(123) 508 19 06d9 # unsigned(1753) 509 00 # unsigned(0) 510 19 06da # unsigned(1754) 511 f4 # primitive(20) 512 19 06dc # unsigned(1756) 513 f5 # primitive(21) 514 a2 # map(2) 515 19 06db # unsigned(1755) 516 6e # text(14) 517 4e52432054414320736572766572 # "NRC TAC server" 518 19 06dd # unsigned(1757) 519 a1 # map(1) 520 01 # unsigned(1) 521 6a # text(10) 522 7461632e6e72632e6361 # "tac.nrc.ca" 524 4.4.2. Member names as keys 526 The following example shows the encoding of the the 'server' list 527 using names. This example is described in Section 4.4.1. 529 CBOR diagnostic notation: 531 [ 532 { 533 "ietf-system:name" : "NRC TIC server", 534 "ietf-system:udp" : { 535 "address" : "tic.nrc.ca", 536 "port" : 123 537 }, 538 "ietf-system:association-type" : 0, 539 "ietf-system:iburst" : false, 540 "ietf-system:prefer" : true 541 }, 542 { 543 "ietf-system:name" : "NRC TAC server", 544 "ietf-system:udp" : { 545 "address" : "tac.nrc.ca" 546 } 547 } 548 ] 550 CBOR encoding: 552 82 # array(2) 553 a5 # map(5) 554 70 # text(16) 555 696574662d73797374656d3a6e616d65 # "ietf-system:name" 556 6e # text(14) 557 4e52432054494320736572766572 # "NRC TIC server" 558 6f # text(15) 559 696574662d73797374656d3a756470 # "ietf-system:udp" 560 a2 # map(2) 561 67 # text(7) 562 61646472657373 # "address" 563 6a # text(10) 564 7469632e6e72632e6361 # "tic.nrc.ca" 565 64 # text(4) 566 706f7274 # "port" 567 18 7b # unsigned(123) 568 78 1c # text(28) 569 696574662d73797374656d3a6173736f63696174696f6e2d74797065 570 00 # unsigned(0) 571 72 # text(18) 572 696574662d73797374656d3a696275727374 # "ietf-system:iburst" 573 f4 # primitive(20) 574 72 # text(18) 575 696574662d73797374656d3a707265666572 # "ietf-system:prefer" 576 f5 # primitive(21) 577 a2 # map(2) 578 70 # text(16) 579 696574662d73797374656d3a6e616d65 # "ietf-system:name" 580 6e # text(14) 581 4e52432054414320736572766572 # "NRC TAC server" 582 6f # text(15) 583 696574662d73797374656d3a756470 # "ietf-system:udp" 584 a1 # map(1) 585 67 # text(7) 586 61646472657373 # "address" 587 6a # text(10) 588 7461632e6e72632e6361 # "tac.nrc.ca" 590 4.5. The 'anydata' Data Node 592 An anydata serves as a container for an arbitrary set of schema nodes 593 that otherwise appear as normal YANG-modeled data. An anydata 594 instance is encoded using the same rules as a container, i.e., CBOR 595 map. The requirement that anydata content can be modeled by YANG 596 implies the following: 598 o Keys of any inner data nodes MUST be set to valid deltas or member 599 names. 601 o The CBOR array MUST contain either unique scalar values (as a 602 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 604 o Values MUST follow the encoding rules of one of the datatypes 605 listed in Section 5. 607 4.6. The 'anyxml' Data Node 609 An anyxml schema node is used to serialize an arbitrary CBOR content, 610 i.e., its value can be any CBOR binary object. 612 5. Representing YANG Data Types in CBOR 614 5.1. The unsigned integer Types 616 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 617 a CBOR unsigned integer data item (major type 0). 619 The following example shows the encoding of leaf 'mtu' set to 1280 620 bytes. 622 Definition example from [RFC7277]: 624 leaf mtu { 625 type uint16 { 626 range "68..max"; 627 } 628 } 630 CBOR diagnostic notation: 1280 632 CBOR encoding: 19 0500 634 5.2. The integer Types 636 Leafs of type int8, int16, int32 and int64 MUST be encoded using 637 either CBOR unsigned integer (major type 0) or CBOR signed integer 638 (major type 1), depending on the actual value. 640 The following example shows the encoding of leaf 'timezone-utc- 641 offset' set to -300 minutes. 643 Definition example from [RFC7317]: 645 leaf timezone-utc-offset { 646 type int16 { 647 range "-1500 .. 1500"; 648 } 649 } 651 CBOR diagnostic notation: -300 653 CBOR encoding: 39 012b 655 5.3. The 'decimal64' Type 657 Leafs of type decimal64 MUST be encoded using either CBOR unsigned 658 integer (major type 0) or CBOR signed integer (major type 1), 659 depending on the actual value. The position of the decimal point is 660 defined by the fraction-digits YANG statement and is not available in 661 the CBOR encoding. 663 The following example shows the encoding of leaf 'my-decimal' set to 664 2.57. 666 Definition example from [RFC7317]: 668 leaf my-decimal { 669 type decimal64 { 670 fraction-digits 2; 671 range "1 .. 3.14 | 10 | 20..max"; 672 } 673 } 675 CBOR diagnostic notation: 257 677 CBOR encoding: 19 0101 679 5.4. The 'string' Type 681 Leafs of type string MUST be encoded using a CBOR text string data 682 item (major type 3). 684 The following example shows the encoding of leaf 'name' set to 685 "eth0". 687 Definition example from [RFC7223]: 689 leaf name { 690 type string; 691 } 692 CBOR diagnostic notation: "eth0" 694 CBOR encoding: 64 65746830 696 5.5. The 'boolean' Type 698 Leafs of type boolean MUST be encoded using a CBOR true (major type 699 7, additional information 21) or false data item (major type 7, 700 additional information 20). 702 The following example shows the encoding of leaf 'enabled' set to 703 'true'. 705 Definition example from [RFC7317]: 707 leaf enabled { 708 type boolean; 709 } 711 CBOR diagnostic notation: true 713 CBOR encoding: f5 715 5.6. The 'enumeration' Type 717 Leafs of type enumeration MUST be encoded using a CBOR unsigned 718 integer (major type 0) or CBOR signed integer (major type 1), 719 depending on the actual value. Enumeration values are either 720 explicitly assigned using the YANG statement 'value' or automatically 721 assigned based on the algorithm defined in 722 [I-D.ietf-netmod-rfc6020bis] section 9.6.4.2. 724 The following example shows the encoding of leaf 'oper-status' set to 725 'testing'. 727 Definition example from [RFC7317]: 729 leaf oper-status { 730 type enumeration { 731 enum up { value 1; } 732 enum down { value 2; } 733 enum testing { value 3; } 734 enum unknown { value 4; } 735 enum dormant { value 5; } 736 enum not-present { value 6; } 737 enum lower-layer-down { value 7; } 738 } 739 } 740 CBOR diagnostic notation: 3 742 CBOR encoding: 03 744 5.7. The 'bits' Type 746 Leafs of type bits MUST be encoded using a CBOR byte string data item 747 (major type 2). Bits position are either explicitly assigned using 748 the YANG statement 'position' or automatically assigned based on the 749 algorithm defined in [I-D.ietf-netmod-rfc6020bis] section 9.7.4.2. 751 Bits position 0 to 7 are assigned to the first byte within the byte 752 string, bits 8 to 15 to the second byte, and subsequent bytes are 753 assigned similarly. Within each byte, bits are assigned from least 754 to most significant. 756 The following example shows the encoding of leaf 'mybits' with the 757 'disable-nagle' and '10-Mb-only' flags set. 759 Definition example from [I-D.ietf-netmod-rfc6020bis]: 761 leaf mybits { 762 type bits { 763 bit disable-nagle { 764 position 0; 765 } 766 bit auto-sense-speed { 767 position 1; 768 } 769 bit 10-Mb-only { 770 position 2; 771 } 772 } 773 } 775 CBOR diagnostic notation: h'05' 777 CBOR encoding: 41 05 779 5.8. The 'binary' Type 781 Leafs of type binary MUST be encoded using a CBOR byte string data 782 item (major type 2). 784 The following example shows the encoding of leaf 'aes128-key' set to 785 0x1f1ce6a3f42660d888d92a4d8030476e. 787 Definition example: 789 leaf aes128-key { 790 type binary { 791 length 16; 792 } 793 } 795 CBOR diagnostic notation: h'1f1ce6a3f42660d888d92a4d8030476e' 797 CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e 799 5.9. The 'leafref' Type 801 Leafs of type leafref MUST be encoded using the rules of the schema 802 node referenced by the 'path' YANG statement. 804 The following example shows the encoding of leaf 'interface-state- 805 ref' set to the value "eth1". 807 Definition example from [RFC7223]: 809 typedef interface-state-ref { 810 type leafref { 811 path "/interfaces-state/interface/name"; 812 } 813 } 815 container interfaces-state { 816 list interface { 817 key "name"; 818 leaf name { 819 type string; 820 } 821 leaf-list higher-layer-if { 822 type interface-state-ref; 823 } 824 } 825 } 827 CBOR diagnostic notation: "eth1" 829 CBOR encoding: 64 65746831 831 5.10. The 'identityref' Type 833 This specification supports two approaches for encoding identityref, 834 a SID as defined in [I-D.somaraju-core-sid] or a name as defined in 835 [I-D.ietf-netmod-yang-json] section 6.8. 837 5.10.1. SIDs as identityref 839 SIDs are globally unique and may be used as identityref. This 840 approach is both compact and simple to implement. When SIDs are 841 used, identityref MUST be encoded using a CBOR unsigned integer data 842 item (major type 0) and set to a SID allocated from a registered SID 843 range. 845 The following example shows the encoding of leaf 'type' set to the 846 value 'iana-if-type:ethernetCsmacd' (SID 1180). 848 Definition example from [RFC7317]: 850 identity interface-type { 851 } 853 identity iana-interface-type { 854 base interface-type; 855 } 857 identity ethernetCsmacd { 858 base iana-interface-type; 859 } 861 leaf type { 862 type identityref { 863 base interface-type; 864 } 865 } 867 CBOR diagnostic notation: 1180 869 CBOR encoding: 19 049c 871 5.10.2. Name as identityref 873 Alternatively, an identityref may be encoded using a name as defined 874 in [I-D.ietf-netmod-yang-json] section 6.8. When names are used, 875 identityref MUST be encoded using a CBOR text string data item (major 876 type 3). If the identity is defined in another module than the leaf 877 node containing the identityref value, the namespace-qualified form 878 MUST be used. Otherwise, both the simple and namespace-qualified 879 forms are permitted. Names and namespaces are defined in 880 [I-D.ietf-netmod-yang-json] section 4. 882 The following example shows the encoding of the identity 'iana-if- 883 type:ethernetCsmacd' using its name. This example is described in 884 Section 5.10.1. 886 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 888 CBOR encoding: 78 1b 889 69616e612d69662d747970653a65746865726e657443736d616364 891 5.11. The 'empty' Type 893 Leafs of type empty MUST be encoded using the CBOR null value (major 894 type 7, additional information 22). 896 The following example shows the encoding of leaf 'is-router' when 897 present. 899 Definition example from [RFC7277]: 901 leaf is-router { 902 type empty; 903 } 905 CBOR diagnostic notation: null 907 CBOR encoding: f6 909 5.12. The 'union' Type 911 Leafs of type union MUST be encoded using the rules associated with 912 one of the types listed. When used in a union, the following YANG 913 datatypes are prefixed by CBOR tag to avoid confusion between 914 different YANG datatypes encoded using the same CBOR major type. 916 o bits 918 o decimal64 920 o enumeration 922 o identityref 924 o instance-identifier 926 o leafref (Only when the datatype of the leaf referenced using the 927 'path' YANG statement require a CBOR tag) 929 See Section 7.1 for more information about these CBOR tags. 931 The following example shows the encoding of leaf 'ip-address' when 932 set to "2001:db8:a0b:12f0::1". 934 Definition example from [RFC7317]: 936 typedef ipv4-address { 937 type string { 938 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 939 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 940 \p{L}]+)?'; 941 } 942 } 944 typedef ipv6-address { 945 type string { 946 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 947 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 948 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 949 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 950 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 951 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 952 } 953 } 955 typedef ip-address { 956 type union { 957 type ipv4-address; 958 type ipv6-address; 959 } 960 } 962 leaf address { 963 type inet:ip-address; 964 } 966 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 968 CBOR encoding: 74 323030313a6462383a6130623a313266303a3a31 970 5.13. The 'instance-identifier' Type 972 This specification supports two approaches for encoding an instance- 973 identifier, one based on SIDs as defined in [I-D.somaraju-core-sid] 974 and one based on names as defined in [I-D.ietf-netmod-yang-json] 975 section 6.13. 977 5.13.1. SIDs as instance-identifier 979 SIDs uniquely identify a data node. For a single instance data node, 980 the SID is sufficient to identify this instance. For a multi- 981 instance data node, a SID is combined with the list key(s) to 982 identify each instance of this data node within the YANG list(s). 984 Single instance data nodes MUST be encoded using a CBOR unsigned 985 integer data item (major type 0) and set to the targeted data node 986 SID. 988 Multi-instances data nodes MUST be encoded using a CBOR array data 989 item (major type 4) containing the following entries: 991 o The first entry MUST be encoded as a CBOR unsigned integer data 992 item (major type 0) and set to the targeted data node SID. 994 o The following entries MUST contain the value of each key required 995 to identify the instance of the targeted data node. These keys 996 MUST be ordered as defined in the 'key' YANG statement, starting 997 from top level list, and follow by each of the subordinate 998 list(s). 1000 *First example:* 1002 The following example shows the encoding of a leaf of type instance- 1003 identifier which identify the data node "/system/contact" (SID 1737). 1005 Definition example from [RFC7317]: 1007 container system { 1009 leaf contact { 1010 type string; 1011 } 1013 leaf hostname { 1014 type inet:domain-name; 1015 } 1016 } 1018 CBOR diagnostic notation: 1737 1020 CBOR encoding: 19 06c9 1022 *Second example:* 1024 The following example shows the encoding of a leaf of type instance- 1025 identifier which identify the data node instance 1026 "/system/authentication/user/authorized-key/key-data" (SID 1730) for 1027 user name "bob" and authorized-key "admin". 1029 Definition example from [RFC7317]: 1031 list user { 1032 key name; 1034 leaf name { 1035 type string; 1036 } 1037 leaf password { 1038 type ianach:crypt-hash; 1039 } 1041 list authorized-key { 1042 key name; 1044 leaf name { 1045 type string; 1046 } 1047 leaf algorithm { 1048 type string; 1049 } 1050 leaf key-data { 1051 type binary; 1052 } 1053 } 1055 CBOR diagnostic notation: [1730, "bob", "admin"] 1057 CBOR encoding: 1059 83 # array(3) 1060 19 06c2 # unsigned(1730) 1061 63 # text(3) 1062 626f62 # "bob" 1063 65 # text(5) 1064 61646d696e # "admin" 1066 *Third example:* 1068 The following example shows the encoding of a leaf of type instance- 1069 identifier which identify the list instance "/system/authentication/ 1070 user" (SID 1726) corresponding to the user name "jack". 1072 CBOR diagnostic notation: [1726, "jack"] 1074 CBOR encoding: 1076 82 # array(2) 1077 19 06be # unsigned(1726) 1078 64 # text(4) 1079 6a61636b # "jack" 1081 5.13.2. Names as instance-identifier 1083 The use of names as instance-identifier is defined in 1084 [I-D.ietf-netmod-yang-json] section 6.11. The resulting xpath MUST 1085 be encoded using a CBOR text string data item (major type 3). 1087 *First example:* 1089 This example is described in Section 5.13.1. 1091 CBOR diagnostic notation: "/ietf-system:system/contact" 1093 CBOR encoding: 1095 78 1c 2f20696574662d73797374656d3a73797374656d2f636f6e74616374 1097 *Second example:* 1099 This example is described in Section 5.13.1. 1101 CBOR diagnostic notation: 1103 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1104 [name='admin']/key-data" 1106 CBOR encoding: 1108 78 59 1109 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1110 74696f6e2f757365725b6e616d653d27626f62275d2f617574686f72697a 1111 65642d6b65795b6e616d653d2761646d696e275d2f6b65792d64617461 1113 *Third example:* 1115 This example is described in Section 5.13.1. 1117 CBOR diagnostic notation: 1119 "/ietf-system:system/authentication/user[name='bob']" 1121 CBOR encoding: 1123 78 33 1124 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1125 74696f6e2f757365725b6e616d653d27626f62275d 1127 6. Security Considerations 1129 The security considerations of [RFC7049] and 1130 [I-D.ietf-netmod-rfc6020bis] apply. 1132 This document defines an alternative encoding for data modeled in the 1133 YANG data modeling language. As such, this encoding does not 1134 contribute any new security issues in addition of those identified 1135 for the specific protocol or context for which it is used. 1137 To minimize security risks, software on the receiving side SHOULD 1138 reject all messages that do not comply to the rules of this document 1139 and reply with an appropriate error message to the sender. 1141 7. IANA Considerations 1143 7.1. Tags Registry 1145 This specification requires the assignment of CBOR tags for the 1146 following YANG datatypes. These tags are added to the Tags Registry 1147 as defined in section 7.2 of [RFC7049]. 1149 +-----+---------------------+---------------------------+-----------+ 1150 | Tag | Data Item | Semantics | Reference | 1151 +-----+---------------------+---------------------------+-----------+ 1152 | 40 | bits | YANG bits datatype | RFC XXXX | 1153 | 41 | decimal64 | YANG decimal64 datatype | RFC XXXX | 1154 | 42 | enumeration | YANG enumeration datatype | RFC XXXX | 1155 | 43 | identityref | YANG identityref datatype | RFC XXXX | 1156 | 44 | instance-identifier | YANG instance-identifier | RFC XXXX | 1157 | | | datatype | | 1158 +-----+---------------------+---------------------------+-----------+ 1160 // RFC Ed.: update Tag values using allocated tags if needed and 1161 remove this note // RFC Ed.: replace XXXX with RFC number and remove 1162 this note 1164 8. Acknowledgments 1166 This document has been largely inspired by the extensive works done 1167 by Andy Bierman and Peter van der Stok on [I-D.vanderstok-core-comi]. 1168 [I-D.ietf-netmod-yang-json] has also been a critical input to this 1169 work. The authors would like to thank the authors and contributors 1170 to these two drafts. 1172 The authors would also like to acknowledge the review, feedback, and 1173 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1175 9. References 1177 9.1. Normative References 1179 [I-D.ietf-netmod-rfc6020bis] 1180 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1181 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 1182 2016. 1184 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1185 Requirement Levels", BCP 14, RFC 2119, 1186 DOI 10.17487/RFC2119, March 1997, 1187 . 1189 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1190 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1191 October 2013, . 1193 9.2. Informative References 1195 [I-D.ietf-netmod-yang-json] 1196 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1197 draft-ietf-netmod-yang-json-10 (work in progress), March 1198 2016. 1200 [I-D.somaraju-core-sid] 1201 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1202 Minaburo, "Structure Identifier (SID)", draft-somaraju- 1203 core-sid-00 (work in progress), March 2016. 1205 [I-D.vanderstok-core-comi] 1206 Stok, P. and A. Bierman, "CoAP Management Interface", 1207 draft-vanderstok-core-comi-09 (work in progress), March 1208 2016. 1210 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1211 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1212 2014, . 1214 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1215 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1216 . 1218 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1219 Constrained-Node Networks", RFC 7228, 1220 DOI 10.17487/RFC7228, May 2014, 1221 . 1223 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1224 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1225 . 1227 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1228 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1229 2014, . 1231 Authors' Addresses 1233 Michel Veillette (editor) 1234 Trilliant Networks Inc. 1235 610 Rue du Luxembourg 1236 Granby, Quebec J2J 2V2 1237 Canada 1239 Phone: +14503750556 1240 Email: michel.veillette@trilliantinc.com 1242 Alexander Pelov (editor) 1243 Acklio 1244 2bis rue de la Chataigneraie 1245 Cesson-Sevigne, Bretagne 35510 1246 France 1248 Email: a@ackl.io 1250 Abhinav Somaraju 1251 Tridonic GmbH & Co KG 1252 Farbergasse 15 1253 Dornbirn, Vorarlberg 6850 1254 Austria 1256 Phone: +43664808926169 1257 Email: abhinav.somaraju@tridonic.com 1258 Randy Turner 1259 Landis+Gyr 1260 30000 Mill Creek Ave 1261 Suite 100 1262 Alpharetta, GA 30022 1263 US 1265 Phone: ++16782581292 1266 Email: randy.turner@landisgyr.com 1267 URI: http://www.landisgyr.com/ 1269 Ana Minaburo 1270 Acklio 1271 2bis rue de la chataigneraie 1272 Cesson-Sevigne, Bretagne 35510 1273 France 1275 Email: ana@ackl.io