idnits 2.17.1 draft-greevenbosch-appsawg-cbor-cddl-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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 2, 2014) is 3768 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '2' on line 422 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group B. Greevenbosch 3 Internet-Draft Huawei Technologies 4 Intended status: Informational January 2, 2014 5 Expires: July 6, 2014 7 CBOR data definition language: a notational convention to express CBOR 8 data structures. 9 draft-greevenbosch-appsawg-cbor-cddl-00 11 Abstract 13 This document proposes a notational convention to express CBOR data 14 structures. Its main goal is to make it easy to express message 15 structures for protocols that use CBOR. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at http://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on July 6, 2014. 34 Copyright Notice 36 Copyright (c) 2014 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (http://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. Code Components extracted from this document must 45 include Simplified BSD License text as described in Section 4.e of 46 the Trust Legal Provisions and are provided without warranty as 47 described in the Simplified BSD License. 49 Table of Contents 51 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 2 52 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Notational conventions . . . . . . . . . . . . . . . . . . . 3 55 4.1. General conventions . . . . . . . . . . . . . . . . . . . 3 56 4.2. Keywords for data types . . . . . . . . . . . . . . . . . 3 57 4.3. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 4.4. Structures . . . . . . . . . . . . . . . . . . . . . . . 4 59 4.5. Maps . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60 4.6. Constants . . . . . . . . . . . . . . . . . . . . . . . . 5 61 4.7. Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.8. Optional variables . . . . . . . . . . . . . . . . . . . 8 63 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 5.1. Moves in a computer game . . . . . . . . . . . . . . . . 9 65 5.2. Fruit . . . . . . . . . . . . . . . . . . . . . . . . . . 11 66 6. Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . 14 67 7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 14 68 8. Security considerations . . . . . . . . . . . . . . . . . . . 14 69 9. IANA considerations . . . . . . . . . . . . . . . . . . . . . 15 70 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 15 71 11. Normative References . . . . . . . . . . . . . . . . . . . . 15 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 74 1. Requirements notation 76 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 77 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 78 document are to be interpreted as described in [RFC2119]. 80 2. Introduction 82 In this document, a notational convention to express CBOR [RFC7049] 83 data structures is defined. 85 The main goal for the convention is to provide a unified notation 86 that can be used when defining protocols that use CBOR. 88 The CBOR notational convention has the following goals: 90 (G1) Able to provide an unambiguous description of a CBOR data 91 structures. 93 (G2) Easy for humans to read and write. 95 (G3) Flexibility to express the freedoms of choice in the CBOR data 96 format. 98 (G4) Possibility to restrict format choices where appropriate. 100 (G5) Able to express common CBOR data types and structures. 102 (G6) Human and machine readable and processable. 104 (G7) Usable for automatic verification of whether CBOR data is 105 compliant to a predefined format. 107 3. Definitions 109 The following contains a list of used words in this document: 111 "datatype" defines the format of a variable. 113 "variable" a data component encoded in CBOR. 115 4. Notational conventions 117 4.1. General conventions 119 The basic syntax is as follows: 121 o Each field has a name and a type. 123 o The name is written first, followed by a colon and then the type. 124 The declarations is finished with a semicolon. Whitespace may 125 appear around the colon and semicolon, as well as in front of the 126 name. 128 o The name does not appear in the actual CBOR encoding. 130 o If there is a following field, then the type of the previous field 131 is followed by a whitespace and then the name of the following 132 field. 134 o Comments are preceded by a '#' character. 136 4.2. Keywords for data types 138 The following keywords are used: 140 "bool" Boolean value (major type 7, additional information 20 or 141 21). 143 "bstr" A byte string (major type 2). 145 "float(16)" IEEE 754 half-precision float (major type 7, additional 146 information 25). 148 "float(32)" IEEE 754 single-precision float (major type 7, 149 additional information 26). 151 "float(64)" IEEE 754 double-precision float (major type 7, 152 additional information 27). 154 "int" An unsigned integer (mayor type 0) or a negative integer 155 (mayor type 1). 157 "nint" A negative integer (mayor type 1). 159 "simple" Simple value (mayor type 7, additional information 24). 161 "tstr" Text string (major type 3) 163 "uint" An unsigned integer (mayor type 0). 165 4.3. Arrays 167 Arrays can be of fixed length or of variable length. Both fixed 168 length and variable length arrays can be implemented as definite and 169 indefinite length arrays. 171 A fixed length array is is indicated by '[' and ']' characters behind 172 its type, where number in between specifies the number of elements. 174 A variable length array can be indicated with a "*" behind its type. 176 4.4. Structures 178 Structures are a logical grouping of CBOR fields. 180 A structure has a name, which can be used as a value type for other 181 fields. The name is followed by a '{' character and the definitions 182 of the variables inside of the structure. The structure is closed by 183 a '}' character. 185 A structure MAY be encoded as an array, in which case its name is 186 preceded by a '*' character. Otherwise there is no CBOR encoding for 187 the grouping. 189 4.5. Maps 191 If an entity is a map (mayor type 5), it its datatype has the form 193 map( x, y ) 195 where the keys have datatype x, and the values a datatype y. 197 If either x or y is unspecified (i.e. free to choose per entry), it 198 is replaced by a '.'. 200 4.6. Constants 202 In some contexts, it is useful to give special values a name. These 203 constants are defined using the "const" construct. 205 The "const" construct has the form 207 x : const( y ) { 208 ... bundle of constants ... 209 } 211 where x is a name for the bundle of constants, and y is the datatype 212 of the values. 214 The bundle of constants consists of a list of name value pairs. The 215 list is encapsulated by a starting '{' and a closing '}' character. 217 The name x defines a datatype that can be used for variables that 218 take values from the const struct. 220 For example, the "const" construct 222 Weekday const( uint ) { 223 Sunday : 1; 224 Monday : 2; 225 Tuesday : 3; 226 Wednesday : 4; 227 Thursday : 5; 228 Friday : 6; 229 Saturday : 7; 230 } 232 defines integer values associated with the week days. 234 An variable using this structure could be as follows: 236 weekday Weekday; 238 and would be encoded as an unsigned int. 240 Since the weekdays are defined as part of a Weekday structure, they 241 can also be referenced as "Weekday.Sunday", "Weekday.Monday", ..., 242 "Weekday.Saturday". 244 The definition could also have been as follows: 246 const { 247 Sunday : 1; 248 Monday : 2; 249 Tuesday : 3; 250 Wednesday : 4; 251 Thursday : 5; 252 Friday : 6; 253 Saturday : 7; 254 } 256 In this case, the weekdays are just referred to as "Sunday", 257 "Monday", ..., "Saturday". However, since it has no name, the 258 "const" construct cannot be used as a datatype for CBOR variables. 259 Since this also makes the suffix "(uint)" superfluous, that suffix 260 has been omitted. 262 The definition of the datatype can also be left to the definition of 263 the variable, in which case the datatype is encapsulated in round 264 brackets and follows the datatype. In this case the datatype is 265 omitted in the definition of the constants. 267 The following example illustrates this: 269 Weekday const { 270 Sunday : 1; 271 Monday : 2; 272 Tuesday : 3; 273 Wednesday : 4; 274 Thursday : 5; 275 Friday : 6; 276 Saturday : 7; 277 } 279 weekday Weekday( uint ); 281 TBD: there may be too many options for this. We could consider 282 omitting the "const( x )" syntax and mandate definition of the true 283 datatype when defining a CBOR variable. 285 4.7. Tags 287 A variable can have an associated CBOR tag (major type 6). This is 288 indicated by the tag encapsulated between the square brackets '[' and 289 ']', just before the variable's datatype definition. 291 For example, the following defines a positive bignum N: 293 N : [2]bstr; 295 The tag may also be indicated using values from the following "const" 296 struct: 298 Tag const { 299 StandardDT : 0; 300 EpochDT : 1; 301 PBigNum : 2; 302 NBigNum : 3; 303 DFraction : 4; 304 BigFloat : 5; 305 URI : 32; 306 Base64URL : 33; 307 Base64 : 34; 308 RegEx : 35; 309 MimeMsg : 36; 310 } 312 We refer to [RFC7049] for the semantics of these tags. 314 Using above constants, the definition of N can also be as follows: 316 N : [Tag.PBigNum]bstr; 318 A abbreviation of a tagged datatype can be defined using the 319 following construct: 321 x = [y]z; 323 where x is the abbreviation, y is the tag and z is the datatype. 325 For example, once again we can define N, now as follows: 327 BigNum = [Tag.PBigNum]bstr; 328 N : BigNum; 330 4.8. Optional variables 332 There may be variables or structures whose inclusion is optional. In 333 this case, the name of the variable is preceded by a '?'. 335 For example, the following defines a CBOR structure that is dependent 336 on a boolean value. 338 *MainStruct { 339 whichForm : bool; 340 ?data1 : Form1; # when whichForm == true 341 ?data2 : Form2; # when whichForm == false 342 } 344 Form1 { 345 anInteger : int; 346 aTextString : tstr; 347 } 349 Form2 { 350 aFloat : float(16); 351 aBinaryString : bstr; 352 } 354 Notice that it is not possible to define the relationship between 355 "whichForm" and inclusion of either "data1" or "data2" with CBOR 356 content rules. Such relationship should be otherwise communicated to 357 the implementer, for example in the text of the specification that 358 uses the CBOR structure, or with comments as was done in this 359 example. 361 Protocol designers should exhibit utmost care when defining CBOR 362 structures with optional variables, especially when some of these 363 variables have the same datatype. 365 For example, the following CBOR data structure is ambiguous: 367 *DataStruct { 368 ?OptionalVariable : uint; 369 MandatoryVariable : uint; 370 ?AnotherOptionalVariable : uint; 371 } 373 Since optional variables are often detected from their datatype, it 374 is RECOMMENDED to not have a following of multiple variables of the 375 same datatype, when some of these variables are optional. 377 5. Examples 379 This section contains various examples of structures defined using 380 the CBOR notational convention. 382 5.1. Moves in a computer game 384 A multiplayer computer game uses CBOR to exchange moves between the 385 players. To ensure a good game experience, the move information 386 needs to be exchanged quickly and frequently. Therefore, the game 387 uses CBOR to send its information in a compact format. Figure 1 388 shows definition of the CBOR information exchange format. 390 *UpdateMsg { 391 move_no : uint; # increases for each move 392 player_info : PlayerInfo; # general information 393 moves : Moves*; # moves in this message 394 } 396 PlayerInfo { 397 alias : tstr; 398 player_id : uint; 399 experience : Experience; 400 gold : uint; 401 supplies : map( Supplies, uint ); 402 avg_strength : float(16); 403 } 405 Experience const( uint ) { 406 Beginner : 0; 407 Amateur : 1; 408 Professional : 2; 409 Expert : 3; 410 } 412 Supplies const( uint ) { 413 Wood : 0; 414 Iron : 1; 415 Grain : 2; 416 } 418 *Moves { 419 unit_id : uint; 420 unit_strength : uint; # between 0 and 100 421 source_pos : uint[2]; # (x,y) 422 target_pos : uint[2]; # (x,y) 423 } 425 Figure 1: CBOR definition of an information exchange format for a 426 computer game 428 Player "Johnny" does two moves. The game server has assigned Johnny 429 the ID 0x7a3b871f. Johnny is an amateur player, and currently has 430 1200 gold. He has 13 units of wood, 70 units of iron and 29 units of 431 grain. He has several units, with a total average strength of 30.25. 433 The units Johnny plays in move 250 are the unit with ID 19, strength 434 20 from (5,7) to (6,9), and the unit with ID 87, strength 40 from 435 (7,10) to (6,10). 437 This information is coded in CBOR as depicted in Figure 2. 439 9F 440 18 FA # move 250 441 66 4A 6F 68 6E 6E 79 # "Johnny" 442 1A 7A 3B 87 1F # player_id 443 01 # experience, "amateur" 444 19 04 B0 # 1200 gold as uint 445 A3 # begin map "supplies" with 3 elements 446 00 # "wood": 447 0C # 13 as uint 448 01 # "iron": 449 18 86 # 70 as uint 450 02 # "grain": 451 18 1D # 29 as uint 452 F9 4F 90 # average strength 30.25 half-precision float 453 9F # indefinite length "moves" array 454 84 # 4-element array Moves 455 13 # unit id 19 as uint 456 14 # strength 20 as uint 457 82 # 2-element array source_pos 458 05 # source_pos.x=5 459 07 # source_pos.y=7 460 82 # 2-element array target_pos 461 06 # target_pos.x=6 462 09 # target_pos.y=9 463 84 # 4-element array Moves 464 18 57 # unit id 87 465 18 28 # strength 40 466 82 # 2-element array source_pos 467 07 # source_pos.x=7 468 0a # source_pos.y=10 469 82 # 2-element array target_pos 470 06 # target_pos.x=6 471 0a # target_pos.y=10 472 FF # end of "moves" array 473 FF 475 Figure 2: CBOR instance for game example 477 5.2. Fruit 479 Figure 3 contains an example for a CBOR structure that contains 480 information about fruit. 482 fruitlist : Fruit*; 484 *Fruit { 485 name : tstr; 486 colour : Colour[]; 487 avg_weight : float( 16 ); 488 price : uint; 489 international_names : map( Lang, tstr ); 490 rfu : bstr; # reserved for future use 491 } 493 Colour const( uint ) { 494 black : 0; 495 red : 1; 496 green : 2; 497 yellow : 3; 498 blue : 4; 499 magenta : 5; 500 cyan : 6; 501 white : 7; 502 orange : 8; 503 pink : 9; 504 purple : 10; 505 brown : 11; 506 grey : 12; 507 } 509 Lang const( tstr ) { 510 Chinese : "CN"; 511 Dutch : "NL"; 512 English : "EN"; 513 French : "FR"; 514 German : "DE"; 515 } 517 Figure 3: Example CBOR structure 519 For example, apples can be red, yellow or green. They have an 520 average weight of 0.195kg and a price of 30 cents. Chinese for 521 "apple" in UTF-8 is [ E8 8B B9 E6 9E 9C ], the Dutch word is "appel" 522 and the French word "pomme". 524 For simplicity, let's assume that the colour of oranges can only be 525 orange. They have an average weight of 0.230kg and a price of 50 526 cents. Chinese for "orange" in UTF-8 is [ E6 A9 99 E5 AD 90 ], the 527 Dutch word is "sinaasappel" and the German word "Orange". 529 This information would be encoded as depicted in Figure 4. 531 9F # indefinite length "fruitlist" array 532 86 # First "Fruit" instance, 6 elements 533 65 # text string "name" length 5 534 61 70 70 6C 65 # "apple" 535 83 # array for "Colour", 3 elements 536 01 # "red" as uint 537 02 # "green" as uint 538 03 # "yellow" as uint 539 F9 # Floating point half precision 540 32 3D # "avg_weight" 0.195 541 18 1E # "price" 30 as uint 542 A3 # map "international_names", 3 pairs 543 62 43 4E # text string length 2, "CN" 544 66 E8 8B B9 E6 9E 9C # Chinese word for apple 545 62 4E 4C # "NL" 546 65 61 70 70 65 6C # "appel" 547 62 46 52 # "FR" 548 65 70 6F 6D 6D 65 # "pomme" 549 40 # byte string "rfu", 0 bytes length 550 86 # Second "Fruit" instance 551 66 # text string "name" length 6 552 6F 72 61 6E 67 65 # "orange" 553 81 # array for "Colour", 3 elements 554 08 # "orange" as uint 555 F9 # Floating point half precision 556 33 5C # "avg_weight" 0.230 557 18 32 # "price" 50 as uint 558 A3 # map "international_names", 3 pairs 559 62 43 4E # text string length 2, "CN" 560 66 E6 A9 99 E5 AD 90 # Chinese word for orange 561 62 4E 4C # "NL" 562 6B 73 69 6E 61 61 73 61 70 70 65 6C # "sinaasappel" 563 62 44 45 # "DE" 564 66 4F 72 61 6E 67 65 # "Orange" 565 40 # byte string "rfu", 0 bytes length 566 FF # end of "fruitlist" array 568 Figure 4: Example CBOR instance 570 Notice that if the "Fruit" structure did not have the preceding "*", 571 the two "Fruit" instance arrays would have been omitted. In 572 addition, the "fruitlist" array would have had 12 elements instead of 573 2. (Although for "fruitlist" the indefinite length approach was 574 chosen, such that the number of elements is not explicitely 575 signalled.) 577 6. Philosophy 579 The CBOR notational convention can be used to efficiently define the 580 layout of CBOR data. 582 In addition, it has been specified such that a machine can verify 583 whether or not CBOR data is compliant to its definition. 585 The matter in how far the data description must be enforced by an 586 application is left solely to the implementers and specifiers of that 587 application. For example, an application may decide not to verify 588 the data structure at all, and use the CBOR content rules solely as a 589 means to indicate the structure of the data to the programmer. On 590 the other hand, the application may also implement a verification 591 method that goes as far as verifying that variables that depend on 592 the "const" construction actually only take values defined in that 593 construction. 595 The content rules do not specify the length of a CBOR integer. But 596 this can be done in the text specification of a protocol that uses 597 CBOR. 599 7. Open Issues 601 At least the following issues need further consideration: 603 o Whether or not to allow optional variables. 605 o Removal of some "const" construct possibilities. 607 o Definition of constants for missing tags. 609 o More extensive security considerations. 611 o The various flavours of consts and tags increase implementation 612 complexity of a verifier. It is to be considered which flavours 613 provide enough benefit to justify their implementation complexity. 615 o For optional inclusion, one could define structures such as 616 "switch"/"case". However, this would again increase complexity, 617 and would cater only for cases where inclusion is dependent on a 618 simple variable. 620 8. Security considerations 622 This document presents a content rules language for expressing CBOR 623 data structures. As such, it does not bring any security issues on 624 itself, although specification of protocols that use CBOR naturally 625 need security analysis when defined. 627 9. IANA considerations 629 This document does not require any IANA registrations. 631 10. Acknowledgements 633 For this draft, there has been inspiration from the C and Pascal 634 languages, MPEG's conventions for describing structures in the ISO 635 base media file format, and Andrew Lee Newton's "JSON Content Rules" 636 draft. 638 Useful feedback came from Carsten Bormann. 640 11. Normative References 642 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 643 Requirement Levels", BCP 14, RFC 2119, March 1997. 645 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 646 Representation (CBOR)", RFC 7049, October 2013. 648 Author's Address 650 Bert Greevenbosch 651 Huawei Technologies Co., Ltd. 652 Huawei Industrial Base 653 Bantian, Longgang District 654 Shenzhen 518129 655 P.R. China 657 Email: bert.greevenbosch@huawei.com