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