idnits 2.17.1 draft-ietf-core-yang-cbor-01.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. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 23, 2016) is 2865 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 998, but not defined == Missing Reference: '1-9' is mentioned on line 989, but not defined == Missing Reference: '0-4' is mentioned on line 998, but not defined == Missing Reference: '0-5' is mentioned on line 998, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 997, but not defined -- Looks like a reference, but probably isn't: '01' on line 998 ** 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 (~~), 9 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: December 25, 2016 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 June 23, 2016 14 CBOR Encoding of Data Modeled with YANG 15 draft-ietf-core-yang-cbor-01 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 December 25, 2016. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 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 Schema Node Instances . . . . . . . . . . . 6 63 4.1. The 'leaf' Schema Node . . . . . . . . . . . . . . . . . 6 64 4.2. The 'container' Schema Node . . . . . . . . . . . . . . . 6 65 4.3. The 'leaf-list' Schema Node . . . . . . . . . . . . . . . 10 66 4.4. The 'list' Schema Node . . . . . . . . . . . . . . . . . 10 67 4.5. The 'anydata' Schema Node . . . . . . . . . . . . . . . . 16 68 4.6. The 'anyxml' Schema Node . . . . . . . . . . . . . . . . 17 69 5. Representing YANG Data Types in CBOR . . . . . . . . . . . . 17 70 5.1. The unsigned integer Types . . . . . . . . . . . . . . . 17 71 5.2. The integer Types . . . . . . . . . . . . . . . . . . . . 17 72 5.3. The 'decimal64' Type . . . . . . . . . . . . . . . . . . 18 73 5.4. The 'string' Type . . . . . . . . . . . . . . . . . . . . 18 74 5.5. The 'boolean' Type . . . . . . . . . . . . . . . . . . . 19 75 5.6. The 'enumeration' Type . . . . . . . . . . . . . . . . . 19 76 5.7. The 'bits' Type . . . . . . . . . . . . . . . . . . . . . 19 77 5.8. The 'binary' Type . . . . . . . . . . . . . . . . . . . . 20 78 5.9. The 'leafref' Type . . . . . . . . . . . . . . . . . . . 21 79 5.10. The 'identityref' Type . . . . . . . . . . . . . . . . . 21 80 5.11. The 'empty' Type . . . . . . . . . . . . . . . . . . . . 23 81 5.12. The 'union' Type . . . . . . . . . . . . . . . . . . . . 23 82 5.13. The 'instance-identifier' Type . . . . . . . . . . . . . 24 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 84 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 85 7.1. Tags Registry . . . . . . . . . . . . . . . . . . . . . . 29 86 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 87 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 88 9.1. Normative References . . . . . . . . . . . . . . . . . . 30 89 9.2. Informative References . . . . . . . . . . . . . . . . . 31 90 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 92 1. Introduction 94 The specification of the YANG 1.1 data modelling language 95 [I-D.ietf-netmod-rfc6020bis] defines only an XML encoding for data 96 instances, i.e. contents of configuration datastores, state data, RPC 97 inputs and outputs, action inputs and outputs, and event 98 notifications. 100 A new set of encoding rules has been defined to allow the use of the 101 same data models in environments based on the JavaScript Object 102 Notation (JSON) Data Interchange Format [RFC7159]. This is 103 accomplished in the JSON Encoding of Data Modeled with YANG 104 specification [I-D.ietf-netmod-yang-json]. 106 The aim of this document is to define a set of encoding rules for the 107 Concise Binary Object Representation (CBOR) [RFC7049]. The resulting 108 encoding is more compact compared to XML and JSON and more suitable 109 for Constrained Nodes and/or Constrained Networks as defined by 110 [RFC7228]. 112 2. Terminology and Notation 114 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 115 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 116 document are to be interpreted as described in [RFC2119]. 118 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 120 o action 122 o anydata 124 o anyxml 126 o data node 128 o data tree 130 o module 132 o notification 134 o RPC 136 o schema node 138 o schema tree 140 o submodule 142 The following terms are defined in [I-D.ietf-netmod-yang-json]: 144 o member name 145 o name of an identity 147 The following term is defined in [I-D.vanderstok-core-comi]: 149 o YANG hash 151 This specification also makes use of the following terminology: 153 o child: A schema node defined within a collection such as a 154 container, a list, a case, a notification, an RPC input, an RPC 155 output, an action input, an action output. 157 o delta : Difference between the SID assigned to the current schema 158 node and the SID assigned to the parent. 160 o parent: The collection in which a schema node is defined. 162 o structured identifier or SID: Unsigned integer used to identify 163 different YANG items. 165 2.1. CBOR diagnostic notation 167 Within this document, CBOR binary contents are represented using an 168 equivalent textual form called CBOR diagnostic notation as defined in 169 [RFC7049] section 6. This notation is used strictly for 170 documentation purposes and is never used in the data serialization. 172 +----------+------+--------------------------+-----------+----------+ 173 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 174 | content | type | | | encoding | 175 +----------+------+--------------------------+-----------+----------+ 176 | Unsigned | 0 | Decimal digits | 123 or | 18 7b | 177 | integer | | | +123 | | 178 | Negative | 1 | Decimal digits prefixed | -123 | 38 7a | 179 | integer | | by a minus sign | | | 180 | Byte | 2 | Hexadecimal value | h'f15c' | 42 f15c | 181 | string | | enclosed between single | | | 182 | | | quotes and prefixed by | | | 183 | | | an 'h' | | | 184 | Text | 3 | String of Unicode | "txt" | 63 | 185 | string | | characters enclosed | | 747874 | 186 | | | between double quotes | | | 187 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 188 | | | values within square | | | 189 | | | brackets | | | 190 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 191 | | | key : value pairs within | 2: 456 } | 01187b | 192 | | | curly braces | | 021901c8 | 193 | Boolean | 7/20 | false | false | f4 | 194 | | 7/21 | true | true | f5 | 195 | Null | 7/22 | null | null | f6 | 196 | Not | 7/23 | undefined | undefined | f7 | 197 | assigned | | | | | 198 +----------+------+--------------------------+-----------+----------+ 200 The following extensions to the CBOR diagnostic notation are 201 supported: 203 o Comments can be added to the end of each line. Any characters 204 after a Pound sign ('#') outside of a string, up to the end of the 205 line, are treated as a comment. 207 o Deltas are represented as positive numbers (e.g. +123). 209 3. Properties of the CBOR Encoding 211 This document defines CBOR encoding rules for YANG schema trees and 212 their subtrees. 214 Basic schema nodes such as leaf, leaf-list, list, anydata and anyxml 215 can be encoded standalone. In this case, only the value of this 216 schema node is encoded in CBOR. Identification of this value need to 217 be provided by some external means when needed. 219 A collection such as container, list instance, notification, RPC 220 input, RPC output, action input and action output is serialized using 221 a CBOR map in which each child schema node is encoded using a key and 222 a value. This specification supports three type of keys; SID as 223 defined in [I-D.somaraju-core-sid], member names as defined in 224 [I-D.ietf-netmod-yang-json] and YANG hash as defined by 225 [I-D.vanderstok-core-comi]. Each of these key type is encoded using 226 a specific CBOR type which allows their interpretation during the 227 deserialization process. The end user of this mapping specification 228 can mandate the use of a specific key type or a specific subset of 229 key types. 231 In order to minimize the size of the encoded data, the proposed 232 mapping avoid any unnecessary meta-information beyond those natively 233 supported by CBOR. For instance, CBOR tags are used sorely in the 234 case of the union datatype to distinguish explicitly the use of 235 different YANG datatypes encoded using the same CBOR major type. 237 It is expected that entities generating and decoding CBOR contents 238 have enough knowledge about the information processed in order to 239 perform the expected task without the need of such extra meta- 240 information. The CoAP Content-Format Option, or an HTTP Content-Type 241 header field, conveys that the data is YANG-encoded CBOR in the first 242 place. 244 4. Encoding of YANG Schema Node Instances 246 Schema node instances defined using the YANG modeling language are 247 encoded using CBOR [RFC7049] based on the rules defined in this 248 section. We assume that the reader is already familiar with both 249 YANG [I-D.ietf-netmod-rfc6020bis] and CBOR [RFC7049]. 251 4.1. The 'leaf' Schema Node 253 Leafs MUST be encoded based on the encoding rules specified in 254 Section 5. 256 4.2. The 'container' Schema Node 258 Collections such as containers, list instances, notifications, RPC 259 inputs, RPC outputs, action inputs and action outputs MUST be encoded 260 using a CBOR map data item (major type 5). A map is comprised of 261 pairs of data items, with each data item consisting of a key and a 262 value. Each key within the CBOR map is set to a data node 263 identifier, each value is set to the value of this data node 264 instance. 266 This specification supports three type of keys; SID as defined in 267 [I-D.somaraju-core-sid], member names as defined in 268 [I-D.ietf-netmod-yang-json] and YANG hash as defined by 269 [I-D.vanderstok-core-comi]. 271 *SIDs as keys* 273 Keys implemented using SIDs MUST be encoded using a CBOR unsigned 274 integer (major type 0) or CBOR signed integer (major type 1), 275 depending on the actual value. Keys are set to the delta of the 276 associated SID, delta values are computed as follows: 278 o The delta value is equal to the SID of the current schema node 279 minus the SID of the parent schema node. When no parent exists in 280 the context of use of this container, the delta is set to the SID 281 of the current schema node (a parent with SID equal to zero is 282 assumed). 284 o Delta values may result in a negative number, clients and servers 285 MUST support negative deltas. 287 *Member names as keys* 289 Keys implemented using member names MUST be encoded using a CBOR text 290 string data item (major type 3). A namespace-qualified member name 291 MUST be used for all members of a top-level collection, and then also 292 whenever the namespaces of the schema node and its parent are 293 different. In all other cases, the simple form of the member name 294 MUST be used. Member names and namespaces are defined in 295 [I-D.ietf-netmod-yang-json] section 4. 297 *YANG hashes as keys* 299 Keys implemented using YANG hashes MUST be encoded using a CBOR byte 300 string data item (major type 2). 302 Values MUST be encoded using the appropriate rules defined in 303 Section 4 and Section 5. 305 Definition example [RFC7317]: 307 typedef date-and-time { 308 type string { 309 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 310 \d{2}:\d{2})'; 311 } 312 } 314 container system { 315 leaf hostname { 316 type inet:domain-name; 318 container clock { 319 leaf current-datetime { 320 type date-and-time; 321 } 323 leaf boot-datetime { 324 type date-and-time; 325 } 326 } 327 } 329 *SIDs example* 331 This example is encoded using the SIDs defined in 332 [I-D.somaraju-core-sid] Appendix C. 334 CBOR diagnostic notation: 336 { 337 1708 : { # clock 338 +2 : "2015-10-02T14:47:24Z-05:00", # current-datetime, SID 1710 339 +1 : "2015-09-15T09:12:58Z-05:00" # boot-datetime, SID 1709 340 } 341 } 343 CBOR encoding: 345 a1 # map(1) 346 19 06ac # unsigned(1708) 347 a2 # map(2) 348 02 # unsigned(2) 349 78 1a # text(26) 350 323031352d31302d30325431343a34373a32345a2d30353a3030 351 01 # unsigned(1) 352 78 1a # text(26) 353 323031352d30392d31355430393a31323a35385a2d30353a3030 355 *Member names example* 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 *YANG Hashes example* 383 CBOR diagnostic notation: 385 { 386 h'334c67d9' : { # clock 387 h'047c468b' : "2015-10-02T14:47:24Z-05:00", # current-datetime 388 h'2fe1a167' : "2015-09-15T09:12:58Z-05:00" # boot-datetime 389 } 390 } 392 CBOR encoding: 394 a1 # map(1) 395 44 # bytes(4) 396 334c67d9 397 a2 # map(2) 398 44 # bytes(4) 399 047c468b 400 78 1a # text(26) 401 323031352d31302d30325431343a34373a32345a2d30353a3030 402 44 # bytes(4) 403 2fe1a167 404 78 1a # text(26) 405 323031352d30392d31355430393a31323a35385a2d30353a3030 407 4.3. The 'leaf-list' Schema Node 409 A leaf-list MUST be encoded using a CBOR array data item (major type 410 4). Each entry of this array MUST be encoded using the rules defined 411 by the YANG type specified. 413 Definition example [RFC7317]: 415 typedef domain-name { 416 type string { 417 length "1..253"; 418 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 419 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 420 )|\.'; 421 } 422 } 424 leaf-list search { 425 type domain-name; 426 ordered-by user; 427 } 429 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 431 CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267 433 4.4. The 'list' Schema Node 435 A list MUST be encoded using a CBOR array data item (major type 4). 436 Each list instance within this CBOR array is encoded using a CBOR map 437 data item (major type 5) based on the same rules as a YANG container 438 as defined in Section 4.2. 440 Definition example [RFC7317]: 442 list server { 443 key name; 445 leaf name { 446 type string; 447 } 448 choice transport { 449 case udp { 450 container udp { 451 leaf address { 452 type host; 453 mandatory true; 454 } 455 leaf port { 456 type port-number; 457 } 458 } 459 } 460 } 461 leaf association-type { 462 type enumeration { 463 enum server; 464 enum peer; 465 enum pool; 466 } 467 default server; 468 } 469 leaf iburst { 470 type boolean; 471 default false; 472 } 473 leaf prefer { 474 type boolean; 475 default false; 476 } 477 } 479 *SIDs example* 481 SIDs used in this example are defined in [I-D.somaraju-core-sid] 482 Appendix C. It is important to note that the protocol or method 483 using this mapping may carry a parent SID or may have the knowledge 484 of this parent SID based on its context. In these cases, delta 485 encoding can be performed based on this parent SID which minimizes 486 the size of the encoded data. 488 CBOR diagnostic notation: 490 [ 491 { 492 1746 : "NRC TIC server", # name 493 1748 : { # udp 494 +1 : "tic.nrc.ca", # address, SID 1749 495 +2 : 123 # port, SID 1750 496 }, 497 1744 : 0, # association-type 498 1745 : false, # iburst 499 1747 : true # prefer 500 }, 501 { 502 1746 : "NRC TAC server", # name 503 1748 : { # udp 504 +1 : "tac.nrc.ca" # address, SID 1749 505 } 506 } 507 ] 509 CBOR encoding: 511 82 # array(2) 512 a5 # map(5) 513 19 06d2 # unsigned(1746) 514 6e # text(14) 515 4e52432054494320736572766572 # "NRC TIC server" 516 19 06d4 # unsigned(1748) 517 a2 # map(2) 518 01 # unsigned(1) 519 6a # text(10) 520 7469632e6e72632e6361 # "tic.nrc.ca" 521 02 # unsigned(2) 522 18 7b # unsigned(123) 523 19 06d0 # unsigned(1744) 524 00 # unsigned(0) 525 19 06d1 # unsigned(1745) 526 f4 # primitive(20) 527 19 06d3 # unsigned(1747) 528 f5 # primitive(21) 529 a2 # map(2) 530 19 06d2 # unsigned(1746) 531 6e # text(14) 532 4e52432054414320736572766572 # "NRC TAC server" 533 19 06d4 # unsigned(1748) 534 a1 # map(1) 535 01 # unsigned(1) 536 6a # text(10) 537 7461632e6e72632e6361 # "tac.nrc.ca" 539 *Member names example* 541 CBOR diagnostic notation: 543 [ 544 { 545 "ietf-system:name" : "NRC TIC server", 546 "ietf-system:udp" : { 547 "address" : "tic.nrc.ca", 548 "port" : 123 549 }, 550 "ietf-system:association-type" : 0, 551 "ietf-system:iburst" : false, 552 "ietf-system:prefer" : true 553 }, 554 { 555 "ietf-system:name" : "NRC TAC server", 556 "ietf-system:udp" : { 557 "address" : "tac.nrc.ca" 558 } 559 } 560 ] 562 CBOR encoding: 564 82 # array(2) 565 a5 # map(5) 566 70 # text(16) 567 696574662d73797374656d3a6e616d65 # "ietf-system:name" 568 6e # text(14) 569 4e52432054494320736572766572 # "NRC TIC server" 570 6f # text(15) 571 696574662d73797374656d3a756470 # "ietf-system:udp" 572 a2 # map(2) 573 67 # text(7) 574 61646472657373 # "address" 575 6a # text(10) 576 7469632e6e72632e6361 # "tic.nrc.ca" 577 64 # text(4) 578 706f7274 # "port" 579 18 7b # unsigned(123) 580 78 1c # text(28) 581 696574662d73797374656d3a6173736f63696174696f6e2d74797065 582 00 # unsigned(0) 583 72 # text(18) 584 696574662d73797374656d3a696275727374 # "ietf-system:iburst" 585 f4 # primitive(20) 586 72 # text(18) 587 696574662d73797374656d3a707265666572 # "ietf-system:prefer" 588 f5 # primitive(21) 589 a2 # map(2) 590 70 # text(16) 591 696574662d73797374656d3a6e616d65 # "ietf-system:name" 592 6e # text(14) 593 4e52432054414320736572766572 # "NRC TAC server" 594 6f # text(15) 595 696574662d73797374656d3a756470 # "ietf-system:udp" 596 a1 # map(1) 597 67 # text(7) 598 61646472657373 # "address" 599 6a # text(10) 600 7461632e6e72632e6361 # "tac.nrc.ca" 602 *YANG hashes example* 604 CBOR diagnostic notation: 606 [ 607 { 608 h'06c32032' : "NRC TIC server", # name 609 h'11889c84' : { # udp 610 h'3158c529' : "tic.nrc.ca", # address 611 h'34492d05' : 123 # port 612 }, 613 h'2c2c2ccf' : 0, # association-type 614 h'1058dc5d' : false, # iburst 615 h'390e346a' : true # prefer 616 }, 617 { 618 h'06c32032' : "NRC TAC server", # name 619 h'11889c84' : { # udp 620 h'3158c529' : "tac.nrc.ca" # address 621 } 622 } 623 ] 625 CBOR encoding: 627 82 # array(2) 628 a5 # map(5) 629 44 # bytes(4) 630 06c32032" 631 6e # text(14) 632 4e52432054494320736572766572 # "NRC TIC server" 633 44 # bytes(4) 634 11889c84 " 635 a2 # map(2) 636 44 # bytes(4) 637 3158c529 638 6a # text(10) 639 7469632e6e72632e6361 # "tic.nrc.ca" 640 44 # bytes(4) 641 34492d05 642 18 7b # unsigned(123) 643 44 # bytes(4) 644 2c2c2ccf 645 00 # unsigned(0) 646 44 # bytes(4) 647 1058dc5d 648 f4 # primitive(20) 649 44 # bytes(4) 650 390e346a 651 f5 # primitive(21) 652 a2 # map(2) 653 44 # bytes(4) 654 06c32032 655 6e # text(14) 656 4e52432054414320736572766572 # "NRC TAC server" 657 44 # bytes(4) 658 11889c84 659 a1 # map(1) 660 44 # bytes(4) 661 3158c529 662 6a # text(10) 663 7461632e6e72632e6361 # "tac.nrc.ca" 665 4.5. The 'anydata' Schema Node 667 An anydata serves as a container for an arbitrary set of schema nodes 668 that otherwise appear as normal YANG-modeled data. An anydata 669 instance is encoded using the same rules as a container, i.e., CBOR 670 map. The requirement that anydata content can be modeled by YANG 671 implies the following: 673 o Keys MUST be set to valid SIDs, member names or YANG hashes. This 674 rule applies to the key of the anydata node and the key of any 675 inner schema node. 677 o The CBOR array MUST contain either unique scalar values (as a 678 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 680 o Values MUST follow the encoding rules of one of the datatypes 681 listed in Section 5. 683 4.6. The 'anyxml' Schema Node 685 An anyxml instance is encoded as a CBOR key/value pair. The key of 686 the anyxml schema node MUST be a valid SID, member name or YANG hash 687 but the value is unrestricted, i.e., the value can be any CBOR 688 encoded content. 690 5. Representing YANG Data Types in CBOR 692 5.1. The unsigned integer Types 694 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 695 a CBOR unsigned integer data item (major type 0). 697 Definition example [RFC7277]: 699 leaf mtu { 700 type uint16 { 701 range "68..max"; 702 } 703 } 705 CBOR diagnostic notation: 1280 707 CBOR encoding: 19 0500 709 5.2. The integer Types 711 Leafs of type int8, int16, int32 and int64 MUST be encoded using 712 either CBOR unsigned integer (major type 0) or CBOR signed integer 713 (major type 1), depending on the actual value. 715 Definition example [RFC7317]: 717 leaf timezone-utc-offset { 718 type int16 { 719 range "-1500 .. 1500"; 720 } 721 } 723 CBOR diagnostic notation: -300 725 CBOR encoding: 39 012b 727 5.3. The 'decimal64' Type 729 f type decimal64 MUST be encoded using either CBOR unsigned integer 730 (major type 0) or CBOR signed integer (major type 1), depending on 731 the actual value. Leafs oThe position of the decimal point is 732 defined by the fraction-digits YANG statement and is not available in 733 the CBOR encoding. 735 Definition example [RFC7317]: 737 leaf my-decimal { 738 type decimal64 { 739 fraction-digits 2; 740 range "1 .. 3.14 | 10 | 20..max"; 741 } 742 } 744 CBOR diagnostic notation: 257 (Represents decimal value 2.57) 746 CBOR encoding: 19 0101 748 5.4. The 'string' Type 750 Leafs of type string MUST be encoded using a CBOR text string data 751 item (major type 3). 753 Definition example [RFC7223]: 755 leaf name { 756 type string; 757 } 759 CBOR diagnostic notation: "eth0" 761 CBOR encoding: 64 65746830 763 5.5. The 'boolean' Type 765 Leafs of type boolean MUST be encoded using a CBOR true (major type 766 7, additional information 21) or false data item (major type 7, 767 additional information 20). 769 Definition example [RFC7317]: 771 leaf enabled { 772 type boolean; 773 } 775 CBOR diagnostic notation: true 777 CBOR encoding: f5 779 5.6. The 'enumeration' Type 781 Leafs of type enumeration MUST be encoded using a CBOR unsigned 782 integer (major type 0) or CBOR signed integer (major type 1), 783 depending on the actual value. Enumeration values are either 784 explicitly assigned using the YANG statement 'value' or automatically 785 assigned based on the algorithm defined in 786 [I-D.ietf-netmod-rfc6020bis] section 9.6.4.2. 788 Definition example [RFC7317]: 790 leaf oper-status { 791 type enumeration { 792 enum up { value 1; } 793 enum down { value 2; } 794 enum testing { value 3; } 795 enum unknown { value 4; } 796 enum dormant { value 5; } 797 enum not-present { value 6; } 798 enum lower-layer-down { value 7; } 799 } 800 } 802 CBOR diagnostic notation: 3 (Represents enumeration value 'testing') 804 CBOR encoding: 03 806 5.7. The 'bits' Type 808 Leafs of type bits MUST be encoded using a CBOR byte string data item 809 (major type 2). Bits position are either explicitly assigned using 810 the YANG statement 'position' or automatically assigned based on the 811 algorithm defined in [I-D.ietf-netmod-rfc6020bis] section 9.7.4.2. 813 Bits position 0 to 7 are assigned to the first byte within the byte 814 string, bits 8 to 15 to the second byte, and subsequent bytes are 815 assigned similarly. Within each byte, bits are assigned from least 816 to most significant. 818 Definition example [I-D.ietf-netmod-rfc6020bis]: 820 leaf mybits { 821 type bits { 822 bit disable-nagle { 823 position 0; 824 } 825 bit auto-sense-speed { 826 position 1; 827 } 828 bit 10-Mb-only { 829 position 2; 830 } 831 } 832 } 834 CBOR diagnostic notation: h'05' (Represents bits disable-nagle and 835 10-Mb-only set) 837 CBOR encoding: 41 05 839 5.8. The 'binary' Type 841 Leafs of type binary MUST be encoded using a CBOR byte string data 842 item (major type 2). 844 Definition example: 846 leaf aes128-key { 847 type binary { 848 length 16; 849 } 850 } 852 CBOR diagnostic notation: h'1f1ce6a3f42660d888d92a4d8030476e' 854 CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e 856 5.9. The 'leafref' Type 858 Leafs of type leafref MUST be encoded using the rules of the schema 859 node referenced by the 'path' YANG statement. 861 Definition example [RFC7223]: 863 typedef interface-state-ref { 864 type leafref { 865 path "/interfaces-state/interface/name"; 866 } 867 } 869 container interfaces-state { 870 list interface { 871 key "name"; 872 leaf name { 873 type string; 874 } 875 leaf-list higher-layer-if { 876 type interface-state-ref; 877 } 878 } 879 } 881 CBOR diagnostic notation: "eth1" 883 CBOR encoding: 64 65746831 885 5.10. The 'identityref' Type 887 This specification supports two approaches for encoding identityref, 888 a SID as defined in [I-D.somaraju-core-sid] or a name as defined in 889 [I-D.ietf-netmod-yang-json] section 6.8. 891 *SIDs as identityref* 893 SIDs are globally unique and can be used as identityref. This 894 approach is both compact and simple to implement. When SIDs are 895 used, identityref MUST be encoded using a CBOR unsigned integer data 896 item (major type 0) or CBOR signed integer (major type 1), depending 897 on the actual value. The value represents the delta between the SID 898 of the identity assigned to the leaf and the SID of the base identity 899 defined for this leaf. 901 *Name as identityref* 902 Alternatively, an identityref may be encoded using a name as defined 903 in [I-D.ietf-netmod-yang-json] section 6.8. When names are used, 904 identityref MUST be encoded using a CBOR text string data item (major 905 type 3). If the identity is defined in another module than the leaf 906 node containing the identityref value, the namespace-qualified form 907 MUST be used. Otherwise, both the simple and namespace-qualified 908 forms are permitted. 910 Definition example [RFC7317]: 912 identity radius-authentication-type { 913 description 914 "Base identity for RADIUS authentication types."; 915 } 917 identity radius-chap { 918 base radius-authentication-type; 919 } 921 identity radius-pap { 922 base radius-authentication-type; 923 } 925 leaf authentication-type { 926 type identityref { 927 base radius-authentication-type; 928 } 929 } 931 *SIDs as identityref* 933 This example represents the encoding of identity "radius-pap" (SID 934 1705) assuming the base identity "radius-authentication-type" (SID 935 1703). 937 CBOR diagnostic notation: 2 939 CBOR encoding: 02 941 *Name as identityref* 943 CBOR diagnostic notation: "ietf-system:radius-pap" 945 CBOR encoding: 76 696574662d73797374656d3a7261646975732d706170 947 5.11. The 'empty' Type 949 Leafs of type empty MUST be encoded using the CBOR null value (major 950 type 7, additional information 22). 952 Definition example [RFC7277]: 954 leaf is-router { 955 type empty; 956 } 958 CBOR diagnostic notation: null 960 CBOR encoding: f6 962 5.12. The 'union' Type 964 Leafs of type union MUST be encoded using the rules associated with 965 one of the types listed. When used in a union, the following YANG 966 datatypes are prefixed by CBOR tag to avoid confusion between 967 different YANG datatypes encoded using the same CBOR major type. 969 o bits 971 o decimal64 973 o enumeration 975 o identityref 977 o instance-identifier 979 o leafref (Only when the datatype of the leaf referenced using the 980 'path' YANG statement require a CBOR tag) 982 See Section 7.1 for more information about these CBOR tags. 984 Definition example [RFC7317]: 986 typedef ipv4-address { 987 type string { 988 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 989 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 990 \p{L}]+)?'; 991 } 992 } 994 typedef ipv6-address { 995 type string { 996 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 997 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 998 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 999 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 1000 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 1001 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 1002 } 1003 } 1005 typedef ip-address { 1006 type union { 1007 type ipv4-address; 1008 type ipv6-address; 1009 } 1010 } 1012 leaf address { 1013 type inet:ip-address; 1014 } 1016 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 1018 CBOR encoding: 74 323030313a6462383a6130623a313266303a3a31 1020 5.13. The 'instance-identifier' Type 1022 This specification supports three approaches for encoding an 1023 instance-identifier, one based on SIDs as defined in 1024 [I-D.somaraju-core-sid], one based on names as defined in 1025 [I-D.ietf-netmod-yang-json] section 6.13 and one based on YANG hashes 1026 as defined in [I-D.vanderstok-core-comi]. 1028 *SIDs as instance-identifier* 1030 SIDs uniquely identify a data node. For a single instance data node, 1031 the SID is sufficient to identify this instance. For a multi- 1032 instance data node, a SID is combined with the list key(s) to 1033 identify each instance of this data node within the YANG list(s). 1035 Single instance data nodes MUST be encoded using a CBOR unsigned 1036 integer data item (major type 0) and set to the targeted data node 1037 SID. 1039 Multi-instances data nodes MUST be encoded using a CBOR array data 1040 item (major type 4) containing the following entries: 1042 o The first entry MUST be encoded as a CBOR unsigned integer data 1043 item (major type 0) and set to the targeted data node SID. 1045 o The following entries MUST contain the value of each key required 1046 to identify the instance of the targeted data node. These keys 1047 MUST be ordered as defined in the 'key' YANG statement, starting 1048 from top level list, and follow by each of the subordinate 1049 list(s). 1051 *Names as instance-identifier* 1053 The use of names as instance-identifier is defined in 1054 [I-D.ietf-netmod-yang-json] section 6.11. The resulting xpath MUST 1055 be encoded using a CBOR text string data item (major type 3). 1057 *YANG hashes as instance-identifier* 1059 When YANG hashes are used, xpath can be compressed based on the 1060 method defined by [I-D.vanderstok-core-comi] sections 4.1.4.1 and 1061 4.1.4.2. The resulting hash MUST be encoded using a CBOR byte string 1062 data item (major type 2). 1064 Definition example [RFC7317]: 1066 container system { 1068 leaf contact { 1069 type string; 1070 } 1072 leaf hostname { 1073 type inet:domain-name; 1074 } 1075 } 1077 *First example based on SID* 1079 In this example, a field of type instance-identifier identifies the 1080 data node "/system/contact" (SID 1728). 1082 1728 1083 CBOR encoding: 1085 19 06c0 1087 *First example based on name* 1089 Same example as above based on names. 1091 "/ietf-system:system/contact" 1093 CBOR encoding: 1095 78 1c 2f20696574662d73797374656d3a73797374656d2f636f6e74616374 1097 *First example based on YANG hash* 1099 Same example assuming data node "/system/contact" is associated to 1100 YANG hash 0x09b06d17 or "JsG0X" in base64. 1102 CBOR diagnostic notation: 1104 "/JsG0X" 1106 CBOR encoding: 1108 66 2f4a73473058 1110 Definition example [RFC7317]: 1112 list user { 1113 key name; 1115 leaf name { 1116 type string; 1117 } 1118 leaf password { 1119 type ianach:crypt-hash; 1120 } 1122 list authorized-key { 1123 key name; 1125 leaf name { 1126 type string; 1127 } 1128 leaf algorithm { 1129 type string; 1130 } 1131 leaf key-data { 1132 type binary; 1133 } 1134 } 1136 *Second example based on SID* 1138 In this example, a field of type instance-identifier identify the 1139 data node "/system/authentication/user/authorized-key/key-data" (SID 1140 1721) for the user name "bob" and the authorized-key name "admin". 1142 CBOR diagnostic notation: 1144 [1721, "bob", "admin"] 1146 CBOR encoding: 1148 83 # array(3) 1149 19 06b9 # unsigned(1721) 1150 63 # text(3) 1151 626f62 # "bob" 1152 65 # text(5) 1153 61646d696e # "admin" 1155 *Second example based on name* 1157 Same example as above based on names. 1159 CBOR diagnostic notation: 1161 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1162 [name='admin']/key-data" 1164 CBOR encoding: 1166 78 59 1167 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1168 74696f6e2f757365725b6e616d653d27626f62275d2f617574686f72697a 1169 65642d6b65795b6e616d653d2761646d696e275d2f6b65792d64617461 1171 *Second example based on YANG hash* 1173 Same example assuming data node "/ietf- 1174 system:system/authentication/user/authorized-key/key-data" is 1175 associated to YANG hash 0x0d6e7afb or "Nbnr7" in base64. 1177 CBOR diagnostic notation: 1179 "/Nbnr7?keys=\"bob\",\"admin\"" 1181 CBOR encoding: 1183 78 19 2f4e626e72373f6b6579733d22626f62222c2261646d696e22 1185 *Third example based on SID* 1187 This third example identify an instance within the list 1188 "/system/authentication/user" (SID 1717) corresponding to the user 1189 name "jack". 1191 CBOR diagnostic notation: 1193 [1717, "jack"] 1195 CBOR encoding: 1197 82 # array(2) 1198 19 06b5 # unsigned(1717) 1199 64 # text(4) 1200 6a61636b # "jack" 1202 *Third example based on name* 1204 Same example as above based on names. 1206 CBOR diagnostic notation: 1208 "/ietf-system:system/authentication/user[name='bob']" 1209 CBOR encoding: 1211 78 33 1212 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1213 74696f6e2f757365725b6e616d653d27626f62275d 1215 *Third example based on YANG hash* 1217 Same example assuming data node "/ietf-system:system/authentication/ 1218 user" is associated to YANG hash 0x2677c6c1 or "md8bB" in base64. 1220 CBOR diagnostic notation: 1222 "/md8bB?keys=\"bob\"" 1224 CBOR encoding: 1226 71 2f6d643862423f6b6579733d22626f6222 1228 6. Security Considerations 1230 The security considerations of [RFC7049] and 1231 [I-D.ietf-netmod-rfc6020bis] apply. 1233 This document defines an alternative encoding for data modeled in the 1234 YANG data modeling language. As such, this encoding does not 1235 contribute any new security issues in addition of those identified 1236 for the specific protocol or context for which it is used. 1238 To minimize security risks, software on the receiving side SHOULD 1239 reject all messages that do not comply to the rules of this document 1240 and reply with an appropriate error message to the sender. 1242 7. IANA Considerations 1244 7.1. Tags Registry 1246 This specification requires the assignment of CBOR tags for the 1247 following YANG datatypes. These tags are added to the Tags Registry 1248 as defined in section 7.2 of [RFC7049]. 1250 +-----+---------------------+---------------------------+-----------+ 1251 | Tag | Data Item | Semantics | Reference | 1252 +-----+---------------------+---------------------------+-----------+ 1253 | 40 | bits | YANG bits datatype | RFC XXXX | 1254 | 41 | decimal64 | YANG decimal64 datatype | RFC XXXX | 1255 | 42 | enumeration | YANG enumeration datatype | RFC XXXX | 1256 | 43 | identityref | YANG identityref datatype | RFC XXXX | 1257 | 44 | instance-identifier | YANG instance-identifier | RFC XXXX | 1258 | | | datatype | | 1259 +-----+---------------------+---------------------------+-----------+ 1261 // RFC Ed.: update Tag values using allocated tags if needed and 1262 remove this note // RFC Ed.: replace XXXX with RFC number and remove 1263 this note 1265 8. Acknowledgments 1267 This document has been largely inspired by the extensive works done 1268 by Andy Bierman and Peter van der Stok on [I-D.vanderstok-core-comi]. 1269 [I-D.ietf-netmod-yang-json] has also been a critical input to this 1270 work. The authors would like to thank the authors and contributors 1271 to these two drafts. 1273 The authors would also like to acknowledge the review, feedback, and 1274 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1276 9. References 1278 9.1. Normative References 1280 [I-D.ietf-netmod-rfc6020bis] 1281 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1282 draft-ietf-netmod-rfc6020bis-14 (work in progress), June 1283 2016. 1285 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1286 Requirement Levels", BCP 14, RFC 2119, 1287 DOI 10.17487/RFC2119, March 1997, 1288 . 1290 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1291 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1292 October 2013, . 1294 9.2. Informative References 1296 [I-D.ietf-netmod-yang-json] 1297 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1298 draft-ietf-netmod-yang-json-10 (work in progress), March 1299 2016. 1301 [I-D.somaraju-core-sid] 1302 Somaraju, A., Veillette, M., Pelov, A., Turner, R., and A. 1303 Minaburo, "Structure Identifier (SID)", draft-somaraju- 1304 core-sid-00 (work in progress), March 2016. 1306 [I-D.vanderstok-core-comi] 1307 Stok, P. and A. Bierman, "CoAP Management Interface", 1308 draft-vanderstok-core-comi-09 (work in progress), March 1309 2016. 1311 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1312 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1313 2014, . 1315 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1316 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1317 . 1319 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1320 Constrained-Node Networks", RFC 7228, 1321 DOI 10.17487/RFC7228, May 2014, 1322 . 1324 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1325 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1326 . 1328 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1329 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1330 2014, . 1332 Authors' Addresses 1334 Michel Veillette (editor) 1335 Trilliant Networks Inc. 1336 610 Rue du Luxembourg 1337 Granby, Quebec J2J 2V2 1338 Canada 1340 Phone: +14503750556 1341 Email: michel.veillette@trilliantinc.com 1342 Alexander Pelov (editor) 1343 Acklio 1344 2bis rue de la Chataigneraie 1345 Cesson-Sevigne, Bretagne 35510 1346 France 1348 Email: a@ackl.io 1350 Abhinav Somaraju 1351 Tridonic GmbH & Co KG 1352 Farbergasse 15 1353 Dornbirn, Vorarlberg 6850 1354 Austria 1356 Phone: +43664808926169 1357 Email: abhinav.somaraju@tridonic.com 1359 Randy Turner 1360 Landis+Gyr 1361 30000 Mill Creek Ave 1362 Suite 100 1363 Alpharetta, GA 30022 1364 US 1366 Phone: ++16782581292 1367 Email: randy.turner@landisgyr.com 1368 URI: http://www.landisgyr.com/ 1370 Ana Minaburo 1371 Acklio 1372 2bis rue de la chataigneraie 1373 Cesson-Sevigne, Bretagne 35510 1374 France 1376 Email: ana@ackl.io