idnits 2.17.1 draft-ietf-stdguide-ops-06.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-19) 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 124 has weird spacing: '...cedures pleas...' == Line 784 has weird spacing: '...rly the threa...' -- 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 (March 1998) is 9532 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: 7 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group G. Scott, Editor 3 INTERNET DRAFT Defense Information Systems Agency 4 March 1998 6 Guide for Internet Standards Writers 7 9 Status of this Memo 11 This document is an Internet Draft. Internet Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, 13 and its working groups. Note that other groups may also distribute 14 working documents as Internet Drafts. 16 Internet Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is not appropriate to use Internet Drafts as reference 19 material or to cite them other than as a "working draft" or "work in 20 progress." 22 To learn the current status of any Internet-Draft, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ds.internic.net (US East Coast), nic.nordu.net 25 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 26 Rim). 28 Distribution of this document is unlimited. 30 This Internet Draft expires on 15 September 1998. 32 Abstract 34 This document is a guide for Internet standard writers. It defines 35 those characteristics that make standards coherent, unambiguous, and 36 easy to interpret. Also, it singles out usage believed to have led 37 to unclear specifications, resulting in non-interoperable 38 interpretations in the past. These guidelines are to be used with 39 RFC 1543, "Instructions to RFC Authors." 41 This version of the document is a draft. 43 CHANGES FROM DRAFT -04 45 A paragraph pointing to a pending document that further addresses 46 security was updated. 48 References to RFC 1583 were changed to RFC 2178 which obsoleted it. 50 Editorial changes and corrections were also made. 52 CHANGES FROM DRAFT -05 54 A sentence pointing to a pending document that further addresses IANA 55 considerations was added to section 2.13. The current draft of that 56 document is draft-iesg-iana-considerations-02.txt. A clause stating 57 that the IANA established the assignment policies was removed since 58 it appeared to conflict with the intent of the referenced ID. Place 59 holders for the BCP and RFC number have been added to the text and 60 reference section. 62 A new section (2.5) requiring change logs as documents progress along 63 the standards track was added. 65 References to RFC 2044 were changed to RFC 2279 which obsoleted it. 67 Spelling and grammar corrections were made. 69 Table of Contents 71 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2 General Guidelines . . . . . . . . . . . . . . . . . . . . . . 3 73 2.1 Discussion of Security . . . . . . . . . . . . . . . . . . . . 3 74 2.2 Protocol Description . . . . . . . . . . . . . . . . . . . . . 5 75 2.3 Target Audience . . . . . . . . . . . . . . . . . . . . . . . . 6 76 2.4 Level of Detail . . . . . . . . . . . . . . . . . . . . . . . . 6 77 2.5 Change Logs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 2.6 Protocol Versions . . . . . . . . . . . . . . . . . . . . . . . 7 79 2.7 Decision History . . . . . . . . . . . . . . . . . . . . . . . 7 80 2.8 Response to Out of Specification Behavior . . . . . . . . . . . 7 81 2.9 The Liberal/Conservative Rule . . . . . . . . . . . . . . . . . 8 82 2.10 Handling of Protocol Options . . . . . . . . . . . . . . . . . 9 83 2.11 Indicating Requirement Levels . . . . . . . . . . . . . . . . . 10 84 2.12 Notational Conventions . . . . . . . . . . . . . . . . . . . . 10 85 2.13 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 11 86 2.14 Network Management Considerations . . . . . . . . . . . . . . . 11 87 2.15 Scalability Considerations . . . . . . . . . . . . . . . . . . 11 88 2.16 Network Stability . . . . . . . . . . . . . . . . . . . . . . . 12 89 2.17 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 90 3 Specific Guidelines . . . . . . . . . . . . . . . . . . . . . . 13 91 3.1 Packet Diagrams . . . . . . . . . . . . . . . . . . . . . . . . 13 92 3.2 Summary Tables . . . . . . . . . . . . . . . . . . . . . . . . 14 93 3.3 State Machine Descriptions . . . . . . . . . . . . . . . . . . 14 94 3.4 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . 16 95 4 Document Checklist . . . . . . . . . . . . . . . . . . . . . . 16 96 5 Security Considerations . . . . . . . . . . . . . . . . . . . . 17 97 6 References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 98 7 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 19 99 8 Editor's Address . . . . . . . . . . . . . . . . . . . . . . . 19 101 1 Introduction 103 This document is a guide for Internet standard writers. It offers 104 guidelines on how to write a standards-track document with clarity, 105 precision, and completeness. These guidelines are based on both 106 prior successful and unsuccessful IETF specification experiences. 107 These guidelines are to be used with RFC 1543, "Instructions to RFC 108 Authors," or its update. Note that some guidelines may not apply in 109 certain situations. 111 The goal is to increase the possibility that multiple implementations 112 of a protocol will interoperate. Writing specifications to these 113 guidelines will not guarantee interoperability. However, a 114 recognized barrier to the creation of interoperable protocol 115 implementations is unclear specifications. 117 Many will benefit from having well-written protocol specifications. 118 Implementors will have a better chance to conform to the protocol 119 specification. Protocol testers can use the specification to derive 120 unambiguous testable statements. Purchasers and users of the 121 protocol will have a better understanding of its capabilities. 123 For further information on the process for standardizing protocols 124 and procedures please refer to BCP 9/RFC 2026, "The Internet 125 Standards Process -- Revision 3." Also, some considerations for 126 protocol design are given in RFC 1958, "Architectural Principles of 127 the Internet." 129 2 General Guidelines 131 It is important that multiple readers and implementors of a standard 132 have the same understanding of a document. To this end, information 133 should be orderly and detailed. The following are general guidelines 134 intended to help in the production of such a document. The IESG may 135 require that all or some of the following sections appear in a 136 standards track document. 138 2.1 Discussion of Security 140 If the Internet is to achieve its full potential in commercial, 141 governmental, and personal affairs, it must assure users that their 142 information transfers are free from tampering or compromise. Well- 143 written security sections in standards-track documents can help 144 promote the confidence level required. For an implementor will find 145 it easier to provide the security measures specified. While users 146 will understand the security measures, and so have a higher level of 147 trust in the Internet. Above all, new protocols and practices must 148 not worsen overall Internet security. 150 A significant threat to the Internet are those individuals who are 151 motivated and capable of exploiting circumstances, events, or 152 vulnerabilities of the system to cause harm. Also, deliberate or 153 inadvertent user behavior may expose the system to attack or 154 exploitation. The harm could range from disrupting or denying 155 network service, to damaging user systems. Additionally, information 156 disclosure could provide the means to attack another system, or 157 reveal patterns of behavior that could be used to harm an individual, 158 organization, or network. This is a particular concern with 159 standards that define a portion of the Management Information Base 160 (MIB). 162 Standards authors must accept that the protocol they specify will be 163 subject to attack. They are responsible for determining what attacks 164 are possible, and for detailing the nature of the attacks in the 165 document. Otherwise, they must convincingly argue that attack is not 166 realistic in a specific environment, and restrict the use of the 167 protocol to that environment. 169 This discussion of the threat model and other assumptions should 170 appear early in the standard. Doing so will establish a basis for 171 the further discussion of security throughout the document. 173 After the document has exhaustively identified the security risks the 174 protocol is exposed to, the authors must formulate and detail a 175 defense against those attacks. They must discuss the applicable 176 countermeasures employed, or the risk the user is accepting by using 177 the protocol. The countermeasures may be provided by a protocol 178 mechanism or by reliance on external mechanisms. Authors should be 179 knowledgeable of existing security mechanisms, and reuse them if 180 practical. When a cryptographic algorithm is used, the protocol 181 should be written to permit its substitution with another algorithm 182 in the future. Finally, the authors should discuss implementation 183 hints or guidelines, e.g., how to deal with untrustworthy data or 184 peer systems. 186 Additionally, the effects the security measures have on the 187 protocol's use and performance should be discussed. Security 188 measures will have an impact on the environment they are used in. 189 Perhaps users will now be locked out of portions of the Internet 190 previously open to them, or users will experience a degradation in 191 the speed of service. The user may decided to accept a greater risk 192 in exchange for improved access or service. But the user must be 193 able to make an informed decision. They need to understand the risks 194 they are facing and the costs of reducing their risk. 196 The discussion of security can be concentrated in the Security 197 Considerations section of the document, or throughout the document 198 where it is relevant to particular parts of the specification. An 199 advantage of the second approach is that it ensures security is an 200 integral part of the protocol's development, rather than something 201 that is a follow-on or secondary effort. If security is discussed 202 throughout the document, the Security Considerations section must 203 summarized and make reference to the appropriate specification 204 sections. This will insure that the protocol's security measures are 205 emphasized to implementor and user both. 207 Within the Security Considerations section a discussion of the path 208 not taken may be appropriate. There may be several security 209 mechanisms that were not selected for a variety of reasons: cost or 210 difficulty of implementation; ineffectiveness for a given network 211 environment; or export control. By listing the mechanisms they did 212 not use and the reasons, editors can demonstrate that the protocol's 213 WG gave security the necessary thought. Also, this gives the 214 protocol's users the information they need to consider whether one of 215 the non-selected mechanisms would be better suited to their 216 particular requirements. 218 A document giving further guidance on security topics is in 219 development. Authors should obtain a copy of the completed RFC to 220 help them prepare the security portion of the standard. 222 Finally, it is no longer acceptable that Security Considerations 223 sections consist solely of statements to the effect that security was 224 not considered in preparing the standard. 226 Some examples of Security Considerations sections are found in 227 STD 33/RFC 1350, STD 51/RFC 1662, and STD 53/RFC 1939. 229 2.2 Protocol Description 231 Standards track documents must include a description of the protocol. 232 This description must address the protocol's purpose, intended 233 functions, services it provides, and, the arena, circumstances, or 234 any special considerations of the protocol's use. 236 The authors of a protocol specification will have a great deal of 237 knowledge as to the reason for the protocol. However, the reader is 238 more likely to have general networking knowledge and experience, 239 rather than expertise in a particular protocol. An explanation of 240 it's purpose and use will give the reader a reference point for 241 understanding the protocol, and where it fits in the Internet. The 242 Draft Standard RFC 2178 was recommended to the STDGUIDE working guide 243 as providing a good example of this in it's "Protocol Overview" 244 section. 246 The protocol's general description must also provide information on 247 the relationship between the different parties to the protocol. 248 This can be done by showing typical packet sequences. 250 This also applies to the algorithms used by a protocol. A detailed 251 description of the algorithms or citation of readily available 252 references that give such a description is necessary. 254 2.3 Target Audience 256 RFCs have been written with many different purposes, ranging from the 257 technical to the administrative. Those written as standards should 258 clearly identify the intended audience, for example, designers, 259 implementors, testers, help desk personnel, educators, end users, or 260 others. If there are multiple audiences being addressed in the 261 document, what sections are for each audience needs to be identified. 262 The goal is to help the reader discover and focus on what they have 263 turned to the document for, and avoid what they may find confusing, 264 diverting, or extraneous. 266 2.4 Level of Detail 268 The author should consider what level of descriptive detail best 269 conveys the protocol's intent. Concise text has several advantages. 270 It makes the document easier to read. Such text reduces the chance 271 for conflict between different portions of the specification. The 272 reader can readily identify the required protocol mechanisms in the 273 standard. Also, it makes it easier to identify the requirements for 274 protocol implementation. A disadvantage of concise descriptions is 275 that a reader may not fully comprehend the reasoning behind the 276 protocol, and thus make assumptions that will lead to implementation 277 errors. 279 Longer descriptions may be necessary to explain purpose, background, 280 rationale, implementation experience, or to provide tutorial 281 information. This helps the reader understand the protocol. Yet 282 several dangers exist with lengthy text. Finding the protocol 283 requirements in the text is difficult or confusing. The same 284 mechanism may have multiple descriptions, which leads to 285 misinterpretation or conflict. Finally, it is more difficult to 286 comprehend, a consideration as English is not the native language of 287 the many worldwide readers of IETF standards. 289 One approach is to divide the standard into sections: one describing 290 the protocol concisely, while another section consists of explanatory 291 text. The STD 3/RFC 1122/RFC 1123 and Draft Standard RFC 2178 292 provides examples of this method. 294 2.5 Change Logs 296 As a document moves along the standards track, from Proposed to Draft 297 or Draft to Full, or cycles in level, it will undergo changes due to 298 better understanding of the protocol or implementation experience. 299 To help it in tracking the progress being made, the IESG requires 300 each document to have a log showing what has changed from the 301 pervious version of the specification. 303 2.6 Protocol Versions 305 Often the standard is specifying a new version of an existing 306 protocol. In such a case, the authors should detail the differences 307 between the previous version and the new version. This should 308 include the rationale for the changes, for example, implementation 309 experience, changes in technology, responding to user demand, etc. 311 2.7 Decision History 313 In standards development, reaching consensus requires making 314 difficult choices. These choices are made through working group 315 discussions or from implementation experience. By including the 316 basis for a contentious decision, the author can prevent future 317 revisiting of these disagreements when the original parties have 318 moved on. Also, the knowledge of the "why" is as useful to an 319 implementor as the description of "how." For example, the 320 alternative not taken may have been simpler to implement, so 321 including the reasons behind the choice may prevent future 322 implementors from taking nonstandard shortcuts. 324 2.8 Response to Out of Specification Behavior 326 Detail descriptions of the actions taken in case of behavior that is 327 deviant from or exceeds the specification is useful. This is an area 328 where implementors often differ in opinion as to the appropriate 329 response. By specifying a common response, the standard author can 330 reduce the risk that different implementations will come in to 331 conflict. 333 The standard should describe responses to behavior explicitly 334 forbidden or out of the boundaries defined by the specification. Two 335 possible approaches to such cases are discarding, or invoking 336 error-handling mechanisms. If discarding is chosen, detailing the 337 disposition may be necessary. For instance, treat dropped frames as 338 if they were never received, or reset an existing connection or 339 adjacency state. 341 The specification should describe actions taken when critical 342 resource or performance scaling limits are exceeded. This is 343 necessary for cases where a risk of network degradation or 344 operational failure exists. In such cases, a consistent behavior 345 between implementations is necessary. 347 2.9 The Liberal/Conservative Rule 349 A rule, first stated in STD 5/RFC 791, recognized as having benefits 350 in implementation robustness and interoperability is: 352 "Be liberal in what you accept, and 353 conservative in what you send." 355 Or establish restrictions on what a protocol transmits, but be able 356 to deal with every conceivable error received. Caution is urged in 357 applying this approach in standards track protocols. It has in the 358 past lead to conflicts between vendors when interoperability fails. 359 The sender accuses the receiver of failing to be liberal enough, and 360 the receiver accuses the sender of not being conservative enough. 361 Therefore, the author is obligated to provide extensive detail on 362 send and receive behavior. 364 To avoid any confusion between the two, recommend that standard 365 authors specify send and receive behavior separately. The 366 description of reception will require the most detailing. For 367 implementations will be expected to accept any packet from the 368 network without failure or malfunction. Therefore, the actions taken 369 to achieve that result, need to be laid out in the protocol 370 specification. Standard authors should concern themselves on 371 achieving a level of cooperation that limits network disruption, not 372 just how to survive on the network. The appearance of undefined 373 information or conditions must not cause a network or host failure. 375 This requires specification on how to attempt acceptance of most of 376 the packets. Two approaches are available, either using as much of 377 the packet's content as possible, or invoking error procedures. The 378 author should specify a dividing line on when to take which approach. 380 A case for consideration is that of a routing protocol, where 381 acceptance of flawed information can cause network failure. For 382 protocols such as this, the specification should identify packets 383 that could have differing interpretations and mandate that they be 384 either rejected completely or the nature of the attempt to recover 385 some information from them. For example, routing updates that 386 contain more data than the tuple count shows. The protocol authors 387 should consider whether some trailing data can be accepted as 388 additional routes, or to reject the entire packet as suspect because 389 it is non-conformant. 391 2.10 Handling of Protocol Options 393 Specifications with many optional features increase the complexity of 394 the implementation and the chance of non-interoperable 395 implementations. The danger is that different implementations may 396 specify some combination of options that are unable to interoperate 397 with each other. 399 As the document moves along the standard track, implementation 400 experience shall determine the need for each option. Implementation 401 shall show whether the option should be a mandatory part of the 402 protocol or remain an option. If an option is not implemented as the 403 document advances, it must be removed from the protocol before it 404 reaches draft standard status. 406 Therefore, options shall only be present in a protocol to address a 407 real requirement. For example, options can support future 408 extensibility of the protocol, a particular market, e.g., the 409 financial industry, or a specific network environment, e.g., a 410 network constrained by limited bandwidth. They shall not be included 411 as a means to "buy-off" a minority opinion. Omission of the optional 412 item shall have no interoperability consequences for the 413 implementation that does so. 415 One possible approach is to document protocol options in a separate 416 specification. Doing so would make it clear that the options are not 417 integral to the implementation of the protocol, and would keep the 418 main protocol specification clean. Regardless of whether they appear 419 within the specification or in a separate document, the text shall 420 discuss the full implications of either using the option or not, and 421 the case for choosing either course. As part of this, the author 422 needs to consider and describe how the options are intended to be 423 used alongside other protocols. The text must also specify the 424 default conditions of all options. For security checking options the 425 default condition is on or enabled. 427 There may be occasions when mutually exclusive options appear within 428 a protocol. That is, the implementation of an optional feature 429 precludes the implementation of the other optional feature. For 430 clarity, the author needs to state when to implement one or the 431 other, what the effect of choosing one over the other is, and what 432 problems the implementor or user may face. The choice of one or the 433 other options shall have no interoperability consequences between 434 multiple implementations. 436 2.11 Indicating Requirement Levels 438 The BCP 14/RFC 2119, "Key words for use in RFCs to Indicate 439 Requirement Level," defines several words that are necessary for 440 writing a standards track document. Editors of standards track 441 documents must not deviate from the definitions provided as they are 442 intended to identify interoperability requirements or limit 443 potentially harmful behavior. The capitalization of these words is 444 the accepted norm, and can help in identifying an unintentional or 445 unreasonable requirement. These words have been used in several RFCs 446 the first instances being STD 3/RFC 1122/RFC 1123. 448 2.12 Notational Conventions 450 Formal syntax notations can be used to define complicated protocol 451 concepts or data types, and to specify values of these data types. 452 This permits the protocol to be written without concern on how the 453 implementation is constructed, or how the data type is represented 454 during transfer. The specification is simplified because it can be 455 presented as "axioms" that will be proven by implementation. 457 The formal specification of the syntax used should be referenced in 458 the text of the standard. Any extensions, subsets, alterations, or 459 exceptions to that formal syntax should be defined within the 460 standard. 462 The STD 11/RFC 822 provides an example of this. In RFC 822 (Section 463 2 and Appendix D) the Backus-Naur Form (BNF) meta-language was 464 extended to make its representation smaller and easier to understand. 465 Another example is STD 16/RFC 1155 (Section 3.2) where a subset of 466 the Abstract Syntax Notation One (ASN.1) is defined. 468 The author of a standards track protocol needs to consider several 469 things before they use a formal syntax notation. Is the formal 470 specification language being used parseable by an existing machine? 471 If no parser exists, is there enough information provided in the 472 specification to permit the building of a parser? If not, it is 473 likely the reader will not have enough information to decide what the 474 notation means. Also, the author should remember machine parseable 475 syntax is often unreadable by humans, and can make the specification 476 excessive in length. Therefore, syntax notations cannot take the 477 place of a clearly written protocol description. 479 2.13 IANA Considerations 481 The common use of the Internet standard track protocols by the 482 Internet community requires that unique values be assigned to 483 parameter fields. An IETF WG does not have the authority to assign 484 these values for the protocol it is working on. The Internet 485 Assigned Numbers Authority (IANA) is the central coordinator for the 486 assignment of unique parameter values for Internet protocols. The 487 authors of a developing protocol that use a link, socket, port, 488 protocol, etc., need to coordinate with the IANA the rules and 489 procedures to be used to register constants and tags. This 490 coordination needs to be completed prior to submitting the internet 491 draft to the standards track. For further information on parameter 492 assignment and current assignments, authors can reference STD 2/RFC 493 1700, "Assigned Numbers." The BCP /RFC , "Guidelines for Writing an 494 IANA Considerations Section in RFCs," gives further guidance on 495 determining indentifier assignment policy and providing IANA with 496 instructions to administer that policy. 498 2.14 Network Management Considerations 500 When relevant, each standard needs to discuss how to manage the 501 protocol being specified. This management process should be 502 compatible with the current IETF Standard management protocol. Also 503 a MIB must be defined within the standard or in a companion document. 504 The MIB must be compatible with current Structure of Management 505 Information (SMI) and parseable using a tool such as SMICng. Where 506 management or a MIB is not necessary this section of the standard 507 should explain the reason it is not relevant to the protocol. 509 2.15 Scalability Considerations 511 The standard should establish the limitations on the scale of use, 512 e.g., tens of millions of sessions, gigabits per second, etc., and 513 establish limits on the resources used, e.g, round trip time, 514 computing resources, etc. This is important because it establishes 515 the ability of the network to accommodate the number of users and the 516 complexity of their relations. The STD 53/RFC 1939 has an example of 517 such a section. If this is not applicable to the protocol an 518 explanation of why not should be included. 520 2.16 Network Stability 522 A standard should discuss the relationship between network topology 523 and convergence behavior. As part of this, any topology which would 524 be troublesome for the protocol should be identified. Additionally, 525 the specification should address any possible destablizing events, 526 and how the protocol resists or recovers from them. The purpose is 527 to insure that the network will stabilize, in a timely fashion, after 528 a change, and that a combination of errors or events will not plunge 529 the network into chaos. The STD 34/RFC 1058, as an example, has 530 sections which discuss how that protocol handles the affects of 531 changing topology. 533 The obvious case this would apply to is a routing protocol. However, 534 an application protocol could also have dynamic behavior that would 535 affect the network. For example, a messaging protocol could suddenly 536 dump a large number of messages onto the network. Therefore, editors 537 of an application protocol will have to consider possible impacts to 538 network stability and convergence behavior. 540 2.17 Glossary 542 Every standards track RFC should have a glossary, as words can have 543 many meanings. By defining any new words introduced, the author can 544 avoid confusing or misleading the implementer. The definition should 545 appear on the word's first appearance within the text of the protocol 546 specification, and in a separate glossary section. 548 It is likely that definition of the protocol will rely on many words 549 frequently used in IETF documents. All authors must be knowledgeable 550 of the common accepted definitions of these frequently used words. 551 FYI 18/RFC 1983, "Internet Users' Glossary," provides definitions 552 that are specific to the Internet. Any deviation from these 553 definitions by authors is strongly discouraged. If circumstances 554 require deviation, an author should state that he is altering the 555 commonly accepted definition, and provide rationale as to the 556 necessity of doing so. The altered definition must be included in 557 the Glossary section. 559 If the author uses the word as commonly defined, she does not have to 560 include the definition in the glossary. As a minimum, FYI 18/RFC 561 1983 should be referenced as a source. 563 3 Specific Guidelines 565 The following are guidelines on how to present specific technical 566 information in standards. 568 3.1 Packet Diagrams 570 Most link, network, and transport layer protocols have packet 571 descriptions. Packet diagrams included in the standard are very 572 helpful to the reader. The preferred form for packet diagrams is a 573 sequence of long words in network byte order, with each word 574 horizontal on the page and bit numbering at the top: 576 0 1 2 3 577 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 578 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 579 |Version| Prio. | Flow Label | 580 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 582 In cases where a packet is strongly byte-aligned rather than 583 word-aligned (e.g., when byte-boundary variable-length fields are 584 used), display packet diagrams in a byte-wide format. The author can 585 use different height boxes for short and long words, and broken boxes 586 for variable-length fields: 588 0 1 2 3 4 5 6 7 589 +-+-+-+-+-+-+-+-+ 590 | Length N | 591 +-+-+-+-+-+-+-+-+ 592 | | 593 + Address + 594 ... 595 + (N bytes) + 596 | | 597 +-+-+-+-+-+-+-+-+ 598 | | 599 + 2-byte field + 600 | | 601 +-+-+-+-+-+-+-+-+ 603 3.2 Summary Tables 605 The specifications of some protocols are particularly lengthy, 606 sometimes covering a hundred pages or more. In such cases the 607 inclusion of a summary table can reduce the risk of conformance 608 failure by an implementation through oversight. A summary table 609 itemizes what in a protocol is mandatory, optional, or prohibited. 610 Summary tables do not guarantee conformance, but serve to assist an 611 implementor in checking that they have addressed all protocol 612 features. 614 The summary table will consist of, as a minimum, four (4) columns: 615 Protocol Feature, Section Reference, Status, and 616 References/Footnotes. The author may add columns if they further 617 explain or clarify the protocol. 619 In the Protocol Feature column describe the feature, for example, a 620 command word. We recommend grouping series of related transactions 621 under descriptive headers, for example, RECEPTION. 623 Section reference directs the implementor to the section, paragraph, 624 or page that describes the protocol feature in detail. 626 Status indicates whether the feature is mandatory, optional, or 627 prohibited. The author can either use a separate column for each 628 possibility, or a single column with appropriate codes. These codes 629 need to be defined at the start of the summary table to avoid 630 confusion. Possible status codes: 632 M - must or mandatory 633 MN - must not 634 O - optional 635 S - should 636 SN - should not 637 X - prohibited 639 In the References/Footnotes column authors can point to other RFCs 640 that are necessary to consider in implementing this protocol feature, 641 or any footnotes necessary to explain the implementation further. 643 The STD 3/RFC 1122/RFC 1123 provides examples of summary tables. 645 3.3 State Machine Descriptions 647 A convenient method of presenting a protocol's behavior is as a 648 state-machine model. That is, a protocol can be described by a 649 series of states resulting from a command, operation, or transaction. 650 State-machine models define the variables and constants that 651 establish a state, the events that cause state transitions, and the 652 actions that result from those transitions. Through these models, an 653 understanding of the protocol's dynamic operation as sequence of 654 state transitions that occur for any given event is possible. State 655 transitions can be detailed by diagrams, tables, or time lines. 657 Note that state-machine models are never to take the place of 658 detailed text description of the specification. They are adjuncts to 659 the text. The protocol specification shall always take precedence in 660 the case of a conflict. 662 When using a state transition diagram, show each possible protocol 663 state as a box connected by state transition arcs. The author should 664 label each arc with the event that causes the transition, and, in 665 parentheses, any actions taken during the transition. The STD 5/RFC 666 1112 provides an example of such a diagram. As ASCII text is the 667 preferred storage format for RFCs, only simple diagrams are possible. 668 Tables can summarize more complex or extensive state transitions. 670 In a state transition table, read events vertically and states 671 horizontally. The form, action/new state, represents state 672 transitions and actions. Commas separate multiple actions, and 673 succeeding lines are used as required. The authors should present 674 multiple actions in the order they must be executed, if relevant. 675 Letters that follow the state indicate an explanatory footnote. The 676 dash ('-') indicates an illegal transition. The STD 51/RFC 1661 677 provides an example of such a state transition table. The initial 678 columns and rows of that table follow as an example: 680 | State 681 | 0 1 2 3 4 5 682 Events| Initial Starting Closed Stopped Closing Stopping 683 ------+----------------------------------------------------------- 684 Up | 2 irc,scr/6 - - - - 685 Down | - - 0 tls/1 0 1 686 Open | tls/1 1 irc,scr/6 3r 5r 5r 687 Close| 0 tlf/0 2 2 4 4 688 | 689 TO+ | - - - - str/4 str/5 690 TO- | - - - - tlf/2 tlf/3 692 The STD 18/RFC 904 also presents state transitions in table format. 693 However, it lists transitions in the form n/a, where n is the next 694 state and a represents the action. The method in RFC 1661 is 695 preferred as new-state logically follows action. Also, RFC 904's 696 Appendix C models transitions as the Cartesian product of two state 697 machines. This is a more complex representation that may be 698 difficult to comprehend for those readers that are unfamiliar with 699 the format. We recommend that authors present tables as defined in 700 the previous paragraph. 702 A final method of representing state changes is by a time line. The 703 two sides of the time line represent the machines involved in the 704 exchange. The author lists the states the machines enter as time 705 progresses (downward) along the outside of time line. Within the 706 time line, show the actions that cause the state transitions. An 707 example: 709 client server 711 | | 712 | | LISTEN 713 SYN_SENT |----------------------- | 714 | \ syn j | 715 | ----------------->| SYN_RCVD 716 | | 717 | ------------------| 718 | syn k, ack j+1 / | 719 ESTABLISHED |<---------------------- | 720 | | 722 3.4 Character Sets 724 At one time the Internet had a geographic boundary and was English 725 only. Since the Internet now extends internationally, application 726 protocols must assume that the contents of any text string may be in 727 a language other than English. Therefore, new or updated protocols 728 which transmit text must use ISO 10646 as the default Coded Character 729 Set, and RFC 2279, "UTF-8, a transformation format of Unicode and 730 ISO 10646" as the default Character Encoding Scheme. An exception is 731 the use of US-ASCII for a protocol's controlling commands and 732 replies. Protocols that have a backwards compatibility requirement 733 should use the default of the existing protocol. This is in keeping 734 with the recommendations of RFC 2130, "The Report of the IAB 735 Character Set Workshop held 29 February - 1 March 1996." 737 4 Document Checklist 739 The following is a checklist based on these guidelines that can be 740 applied to a document: 742 o Does it identify the security risks? Are countermeasures for each 743 potential attack provided? Are the effects of the security 744 measures on the operating environment detailed? 745 o Does it explain the purpose of the protocol or procedure? Are the 746 intended functions and services addressed? Does it describe how it 747 relates to existing protocols? 748 o Does it consider scaling and stability issues? 749 o Have procedures for assigning numbers been coordinated with IANA? 750 o Does it discuss how to manage the protocol being specified? Is a 751 MIB defined? 752 o Is a target audience defined? 753 o Does it reference or explain the algorithms used in the protocol? 754 o Does it give packet diagrams in recommended form, if applicable? 755 o Is there a change log? 756 o Does it describe differences from previous versions, if applicable? 757 o Does it separate explanatory portions of the document from 758 requirements? 759 o Does it give examples of protocol operation? 760 o Does it specify behavior in the face of incorrect operation by 761 other implementations? 762 o Does it delineate which packets should be accepted for processing 763 and which should be ignored? 764 o If multiple descriptions of a requirement are given, does it 765 identify one as binding? 766 o How many optional features does it specify? Does it separate them 767 into option classes? 768 o Have all combinations of options or option classes been examined 769 for incompatibility? 770 o Does it explain the rationale and use of options? 771 o Have all mandatory and optional requirements be identified and 772 documented by the accepted key words that define Internet 773 requirement levels? 774 o Does it use the recommended Internet meanings for any terms use to 775 specify the protocol? 776 o Are new or altered definitions for terms given in a glossary? 778 5 Security Considerations 780 This document does not define a protocol or procedure that could be 781 subject to an attack. It establishes guidelines for the information 782 that should be included in RFCs that are to be submitted to the 783 standards track. In the area of security, IETF standards authors are 784 called on to define clearly the threats faced by the protocol and the 785 way the protocol does or does not provide security assurances to the 786 user. 788 6 References 790 RFC 791 "Internet Protocol (IP)," J. Postel, September 1981. 792 RFC 904 "Exterior Gateway Protocol formal specification," D. Mills, 793 April 1984 795 RFC 1058 "Routing Information Protocol," C. Hedrick, June 1988 797 RFC 1112 "Host extensions for IP multicasting," S. Deering, 798 August 1989 800 RFC 1122 "Requirements for Internet Hosts -- Communication Layers," 801 R. Braden, October 1989 803 RFC 1123 "Requirements for Internet hosts -- Application and 804 Support," R. Braden, October 1989 806 RFC 1311 "Introduction to the STD Notes," J. Postel, March 1992 808 RFC 1350 "The TFTP Protocol (Revision 2)," K. Sollins, July 1992 810 RFC 1661 "The Point-to-Point Protocol (PPP)," W. Simpson, July 1994 812 RFC 1662 "PPP in HLDC-like Framing," W. Simpson, July 1994 814 RFC 1700 "Assigned Numbers," J. Reynolds, J. Postel, October 1994 816 RFC 1939 "Post Office Protocol - Version 3," J. Meyers, M. Rose, 817 May 1996 819 RFC 1958 "Architectural Principles of the Internet," B. Carpenter, 820 June 1996 822 RFC 1983 "Internet Users' Glossary," G. Malkin, August 1996 824 RFC 2026 "The Internet Standards Process -- Revision 3," S. Bradner, 825 October 1996 827 RFC 2119 "Key words for use in RFCs to Indicate Requirement Level," 828 S. Bradner, March 1997 830 RFC 2130 "The Report of the IAB Character Set Workshop held 29 831 February - 1 March 1996," C. Weider, C. Preston, 832 K. Simonsen, H. Alvestrand, R. Atkinson, M. Crispin, 833 P. Svanberg, April 1997 835 RFC 2178 "OSPF Version 2," J. Moy, July 1997 837 RFC 2279 "UTF-8, a transformation format of ISO 10646," F. Yergeau, 838 January 1998 840 RFC "Guidelines for Writing an IANA Considerations Section in 841 RFCs," 843 7 Acknowledgments 845 Peter Desnoyers and Art Mellor began the work on this document. The 846 area directors that oversaw the STDGUIDE WG's efforts were 847 Scott Bradner, Mike O'Dell, and John Curran. Others that contributed 848 to this document were: 850 Bernard Aboba 851 Harald T. Alvestrand 852 Fred Baker 853 Brian Carpenter 854 Robert Elz 855 Dirk Fieldhouse 856 Dale Francisco 857 Gary Malkin 858 Neal McBurnett 859 Craig Partridge 860 Henning Schulzrinne 861 Kurt Starsinic 862 James Watt 864 8 Editor's Address 866 Gregor D. Scott 867 Director, Defense Information Systems Agency 868 ATTN: JIEO-JEBBC 869 Ft. Monmouth, NJ 07703-5613 870 USA 872 Phone: (732) 427-6856 873 Fax: (732) 532-0853 874 EMail: scottg@ftm.disa.mil 876 This Internet Draft expires on 15 September 1998.