idnits 2.17.1 draft-farrel-rtg-common-bnf-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 570. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 581. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 588. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 594. 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 1, 2008) is 5649 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) No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Networking Working Group A. Farrel 3 Internet-Draft Old Dog Consulting 4 Intended Status: Standards Track 5 Created: November 1, 2008 6 Expires: May 1, 2009 8 Reduced Backus-Naur Form (RBNF) 9 A Syntax Used in Various Protocol Specifications 11 draft-farrel-rtg-common-bnf-07.txt 13 Status of this Memo 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 Abstract 38 Several protocols have been specified using a common variant of the 39 Backus-Naur Form (BNF) of representing message syntax. However, there 40 is no formal definition of this version of BNF. 42 There is value in using the same variant of BNF for the set of 43 protocols that are commonly used together. This reduces confusion and 44 simplifies implementation. 46 Updating existing documents to use some other variant of BNF that is 47 already formally documented would be a substantial piece of work. 49 This document provides a formal definition of the variant of BNF that 50 has been used (that we call Reduced BNF), and makes it available for 51 use by new protocols. 53 Table of Contents 55 1. Introduction ................................................... 56 1.1. Terminology .................................................. 57 1.2. Existing Uses ................................................ 58 2. Formal Definitions ............................................. 59 2.1. Rule Definitions ............................................. 60 2.1.1. Rule Name Delimitation ..................................... 61 2.1.2. Objects .................................................... 62 2.1.3. Constructs ................................................. 63 2.1.4. Messages ................................................... 64 2.2. Operators .................................................... 65 2.2.1. Assignment ................................................. 66 2.2.2. Concatenation .............................................. 67 2.2.3. Optional Presence .......................................... 68 2.2.4. Alternatives ............................................... 69 2.2.5. Repetition ................................................. 70 2.2.6. Grouping ................................................... 71 2.3. Editorial Conventions ........................................ 72 2.3.1. White Space ................................................ 73 2.3.2. Line Breaks ................................................ 74 2.3.3. Ordering ................................................... 75 2.4. Precedence ................................................... 76 3. Automated Validation ........................................... 77 4. IANA Considerations ............................................ 78 5. Security Considerations ........................................ 79 6. Acknowledgments ................................................ 80 7. References .................................................... 81 7.1. Normative References ........................................ 82 7.2. Informative References ....................................... 84 1. Introduction 86 Backus-Naur Form (BNF) has been used to specify the message formats 87 of several protocols within the IETF. Unfortunately these 88 specifications are not based on any specific formal definition of BNF 89 and differ slightly from the definitions provided in other places. 91 It is clearly valuable to have a formal definition of the syntax- 92 defining language that is used. It would be possible to convert all 93 existing specifications to use an established specification of BNF 94 (for example, Augmented BNF or ABNF [RFC5234]), however this would 95 require a lot of work. 97 On the other hand, the variant of BNF used by the specifications in 98 question (which is similar to a subset of Extended BNF [EBNF]) is 99 consistent and has only a small number of constructs. It makes sense, 100 therefore, to provide a definition of this variant of BNF to allow 101 ease of interpretation of existing documents and to facilitate the 102 development of new protocol specifications using the same variant of 103 BNF. A specification will also facilitate automated verification of 104 the formal definitions used in future documents. 106 This document provides such a specification and names the BNF variant 107 Reduced BNF (RBNF). 109 1.1. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in [RFC2119]. 115 1.2. Existing Uses 117 The first notable use of the variant of BNF that concerns us is in 118 the specification of the Resource Reservation Protocol (RSVP) 119 [RFC2205]. RSVP has been extended for use in Multiprotocol Label 120 Switching (MPLS) networks to provide signaling for Traffic 121 Engineering (TE) [RFC3209], and this has been developed for use as 122 the signaling protocol in Generalized MPLS (GMPLS) networks 123 [RFC3473]. 125 Each of these three uses of RSVP has given rise to a large number of 126 specifications of protocol extensions to provide additional features 127 over and above those in the base documents. Each new feature is 128 defined in its own document using the common variant of BNF. 130 New protocols have also been specified using the same variant of BNF. 131 This has arisen partly because the developers were familiar with the 132 BNF used in [RFC2205], etc., but also because of the overlap between 133 the protocols especially with respect to the network objects 134 controlled and operated. 136 Notable among these additional protocols are the Link Management 137 Protocol (LMP) [RFC4204] and the Path Computation Element Protocol 138 (PCEP) [PCEP]. In both cases further documents that specify protocol 139 extensions also use the same variant of BNF. 141 2. Formal Definitions 143 The basic building blocks of BNF are rules and operators. At its 144 simplest form, a rule in the context we are defining is a protocol 145 object that is traditionally defined by a bit diagram in the protocol 146 specification. Further and more complex rules are constructed by 147 combining other rules using operators. The most complex rule is the 148 message that is constructed from an organization of protocol objects 149 as specified by the operators. 151 An RBNF specification consists of a sequence of rule definitions 152 using the operators defined in Section 2.2. One rule may be 153 constructed from a set of other rules using operators. The order of 154 definition of rules does not matter. That is, the sub-ordinate rules 155 MAY be defined first and then used in subsequent definitions of 156 further rules, or the top-level rules MAY be defined first followed 157 by a set of definitions of the sub-ordinate rules. 159 2.1. Rule Definitions 161 No semantics should be assumed from special characters used in rule 162 names. For example, it would be wrong to assume that a rule carries a 163 decimal number because the rule name begins or ends with the letter 164 "d". However, individual specifications MAY choose to assign rule 165 names in any way that makes the human interpretation of the rule more 166 easy. 168 2.1.1. Rule Name Delimitation 170 All rule names are enclosed by angle brackets ("<" and ">"). Rule 171 names MAY include any printable characters, but MUST NOT include tabs 172 or line feeds/breaks. 174 Example: 175 177 2.1.2. Objects 179 The most basic (indivisible) rule is termed an object. The definition 180 of an object is derived from its context. 182 Objects are typically named in upper case. They do not usually use 183 spaces within the name, favoring underbars ("_"). 185 Example: 186 188 2.1.3. Constructs 190 Rules that are constructed from other rules using operators are 191 termed constructs. 193 Constructs are named in lower case, although capitals are commonly 194 used to indicate acronyms. Spaces and hyphens are used between words 195 within names. 197 Example: 198 200 2.1.4. Messages 202 The final objective is the definition of messages. These are rules 203 that are constructed from objects and constructs using operators. The 204 only syntactic difference between a message and a construct is that 205 no other rule is typically constructed from a message. 207 Messages are typically named in title case. 209 Example: 210 212 2.2. Operators 214 Operators are used to build constructs and messages from objects and 215 constructs. 217 2.2.1. Assignment 219 Assignment is used to form constructs and messages. 221 Meaning: 222 The named construct or message on the left-hand side is defined to 223 be set equal to the right-hand side of the assignment. 225 Encoding: 226 colon, colon, equal sign ("::=") 228 Example: 229 ::= 231 Note: 232 The left-hand side of the assignment and the assignment operator 233 MUST be present on the same line. 235 2.2.2. Concatenation 237 Objects and constructs can be combined as a sequence to form a new 238 construct or a message. 240 Meaning: 241 The objects or constructs MUST be present in the order specified. 243 Encoding: 244 A sequence of objects and constructs usually separated by spaces. 245 The objects in a sequence MAY be separated by line breaks. 247 Example: 248 ::= 250 Note: 251 See Section 2.3.3 for further comments on ordering of objects and 252 constructs. 254 2.2.3. Optional Presence 256 Objects and constructs can be marked as optionally present. 258 Meaning: 259 The optional objects or constructs MAY be present or absent within 260 the assignment. Unless indicated as optional, objects and 261 constructs are mandatory and MUST be present. The optional operator 262 can also be nested to give a hierarchical dependency of presence as 263 shown in the example below. 265 Encoding: 266 Contained in square brackets ("[" and "]"). 268 Example: 269 ::= [ ] 270 271 [ ] 273 Example of nesting: 274 The optional operator can be nested. For example, 276 ::= [ [ ] ] 278 In this construction, the object OPT_2 can only be present if OPT_1 279 is also present. 281 Note: 282 The set of objects and constructs within the same pair of square 283 brackets is treated as a unit (an unnamed construct). This means 284 that when multiple objects and constructs are included within the 285 same pair of square brackets, all MUST be included when one is 286 included unless nested square brackets are used as in the previous 287 example. 289 2.2.4. Alternatives 291 Choices can be indicated within assignments. 293 Meaning: 294 Either one rule or the other MUST be present. 296 Encoding: 297 The pipe symbol ("|") is used between the objects or constructs 298 that are alternatives. 300 Example: 301 ::= 302 | 304 Notes: 305 1. Use of explicit grouping (Section 2.2.6) is RECOMMENDED to avoid 306 confusion. Implicit grouping using line breaks (Section 2.3.2) 307 is often used, but gives rise to potential misinterpretation and 308 SHOULD be avoided in new definitions. 310 2. Multi-way alternates are not common. To avoid confusion, 311 explicit grouping (see Section 2.2.6), or an intermediary MUST 312 be used. Thus: 314 ::= | | 316 is not allowed and MUST be presented using grouping or using an 317 intermediary construct. For example: 319 ::= ( | ) | 321 or 323 ::= | 324 ::= | 326 2.2.5. Repetition 328 It could be the case that a sequence of identical objects or 329 constructs is required within an assignment. 331 Meaning: 332 One or more of the same object, intermediate construct, or 333 construct MUST be present. 335 Encoding: 336 Three dots ("..."). 338 Example: 339 ::= [ ] 340 341 342 [ ... ] 343 [ ] 345 Notes: 346 1. A set of zero or more objects or constructs can be achieved by 347 combining with the Optional concept as shown in the example 348 above. 350 2. Sequences can also be encoded by building a recursive construct 351 using the Alternative operator. For example: 353 ::= | 354 356 3. Repetition can also be applied to a component of an assignment 357 to indicate the optional repetition of that component. For 358 example, the Notify message in [RFC3473] is defined as follows: 360 ::= 361 [] 362 [ [ | ] ... ] 363 [ ] 364 366 In this example, there is a sequence of zero or more instances 367 of [ | ]. One could argue that 368 the use of grouping (see Section 2.2.6) or a recursive construct 369 (see Note 2, above) would be more clear. 371 2.2.6. Grouping 373 Meaning: 374 A group of objects or constructs to be treated together. This 375 notation is not mandatory but is RECOMMENDED for clarity. See 376 Section 2.4 on Precedence. 378 Encoding: 379 Round brackets ("(" and ")") enclosing a set of objects, 380 constructs, and operators. 382 Example: 383 ::= ( ) 385 Notes: 386 1. The precedence rule in Section 2.4 means that the use of 387 grouping is not necessary for the formal interpretation of the 388 BNF representation. However, grouping can make the BNF easier to 389 parse unambiguously. Either grouping or an intermediate 390 construct MUST be used for multi-alternates (Section 2.2.4). 392 2. Line breaks (Section 2.3.2) are often used to clarify grouping 393 as can be seen in the definition of in Section 2.2.5, 394 but these are open to misinterpretation, and explicit grouping 395 is RECOMMENDED. 397 3. A practical alternative to grouping is the definition of 398 intermediate constructs as illustrated in Note 2 of Section 399 2.2.4. 401 2.3. Editorial Conventions 403 2.3.1. White Space 405 White space (that is space characters) between operators, objects, 406 and constructs is ignored, but SHOULD be used for readability. 408 2.3.2. Line Breaks 410 Line breaks within an assignment are ignored, but SHOULD be used for 411 readability. 413 Line breaks are often used to imply grouping within the precedence 414 rules set out in Section 2.4, but explicit grouping (Section 2.2.6) 415 or intermediary constructs (Section 2.2.4) SHOULD be used in new 416 definitions. 418 A line break MUST NOT be present between the left-hand side of an 419 assignment and the assignment operator (see Section 2.2.1). 421 New assignments (i.e., new construct or message definitions) MUST 422 begin on a new line. 424 2.3.3. Ordering 426 The ordering of objects and constructs in an assignment is explicit. 428 Protocol specifications MAY opt to state that ordering is only 429 RECOMMENDED. In this case, elements of a list of objects and 430 constructs MAY be received in any order. 432 2.4. Precedence 434 Precedence can be deduced from a "proper" reading of the BNF using 435 the rules defined above and the precedence ordering shown below. 436 Grouping (Section 2.2.6) and ordering (Section 2.3.3) are RECOMMENDED 437 for clarity. 439 The various mechanisms described above have the following precedence, 440 from highest (binding tightest) at the top, to lowest and loosest at 441 the bottom: 443 objects, constructs 444 repetition 445 grouping, optional 446 concatenation 447 alternative 449 Note: 450 Precedence is the main opportunity for confusion in the use of BNF. 451 Authors are strongly RECOMMENDED to use grouping (Section 2.2.6) in 452 all places where there is any scope for misinterpretation even when 453 the meaning is obvious to the authors. 455 Example: 456 An example of the confusion in precedence can be found in Section 457 3.1.4 of [RFC2205]. 459 ::= | 460 462 The implementer MUST decide which of the following is intended. 464 a. ::= | 465 ( ) 467 b. ::= ( | ) 468 470 The line break MAY be interpreted as implying grouping, but that is 471 not an explicit rule. However, the precedence rules say that 472 Concatenation has higher precedence than the Alternative operator. 473 Thus, the text in [RFC2205] SHOULD be interpretted as shown in 474 formulation a. 476 Similarly (from the same section of [RFC2205]) 478 ::= 479 | 480 482 SHOULD be interpretted as 484 ::= 485 ( ) | 486 ( ) 488 The use of explicit grouping or intermediary constructs is strongly 489 RECOMMENDED in new text to avoid confusion. 491 3. Automated Validation 493 RBNF would be appropriate for verification using automated validation 494 tools. No tools are known at this time. 496 4. IANA Considerations 498 This document makes no requests for IANA action. 500 5. Security Considerations 502 This document does not define any network behavior and does not 503 introduce or seek to solve any security issues. 505 It may be noted that clear and unambiguous protocol specifications 506 reduce the likelihood of incompatible or defective implementations 507 that might be exploited in security attacks. 509 6. Acknowledgments 511 Thanks to Magnus Westerlund, Nic Neate, Chris Newman, Alfred Hoenes, 512 Lou Berger, and Julien Meuric for review and useful comments. 514 7. References 516 7.1. Normative References 518 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 519 Requirement Levels", BCP 14, RFC 2119, March 1997. 521 7.2. Informative References 523 [RFC2205] Braden, R. (Ed.), Zhang, L., Berson, S., Herzog, S., and S. 524 Jamin, "Resource ReserVation Protocol -- Version 1 525 Functional Specification", RFC 2205, September 1997. 527 [RFC3209] Awduche, D., Berger, L., Gan, D., Li, T., Srinivasan, V., 528 and G. Swallow, "RSVP-TE: Extensions to RSVP for LSP 529 Tunnels", RFC 3209, December 2001. 531 [RFC3473] Berger, L., "Generalized Multi-Protocol Label Switching 532 (GMPLS) Signaling Resource ReserVation Protocol-Traffic 533 Engineering (RSVP-TE) Extensions", RFC 3473, January 2003. 535 [RFC4204] Lang, J., Ed., "The Link Management Protocol (LMP)", RFC 536 4204, September 2005. 538 [RFC5234] Crocker, D. (Ed.) and Overell, P., "Augmented BNF for 539 Syntax Specifications: ABNF", STD 68, RFC 5234, January 540 2008. 542 [PCEP] Vasseur, J.P., and Le Roux, J.-L., "Path Computation 543 Element (PCE) Communication Protocol (PCEP) - Version 1", 544 draft-ietf-pce-pcep, work in progress. 546 [EBNF] ISO/IEC 14977, "Information technology -- Syntactic 547 metalanguage -- Extended BNF", 1996 549 Author's Address 551 Adrian Farrel 552 Old Dog Consulting 554 Email: adrian@olddog.co.uk 556 Full Copyright Statement 558 Copyright (C) The IETF Trust (2008). 560 This document is subject to the rights, licenses and restrictions 561 contained in BCP 78, and except as set forth therein, the authors 562 retain all their rights. 564 This document and the information contained herein are provided on an 565 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 566 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 567 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 568 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 569 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 570 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 572 Intellectual Property 574 The IETF takes no position regarding the validity or scope of any 575 Intellectual Property Rights or other rights that might be claimed to 576 pertain to the implementation or use of the technology described in 577 this document or the extent to which any license under such rights 578 might or might not be available; nor does it represent that it has 579 made any independent effort to identify any such rights. Information 580 on the procedures with respect to rights in RFC documents can be 581 found in BCP 78 and BCP 79. 583 Copies of IPR disclosures made to the IETF Secretariat and any 584 assurances of licenses to be made available, or the result of an 585 attempt made to obtain a general license or permission for the use of 586 such proprietary rights by implementers or users of this 587 specification can be obtained from the IETF on-line IPR repository at 588 http://www.ietf.org/ipr. 590 The IETF invites any interested party to bring to its attention any 591 copyrights, patents or patent applications, or other proprietary 592 rights that may cover technology that may be required to implement 593 this standard. Please address the information to the IETF at 594 ietf-ipr@ietf.org.