idnits 2.17.1 draft-ietf-stdguide-ops-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** 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 document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 144 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 440: '... MAY...' RFC 2119 keyword, line 444: '... MUST...' RFC 2119 keyword, line 449: '... MUST NOT...' RFC 2119 keyword, line 453: '... OPTIONAL...' RFC 2119 keyword, line 457: '... RECOMMENDED...' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 369 has weird spacing: '...machine mode...' -- 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 (August 1996) is 10115 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 section? 'X' on line 503 looks like a reference Summary: 11 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 st 3 Network Working Group G. Scott 4 INTERNET DRAFT Defense Information Systems Agency 5 August 1996 7 Guide for Internet Standards Writers 8 10 Status of this Document 12 This document is an Internet Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, 14 and its working groups. Note that other groups may also distribute 15 working documents as Internet Drafts. 17 Internet Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is not appropriate to use Internet Drafts as reference 20 material or to cite them other than as a "working draft" or "work in 21 progress." 23 To learn the current status of any Internet Draft, please check the 24 ``1id-abstracts.txt'' listing contained in the Internet-Drafts Shadow 25 Directories on ds.internic.net (US East Coast), nic.nordu.net 26 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 27 Rim). 29 Distribution of this document is unlimited. 31 This Internet Draft expires 21 February 1997. 33 Abstract 35 This document is a guide for Internet standard writers. It defines those 36 characteristics that make standards coherent, unambiguous, and easy to 37 interpret. Also, it singles out usage believed to have led to unclear 38 specifications, resulting in non-interoperable interpretations in the past. 40 This version of the document is a draft. It's intended to generate further 41 discussion and addition by the STDGUIDE working group. Please send comments 42 to stdguide@midnight.com or to the author. 44 Table of Contents 46 1 Introduction 47 2 General Guidelines 48 2.1 Protocol Description 49 2.2 Discussion of Security 50 2.3 Level of Detail 51 2.4 Protocol Versions 52 2.5 Decision History 53 2.6 Response to Behavior Out of Scope 54 2.7 The Liberal/Conservative Rule 55 2.8 Handling of Protocol Options 56 2.9 BNF Notation 57 2.10 Implementation Experience 58 3 Specific Guidelines 59 3.1 Packet Diagrams 60 3.2 Summary Tables 61 3.3 State Machine Descriptions 62 4 Glossary 63 5 Document Checklist 64 6 Author's Addresses 65 7 References 67 1 Introduction 69 This document is a guide for Internet standard writers. It offers 70 guidelines on how to write a protocol specification with clarity, 71 precision, and completeness. These guidelines are based on both prior 72 successful and unsuccessful IETF specification experiences. Note that some 73 guidelines may not apply in certain situations. 75 The goal is to increase the possibility that multiple implementations of a 76 protocol will interoperate. Writing specifications to these guidelines 77 will not guarantee interoperability. However, a recognized barrier to the 78 creation of interoperable protocol implementations is unclear 79 specifications. 81 Many will benefit from having well-written protocol specifications. 82 Implementors will have a better chance to conform to the protocol 83 specification. Protocol testers can use the specification to derive 84 unambiguous testable statements. Purchasers and users of the protocol will 85 have a better understanding of its capabilities. 87 2 General Guidelines 89 It is important that multiple readers and implementors of a standard have 90 the same understanding of a document. To this end, information should be 91 orderly and detailed. The following are general guidelines intended to 92 help in the production of such a document. 94 2.1 Protocol Description 96 Standards must include a description of the purpose or context of a 97 protocol's use. The author of a protocol specification will have a great 98 deal of knowledge as to the purpose of a protocol. However, the reader is 99 more likely to have general networking knowledge and experience, rather 100 than expertise in a particular protocol. Without an explanation of the 101 purpose behind a protocol interpreting it is far more difficult, and a 102 reader is more prone to error. 104 This also applies to the algorithms used by a protocol. A detailed 105 description of the algorithms or citation of readily available references 106 that give such a description is necessary. 108 2.2 Discussion of Security 110 If the Internet is to achieve its full potential in commercial, 111 governmental, and personal affairs, it must assure users that deliveries of 112 their information transfers are free from tampering or compromise. 113 Well-written security sections in standard protocol documents can do much to 114 achieve that condition. Implementors will find it easier to comply and do 115 security. Users can understand the security measures in place, and so have 116 faith in the Internet. 118 The security section should address several topics. Very important is a 119 description of the security issues the protocol solves, and what issues 120 remain unsolved. The effects the security measures have on the protocol's 121 use and performance. If possible, the discussion should address how much 122 insurance the implementation of the security measures achieves. 124 An author may not include security measures or considerations in the 125 protocol standard. If so, a detail explanation why they did not is 126 necessary. This discussion could present the reasons why the security 127 issues are unresolvable at this time. Alternatively, the author could 128 present a case why security is unneeded when using the protocol. 130 These security sections should be complete and stand alone. If security 131 measures are part of the general protocol text, they will be difficult to 132 find. If the security measures are not clear they may not be implemented, 133 nor will a user be assured that they exist. 135 Finally, it is no longer acceptable that security sections consist solely 136 of statements similar to: "Security issues are not discussed in this RFC." 138 2.3 Level of Detail 140 The author should consider whether concise or verbose text best conveys the 141 protocol's intent. Concise text has several advantages. It makes the 142 document easier to read. Such text reduces the chance for conflict between 143 different portions of the specification. The reader can readily identify 144 the required protocol mechanisms in the standard. Also, it makes it easier 145 to identify the requirements for protocol implementation. A disadvantage 146 of concise descriptions is that a reader may not fully comprehend the 147 reasoning behind the protocol, and thus make assumptions that will lead to 148 implementation errors. 150 Longer descriptions may be necessary, however, to explain purpose, 151 background, rationale, implementation experience, or to provide tutorial 152 information. This permits explanations at sufficient depth to insure 153 understanding of the protocol. Yet several dangers exist with lengthy 154 text. Finding the protocol requirements in the text is difficult or 155 confusing. An increased risk that the same mechanism may have multiple 156 descriptions, which leads to misinterpretations or conflict. Lengthy text 157 is a challenge to the attention span of some readers. Finally, it is more 158 difficult to comprehend, a consideration as English is not the native 159 language of the many worldwide readers of IETF standards. 161 One approach is to divide the standard into sections: one describing the 162 protocol concisely, while another section consists of explanatory text. 163 The STD 3/RFC 1122/RFC 1123 1812 provides examples of this method. 165 2.4 Protocol Versions 167 Often the standard is specifying a new version of an existing protocol. In 168 such a case, the authors should detail the differences between the previous 169 version and the new version. This should include the rationale for the 170 changes, for example, implementation experience, changes in technology, 171 responding to user demand, etc. 173 2.5 Decision History 175 In standards development, reaching consensus requires making difficult 176 choices. Including a discussion history and rationales for a decision can 177 prevent future revisiting of these disagreements later, when the original 178 parties have moved on. Occasionally, the alternative not taken may have 179 been simpler to implement, so including the logic behind the choice may 180 prevent future implementors from taking nonstandard shortcuts. 182 2.6 Response to Out of Specification Behavior 184 Recommend that detail description of the actions taken in case of behavior 185 that is deviant from or exceeds the specification be included. This is an 186 area where implementors often differ in opinion as to the appropriate 187 response. By specifying a common response, the standard author can strike 188 a blow against the law of unintended consequences. 190 The standard should describe responses to behavior explicitly forbidden or 191 out of the boundaries defined by the specification. Two possible 192 approaches to such cases are discarding, or invoking error-handling 193 mechanisms. If discarding is chosen, detailing the disposition may be 194 necessary. For instance, treat dropped frames as if they never were 195 received, or reset an existing connection or adjacency state. 197 The specification should describe actions taken when critical resource or 198 performance scaling limits are exceeded. This is not necessary for every 199 case. It is necessary for cases where a risk of network degradation or 200 operational failure exists. In such cases, a consistent behavior between 201 implementations is necessary. 203 2.7 The Liberal/Conservative Rule 205 A rule, first stated in RFC 791, recognized as having benefits in 206 implementation robustness and interoperability is: 208 "Be liberal in what you accept, and 209 conservative in what you send." 211 Or establish restrictions on what a protocol transmits, but have few 212 restrictions on what it will receive. To avoid any confusion between the 213 two, recommend that standard authors specify send and receive behavior 214 separately. 216 The effect of this approach is that the description of reception will 217 require the most detailing. For implementations will be expected to accept 218 any packet from the network without failure or malfunction. Therefore, the 219 actions taken to achieve that result, need to be laid out in the protocol 220 specification. Standard authors should consider not just how to survive on 221 the network, but achieve the highest level of cooperation possible to limit 222 the amount of network disruption. The appearance of undefined information 223 or conditions must not cause a network or host failure. This requires 224 specification on how to attempt acceptance of most of the packets. Two 225 approaches are available, either using as much of the packet's content as 226 possible, or invoking error procedures. Specify a dividing line on when to 227 take which approach. 229 A case for consideration is that of a routing protocol, where acceptance of 230 flawed information can cause network failure. For protocols such as this, 231 the specification should identify packets that could have differing 232 interpretations and mandate that they be ignored. For example, routing 233 updates contain more data than the tuple count shows. 235 2.8 Handling of Protocol Options 237 Standards with many optional features increase the chance of 238 non-interoperable implementations. The danger is that different protocol 239 implementations may specify some optional combinations that are unable to 240 interoperate with each other. Ideally, implementation experience purges 241 options from the protocol while the document moves along the standard 242 track. 244 Options should only be present in cases where the protocol has an item that 245 a particular marketplace requires, or because it enhances the product. The 246 protocol specification must explain the full implications of either using 247 the option or not, and the case for choosing either course. However, 248 omission of the optional item should have no interoperability consequences 249 for the implementation that does so. 251 Certain cases will require the specifying of mutually exclusive options 252 within a protocol. That is, the implementation of an optional feature 253 precludes the implementation of the other optional feature. For clarity, 254 provide details on when to implement one or the other, what the effect of 255 choosing one over the other is, and what problems the implementor or user 256 may face. The choice of one or the other options should have no 257 interoperability consequences between multiple implementations. 259 The most prevalent current practice in the specification of Internet 260 standards is to identify mandatory protocol features by the term "MUST," 261 and optional features by "MAY" or "SHOULD." 262 2.9 Notational Conventions 264 Formal syntax notations can be used to define complicated protocol concepts 265 or data types, and also to specify values of these data types. This 266 permits the protocol to be written with out concern on how the 267 implementation is constructed or how the data type is represented during 268 transfer. The specification is simplifed because it can be presented as 269 "axioms" that will be proven by implementation. 271 The formal specification of the syntax used should be referenced in the 272 text of the standard. Any extensions, subsets, alterations, or exceptions 273 to the formal syntax should be defined. 275 The STD 11/RFC 822 provides an example of this. In RFC 822 (Section 2 and 276 Appendix D) the Backus-Naur Form (BNF) meta-language was extended to make 277 its representation smaller and easier to understand. Another example is 278 STD 16/RFC 1155 (Section 3.2) where a subset of the Abstract Syntax 279 Notation One (ASN.1) is defined. 281 2.10 Implementation Experience 283 For a protocol to be designated a standard, it must go through the rigors 284 of actual implementation. This implementation experience should be 285 captured in the final document. For example, lessons learned from bakeoffs 286 between multiple vendors. 288 3 Specific Guidelines 290 The following are guidelines on how to present specific technical 291 information in standards. 293 3.1 Packet Diagrams 295 Most link, network, and transport layer protocols have packet descriptions. 296 Recommend that packet diagrams be included in the standard, as they are 297 very helpful to the reader. The preferred form for packet diagrams is a 298 sequence of long words in network byte order, with each word horizontal on 299 the page and bit numbering at the top: 301 0 1 2 3 302 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 303 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 304 |Version| Prio. | Flow Label | 305 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 307 In cases where a packet is strongly byte-aligned rather than word-aligned 308 (e.g., when byte-boundary variable-length fields are used), display packet 309 diagrams in a byte-wide format. Use different height boxes for short and 310 long words, and broken boxes for variable-length fields: 312 0 1 2 3 4 5 6 7 313 +-+-+-+-+-+-+-+-+ 314 | Length N | 315 +-+-+-+-+-+-+-+-+ 316 | | 317 + Address + 318 ... 319 + (N bytes) + 320 | | 321 +-+-+-+-+-+-+-+-+ 322 | | 323 + 2-byte field + 324 | | 325 +-+-+-+-+-+-+-+-+ 327 3.2 Summary Tables 329 The specifications of some protocols are particularly lengthy, sometimes 330 covering a hundred pages or more. In such cases the inclusion of a summary 331 table can reduce the risk of conformance failure by an implementation 332 through oversight. A summary table itemizes what in a protocol is 333 mandatory, optional, or prohibited. Summary tables do not guarantee 334 conformance, but serve to assist an implementor in checking that they have 335 addressed all protocol features. 337 The summary table will consist of, as a minimum, four (4) columns: 338 Protocol Feature, Section Reference, Status, and References/Footnotes. Use 339 additional columns if they further explain or clarify the protocol. 341 In the Protocol Feature column describe the feature, for example, a command 342 word. Group series of related transactions under descriptive headers, for 343 example, RECEPTION. 345 Section reference directs the implementor to the section, paragraph, or 346 page that describes the protocol feature in detail. 348 Status indicates whether the feature is mandatory, optional, or prohibited. 349 Provide a separate column for each possibility, or a single column with 350 appropriate codes. These codes need to be defined at the start of the 351 summary table to avoid confusion. Possible status codes: 353 M - must M - mandatory 354 MN - must not O - optional 355 S - should X - prohibited 356 SN - should not 358 Use the References/Footnotes column to point to other RFCs that are 359 necessary to consider in implementing this protocol feature, or any 360 footnotes necessary to further explain the implementation. 362 RFCs 1122 and 1123 provide examples of summary tables. 364 3.3 State Machine Descriptions 366 A convenient method of presenting a protocol's behavior is as a 367 state-machine model. That is, a protocol can be described by as a series 368 of states resulting from a command, operation, or transaction. 369 State-machine models define the variables and constants that establish a 370 state, the events that cause state transitions, and the actions that result 371 from those transitions. Through these models, understanding the dynamic 372 operation of the protocol as sequence of state transitions that occur for 373 any given event. Detailed text description of the state machines is 374 necessary. Also, recommend the use of diagrams, tables, or timelines to 375 detail state transitions. 377 When using a state transition diagram, show each possible protocol state as 378 a box connected by state transition arcs. Label each arc with the event 379 that causes the transition, and, in parentheses, any actions taken during 380 the transition. The STD 5/RFC 1112 provides an example of such a diagram. 381 As ASCII text is the preferred storage format for RFCs, only simple 382 diagrams are possible. Tables can summarize more complex or extensive 383 state transitions. 385 In a state transition table, read events vertically and states 386 horizontally. Represent state transitions and actions in the form 387 action/new-state. Use commas to separate multiple actions, and go on 388 succeeding lines as required. Present multiple actions in the order they 389 must be executed, if relevant. Letters that follow the state indicate an 390 explanatory footnote. The dash ('-') indicates an illegal transition. The 391 STD 51/RFC 1661 provides an example of such a state transition table. The 392 initial columns and rows of that table are below as an example: 394 | State 395 | 0 1 2 3 4 5 396 Events| Initial Starting Closed Stopped Closing Stopping 397 ------+----------------------------------------------------------- 398 Up | 2 irc,scr/6 - - - - 399 Down | - - 0 tls/1 0 1 400 Open | tls/1 1 irc,scr/6 3r 5r 5r 401 Close| 0 tlf/0 2 2 4 4 402 | 403 TO+ | - - - - str/4 str/5 404 TO- | - - - - tlf/2 tlf/3 406 The STD 18/RFC 904 also presents state transitions in table format. 407 However, it lists transitions in the form n/a, where n is the next state 408 and a represents the action. The method in RFC 1661 is preferred as 409 new-state logical follows action. Also, this RFC's Appendix C models 410 transitions as the Cartesian product of two state machines. This is a more 411 complex representation that may be difficult to comprehend for those 412 readers that are unfamiliar with the format. Recommend that authors 413 present tables as defined in the previous paragraph. 415 A final method of representing state changes is by a timeline. The two 416 sides of the timeline represent the machines involved in the exchange. 417 List the states the machines enter as time progresses (downward) along the 418 outside of timeline. Within the timeline, show the actions that cause the 419 state transitions. An example: 421 client server 423 | | 424 | | LISTEN 425 SYN_SENT |----------------------- | 426 | \ syn j | 427 | ----------------->| SYN_RCVD 428 | | 429 | ------------------| 430 | syn k, ack j+1 / | 431 ESTABLISHED |<---------------------- | 432 | | 434 4 Glossary 436 Internet standards are to use the following terms. Deviations from the 437 definitions given are discouraged, as it will likely cause 438 misinterpretations among readers. 440 MAY 442 This word defines the existence of an item that is optional. 444 MUST 446 This word defines the existence of an item that is an absolute requirement 447 of the specification. 449 MUST NOT 451 This phrase prohibits the use of the item. 453 OPTIONAL 455 This word specifies that implementation of an item is discretionary. 457 RECOMMENDED 459 This word specifies an item that there may exist valid reasons in 460 particular circumstances to ignore. 462 REQUIRED 464 This word specifies an item that is an absolute requirement of the 465 specification. 467 SHOULD 469 This word defines the existence of an item that there may exist valid 470 reasons in particular circumstances to ignore. 472 SHOULD NOT 474 This phrase means that there may exist circumstances when the described 475 behavior is acceptable or even useful. Even so, describe the full 476 implications so that the implementor can carefully weigh the pros and cons 477 of the behavior. 479 The above definitions are of a "contractual" nature. This RFC does not 480 define technical terms. These definitions have been evolving with 481 technology. Extensive and detailed technical definitions in documents aid 482 understanding. 484 5.0 Document Checklist 486 The following is a checklist based on these suggestions which can be 487 applied to a document: 489 o Does it explain the purpose of the protocol? 490 o Does it reference or explain the algorithms used in the protocol? 491 o Does it give packet diagrams in recommended form, if applicable? 492 o Does it use the recommended meaning for any of the terms defined in the 493 glossary above? 494 o Does it separate explanatory portions of the document from requirements? 495 o Does it describe differences from previous versions, if applicable? 496 o Does it give examples of protocol operation? 497 o Does it specify behavior in the face of incorrect operation by other 498 implementations? 499 o Does it delineate which packets should be accepted for processing and 500 which should be ignored? 501 o Does it consider performance and scaling issues? 502 o How many optional features (MAY, SHOULD) does it specify? If more than 503 [X], does it separate them into option classes? 504 o Have all combinations of options or option classes been examined for 505 incompatibility? 506 o If multiple descriptions of a requirement are given, does it identify 507 one as binding? 509 6. Author's Addresses 511 Gregor D. Scott 512 Director, Defense Information Systems Agency 513 ATTN: JIEO-JEBBD 514 Ft. Monmouth, NJ 07703-5613 USA 516 Phone: (908) 532-7726 517 Fax: (908) 532-7723 518 EMail: scottg@ftm.disa.mil 519 7. References 521 RFC 791 "Internet Protocol (IP)," J. Postel, September 1981. 523 RFC 904 "Exterior Gateway Protocol formal specification," D. Mills, 524 April 1984 526 RFC1112 "Host extensions for IP multicasting," S. Deering, August 1989 528 RFC 1122 "Requirements for Internet Hosts -- Communication Layers," 529 October 1989 531 RFC 1123 "Requirements for Internet hosts -- Application and Support," 532 October 1989 534 RFC 1311 "Introduction to the STD Notes" 536 RFC 1602 "The Internet Standards Process - Revision 2" 538 RFC 1661 "The Point-to-Point Protocol (PPP)," W. Simpson, July 1994 540 This Internet Draft expires 21 February 1997.