idnits 2.17.1 draft-veillette-core-yang-cbor-mapping-00.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 document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** 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 (March 11, 2016) is 2958 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'I-D.somaraju-core-sid' is mentioned on line 864, but not defined == Missing Reference: '0-9' is mentioned on line 954, but not defined == Missing Reference: '1-9' is mentioned on line 945, but not defined == Missing Reference: '0-4' is mentioned on line 954, but not defined == Missing Reference: '0-5' is mentioned on line 954, but not defined == Missing Reference: '0-9a-fA-F' is mentioned on line 953, but not defined -- Looks like a reference, but probably isn't: '01' on line 954 == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-11 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-yang-json-09 == 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: 3 errors (**), 0 flaws (~~), 11 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: Informational A. Pelov, Ed. 5 Expires: September 12, 2016 Acklio 6 A. Somaraju 7 Tridonic GmbH & Co KG 8 R. Turner 9 Landis+Gyr 10 A. Minaburo 11 Acklio 12 March 11, 2016 14 CBOR Encoding of Data Modeled with YANG 15 draft-veillette-core-yang-cbor-mapping-00 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 September 12, 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 . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . . 20 79 5.10. The "identityref" Type . . . . . . . . . . . . . . . . . 21 80 5.11. The "empty" Type . . . . . . . . . . . . . . . . . . . . 22 81 5.12. The "union" Type . . . . . . . . . . . . . . . . . . . . 23 82 5.13. The "instance-identifier" Type . . . . . . . . . . . . . 23 83 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 84 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 28 85 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 86 8.1. Normative References . . . . . . . . . . . . . . . . . . 29 87 8.2. Informative References . . . . . . . . . . . . . . . . . 29 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 90 1. Introduction 92 The specification of the YANG 1.1 data modelling language 93 [I-D.ietf-netmod-rfc6020bis] defines only an XML encoding for data 94 instances, i.e. contents of configuration datastores, state data, RPC 95 inputs and outputs, action inputs and outputs, and event 96 notifications. 98 A new set of encoding rules has been defined to allow the use of the 99 same data models in environments based on the JavaScript Object 100 Notation (JSON) Data Interchange Format [RFC7159]. This is 101 accomplished in the JSON Encoding of Data Modeled with YANG 102 specification [I-D.ietf-netmod-yang-json]. 104 The aim of this document is to define a set of encoding rules for the 105 Concise Binary Object Representation (CBOR) [RFC7049]. The resulting 106 encoding is more compact compared to XML and JSON and more suitable 107 for Constrained Nodes and/or Constrained Networks as defined by 108 [RFC7228]. 110 2. Terminology and Notation 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in [RFC2119]. 116 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 118 o action 120 o anydata 122 o anyxml 124 o data node 126 o data tree 128 o module 130 o notification 132 o RPC 134 o schema node 136 o schema tree 138 o submodule 140 The following terms are defined in [I-D.ietf-netmod-yang-json]: 142 o member name 144 o name of an identity 145 The following term is defined in [I-D.vanderstok-core-comi]: 147 o YANG hash 149 This specification also makes use of the following terminology: 151 o child: A schema node defined within a collection such as a 152 container, a list, a case, a notification, an RPC input, an RPC 153 output, an action input, an action output. 155 o delta : Difference between the SID assigned to the current schema 156 node and the SID assigned to the parent. 158 o parent: The collection in which a schema node is defined. 160 o structured identifier or SID: Unsigned integer used to identify 161 different YANG items. 163 2.1. CBOR diagnostic notation 165 Within this document, CBOR binary contents are represented using an 166 equivalent textual form called CBOR diagnostic notation as defined in 167 [RFC7049] section 6. This notation is used strictly for 168 documentation purposes and is never used in the data serialization. 170 +----------+------+--------------------------+-----------+----------+ 171 | CBOR | CBOR | Diagnostic notation | Example | CBOR | 172 | content | type | | | encoding | 173 +----------+------+--------------------------+-----------+----------+ 174 | Unsigned | 0 | Decimal digits | 123 | 18 7b | 175 | integer | | | | | 176 | Negative | 1 | Decimal digits prefixed | -123 | 38 7a | 177 | integer | | by a minus sign | | | 178 | Byte | 2 | Hexadecimal value | h'f15c' | 42 f15c | 179 | string | | enclosed between single | | | 180 | | | quotes and prefixed by | | | 181 | | | an 'h' | | | 182 | Text | 3 | String of Unicode | "txt" | 63 | 183 | string | | characters enclosed | | 747874 | 184 | | | between double quotes | | | 185 | Array | 4 | Comma-separated list of | [ 1, 2 ] | 82 01 02 | 186 | | | values within square | | | 187 | | | brackets | | | 188 | Map | 5 | Comma-separated list of | { 1: 123, | a2 | 189 | | | key : value pairs within | 2: 456 } | 01187b | 190 | | | curly braces | | 021901c8 | 191 | Boolean | 7/20 | false | false | f4 | 192 | | 7/21 | true | true | f5 | 193 | Null | 7/22 | null | null | f6 | 194 | Not | 7/23 | undefined | undefined | f7 | 195 | assigned | | | | | 196 +----------+------+--------------------------+-----------+----------+ 198 Within this document, comments are allowed in CBOR diagnostic 199 notation. Any characters after a Pound sign ('#') outside of a 200 string, up to the end of the line, are treated as a comment. 202 3. Properties of the CBOR Encoding 204 This document defines CBOR encoding rules for YANG schema trees and 205 their subtrees. 207 Basic schema nodes such as leaf, leaf-list, list, anydata and anyxml 208 can be encoded standalone. In this case, only the value of this 209 schema node is encoded in CBOR. Identification of this value need to 210 be provided by some external means when needed. 212 A collection such as container, list instance, notification, RPC 213 input, RPC output, action input and action output is serialized using 214 a CBOR map in which each child schema node is encoded using a key and 215 a value. This specification supports three type of keys; SID as 216 defined in [I-D.somaraju-core-sid], member names as defined in 217 [I-D.ietf-netmod-yang-json] and YANG hash as defined by 219 [I-D.vanderstok-core-comi]. Each of these key type is encoded using 220 a specific CBOR type which allows their interpretation during the 221 deserialization process. The end user of this mapping specification 222 can mandate the use of a specific key type or a specific subset of 223 key types. 225 In order to minimize the size of the encoded data, the proposed 226 mapping does not make use of any meta-information beyond those 227 natively supported by CBOR. For instance, CBOR tags are not used for 228 any of the proposed mapping. It is expected that entities generating 229 and decoding CBOR contents have enough knowledge about the 230 information processed in order to perform the expected task without 231 the need of such extra meta-information. The CoAP Content-Format 232 Option, or an HTTP Content-Type header field, conveys that the data 233 is YANG-encoded CBOR in the first place. 235 4. Encoding of YANG Schema Node Instances 237 Schema node instances defined using the YANG modeling language are 238 encoded using CBOR [RFC7049] based on the rules defined in this 239 section. We assume that the reader is already familiar with both 240 YANG [I-D.ietf-netmod-rfc6020bis] and CBOR [RFC7049]. 242 4.1. The "leaf" Schema Node 244 Leafs MUST be encoded based on the encoding rules specified in 245 Section 5. 247 4.2. The "container" Schema Node 249 Collections such as containers, list instances, notifications, RPC 250 inputs, RPC outputs, action inputs and action outputs MUST be encoded 251 using a CBOR map data item (major type 5). A map is comprised of 252 pairs of data items, with each data item consisting of a key and a 253 value. This specification supports three type of keys; SID as 254 defined in [I-D.somaraju-core-sid], member names as defined in 255 [I-D.ietf-netmod-yang-json] and YANG hash as defined by 256 [I-D.vanderstok-core-comi]. 258 *SIDs as keys* 260 Keys implemented using SIDs MUST be encoded using a CBOR unsigned 261 integer (major type 0) and set to the delta value of the associated 262 SID. Delta values are computed as follows: 264 o The delta value is equal to the SID of the current schema node 265 minus the SID of the parent schema node. When no parent exists in 266 the context of use of this container, the delta is set to the SID 267 of the current schema node (a parent with SID equal to zero is 268 assumed). 270 o Delta values may result in a negative number, clients and servers 271 MUST support negative deltas. 273 *Member names as keys* 275 Keys implemented using member names MUST be encoded using a CBOR text 276 string data item (major type 3). A namespace-qualified member name 277 MUST be used for all members of a top-level collection, and then also 278 whenever the namespaces of the schema node and its parent are 279 different. In all other cases, the simple form of the member name 280 MUST be used. Member names and namespaces are defined in 281 [I-D.ietf-netmod-yang-json] section 4. 283 *YANG hashes as keys* 285 Keys implemented using YANG hashes MUST be encoded using a CBOR byte 286 string data item (major type 2). 288 Values MUST be encoded using the appropriate rules defined in 289 Section 4 and Section 5. 291 Definition example [RFC7317]: 293 typedef date-and-time { 294 type string { 295 pattern '\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[\+\-] 296 \d{2}:\d{2})'; 297 } 298 } 300 container system { 301 leaf hostname { 302 type inet:domain-name; 304 container clock { 305 leaf current-datetime { 306 type date-and-time; 307 } 309 leaf boot-datetime { 310 type date-and-time; 311 } 312 } 313 } 314 *SIDs example* 316 This example is encoded using the SIDs defined in [I-D.somaraju-core- 317 sid] Appendix C. 319 CBOR diagnostic notation: 321 { 322 1708 : { # clock 323 2 : "2015-10-02T14:47:24Z-05:00", # current-datetime, SID 1710 324 1 : "2015-09-15T09:12:58Z-05:00" # boot-datetime, SID 1709 325 } 326 } 328 CBOR encoding: 330 a1 # map(1) 331 19 06ac # unsigned(1708) 332 a2 # map(2) 333 02 # unsigned(2) 334 78 1a # text(26) 335 323031352d31302d30325431343a34373a32345a2d30353a3030 336 01 # unsigned(1) 337 78 1a # text(26) 338 323031352d30392d31355430393a31323a35385a2d30353a3030 340 *Member names example* 342 CBOR diagnostic notation: 344 { 345 "ietf-system:clock" : { 346 "current-datetime" : "2015-10-02T14:47:24Z-05:00", 347 "boot-datetime" : "2015-09-15T09:12:58Z-05:00" 348 } 349 } 351 CBOR encoding: 353 a1 # map(1) 354 71 # text(17) 355 696574662d73797374656d3a636c6f636b # "ietf-system:clock" 356 a2 # map(2) 357 70 # text(16) 358 63757272656e742d6461746574696d65 # "current-datetime" 359 78 1a # text(26) 360 323031352d31302d30325431343a34373a32345a2d30353a3030 361 6d # text(13) 362 626f6f742d6461746574696d65 # "boot-datetime" 363 78 1a # text(26) 364 323031352d30392d31355430393a31323a35385a2d30353a3030 366 *YANG Hashes example* 368 CBOR diagnostic notation: 370 { 371 h'334c67d9' : { # clock 372 h'047c468b' : "2015-10-02T14:47:24Z-05:00", # current-datetime 373 h'2fe1a167' : "2015-09-15T09:12:58Z-05:00" # boot-datetime 374 } 375 } 377 CBOR encoding: 379 a1 # map(1) 380 44 # bytes(4) 381 334c67d9 382 a2 # map(2) 383 44 # bytes(4) 384 047c468b 385 78 1a # text(26) 386 323031352d31302d30325431343a34373a32345a2d30353a3030 387 44 # bytes(4) 388 2fe1a167 389 78 1a # text(26) 390 323031352d30392d31355430393a31323a35385a2d30353a3030 392 4.3. The "leaf-list" Schema Node 394 A leaf-list MUST be encoded using a CBOR array data item (major type 395 4). Each entry of this array MUST be encoded using the rules defined 396 by the YANG type specified. 398 Definition example [RFC7317]: 400 typedef domain-name { 401 type string { 402 length "1..253"; 403 pattern '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9].) 404 *([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.? 405 )|\.'; 406 } 407 } 409 leaf-list search { 410 type domain-name; 411 ordered-by user; 412 } 414 CBOR diagnostic notation: [ "ietf.org", "ieee.org" ] 416 CBOR encoding: 82 68 696574662e6f7267 68 696565652e6f7267 418 4.4. The "list" Schema Node 420 A list MUST be encoded using a CBOR array data item (major type 4). 421 Each entry of this array is encoded using a CBOR map data item (major 422 type 5) based on the same rules as a YANG container, see Section 4.2. 424 Definition example [RFC7317]: 426 list server { 427 key name; 429 leaf name { 430 type string; 431 } 432 choice transport { 433 case udp { 434 container udp { 435 leaf address { 436 type host; 437 mandatory true; 438 } 439 leaf port { 440 type port-number; 441 } 442 } 443 } 444 } 445 leaf association-type { 446 type enumeration { 447 enum server; 448 enum peer; 449 enum pool; 450 } 451 default server; 452 } 453 leaf iburst { 454 type boolean; 455 default false; 456 } 457 leaf prefer { 458 type boolean; 459 default false; 460 } 461 } 463 *SIDs example* 465 SIDs used in this example are defined in [I-D.somaraju-core-sid] 466 Appendix C. It is important to note that the protocol or method 467 using this mapping may carry a parent SID or may have the knowledge 468 of this parent SID based on its context. In these cases, delta 469 encoding can be performed based on this parent SID which minimizes 470 the size of the encoded data. 472 CBOR diagnostic notation: 474 [ 475 { 476 1746 : "NRC TIC server", # name 477 1748 : { # udp 478 1 : "tic.nrc.ca", # address, SID 1749 479 2 : 123 # port, SID 1750 480 }, 481 1744 : 0, # association-type 482 1745 : false, # iburst 483 1747 : true # prefer 484 }, 485 { 486 1746 : "NRC TAC server", # name 487 1748 : { # udp 488 1 : "tac.nrc.ca" # address, SID 1749 489 } 490 } 491 ] 493 CBOR encoding: 495 82 # array(2) 496 a5 # map(5) 497 19 06d2 # unsigned(1746) 498 6e # text(14) 499 4e52432054494320736572766572 # "NRC TIC server" 500 19 06d4 # unsigned(1748) 501 a2 # map(2) 502 01 # unsigned(1) 503 6a # text(10) 504 7469632e6e72632e6361 # "tic.nrc.ca" 505 02 # unsigned(2) 506 18 7b # unsigned(123) 507 19 06d0 # unsigned(1744) 508 00 # unsigned(0) 509 19 06d1 # unsigned(1745) 510 f4 # primitive(20) 511 19 06d3 # unsigned(1747) 512 f5 # primitive(21) 513 a2 # map(2) 514 19 06d2 # unsigned(1746) 515 6e # text(14) 516 4e52432054414320736572766572 # "NRC TAC server" 517 19 06d4 # unsigned(1748) 518 a1 # map(1) 519 01 # unsigned(1) 520 6a # text(10) 521 7461632e6e72632e6361 # "tac.nrc.ca" 523 *Member names example* 525 CBOR diagnostic notation: 527 [ 528 { 529 "ietf-system:name" : "NRC TIC server", 530 "ietf-system:udp" : { 531 "address" : "tic.nrc.ca", 532 "port" : 123 533 }, 534 "ietf-system:association-type" : 0, 535 "ietf-system:iburst" : false, 536 "ietf-system:prefer" : true 537 }, 538 { 539 "ietf-system:name" : "NRC TAC server", 540 "ietf-system:udp" : { 541 "address" : "tac.nrc.ca" 542 } 543 } 544 ] 546 CBOR encoding: 548 82 # array(2) 549 a5 # map(5) 550 70 # text(16) 551 696574662d73797374656d3a6e616d65 # "ietf-system:name" 552 6e # text(14) 553 4e52432054494320736572766572 # "NRC TIC server" 554 6f # text(15) 555 696574662d73797374656d3a756470 # "ietf-system:udp" 556 a2 # map(2) 557 67 # text(7) 558 61646472657373 # "address" 559 6a # text(10) 560 7469632e6e72632e6361 # "tic.nrc.ca" 561 64 # text(4) 562 706f7274 # "port" 563 18 7b # unsigned(123) 564 78 1c # text(28) 565 696574662d73797374656d3a6173736f63696174696f6e2d74797065 566 00 # unsigned(0) 567 72 # text(18) 568 696574662d73797374656d3a696275727374 # "ietf-system:iburst" 569 f4 # primitive(20) 570 72 # text(18) 571 696574662d73797374656d3a707265666572 # "ietf-system:prefer" 572 f5 # primitive(21) 573 a2 # map(2) 574 70 # text(16) 575 696574662d73797374656d3a6e616d65 # "ietf-system:name" 576 6e # text(14) 577 4e52432054414320736572766572 # "NRC TAC server" 578 6f # text(15) 579 696574662d73797374656d3a756470 # "ietf-system:udp" 580 a1 # map(1) 581 67 # text(7) 582 61646472657373 # "address" 583 6a # text(10) 584 7461632e6e72632e6361 # "tac.nrc.ca" 586 *YANG hashes example* 588 CBOR diagnostic notation: 590 [ 591 { 592 h'06c32032' : "NRC TIC server", # name 593 h'11889c84' : { # udp 594 h'3158c529' : "tic.nrc.ca", # address 595 h'34492d05' : 123 # port 596 }, 597 h'2c2c2ccf' : 0, # association-type 598 h'1058dc5d' : false, # iburst 599 h'390e346a' : true # prefer 600 }, 601 { 602 h'06c32032' : "NRC TAC server", # name 603 h'11889c84' : { # udp 604 h'3158c529' : "tac.nrc.ca" # address 605 } 606 } 607 ] 609 CBOR encoding: 611 82 # array(2) 612 a5 # map(5) 613 44 # bytes(4) 614 06c32032" 615 6e # text(14) 616 4e52432054494320736572766572 # "NRC TIC server" 617 44 # bytes(4) 618 11889c84 " 619 a2 # map(2) 620 44 # bytes(4) 621 3158c529 622 6a # text(10) 623 7469632e6e72632e6361 # "tic.nrc.ca" 624 44 # bytes(4) 625 34492d05 626 18 7b # unsigned(123) 627 44 # bytes(4) 628 2c2c2ccf 629 00 # unsigned(0) 630 44 # bytes(4) 631 1058dc5d 632 f4 # primitive(20) 633 44 # bytes(4) 634 390e346a 635 f5 # primitive(21) 636 a2 # map(2) 637 44 # bytes(4) 638 06c32032 639 6e # text(14) 640 4e52432054414320736572766572 # "NRC TAC server" 641 44 # bytes(4) 642 11889c84 643 a1 # map(1) 644 44 # bytes(4) 645 3158c529 646 6a # text(10) 647 7461632e6e72632e6361 # "tac.nrc.ca" 649 4.5. The "anydata" Schema Node 651 An anydata serves as a container for an arbitrary set of schema nodes 652 that otherwise appear as normal YANG-modeled data. An anydata 653 instance is encoded using the same rules as a container, i.e., CBOR 654 map. The requirement that anydata content can be modeled by YANG 655 implies the following: 657 o Keys MUST be set to valid SIDs, member names or YANG hashes. This 658 rule applies to the key of the anydata node and the key of any 659 inner schema node. 661 o The CBOR array MUST contain either unique scalar values (as a 662 leaf-list, see Section 4.3), or maps (as a list, see Section 4.4). 664 o Values MUST follow the encoding rules of one of the datatypes 665 listed in Section 5. 667 4.6. The "anyxml" Schema Node 669 An anyxml instance is encoded as a CBOR key/value pair. The key of 670 the anyxml schema node MUST be a valid SID, member name or YANG hash 671 but the value is unrestricted, i.e., the value can be any CBOR 672 encoded content. 674 5. Representing YANG Data Types in CBOR 676 5.1. The unsigned integer Types 678 Leafs of type uint8, uint16, uint32 and uint64 MUST be encoded using 679 a CBOR unsigned integer data item (major type 0). 681 Definition example [RFC7277]: 683 leaf mtu { 684 type uint16 { 685 range "68..max"; 686 } 687 } 689 CBOR diagnostic notation: 1280 691 CBOR encoding: 19 0500 693 5.2. The integer Types 695 Leafs of type int8, int16, int32 and int64 MUST be encoded using 696 either CBOR unsigned integer (major type 0) or CBOR signed integer 697 (major type 1), depending on the actual value. 699 Definition example [RFC7317]: 701 leaf timezone-utc-offset { 702 type int16 { 703 range "-1500 .. 1500"; 704 } 705 } 707 CBOR diagnostic notation: -300 709 CBOR encoding: 39 012b 711 5.3. The "decimal64" Type 713 Leafs of type decimal64 MUST be encoded using either CBOR unsigned 714 integer (major type 0) or CBOR signed integer (major type 1), 715 depending on the actual value. The position of the decimal point is 716 defined by the fraction-digits YANG statement and is not available in 717 the CBOR encoding. 719 Definition example [RFC7317]: 721 leaf my-decimal { 722 type decimal64 { 723 fraction-digits 2; 724 range "1 .. 3.14 | 10 | 20..max"; 725 } 726 } 728 CBOR diagnostic notation: 257 (Represents decimal value 2.57) 730 CBOR encoding: 19 0101 732 5.4. The "string" Type 734 Leafs of type string MUST be encoded using a CBOR text string data 735 item (major type 3). 737 Definition example [RFC7223]: 739 leaf name { 740 type string; 741 } 743 CBOR diagnostic notation: "eth0" 745 CBOR encoding: 64 65746830 747 5.5. The "boolean" Type 749 Leafs of type boolean MUST be encoded using a CBOR true (major type 750 7, additional information 21) or false data item (major type 7, 751 additional information 20). 753 Definition example [RFC7317]: 755 leaf enabled { 756 type boolean; 757 } 759 CBOR diagnostic notation: true 761 CBOR encoding: f5 763 5.6. The "enumeration" Type 765 Leafs of type enumeration MUST be encoded using a CBOR unsigned 766 integer data item (major type 0). 768 Definition example [RFC7317]: 770 leaf oper-status { 771 type enumeration { 772 enum up { value 1; } 773 enum down { value 2; } 774 enum testing { value 3; } 775 enum unknown { value 4; } 776 enum dormant { value 5; } 777 enum not-present { value 6; } 778 enum lower-layer-down { value 7; } 779 } 780 } 782 CBOR diagnostic notation: 3 (Represents enumeration value "testing") 784 CBOR encoding: 03 786 5.7. The "bits" Type 788 Leafs of type bits MUST be encoded using a CBOR byte string data item 789 (major type 2). Bits position 0 to 7 are assigned to the first byte 790 within the byte string, bits 8 to 15 to the second byte, and 791 subsequent bytes are assigned similarly. Within each byte, bits are 792 assigned from least to most significant. 794 Definition example [I-D.ietf-netmod-rfc6020bis]: 796 leaf mybits { 797 type bits { 798 bit disable-nagle { 799 position 0; 800 } 801 bit auto-sense-speed { 802 position 1; 803 } 804 bit 10-Mb-only { 805 position 2; 806 } 807 } 808 } 810 CBOR diagnostic notation: h'05' (Represents bits disable-nagle and 811 10-Mb-only set) 813 CBOR encoding: 41 05 815 5.8. The "binary" Type 817 Leafs of type binary MUST be encoded using a CBOR byte string data 818 item (major type 2). 820 Definition example: 822 leaf aes128-key { 823 type binary { 824 length 16; 825 } 826 } 828 CBOR diagnostic notation: h'1f1ce6a3f42660d888d92a4d8030476e' 830 CBOR encoding: 50 1f1ce6a3f42660d888d92a4d8030476e 832 5.9. The "leafref" Type 834 Leafs of type leafref MUST be encoded using the rules of the schema 835 node referenced by the "path" YANG statement. 837 Definition example [RFC7223]: 839 typedef interface-state-ref { 840 type leafref { 841 path "/interfaces-state/interface/name"; 842 } 843 } 845 container interfaces-state { 846 list interface { 847 key "name"; 848 leaf name { 849 type string; 850 } 851 leaf-list higher-layer-if { 852 type interface-state-ref; 853 } 854 } 855 } 857 CBOR diagnostic notation: "eth1" 859 CBOR encoding: 64 65746831 861 5.10. The "identityref" Type 863 This specification supports two approaches for encoding identityref, 864 a SID as defined in [I-D.somaraju-core-sid] or a name as defined in 865 [I-D.ietf-netmod-yang-json] section 6.8. 867 *SIDs as identityref* 869 SIDs are globally unique and may be used as identityref. This 870 approach is both compact and simple to implement. When SIDs are 871 used, identityref MUST be encoded using a CBOR unsigned integer data 872 item (major type 0) and set to a SID allocated from a registered SID 873 range. 875 *Name as identityref* 877 Alternatively, an identityref may be encoded using a name as defined 878 in [I-D.ietf-netmod-yang-json] section 6.8. When names are used, 879 identityref MUST be encoded using a CBOR text string data item (major 880 type 3). If the identity is defined in another module than the leaf 881 node containing the identityref value, the namespace-qualified form 882 MUST be used. Otherwise, both the simple and namespace-qualified 883 forms are permitted. 885 Definition example [RFC7223]: 887 identity interface-type { 888 } 890 identity iana-interface-type { 891 base interface-type; 892 } 894 identity ethernetCsmacd { 895 base iana-interface-type; 896 } 898 leaf type { 899 type identityref { 900 base interface-type; 901 } 902 } 904 *SIDs as identityref* 906 Assuming that the identity "iana-if-type:ethernetCsmacd" has been 907 assigned to the SID value 1179. 909 CBOR diagnostic notation: 1179 911 CBOR encoding: 19 049b 913 *Name as identityref* 915 CBOR diagnostic notation: "iana-if-type:ethernetCsmacd" 917 CBOR encoding: 78 1b 918 69616e612d69662d747970653a65746865726e657443736d616364 920 5.11. The "empty" Type 922 Leafs of type empty MUST be encoded using the CBOR null value (major 923 type 7, additional information 22). 925 Definition example [RFC7277]: 927 leaf is-router { 928 type empty; 929 } 931 CBOR diagnostic notation: null 933 CBOR encoding: f6 935 5.12. The "union" Type 937 Leafs of type union MUST be encoded using the rules associated with 938 one of the types listed. 940 Definition example [RFC7317]: 942 typedef ipv4-address { 943 type string { 944 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3} 945 ([0-9][1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])(%[\p{N} 946 \p{L}]+)?'; 947 } 948 } 950 typedef ipv6-address { 951 type string { 952 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}((([0-9a 953 -fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|(((25[0-5]|2[0-4][0 954 -9]|[01]?[0-9]?[0-9])\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0 955 -9]?[0-9])))(%[\p{N}\p{L}]+)?'; 956 pattern '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|((([^:]+:)*[^:]+) 957 ?::(([^:]+:)*[^:]+)?)(%.+)?'; 958 } 959 } 961 typedef ip-address { 962 type union { 963 type ipv4-address; 964 type ipv6-address; 965 } 966 } 968 leaf address { 969 type inet:ip-address; 970 } 972 CBOR diagnostic notation: "2001:db8:a0b:12f0::1" 974 CBOR encoding: 74 323030313a6462383a6130623a313266303a3a31 976 5.13. The "instance-identifier" Type 978 This specification supports three approaches for encoding an 979 instance-identifier, one based on SIDs as defined in [I-D.somaraju- 980 core-sid], one based on names as defined in 981 [I-D.ietf-netmod-yang-json] section 6.13 and one based on YANG hashes 982 as defined in [I-D.vanderstok-core-comi]. 984 *SIDs as instance-identifier* 986 SIDs uniquely identify a data node. For a single instance data node, 987 the SID is sufficient to identify this instance. For a multi- 988 instance data node, a SID is combined with the list key(s) to 989 identify each instance of this data node within the YANG list(s). 991 Single instance data nodes MUST be encoded using a CBOR unsigned 992 integer data item (major type 0) and set to the targeted data node 993 SID. 995 Multi-instances data nodes MUST be encoded using a CBOR array data 996 item (major type 4) containing the following entries: 998 o The first entry MUST be encoded as a CBOR unsigned integer data 999 item (major type 0) and set to the targeted data node SID. 1001 o The following entries MUST contain the value of each key required 1002 to identify the instance of the targeted data node. These keys 1003 MUST be ordered as defined in the "key" YANG statement, starting 1004 from top level list, and follow by each of the subordinate 1005 list(s). 1007 When SIDs identify a YANG list, the presence of the key(s) for this 1008 list is optional. When the key(s) are present, the targeted instance 1009 within this list is selected. When the key(s) are absent, the entire 1010 YANG list is selected. 1012 *Names as instance-identifier* 1014 The use of names as instance-identifier is defined in 1015 [I-D.ietf-netmod-yang-json] section 6.11. The resulting xpath MUST 1016 be encoded using a CBOR text string data item (major type 3). 1018 *YANG hashes as instance-identifier* 1020 When YANG hashes are used, xpath can be compressed based on the 1021 method defined by [I-D.vanderstok-core-comi] sections 4.1.4.1 and 1022 4.1.4.2. 1024 Definition example [RFC7317]: 1026 container system { 1028 leaf contact { 1029 type string; 1030 } 1032 leaf hostname { 1033 type inet:domain-name; 1034 } 1035 } 1037 *First example based on SID* 1039 In this example, a field of type instance-identifier identifies the 1040 data node "/system/contact" (SID 1728). 1042 1728 1044 CBOR encoding: 1046 19 06c0 1048 *First example based on name* 1050 Same example as above based on names. 1052 "/ietf-system:system/contact" 1054 CBOR encoding: 1056 78 1c 2f20696574662d73797374656d3a73797374656d2f636f6e74616374 1058 *First example based on YANG hash* 1060 Same example assuming data node "/system/contact" is associated to 1061 YANG hash 0x09b06d17 or "JsG0X" in base64. 1063 CBOR diagnostic notation: 1065 "/JsG0X" 1067 CBOR encoding: 1069 66 2f4a73473058 1071 Definition example [RFC7317]: 1073 list user { 1074 key name; 1076 leaf name { 1077 type string; 1078 } 1079 leaf password { 1080 type ianach:crypt-hash; 1081 } 1083 list authorized-key { 1084 key name; 1086 leaf name { 1087 type string; 1088 } 1089 leaf algorithm { 1090 type string; 1091 } 1092 leaf key-data { 1093 type binary; 1094 } 1095 } 1097 *Second example based on SID* 1099 In this example, a field of type instance-identifier identify the 1100 data node "/system/authentication/user/authorized-key/key-data" (SID 1101 1721) for the user name "bob" and the authorized-key name "admin". 1103 CBOR diagnostic notation: 1105 [1721, "bob", "admin"] 1107 CBOR encoding: 1109 83 # array(3) 1110 19 06b9 # unsigned(1721) 1111 63 # text(3) 1112 626f62 # "bob" 1113 65 # text(5) 1114 61646d696e # "admin" 1116 *Second example based on name* 1118 Same example as above based on names. 1120 CBOR diagnostic notation: 1122 "/ietf-system:system/authentication/user[name='bob']/authorized-key 1123 [name='admin']/key-data" 1125 CBOR encoding: 1127 78 59 1128 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1129 74696f6e2f757365725b6e616d653d27626f62275d2f617574686f72697a 1130 65642d6b65795b6e616d653d2761646d696e275d2f6b65792d64617461 1132 *Second example based on YANG hash* 1134 Same example assuming data node "/ietf- 1135 system:system/authentication/user/authorized-key/key-data" is 1136 associated to YANG hash 0x0d6e7afb or "Nbnr7" in base64. 1138 CBOR diagnostic notation: 1140 "/Nbnr7?keys=\"bob\",\"admin\"" 1142 CBOR encoding: 1144 78 19 2f4e626e72373f6b6579733d22626f62222c2261646d696e22 1146 *Third example based on SID* 1148 This third example identify an instance within the list 1149 "/system/authentication/user" (SID 1717) corresponding to the user 1150 name "jack". 1152 CBOR diagnostic notation: 1154 [1717, "jack"] 1156 CBOR encoding: 1158 82 # array(2) 1159 19 06b5 # unsigned(1717) 1160 64 # text(4) 1161 6a61636b # "jack" 1163 *Third example based on name* 1165 Same example as above based on names. 1167 CBOR diagnostic notation: 1169 "/ietf-system:system/authentication/user[name='bob']" 1170 CBOR encoding: 1172 78 33 1173 2f696574662d73797374656d3a73797374656d2f61757468656e74696361 1174 74696f6e2f757365725b6e616d653d27626f62275d 1176 *Third example based on YANG hash* 1178 Same example assuming data node "/ietf-system:system/authentication/ 1179 user" is associated to YANG hash 0x2677c6c1 or "md8bB" in base64. 1181 CBOR diagnostic notation: 1183 "/md8bB?keys=\"bob\"" 1185 CBOR encoding: 1187 71 2f6d643862423f6b6579733d22626f6222 1189 6. Security Considerations 1191 The security considerations of [RFC7049] and 1192 [I-D.ietf-netmod-rfc6020bis] apply. 1194 This document defines an alternative encoding for data modeled in the 1195 YANG data modeling language. As such, this encoding does not 1196 contribute any new security issues in addition of those identified 1197 for the specific protocol or context for which it is used. 1199 To minimize security risks, software on the receiving side SHOULD 1200 reject all messages that do not comply to the rules of this document 1201 and reply with an appropriate error message to the sender. 1203 7. Acknowledgments 1205 This document has been largely inspired by the extensive works done 1206 by Andy Bierman and Peter van der Stok on [I-D.vanderstok-core-comi]. 1207 [I-D.ietf-netmod-yang-json] has also been a critical input to this 1208 work. The authors would like to thank the authors and contributors 1209 to these two drafts. 1211 The authors would also like to acknowledge the review, feedback, and 1212 comments from Ladislav Lhotka and Juergen Schoenwaelder. 1214 8. References 1216 8.1. Normative References 1218 [I-D.ietf-netmod-rfc6020bis] 1219 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 1220 draft-ietf-netmod-rfc6020bis-11 (work in progress), 1221 February 2016. 1223 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1224 Requirement Levels", BCP 14, RFC 2119, 1225 DOI 10.17487/RFC2119, March 1997, 1226 . 1228 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1229 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1230 October 2013, . 1232 8.2. Informative References 1234 [I-D.ietf-netmod-yang-json] 1235 Lhotka, L., "JSON Encoding of Data Modeled with YANG", 1236 draft-ietf-netmod-yang-json-09 (work in progress), March 1237 2016. 1239 [I-D.vanderstok-core-comi] 1240 Stok, P. and A. Bierman, "CoAP Management Interface", 1241 draft-vanderstok-core-comi-09 (work in progress), March 1242 2016. 1244 [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 1245 Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 1246 2014, . 1248 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1249 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014, 1250 . 1252 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 1253 Constrained-Node Networks", RFC 7228, 1254 DOI 10.17487/RFC7228, May 2014, 1255 . 1257 [RFC7277] Bjorklund, M., "A YANG Data Model for IP Management", 1258 RFC 7277, DOI 10.17487/RFC7277, June 2014, 1259 . 1261 [RFC7317] Bierman, A. and M. Bjorklund, "A YANG Data Model for 1262 System Management", RFC 7317, DOI 10.17487/RFC7317, August 1263 2014, . 1265 Authors' Addresses 1267 Michel Veillette (editor) 1268 Trilliant Networks Inc. 1269 610 Rue du Luxembourg 1270 Granby, Quebec J2J 2V2 1271 Canada 1273 Phone: +14503750556 1274 Email: michel.veillette@trilliantinc.com 1276 Alexander Pelov (editor) 1277 Acklio 1278 2bis rue de la Chataigneraie 1279 Cesson-Sevigne, Bretagne 35510 1280 France 1282 Email: a@ackl.io 1284 Abhinav Somaraju 1285 Tridonic GmbH & Co KG 1286 Farbergasse 15 1287 Dornbirn, Vorarlberg 6850 1288 Austria 1290 Phone: +43664808926169 1291 Email: abhinav.somaraju@tridonic.com 1293 Randy Turner 1294 Landis+Gyr 1295 30000 Mill Creek Ave 1296 Suite 100 1297 Alpharetta, GA 30022 1298 US 1300 Phone: ++16782581292 1301 Email: randy.turner@landisgyr.com 1302 URI: http://www.landisgyr.com/ 1303 Ana Minaburo 1304 Acklio 1305 2bis rue de la chataigneraie 1306 Cesson-Sevigne, Bretagne 35510 1307 France 1309 Email: ana@ackl.io