idnits 2.17.1 draft-newman-protocol-design-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) 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 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 an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. 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 (June 1997) is 9812 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) == Unused Reference: 'IMAP4' is defined on line 320, but no explicit reference was found in the text == Unused Reference: 'TBD' is defined on line 325, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) -- Possible downref: Non-RFC (?) normative reference: ref. 'TBD' Summary: 9 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Newman 3 Internet Draft: Application Protocol Design Principles Innosoft 4 Document: draft-newman-protocol-design-00.txt June 1997 5 Expires in six months 7 Application Protocol Design Principles 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 17 months and may be updated, replaced, or obsoleted by other 18 documents at any time. It is inappropriate to use Internet-Drafts 19 as reference material or to cite them other than as "work in 20 progress." 22 To view the entire list of current Internet-Drafts, please check 23 the "1id-abstracts.txt" listing contained in the Internet-Drafts 24 Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net 25 (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East 26 Coast), or ftp.isi.edu (US West Coast). 28 Abstract 30 There are a number of design principles which come into play over 31 and over again when designing application protocols. Many of these 32 are entrenched in IETF lore and spread by word of mouth. Most have 33 been learned the hard way many times. 35 This is an attempt to codify some of these principles so they can 36 be referenced rather than spread by word of mouth. The author has 37 not invented any of these ideas and while the exercise of finding 38 the originator of the ideas would be interesting, it is not deemed 39 necessary for this project. 41 Many of these principles have a much wider scope than application 42 protocol design. However, the author's primary experience is with 43 application protocols and examples provided usually involve 44 application protocols or elements. 46 [Disclaimer: this is a preliminary draft. Some of the case studies 47 and exceptions need tuning. Suggestions welcome.] 48 Table of Contents 50 Status of this memo ............................................... i 51 Abstract .......................................................... i 52 1. K.I.S.S. .................................................... 1 53 2. Make the Common Case Simple & Uncommon Case Possible ......... 1 54 3. 0, 1, N Principle ............................................ 1 55 4. Be Liberal/Conservative ...................................... 2 56 5. Avoid Silly States ........................................... 3 57 6. Text Not Numbers ............................................. 3 58 7. Avoid Alternative Representations ............................ 4 59 8. Announce Features, Not Version ............................... 4 60 9. Avoid Unnecessary Layers ..................................... 5 61 10. Conclusions Based on Design Principles ....................... 5 62 11. Security Considerations ...................................... 6 63 12. References ................................................... 6 64 13. Author's Address ............................................. 6 65 1. K.I.S.S. 67 The "Keep It Simple, Stupid" principle or "KISS" principle is well 68 known. The basic idea is not to add complexity if there is any way 69 to avoid it. Sometimes this also involves a decision of where the 70 complexity should live (e.g. client implementation, server 71 implementation, protocol itself, external layers). This is a very 72 difficult principle to follow in practice. 74 Consequences of Violation: design errors, implementation bugs, poor 75 deployment, poor maintainability, interoperability problems, poor 76 usability, less peer review, protocol has to be "profiled" to 77 interoperate. 79 Case Study: X.400 vs. SMTP/MIME. X.400 is very complex and is 80 losing ground steadily in the marketplace. SMTP/MIME is much 81 simpler and is gaining ground in the marketplace. 83 2. Make the Common Case Simple & Uncommon Case Possible 85 This is largely a corollary of the KISS principle. Sometimes 86 phrased as "design for the common case." The idea is to make the 87 common case very simple without disallowing the useful uncommon 88 cases. 90 Consequences of Violation: Same as KISS. If useful uncommon case 91 is not possible, then a potentially complex protocol extension is 92 necessary which results in more complexity than if the uncommon 93 case was considered from the start. 95 Case Study (common case too complex): ASN.1 makes the common case 96 far too complex. While it does provide for unlimited 97 extensibility, in practice implementations can't deal with many 98 legal structures due to the complexity. 100 Case Study (uncommon case not possible): Internet Mail originally 101 didn't allow non-text data. MIME is more complex than it would 102 have been if designed in from the beginning. 104 3. 0, 1, N Principle 106 The "0, 1, N principle" is not an obvious principle but is true 107 surprisingly often. In general, any protocol element or object 108 should come in quantities of 0, 1, or N where N is an arbitrary 109 number. If a limit is picked, it is likely to be too small. This 110 is especially true of hierarchy, and often true of names. 112 Consequences of Violation: System has to be extended to allow 113 larger values. This causes a transition with severe 114 interoperability problems or a semantic overload of existing 115 structure which adds complexity and confusion. 117 Case Study: 640K 119 Case Study: MIME media types. Two levels of hierarchy were defined 120 in the initial MIME specification. This proved inadequate, so a 121 new hierarchy delimiter had to be introduced to allow more naming 122 hierarchy. 124 Case Study: SMTP error codes have 3 levels of hierarchy with 10 125 settings each. This has proved to be insufficent and inflexible 126 requiring the addition of ESMTP ENHANCEDSTATUSCODES. 128 Exception: A quantity of two is permitted for clearly binary 129 situations. 131 Exception: Has to be balanced with the KISS principle. For 132 example, current practice limits most numbers in protocols to 133 32-bit values. 135 4. Be Liberal/Conservative 137 The "Be Liberal in What You Accept, and Conservative in What You 138 Generate" principle is well known in the IETF, but controversial in 139 some cases. The intention is to interoperability. The basic idea 140 is that on generation one should follow the standard strictly as 141 that will work with all other compliant software. On acceptance if 142 one tolerates minor protocol or format violations, it helps work 143 around known bugs in other software. This principle would work 144 great if everyone followed it. However, when there are mixtures of 145 systems which follow this rule and others which don't the 146 exceptions below need to be considered. 148 Consequences of Violation: decreased interoperability, customers 149 blaming the violator of this principle for bugs in other vendor's 150 software. 152 Case Study: TBD 154 Exception: Don't accept ambiguous interactive input with 155 potentially vastly different meanings. If the user ends up seeing 156 the data in an indecipherable context, severe consequences result. 157 It's often better to reject the data so the problem can be fixed at 158 the source. 160 Exception: Don't accept clearly illegal interactive input when 161 there are no known sources of it. If client vendors notice their 162 illegal behavior before deploying, it gets fixed before it's 163 deployed, and overall interoperability is increased. 165 Exception Case Study: When netnews was initially deployed, a number 166 of clients generated date headers in a variety of illegal formats. 167 Fairly early in the deployment, a major implementation was modified 168 to discard news messages which had missing or improperly formatted 169 date headers. Very soon after this was deployed, all date headers 170 in news were interoperable. 172 5. Avoid Silly States 174 Whenever possible, design the system so no silly states are 175 possible. A silly state is a combination of options or values 176 which contradict each other or are nonsensical. 178 Consequences of Violation: Increased complexity to deal with the 179 possibility of the silly states occurring. 181 Case Study: TBD 183 6. Text Not Numbers 185 Whenever possible, text should be used instead of numbers. Numbers 186 almost always have to be looked up in order for humans to interpret 187 them. Text can be read and debugged by a mere mortal. One common 188 counter argument is that numbers are more compact, but if size is a 189 serious concern, a general purpose compression layer is usually a 190 better solution. Another counter argument is that the mapping 191 tables and parsers to convert to internal numbers add complexity. 192 In practice the complexity of debugging a non-text protocol is 193 usually greater than the complexity of the parser and tables. 195 Consequences of Violation: Protocol is difficult to debug, protocol 196 is difficult to understand, examples are hard to provide. Previous 197 three consequences make this equivalent to a KISS violation. 198 Results in poor user interface. Endian problems. 200 Case Study: X.400 problems are very hard to diagnose. The protocol 201 trace has to be recorded and run through an ASN.1 interpretor to 202 debug. SMTP can be debugged by observing the original protocol 203 trace. 205 Case Study: Whenever numeric error codes are used unqualified by 206 text, humans are invariably presented with these error codes, 207 resulting in a poor user interface and debugging difficulties. 209 Case Study: The telnet ENVIRON option had to be replaced with 210 NEW-ENVIRON due to endian problems. 212 Exceptions: Compression or Encrytion layers (which make things 213 unreadable anyway). Low-level protocols with high performance 214 requirements. Encapsulated non-text objects. 216 7. Avoid Alternative Representations 218 Having several ways to represent the same thing results in 219 interoperability problems. In general, implementors will only test 220 the representation format they use. The less often used 221 representations will fail to work. In a worst case scenario, two 222 or more representions are widely used, but systems which use one 223 often can't talk to systems which use another. 225 Consequences of Violation: Serious interoperability problems, more 226 bugs, conversion support necessary to interoperate. 228 Case Study: The TIFF image format permits both a "big endian" 229 version and a "little endian" version. Some implementations can 230 only read one or the other. Many TIFF applications now have a 231 "Macintosh format TIFF" vs "IBM format TIFF" option when saving 232 TIFF files. 234 Case Study: ASN.1 provides many ways of representing the same 235 thing. This has caused numerous interoperability problems as not 236 all systems support all representations of a given field. Profiles 237 of ASN.1 are usually necessary to interoperate at all. 239 Case Study: RFC 822 allows several different ways to quote the same 240 address. The useless ones like: "foo"."bar"@do.main rarely work. 242 Exceptions: An alternative representation may be necessary for a 243 more expressive case. For example, quoted strings and literals in 244 IMAP. Rare alternative representations should be avoided. 246 8. Announce Features, Not Version 248 While version numbers are fine to inform the user of what 249 implementation or conformance level they are at, they are usually a 250 bad idea in protocols. A system where the server announces 251 available features and the client activates the features it wants 252 results in a far better protocol. If a protocol needs to be 253 redesigned from scratch, use of a different port number for the new 254 version will allow a parallel transition period -- otherwise when a 255 major version number is increased on the server, the old clients 256 cease to interoperate with it. 258 Consequences of Violation: Useless version number fields, painful 259 version transition, complexity due to need to support older 260 versions, meaning of version number sometimes ambiguous. 262 Case Study: MIME has the MIME-Version header. Since MIME also has 263 feature announcement via headers, the version number is useless and 264 will never change. 266 Case Study: X.400:1988 fails to interoperate with X.400:1993 due to 267 certain body part types. [XXX: need to confirm] 269 9. Avoid Unnecessary Layers 271 Whenever two layered services can be combined into a single service 272 without a significant increase in complexity, it should be done. 273 Unnecessary layers result in implementor confusion and more 274 complexity. 276 Consequences of Violation: same as KISS violations 278 Case Study: RFC 822 has a multi-layer parsing model which includes 279 unfolding lines, lexing, removal of linear-white-space, and 280 parsing. This has resulted in endless confusion and serious 281 interoperability problems. The DRUMS WG is folding these into a 282 single formal syntax and the result looks promising. 284 10. Conclusions Based on Design Principles 286 KISS: Every protocol should go through a "feature cut review" 287 before going on the standards track. 289 KISS/Text not Binary/Alternate Representations: Use of ASN.1 in new 290 protocols should be strongly discouraged. 292 0,1,N Principle/Text not Numbers: Use of 3 digit SMTP-style error 293 codes in new protocols should be forbidden. 295 Announce Features, Not Version: Server feature announcement should 296 be required in most standards track protocols. 298 Alternate Representations: CRLF line separators should be required. 299 Big endian should be required in new binary protocols and formats. 300 Use of UTF-8 should be preferred over labelled character sets in 301 new protocols. 303 11. Security Considerations 305 Many of these can have profound security implications. Violation 306 of KISS makes a security bug more likely. Alternate 307 Representations makes a security bug more likely in a less 308 frequently used representation. A silly state could introduce a 309 security bug if special handling isn't included. Failure to follow 310 the 0,1,N principle when implementing makes buffer overrun problems 311 more likely. 313 While it's harder to fix a security bug in a binary protocol due to 314 the debugging complexity, text protocols tend to be more 315 susceptible to buffer overrun security problems. These two factors 316 probably offset each other. 318 12. References 320 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 321 4rev1", RFC 2060, University of Washington, December 1996. 323 325 [TBD] 327 13. Author's Address 329 Chris Newman 330 Innosoft International, Inc. 331 1050 Lakes Drive 332 West Covina, CA 91790 USA 334 Email: chris.newman@innosoft.com