idnits 2.17.1 draft-earhart-ap-spec-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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. ** The document is more than 15 pages and seems to lack a Table of Contents. == 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. ** There is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. ** The abstract seems to contain references ([ACAP], [IMAP4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 120: '...ents and servers MUST be capable of ha...' RFC 2119 keyword, line 199: '... A client MUST be prepared to accept...' RFC 2119 keyword, line 210: '...s case, a server MUST respond with a B...' RFC 2119 keyword, line 233: '...otocols using AP MAY define more state...' RFC 2119 keyword, line 234: '... MUST only be reachable from the aut...' (51 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year ** The document contains RFC2119-like boilerplate, but doesn't seem to mention RFC 2119. The boilerplate contains a reference [KEYWORDS], but that reference does not seem to mention RFC 2119 either. -- 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 (July 1998) is 9410 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'KEYWORDS' is mentioned on line 100, but not defined == Unused Reference: 'COMPARATOR' is defined on line 1051, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2245 (ref. 'ANON') (Obsoleted by RFC 4505) -- Possible downref: Non-RFC (?) normative reference: ref. 'CHARSET-LANG-POLICY' -- Possible downref: Non-RFC (?) normative reference: ref. 'COMPARATOR' -- Possible downref: Non-RFC (?) normative reference: ref. 'IMAP4' ** Obsolete normative reference: RFC 1766 (ref. 'LANG-TAGS') (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 2222 (ref. 'SASL') (Obsoleted by RFC 4422, RFC 4752) ** Obsolete normative reference: RFC 2044 (ref. 'UTF8') (Obsoleted by RFC 2279) Summary: 19 errors (**), 0 flaws (~~), 4 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Earhart 3 Internet Draft: AP Carnegie Mellon 4 Document: draft-earhart-ap-spec-01.txt January 1998 5 Expires July 1998 7 Access Protocol 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 documents 18 at any time. It is not appropriate to use Internet-Drafts as 19 reference material or to cite them other than as "work in progress". 21 To learn the current status of any Internet-Draft, please check the 22 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 23 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 24 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 25 ftp.isi.edu (US West Coast). 27 This document suggests a proposed protocol for the Internet 28 community, and requests discussion and suggestions for improvements. 29 Distribution of this draft is unlimited. 31 The protocol discussed in this document is experimental and subject 32 to change. Persons planning on either implementing or using this 33 protocol are STRONGLY URGED to get in touch with the author before 34 embarking on such a project. 36 Copyright 38 Copyright (C) The Internet Society 1998. All Rights Reserved. 40 Abstract 42 The Access Protocol defines a standard extensible framework upon 43 which application-specific protocols may be layered, providing a 44 piece of infrastructure for a common class of internet protocols. 46 Internet DRAFT Access Protocol January 1998 48 Attributions 50 Substantial portions of this protocol and of the text of this 51 document come from [ACAP], which itself borrows much from [IMAP4]. 53 1. Motivation 55 There are an increasing number of internet application-level 56 protocols, solving a wide variety of problems. But as time goes on, 57 it's becoming increasingly obvious that in the course of their 58 development, regargless of their application-level purpose, many of 59 the protocols need to solve the same infrastructure problems, such as 61 Representation of commands (interleaving, protocol structure) 62 Representation of command data 63 Security (Authentication and authorization) 64 Internationalization (UTF8, language control, etc.) 65 Error reporting 66 And a variety of minor issues (inactivity timeouts, etc.) 68 It's hoped that by defining a common infrastructure between 69 application-specific command suites and the underlying stream 70 protocol provided by services such as TCP, a number of these problems 71 can be solved in a general way, allowing application-specific 72 protocols to be more rapidly developed and deployed. 74 In addition, by abstracting the infrastructure from the application, 75 it's hoped that each will be able to evolve independantly, and that 76 the state of the art in protocol design will improve and advance 77 faster than if each new infrastructure-level idea had to be 78 individually incorporated into each application level protocol. 80 ASN.1/BER is *not* used, as there is a significant feeling in the 81 applications area community that the complexity of these standards is 82 a significant barrier to implementation. 84 It is recognized that not all application level protocols will fit 85 into this model; TELNET is a good example of a protocol that does not 86 belong in this framework. Nevertheless, it is believed that this is 87 of sufficient utility to enough protocols to be worth advancing as an 88 IETF standard. 90 2. Conventions Used in this Document 92 In examples, "C:" and "S:" indicate lines sent by the client and 93 server respectively. 95 Internet DRAFT Access Protocol January 1998 97 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 98 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 99 document are to be interpreted as described in [KEYWORDS]. 101 3. Protocol Overview 103 3.1. Link Level 105 The Access Protocol assumes a reliable data stream such as provided 106 by TCP. The command protocol that uses the AP is responsible for 107 specifying any parameters to be used in constructing the stream. 109 3.2. Commands and Responses 111 An AP session consists of the establishment of a client/server 112 connection, an initial greeting from the server, and client/server 113 interactions. These client/server interactions consist of a client 114 command, server data, and a server completion result. 116 All interactions transmitted by client and server are in the form of 117 lines; that is, strings that end with a CRLF. The protocol receiver 118 of an AP client or server is either reading a line, or is reading a 119 sequence of octets with a known count followed by a line. Both 120 clients and servers MUST be capable of handling lines of arbitrary 121 length. 123 3.2.1. Client Protocol Sender and Server Protocol Receiver 125 The client command begins an operation. Each client command is 126 prefixed with a identifier composed of one to thirty-two characters 127 (typically a short alphanumeric string, e.g., A0001, A0002, etc.) 128 called a "tag". A different tag is generated by the client for each 129 command. 131 There are two cases in which a line from the client does not 132 represent a complete command. In one case, a command argument is 133 quoted with an octet count (see the description of literal in section 134 4.1.3); in the other case, the command arguments require server 135 feedback (see the AUTHENTICATE command). In some of these cases, the 136 server sends a command continuation request if it is ready for the 137 next part of the command. This response is prefixed with the token 138 "+". 140 Note: If, instead, the server detected an error in the command, it 141 sends a BAD or NO completion response with tag matching the 143 Internet DRAFT Access Protocol January 1998 145 command (as described below) to reject the command and prevent the 146 client from sending any more of the command. 148 It is also possible for the server to send a completion or 149 intermediate response for some other command (if multiple commands 150 are in progress), or untagged data. In either case, the command 151 continuation request is still pending; the client takes the 152 appropriate action for the response, and reads another response 153 from the server. 155 The server reads a command line from the client, parses the command 156 and its arguments, and transmits server data and a server command 157 completion result. 159 3.2.1. Server Protocol Sender and Client Protocol Receiver 161 Data transmitted by the server to the client come in four forms: 162 command continuation requests, command completion results, 163 intermediate responses, and untagged responses. 165 A command continuation request is prefixed with the token "+". 167 A command completion result indicates the success or failure of the 168 operation. It is tagged with the same tag as the client command 169 which began the operation. Thus, if more than one command is in 170 progress, the tag in a server completion response identifies the 171 command to which the response applies. There are three possible 172 server completion responses: OK (indicating success), NO (indicating 173 failure), or BAD (indicating protocol error such as unrecognized 174 command or command syntax error). 176 An intermediate response returns data which can only be interpreted 177 within the context of a command in progress. It is tagged with the 178 same tag as the client command which began the operation. Thus, if 179 more than one command is in progress, the tag in an intermediate 180 response identifies the command to which the response applies. A 181 tagged response other than "OK", "NO", or "BAD" is an intermediate 182 response. 184 An untagged response returns data or status messages which may be 185 interpreted outside the context of a command in progress. It is 186 prefixed with the token "*". Untagged data may be sent as a result 187 of a client command, or may be sent unilaterally by the server. 188 There is no syntactic difference between untagged data that resulted 189 from a specific command and untagged data that were sent 190 unilaterally. 192 Internet DRAFT Access Protocol January 1998 194 The protocol receiver of an AP client reads a response line from the 195 server. It then takes action on the response based upon the first 196 token of the response, which may be a tag, a "*", or a "+" as 197 described above. 199 A client MUST be prepared to accept any server response at all times. 200 This includes untagged data that it may not have requested. 202 This topic is discussed in greater detail in the Server Responses 203 section. 205 3.3. State and Flow Diagram 207 An AP server is in one of at least three states. Most commands are 208 valid in only certain states. It is a protocol error for the client 209 to attempt a command while the server is in an inappropriate state 210 for that command. In this case, a server MUST respond with a BAD 211 command completion result. 213 3.3.1. Non-Authenticated State 215 In non-authenticated state, the user must supply authentication 216 credentials before most commands will be permitted. This state is 217 entered when a connection starts. 219 3.3.2. Authenticated State 221 In authenticated state, the user is authenticated and most commands 222 will be permitted. This state is entered when acceptable 223 authentication credentials have been provided. 225 3.3.3. Logout State 227 In logout state, the session is being terminated, and the server will 228 close the connection. This state can be entered as a result of a 229 client request or by unilateral server decision. 231 3.3.4. Other States 233 Protocols using AP MAY define more states, as desired. These states 234 MUST only be reachable from the authenticated state, and MUST only 235 transition between themselves, to the authenticated state, or to the 236 logout state. 238 Internet DRAFT Access Protocol January 1998 240 Protocol-specific states MUST only affect the operation of commands 241 defined in those protocols, or in extensions to those protocols. In 242 particular, the NOOP and LOGOUT commands MUST always be available. 244 Protocols MAY define new commands which transition to the logout 245 state. 247 +--------------------------------------+ 248 |initial connection and server greeting| 249 +--------------------------------------+ 250 || (1) (2) || 251 VV || 252 +-----------------+ || 253 |non-authenticated| || 254 +-----------------+ || 255 || (4) || (3) || 256 || VV || 257 || +----------------+ || 258 || | authenticated |<=++ || 259 || +----------------+ || || 260 || || (4) || (5) || (5) || 261 || || VV || || 262 || || +------------+ || || 263 || || |other states|==++ || 264 || || +------------+ || 265 || || || (4) || 266 VV VV VV VV 267 +--------------------------------------+ 268 | logout and close connection | 269 +--------------------------------------+ 271 (1) connection (AP greeting) 272 (2) rejected connection (BYE greeting) 273 (3) successful AUTHENTICATE command 274 (4) LOGOUT or other closing command, server shutdown, 275 or connection closed. 276 (5) State-transition command defined by protocol using AP 278 3.4. Operational Considerations 280 3.4.1. Untagged Status Updates 282 At any time, a server MAY send data that the client did not request. 283 It is recognized that this will cause perfectly good TCP connections 284 to be torn down if the network is unavailable for some transient 285 reason; nevertheless, this is better than forcing the client to poll 287 Internet DRAFT Access Protocol January 1998 289 the server for update information. 291 3.4.2. Response when No Command in Progress 293 Server implementations are permitted to send an untagged response 294 while there is no command in progress. Server implementations that 295 send such responses MUST deal with flow control considerations. 296 Specifically, they must either (1) verify that the size of the data 297 does not exceed the underlying transport's available window size, or 298 (2) use non-blocking writes. 300 3.4.3. Autologout Timer 302 Servers MAY implement an inactivity autologout timer. If such a 303 timer is implemented, that timer MUST be at least 30 minutes' 304 duration. The receipt of ANY data from the client during that 305 interval MUST suffice to reset the autologout timer. 307 Open Issue: is this really necessary? I'd rather forbid timers 308 and the NOOP command, and say that it's the responsibility of the 309 underlying stream protocol to ensure that the other side's still 310 alive...) 312 3.4.4. Multiple Commands in Progress 314 The client is not required to wait for the completion result of a 315 command before sending another command, subject to flow control 316 constraints on the underlying data stream. Similarly, a server is 317 not required to process a command to completion before beginning 318 processing of the next command, although the server MUST compute the 319 results of a command as though any changes caused by previous 320 commands had taken place, and as though any changes caused by 321 subsequent commands have not yet taken place. 323 Protocols which use this protocol as their basis SHOULD NOT define 324 commands in such a way as to create an ambiguity when results from 325 seperate commands are interlaced or reordered. 327 4. Protocol Elements 329 4.1. Data Formats 331 AP uses textual commands and responses. Data in AP can be in one of 332 four forms: atom, number, string, parenthesized list, or NIL. 334 Internet DRAFT Access Protocol January 1998 336 4.1.1. Atom 338 An atom consists of one to 1024 non-special characters. 340 4.1.2. Number 342 A number consists of one or more digit characters, and represents a 343 numeric value. 345 4.1.3. String 347 A string is in one of two forms: literal and quoted string. The 348 literal form is the general form of string. The quoted string form 349 is an alternative that avoids the overhead of processing a literal at 350 the cost of restrictions of what may be in a quoted string. 352 A literal is a sequence of zero or more octets (including CR and LF), 353 prefix-quoted with an octet count in the form of an open brace ("{"), 354 the number of octets, close brace ("}"), and CRLF. In the case of 355 literals transmitted from server to client, the CRLF is immediately 356 followed by the octet data. 358 There are two forms of literals transmitted from client to server. 359 The form where the open brace ("{") and number of octets is 360 immediately followed by a close brace ("}") and CRLF is called a 361 synchronizing literal. When sending a synchronizing literal, the 362 client must wait to receive a command continuation request (described 363 later in this document) before sending the octet data (and the 364 remainder of the command). The other form of literal, the non- 365 synchronizing literal, is used to transmit a string from client to 366 server without waiting for a command continuation request. The non- 367 synchronizing literal differs from the synchronizing literal by 368 having a plus ("+") between the number of octets and the close brace 369 ("}") and by having the octet data immediately following the CRLF. 371 A quoted string is a sequence of zero to 1024 octets excluding CR, 372 LF, double quote (<">), or backslash ("\") with double quote (<">) 373 characters at each end. 375 The empty string is respresented as "" (a quoted string with zero 376 characters between double quotes), as {0} followed by CRLF (a 377 synchronizing literal with an octet count of 0), or as {0+} followed 378 by a CRLF (a non-synchronizing literal with an octet count of 0). 380 Note: Even if the octet count is 0, a client transmitting a 381 synchronizing literal MUST wait to receive a command continuation 383 Internet DRAFT Access Protocol January 1998 385 request. 387 4.1.4. Parenthesized List 389 Data structures are represented as a "parenthesized list"; a sequence 390 of data items, delimited by space, and bounded at each end by 391 parentheses. A parenthesized list can contain other parenthesized 392 lists, using multiple levels of parentheses to indicate nesting. 394 The empty list is represented as () -- a parenthesized list with no 395 members. 397 4.1.5. NIL 399 The special atom "NIL" represents the non-existence of a particular 400 data item that is represented as a string or parenthesized list, as 401 distinct from the empty string "" or the empty parenthesized list (). 403 4.2. Server Status Responses 405 Server status responses (defined in the ABNF as "status-response") 406 MAY include an optional response code. A response code consists of 407 data inside parentheses in the form of an atom, possibly followed by 408 a space and arguments (defined in the ABNF as "resp-code"). The 409 response code contains additional information or status codes for 410 client software beyond the condition triggering the status response, 411 and are defined when there is a specific action that a client can 412 take based upon the additional information. 414 The currently defined response codes are: 416 AUTH-TOO-WEAK 417 This response code is returned on a tagged NO result 418 from an AUTHENTICATE command. It indicates that site 419 security policy forbids the use of the requested 420 mechanism for the specified authentication identity. 422 ENCRYPT-NEEDED 423 This response code is returned on a tagged NO result 424 from an AUTHENTICATE command. It indicates that site 425 security policy requires the use of a strong encryption 426 mechanism for the specified authentication identity and 427 mechanism. 429 Internet DRAFT Access Protocol January 1998 431 SASL This response code can occur in the tagged OK response 432 to a successful AUTHENTICATE command and includes the 433 optional final server response data from the server as 434 specified by SASL [SASL]. 436 TRANSITION-NEEDED 437 This response code occurs on a NO response to an 438 AUTHENTICATE command. It indicates that the user name 439 is valid, but the entry in the authentication database 440 needs to be updated in order to permit authentication 441 with the specified mechanism. This can happen if a user 442 has an entry in a system authentication database such as 443 Unix /etc/passwd, but does not have credentials suitable 444 for use by the specified mechanism. 446 TRYLATER A command failed due to a temporary server failure. The 447 client MAY continue using local information and try the 448 command later. 450 Additional response codes MAY be defined by protocols layered on top 451 of AP or by particular client or server implementations of those 452 protocols. Additional response codes not defined in standards-track 453 documents MUST be prefixed with an "X". Client implementations MUST 454 ignore response codes that they do not recognize. 456 4.3. Server Command Continuation Request 458 The command continuation request is indicated by a "+" token instead 459 of a tag. This indicates that the server is ready to accept the 460 continuation of a command from the client. The remainder of this 461 response is a line of text. 463 This response is used in the AUTHENTICATE command to transmit server 464 data to the client, and request additional client data. This 465 response is also used if an argument to any command is a 466 synchronizing literal. Protocols layered upon this protocol may 467 define additional commands which use continuations, although these 468 should be few and far between. 470 The client is not permitted to send the octets of a synchronizing 471 literal unless the server indicates that it expects it. This permits 472 the server to process commands and reject errors on a line-by-line 473 basis, assuming it checks for non-synchronizing literals at the end 474 of each line. The remainder of the command, including the CRLF that 475 terminates a command, follows the octets of the literal. If there 477 Internet DRAFT Access Protocol January 1998 479 are any additional command arguments the literal octets are followed 480 by a space and those arguments. 482 5. Protocol Specification 484 5.1. Initial Connection 486 Upon session startup, the server sends one of two untagged responses: 487 AP or BYE. The BYE response is documented in section 5.2.8. 489 Open Issue: I'm tempted to change this a little - have the client 490 send its capabilities list in its greeting, and have the server 491 send back a tagged OK, NO, BAD, or BYE response. This would cause 492 negligable network load when used with TCP (the data could be 493 carried in the initial TCP SYN packet which has to be sent 494 anyway), and would allow the server to discover what the client's 495 capable of, at the expense of changing the state diagram a little, 496 hosing backwards compatibility, and adding an additional step for 497 people accessing servers via telnet. 499 5.1.1. AP Untagged Response 501 Data: capability list 503 The untagged AP response indicates that the session is ready to 504 accept commands and contains a space-separated listing of 505 capbilities that the server supports. Each capability is an atom 506 name, possibly followed by an argument in parenthesis (the 507 argument MAY contain parenthesis, but the parenthesis MUST be 508 balanced). 510 AP capability names MUST be defined in a standards track or IESG 511 approved experimental RFC and registered with IANA according to 512 the rules in section
. 514 Client implementations MAY require any capability names, but MUST 515 ignore any unknown capability names. It is recommended that 516 clients require as few capabilities as possible. 518 The following initial capabilities are defined: 520 IMPLEMENTATION 521 The IMPLEMENTATION capability has one argument which is 522 a string describing the server implementation. AP 523 clients MUST NOT alter their behavior based on this 524 value. It is intended primarily for debugging purposes. 526 Internet DRAFT Access Protocol January 1998 528 SASL The SASL capability includes a list of the 529 authentication mechanisms supported by the server. See 530 [SASL] for more information. 532 Example: S: * AP IMPLEMENTATION ("ACME v3.5") SASL ("GSSAPI") 534 5.2. Any State 536 The following commands and responses are valid in any state. 538 5.2.1 NOOP Command 540 Arguments: none 542 Data: no specific data for this command (but see below) 544 Result: OK - noop completed 545 BAD - command unknown or arguments invalid 547 The NOOP command always succeeds. It does nothing. It can be 548 used to reset any inactivity autologout timer on the server. 550 Example: C: a002 NOOP 551 S: a002 OK "NOOP completed" 553 5.2.2 LANG Command 555 Arguments: list of language preferences 557 Data: intermediate response: LANG 559 Result: OK - lang completed 560 NO - no matching language available 561 BAD - command unknown or arguments invalid 563 One or more arguments are supplied to indicate the client's 564 preferred languages [LANG-TAGS] for error messages. The server 565 will match each client preference in order against its internal 566 table of available error string languages. For a client 567 preference to match a server language, the client's language tag 568 MUST be a prefix of the server's tag and match up to a "-" or the 569 end of string. If a match is found, the server returns an 570 intermediate LANG response and an OK response. The LANG response 571 indicates the actual language selected. 573 Internet DRAFT Access Protocol January 1998 575 If no LANG command is issued, all error text strings MUST be in 576 the registered language "i-default" [CHARSET-LANG-POLICY], 577 intended for an international audience. 579 Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" 580 S: A003 LANG "fr-ca" 581 S: A003 OK "Bonjour" 583 5.2.3 LANG Intermediate Response 585 Data: language for error responses 587 The LANG response indicates the language which will be used for 588 responses (in the ABNF, the final "quoted" element of resp-body). 590 5.2.4 LOGOUT Command 592 Arguments: none 594 Data: mandatory untagged response: BYE 596 Result: OK - logout completed 597 BAD - command unknown or arguments invalid 599 The LOGOUT command informs the server that the client is done with 600 the session. The server must send a BYE untagged response before 601 the (tagged) OK response, and then close the network connection. 603 Example: C: A023 LOGOUT 604 S: * BYE "Server logging out" 605 S: A023 OK "LOGOUT completed" 607 (Server and client then close the connection) 609 5.2.5. OK Response 611 Data: optional response code 612 human-readable text 614 The OK response indicates an information message from the server. 615 When tagged, it indicates successful completion of the associated 616 command. The human-readable text may be presented to the user as 617 an information message. The untagged form indicates an 618 information-only message; the nature of the information may be 620 Internet DRAFT Access Protocol January 1998 622 indicated by a response code. 624 Example: S: * OK "Main disk is back on-line" 626 5.2.6. NO Response 628 Data: optional response code 629 human-readable text 631 The NO response indicates an operational error message from the 632 server. When tagged, it indicates unsuccessful completion of the 633 associated command. The untagged form indicates a warning; the 634 command may still complete successfully. The human-readable text 635 describes the condition. 637 Example: C: A222 AUTHENTICATE "FOOBAR" 638 S: A222 NO "Unknown SASL mechanism" 640 5.2.7 BAD Response 642 Data: optional response code 643 human-readable text 645 The BAD response indicates an error message from the server. When 646 tagged, it reports a protocol-level error in the client's command; 647 the tag indicates the command that caused the error. The untagged 648 form indicates a protocol-level error for which the associated 649 command can not be determined; it may also indicate an internal 650 server failure. The human-readable text describes the condition. 652 Example: C: ...empty line... 653 S: * BAD "Empty command line" 654 C: A443 BLURDYBLOOP 655 S: A443 BAD "Unknown command" 656 C: A444 NOOP Hello 657 S: A444 BAD "invalid arguments" 659 5.2.8. BYE Untagged Response 661 Data: optional response code 662 human-readable text 664 The untagged BYE response indicates that the server is about to 665 close the connection. The human-readable text may be displayed to 666 the user in a status report by the client. The BYE response may 668 Internet DRAFT Access Protocol January 1998 670 be sent as part of a normal logout sequence, or as a panic 671 shutdown announcement by the server. It SHOULD also used by 672 server implementations as an announcement of an inactivity 673 autologout. 675 This response is also used as one of two possible greetings at 676 session startup. As a greeting, it indicates that the server is 677 not willing to accept a session from this client. 679 Example: S: * BYE "Autologout; idle for too long" 681 5.2.9. ALERT Untagged Response 683 Data: optional response code 684 human-readable text 686 The human-readable text contains a special human generated alert 687 message that MUST be presented to the user in a fashion that calls 688 the user's attention to the message. This is intended to be used 689 for vital messages from the server administrator to the user, such 690 as a warning that the server will soon be shut down for 691 maintenance. 693 Example: S: * ALERT "This server will be shut down in 10 minutes 694 for system maintenance." 696 5.3. Non-Authenticated State 698 In non-authenticated state, the AUTHENTICATE command establishes 699 authentication and enters authenticated state. The AUTHENTICATE 700 command provides a general mechanism for a variety of authentication 701 techniques. 703 Server implementations may allow non-authenticated access to certain 704 information. The convention is to use an AUTHENTICATE command with 705 the SASL ANONYMOUS mechanism [ANON]. 707 Once authenticated (including as anonymous), it is not possible to 708 re-enter non-authenticated state. 710 In addition to the universal commands (NOOP and LOGOUT), the only 711 command valid in non-authenticated state is AUTHENTICATE. 713 5.3.1 AUTHENTICATE Command 714 Internet DRAFT Access Protocol January 1998 716 Arguments: SASL mechanism name 717 optional initial response 719 Data: continuation data may be requested 721 Result: OK - authenticate completed, now in authenticated state 722 NO - authenticate failure: unsupported authentication 723 mechanism, credentials rejected 724 BAD - command unknown or arguments invalid, 725 authentication exchange cancelled 727 The AUTHENTICATE command indicates a SASL [SASL] authentication 728 mechanism to the server. If the server supports the requested 729 authentication mechanism, it performs an authentication protocol 730 exchange to authenticate and identify the user. Optionally, it 731 also negotiates a security layer for subsequent protocol 732 interactions. If the requested authentication mechanism is not 733 supported, the server rejects the AUTHENTICATE command by sending 734 a tagged NO response. 736 The authentication protocol exchange consists of a series of 737 server challenges and client answers that are specific to the 738 authentication mechanism. A server challenge consists of a 739 command continuation request with the "+" token followed by a 740 string. The client answer consists of a line consisting of a 741 string. If the client wishes to cancel an authentication 742 exchange, it should issue a line with a single unquoted "*". If 743 the server receives such an answer, it must reject the 744 AUTHENTICATE command by sending a tagged BAD response. 746 The optional initial-response argument to the AUTHENTICATE command 747 is used to save a round trip when using authentication mechanisms 748 that are defined to send no data in the initial challenge. When 749 the initial-response argument is used with such a mechanism, the 750 initial empty challenge is not sent to the client and the server 751 uses the data in the initial-response argument as if it were sent 752 in response to the empty challenge. If the initial-response 753 argument to the AUTHENTICATE command is used with a mechanism that 754 sends data in the initial challenge, the server rejects the 755 AUTHENTICATE command by sending a tagged NO response. 757 The service name specified by this protocol's profile of SASL is 758 "ap". 760 If a security layer is negotiated through the SASL authentication 761 exchange, it takes effect immediately following the CRLF that 762 concludes the authentication exchange for the client, and the CRLF 763 of the tagged OK response for the server. 765 Internet DRAFT Access Protocol January 1998 767 All AP implementations MUST implement the CRAM-MD5 SASL mechanism 768 [CRAM-MD5], although they MAY offer a configuration option to 769 disable it if site security policy dictates. The example below is 770 the same example described in the CRAM-MD5 specification. 772 If an AUTHENTICATE command fails with a NO response, the client 773 may try another authentication mechanism by issuing another 774 AUTHENTICATE command. In other words, the client may request 775 authentication types in decreasing order of preference. 777 Example: S: * OK IMPLEMENTATION ("Blorfysoft v3.5") 778 SASL ("CRAM-MD4" "KERBEROS_V4") 779 C: A001 AUTHENTICATE "CRAM-MD5" 780 S: + "1896.697170952@postoffice.reston.mci.net>" 781 C: "tim b913a602c7eda7a495b4e6e7334d3890" 782 S: A001 OK "CRAM-MD5 authentication successful" 784 Note: the line breaks in the first client answer are for 785 editorial clarity and are not in real authenticators. 787 5.3. Authenticated State 789 In the authenticated state, the universal commands (NOOP and LOGOUT) 790 are valid, in addition to any commands defined by protocols that use 791 AP as their foundation. 793 6. Design Philosophy 795 Protocols layered on top of AP SHOULD define a set of commands to be 796 valid in the authenticated state. In addition, protocols MAY define 797 an atom to be returned in the initial AP greeting, possibly allowing 798 multiple protocols to be used over the same connection. 800 Ideally, protocols should limit themselves as much as possible to a 801 simple, uncomplicated suite of commands that relate to each other. 802 Where possible, protocols should be broken up into orthogonal 803 components, such that the components may be reused in other 804 protocols. 806 Example: Instead of defining an advisory lock mechanism, advisory 807 locking should be split into a seperate extension, useable 808 by whatever protocols happen to require it. 810 Quota management is another set of commands that could be 811 written as an extension and made available to all protocols 813 Internet DRAFT Access Protocol January 1998 815 that involve quotas. 817 New commands and responses SHOULD only be defined for the 818 Authenticated state. 820 Responses to commands SHOULD be tagged. This is essential for 821 allowing multiple commands to execute simultaneously, and experience 822 shows that this leads to much simpler implementations for both 823 clients and servers. 825 Where textual data is exchanged, protocols SHOULD use UTF8 [UTF8] 826 whenever possible, for internationalization. 828 New command completion responses MUST NOT be defined -- every command 829 MUST be completed by an "OK", "NO", or "BAD" response. 831 7. Formal Syntax 833 The following syntax specification uses the augmented Backus-Naur 834 Form (BNF) notation as specified in [ABNF] This uses the ABNF core 835 rules as specified in Appendix A of the ABNF specification [ABNF]. 837 Except as noted otherwise, all alphabetic characters are case- 838 insensitive. The use of upper or lower case characters to define 839 token strings is for editorial clarity only. Implementations MUST 840 accept these strings in a case-insensitive fashion. 842 Protocols based on AP should refer to this formal syntax, and augment 843 selected parts via the ABNF "=/" operator, as indicated in the 844 comments. 846 The client produces a sequence of octets matching "command-client"; 847 the server consumes these, and returns a sequence of octets matching 848 "response-server". 850 Protocols using AP MAY augment "capability" (subject to the 851 requirement that "capability" MUST match "capability-generic"), 852 "command" (subject to the requirement that "command" MUST match 853 "command-generic"), "response" (subject to the requirement that 854 "response" MUST match "response-generic"), "resp-code" (subject to 855 the requirement that "resp-code" MUST match "resp-code-generic"), or 856 "status-response" (subject to the requirement that "status-response" 857 MUST match "status-response-generic"). Other syntax elements SHOULD 858 NOT be redefined. 860 For readability, rules which MAY be augmented are defined using the 862 Internet DRAFT Access Protocol January 1998 864 "=/" operator; all other rules are defined using "=". 866 A number of symbols are defined solely for use by protocols using AP. 868 ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E 869 ; Any CHAR except ATOM-SPECIALS 871 ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS 873 DIGIT-NZ = %x31-39 874 ; 1-9 876 QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS 878 QUOTED-SPECIALS = <"> / "\" 880 SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / 881 %x23-5B / %x5D-7F 882 ; Any CHAR except CR, LF, or QUOTED-SPECIALS 884 SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / 885 UTF8-5 / UTF8-6 886 TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E 887 ; Any ATOM-CHAR except "*" or "+" 889 TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS 891 UTF8-1 = %x80-BF 893 UTF8-2 = %xC0-DF UTF8-1 895 UTF8-3 = %xE0-EF 2UTF8-1 897 UTF8-4 = %xF0-F7 3UTF8-1 899 UTF8-5 = %xF8-FB 4UTF8-1 901 UTF8-6 = %xFC-FD 5UTF8-1 903 UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF 905 argument = atom 906 / string 907 / number 908 / "(" [argument *(SP argument)] ")" 910 atom = 1*1024ATOM-CHAR 912 Internet DRAFT Access Protocol January 1998 914 auth-type = <"> auth-type-name <"> 916 auth-type-name = iana-token 917 ; As defined in [SASL] 919 capability =/ "IMPLEMENTATION" SP "(" quoted ")" 921 capability =/ "SASL" SP "(" auth-type *(SP auth-type) ")" 923 ; Other capabilities MAY be defined by protocols using AP, 924 ; but MUST syntactically match capability-generic 926 capability-arg = atom 927 / quoted 928 / "(" [capability-arg *(SP capability-arg)] ")" 930 capability-generic = atom [SP "(" [capability-arg] ")"] 932 command-client = tag SP command CRLF 934 command =/ "NOOP" 936 command =/ "LOGOUT" 938 command =/ "AUTHENTICATE" SP auth-type 939 [SP string] *(CRLF string) 941 ; Other commands MAY be defined by protocols using AP, 942 ; but MUST syntactically match command-generic 944 command-generic = atom *(SP argument) 946 iana-token = atom 947 ; MUST be registered with IANA 949 literal = "{" number [ "+" ] "}" CRLF *OCTET 950 ; The number represents the number of octets 952 literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR 953 ; The number represents the number of octets, 954 ; not the number of characters 956 nil = "NIL" 958 number = 1*DIGIT 960 nz-number = DIGIT-NZ *DIGIT 962 Internet DRAFT Access Protocol January 1998 964 quoted = <"> *QUOTED-CHAR <"> 966 resp-argument = atom 967 / quoted 968 / number 969 / "(" [resp-argument *(SP resp-argument)] ")" 971 resp-body = SP ["(" resp-code ")" SP] quoted 973 resp-code =/ "AUTH-TOO-WEAK" 975 resp-code =/ "ENCRYPT-NEEDED" 977 resp-code =/ "SASL" 979 resp-code =/ "TRANSITION-NEEDED" 981 resp-code =/ "TRYLATER" 983 ; Other resp-codes MAY be defined by protocols using AP, 984 ; but MUST syntactically match resp-code-generic 986 resp-code-generic = atom *(SP resp-argument) 988 response =/ "AP" *(SP capability) 990 response =/ status-response 992 ; Other responses MAY be defined by protocols using AP, 993 ; but MUST syntactically match response-generic 995 response-generic = atom *(SP argument) 997 response-server = (tag / "*") response CRLF 999 status-response =/ "OK" resp-body 1001 status-response =/ "NO" resp-body 1003 status-response =/ "BAD" resp-body 1005 status-response =/ "BYE" resp-body 1007 status-response =/ "ALERT" resp-body 1009 ; Other status-responses MAY be defined by protocols using AP, 1010 ; but MUST syntactically match status-response-generic 1012 Internet DRAFT Access Protocol January 1998 1014 status-response-generic = atom resp-body 1016 string = quoted / literal 1018 string-utf8 = quoted / literal-utf8 1020 tag = 1*32TAG-CHAR 1022 8. Security Considerations 1024 AP protocol transactions are sent in the clear over the network 1025 unless some form of privacy protection is negotiated in the 1026 AUTHENTICATE command. 1028 AP's security is defined by [SASL], and thus has the same security 1029 considerations. 1031 9. References 1033 [ABNF] Crocker, D., and Overell, P., "Augmented BNF for Syntax 1034 Specifications: ABNF", RFC 2234, November 1997. 1036 1038 [ACAP] Myers, J., and Newman, C., "Application Configuration Access 1039 Protocol (ACAP)", RFC 2244, November 1997. 1041 1043 [ANON] Newman, C., "Anonymous SASL Mechanism", RFC 2245, November 1044 1997. 1046 1048 [CHARSET-LANG-POLICY] Alvestrand, H., "IETF Policy on Character Sets 1049 and Languages", work in progress. 1051 [COMPARATOR] Newman, C., Myers, J., "Comparators", work in progress. 1053 [CRAM-MD5] Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP 1054 AUTHorize Extension for Simple Challenge/Response", RFC 2195, 1055 September 1997. 1057 1059 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 1061 Internet DRAFT Access Protocol January 1998 1063 4rev1", RFC 2060, December 1996. 1065 1067 [LANG-TAGS] Alvestrand, H., "Tags for the Identification of 1068 Languages", RFC 1766, March 1995. 1070 1072 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 1073 RFC 2222, October 1997. 1075 1077 [UTF8] Yergeau, F., "UTF-8, a transformation format of Unicode and 1078 ISO 10646", RFC 2044, October 1996. 1080 1082 10. Full Copyright Statement 1084 Copyright (C) The Internet Society 1998. All Rights Reserved. 1086 This document and translations of it may be copied and furnished to 1087 others, and derivative works that comment on or otherwise explain it 1088 or assist in its implementation may be prepared, copied, published 1089 and distributed, in whole or in part, without restriction of any 1090 kind, provided that the above copyright notice and this paragraph are 1091 included on all such copies and derivative works. However, this 1092 document itself may not be modified in any way, such as by removing 1093 the copyright notice or references to the Internet Society or other 1094 Internet organizations, except as needed for the purpose of 1095 developing Internet standards in which case the procedures for 1096 copyrights defined in the Internet Standards process must be 1097 followed, or as required to translate it into languages other than 1098 English. 1100 The limited permissions granted above are perpetual and will not be 1101 revoked by the Internet Society or its successors or assigns. 1103 This document and the information contained herein is provided on an 1104 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1105 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1106 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1107 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1108 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1110 Internet DRAFT Access Protocol January 1998 1112 11. Author's Address 1114 Robert H. Earhart 1115 Carnegie Mellon 1116 5000 Forbes Ave. 1117 Pittsburgh PA, 15213-3890 1119 Email: earhart+@cmu.edu 1121 Expires July 1998