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