Network Working Group R. Earhart Internet Draft: ACP Carnegie Mellon Document: draft-earhart-acp-spec-00.txt February 1999 Expires July 1999 Application Core Protocol Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of section 10 of [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at . The list of current Internet-Draft Shadow Directories can be accessed at . Abstract This document specifies a textual protocol intended as a framework for applications-layer protocols. While complete, it does not do anything in and of itself; it's meant to be extensible to particular applications. 1. Introduction Traditionally, IETF applications-layer protocols have been based directly on top of TCP. This leads to protocol specifications which define a suite of commands (the interesting part of a protocol), but also include syntax and encoding rules for their commands (making the protocol specifications more complicated, which makes them harder to get right and delays their deployment). Earhart [Page 1] Internet DRAFT Application Core Protocol February 1999 ACP (the Application Core Protocol) abstracts the low level decisions of encoding and syntax, along with the core commands which each every applications protocol seems to require, into a standard core which can be built upon by new applications protocols. It's a simple extensible client/server textual protocol with a regular encoding and basic session management interactions, with security security provided via [SASL]. 2. Conventions Used in this Document In examples, "C:" and "S:" indicate lines sent by the client and server respectively. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 3. Structure ACP assumes a reliable data stream such as provided by TCP, to handle communications between clients and servers. Applications protocols which use ACP are responsible for defining any parameters to be used in constructing the stream, such as the TCP port number. 3.1. Lexical Structure Above the basic stream, there are four lexical elements: strings, atoms, numbers, and parenthesized lists. 3.1.1. Strings A string may take one of two forms: quoted, or literal. The literal form is the general form of the string. The quoted string form is an alternative that avoids the overhead of processing a literal at the cost of restricting what may be in a quoted string. A literal is a sequence of zero or more octets (including CR and LF), prefix-quoted with an octet count in the form of an open brace ("{"), the number of octets, close brace ("}"), and CRLF. The CRLF is immediately followed by the octet data. Optionally, a greater-than sign (">") may be included before the Earhart [Page 2] Internet DRAFT Application Core Protocol February 1999 number of octets, indicating a partial literal. This is used when the number of octets can not be known in advance. After the octet data, a partial literal MUST be immediately followed by either another partial literal, or a normal literal (possibly of zero length). A quoted string is a sequence of zero to 1024 octets excluding CR and LF, with double quote (<">) characters at each end. Double quote (<">) and backslash ("\") characters within a quoted string MUST be escaped, by preceeding them with a backslash. The empty string is represented as "" (a quoted string with zero characters between double quotes), or as {0} followed by a CRLF (a literal with an octet count of 0). 3.1.2. Atoms An atom consists of one to 1024 non-special characters (see the ABNF). 3.1.3. Numbers A number consists of one or more digit characters, and represents a numberic value. 3.1.4. Parenthesized Lists Data structures are represented as a "parenthesized list"; a sequence of data items, delimited by space, and bounded at each end by parentheses. A parenthesized list can contain other parenthesized lists, using multiple levels of parentheses to indicate nesting. The empty list is represented as (); a parenthesized list with no members. 3.2. Syntactic Structure An ACP session consists of the establishment of a client/server connection, initial greetings from both sides, and client/server interactions. These interactions consist of commands, responses, status updates (information which doesn't require a response), and command continuation requests (used during authentication exchanges). All interactions are in the form of lines, terminated with a CRLF. Earhart [Page 3] Internet DRAFT Application Core Protocol February 1999 Protocol receivers are either reading a line, or reading a sequence of octets with a known count followed by a line. Both clients and servers MUST be capable of handling lines of arbitrary length. Each line begins with a tag of some sort (defined precisely in the ABNF) to identify the particular interaction. Command tags are short strings (such as "a0") made up by the sender. Response tags are a colon, followed by the tag from the command the response is associated with. Tags for status updates are a "*"; tags for continuation responses are a "+", followed by the tag from the command the response is associated with. Except for command continuations, the tag is followed by an atom (as in lisp) to identify the type of interaction, which is then followed by an interaction-specific sequence of the lexical tokens, and terminated by a CRLF. 4. Base Protocol The following is a brief overview of interactions defined by the base protocol; they are described in more detail below: Commands AUTHENTICATE Sent by a client to establish authentication, possibly including integrity protection and encryption. NOOP Sent by a client to reset a server inactivity timeout. Command Responses OK Success; the command worked. NO Failure; the command failed, and no actions were performed. BAD Bad command: issued in an invalid state (such as when not authenticated), or with invalid syntax. Response Codes AUTH-TOO-WEAK Authentication too weak. Earhart [Page 4] Internet DRAFT Application Core Protocol February 1999 ENCRYPT-NEEDED Encryption is required. SASL Final data from a SASL negotiation. TRANSITION-NEEDED Used for transitioning users from weaker to stronger secu- rity mechanisms. TRYLATER Command failure due to transient conditions. Status Updates CAPABILITY Sent by either side to convey supported extensions. BYE Sent by either side to indicate connection termination. Capabilities IMPL Conveys an implementation-specific vendor string. SASL Lists available SASL mechanisms. 4.1. Commands The base ACP specification provides the core commands common to most applications layer protocols. Additional commands MAY be defined by extensions; these commands MUST follow the "command" rule in the ABNF. In the base protocol, both commands are client-only; note that while most applications protocols will only define client commands, it's possible to define new commands sent by servers as well. 4.1.1. AUTHENTICATE Command Arguments: SASL mechanism name optional initial response Earhart [Page 5] Internet DRAFT Application Core Protocol February 1999 Data: continuation data may be requested Result: OK - authentication completed, now in authenticated state NO - authentication failure: unsupported authentication mechanism, credentials rejected BAD - command unknown or arguments invalid, authentication exchange cancelled The AUTHENTICATE command indicates a [SASL] authentication mecha- nism to the server. If the server supports the requested authen- tication mechanism, it performs an authentication protocol exchange to authenticate and identify the user. Optionally, it also negotiates a security layer for subsequent protocol interac- tions. If the requested authentication mechanism is not sup- ported, the server rejects the AUTHENTICATE command by sending a tagged NO response. The authentication protocol exchange consists of a series of server challenges and client answers that are specific to the authentication mechanism. A server challenge consists of a com- mand continuation request with the "+" token followed by a string. The client answer consists of a line consisting of a string. If the client wishes to cancel an authentication exchange, it should issue a line with a single unquoted "*". If the server receives such an answer, it must reject the AUTHENTICATE command by sending a tagged BAD response. The optional initial-response argument to the AUTHENTICATE command is used to save a round trip when using authentication mechanisms that are defined to send no data in the initial challenge. When the initial-response argument is used with such a mechanism, the initial empty challenge is not sent to the client and the server uses the data in the initial-response argument as if it were sent in response to the empty challenge. If the initial-response argu- ment to the AUTHENTICATE command is used with a mechanism that sends data in the initial challenge, the server rejects the AUTHENTICATE command by sending a tagged NO response. The service name specified by this protocol's profile of SASL is "acp". If a security layer is negotiated through the SASL authentication exchange, it takes effect immediately following the CRLF that con- cludes the authentication exchange for the client, and the CRLF of the tagged OK response for the server. All protocols based on ACP MUST define a mandatory to implement SASL mechanism appropriate to the protocol. It is RECOMMENDED Earhart [Page 6] Internet DRAFT Application Core Protocol February 1999 that this mechanism be Digest authentication [DIGEST]. Note that although implementations MUST implement the mandatory to implement mechanism, they MAY offer a configuration option to disable it if site security policy dictates. The example below is the same example described in the [CRAM-MD5] specification. If an AUTHENTICATE command fails with a NO response, the client may try another authentication mechanism by issuing another AUTHENTICATE command. In other words, the client MAY request authentication types in decreasing order of preference. Example: S: * CAPABILITY SASL ("CRAM-MD5" "KERBEROS_V4") C: a1 AUTHENTICATE "CRAM-MD5" S: +a1 "1896.697170952@postoffice.reston.mci.net>" C: +a1 "tim b913a602c7eda7a495b4e6e7334d3890" S: :a1 OK "CRAM-MD5 authentication successful" 4.1.2. NOOP Command Arguments: none Data: no specific data for this command (but see below) Result: OK - noop completed BAD - command unknown or arguments invalid The NOOP command always succeeds. It can be used to reset any inactivity autologout timer on the server. Example: C: a2 NOOP S: :a2 OK "NOOP Completed" 4.2. Responses Each command requires at least one final response; extensions MAY define other responses. A final response MUST be an "OK" , "NO", or "BAD". Additional responses to specific commands MAY be defined by extensions; these MUST follow the "response" rule specified in the ABNF, and they MUST NOT be the final response to a command. 4.2.1. OK Response Earhart [Page 7] Internet DRAFT Application Core Protocol February 1999 Data: optional response code human-readable text The OK response indicates successful completion of the associated command. The human-readable text MAY be presented to the user as an informational message. Example: C: a2 NOOP S: :a2 OK "NOOP Completed" 4.2.2. NO Response Data: optional response code human-readable text The NO response indicates failure of the associated command. The human-readable text MAY be presented to the user as an informa- tional message. Example: C: a1 AUTHENTICATE "CRAM-MD5" S: :a1 NO TRYLATER "The CRAM-MD5 auth server is down" 4.2.3. BAD Response Data: optional response code human-readable text The BAD response indicates a protocol-level error in the associ- ated command; the human-readable text describes the condition. Example: C: a3 BLURDYBLOOP S: :a3 BAD "Unknown command" 4.2.4. Additional Final Response Codes Each final response MAY include one or more response codes. Additional response codes MAY be defined by extensions; these MUST follow the "resp-code" rule specified in the ABNF. AUTH-TOO-WEAK This response code is returned on a NO result from an AUTHENTICATE Earhart [Page 8] Internet DRAFT Application Core Protocol February 1999 command. It indicates that site security policy forbids the use of the requested mechanism for the specified authentication iden- tity. ENCRYPT-NEEDED This response code is returned on a NO result from an AUTHENTICATE command. It indicates that site security policy requires the use of a strong encryption mechanism for the specified authentication identity and mechanism. SASL This response code can occur in the OK response to a successful AUTHENTICATE command and includes the optional final server response data from the server as specified by [SASL]. TRANSITION-NEEDED This response code occurs on a NO response to an AUTHENTICATE com- mand. It indicates that the user name is valid, but the entry in the authentication database needs to be updated in order to permit authentication with the specified mechanism. This can happen if a user has an entry in a system authentication database such as Unix /etc/passwd, but does not have credentials suitable for use by the specified mechanism. TRYLATER This response code MAY occur with any NO response, and indicates that a command failed due to conditions which may be transient; the command may succeed if tried again later. 4.3. Status Updates Status updates are informational messages which do not require a response; this base spec defines CAPABILITY, and BYE, as described below. Additional status update interactions MAY be defined by extensions; these MUST follow the "update" rule specified in the ABNF. 4.3.1. CAPABILITY Status Update Data: capability list Earhart [Page 9] Internet DRAFT Application Core Protocol February 1999 The CAPABILITY update indicates that the session is ready to accept commands and contains a space-separated listing of sup- ported capbilities. Each capability is an atom name, possibly followed by an argument in parentheses (the argument MAY contain parentheses, but the parentheses MUST be balanced). Additional capabilities MAY be provided by extensions; these capa- bilities MUST follow the "capability" rule in the ABNF. Implementations MAY require any set of capabilities, but MUST ignore any unknown capability names. It is recommended that as few capabilities be required as possible. The following initial capabilities are defined: IMPL The IMPL capability has one argument which is a string describ- ing the server implementation. ACP implementations MUST NOT alter their behavior based on this value. It is intended pri- marily for debugging purposes. SASL The SASL capability includes a list of the authentication mech- anisms supported by a server (as the client selects the mecha- nism, there's no need for the client to send its list). See [SASL] for more information. Example: C: * CAPABILITY IMPL ("CMU v3.5") S: * CAPABILITY IMPL ("MIT v3.5") SASL ("GSSAPI") 4.3.2. BYE Status Update Data: none The BYE update is used to indicate the end of an ACP session. It may be issued by either side at any time. The sender MUST NOT issue any further interactions on the stream; the receiver SHOULD complete any outstanding commands, and issue its own BYE response. Once a BYE update has been issued and a BYE update has been received, the stream connection can be torn down. This MAY be sent as an initial session greeting, indicating the unwillingness of the peer to participate (and possibly conveying a reason). Earhart [Page 10] Internet DRAFT Application Core Protocol February 1999 Example: C: * BYE "Closing down the connection" S: * BYE "Cya later" (the connection is then torn down) 5. Operational Considerations Commands MAY be defined to be sent by either side (although it is anticipated that most application protocols will only define commands sent by clients). Both sides MUST be prepared to accept data at all times; this includes data which may not have been requested. The only state defined in this document is whether or not authentication has been performed. Extensions MAY define more state; this state MUST only affect extensions which indicate that they are affected by it. Certain commands MAY only be available in certain states; in particular, the AUTHENTICATE command MUST be available when the connection is unauthenticated (and only in that state), and the NOOP command MUST always be available. The CAPABILITY status update MAY be sent anytime either side wishes to announce new capabilities; in particular, if encryption is negotiated, a server MAY provide operations (such as insecure authentication mechanisms) which are not available without encryption. The BYE status update MAY be sent at any time by either side. Servers MAY implement an inactivity timeout. This inactivity timeout MUST be at least ten minutes long, and MUST be reset by the reciept of any data from the client. It is RECOMMENDED that servers not automatically close connections unless resources are scarce, even if the inactivity timeout has expired. There may be multiple commands outstanding at either the client or the server. These commands MAY be processed and completed in any order (with their final responses being sent in any order); however, the side effects (if any) of the commands MUST be as if they were processed serially. The stream connection may be unexpectedly terminated for reasons outside the control of the client or the server. In this event, outstanding commands MAY be either completed or terminated, except for the serial command processing restriction as indicated above (although outstanding commands MAY still fail in ways which would Earhart [Page 11] Internet DRAFT Application Core Protocol February 1999 result in a NO response); this is completely implementation dependant. 5. Formal Syntax The following syntax specification uses the ABNF notation as specified in [ABNF]. This uses the ABNF core rules as specified in Appendix A of the ABNF specification [ABNF]. Except as noted otherwise, all alphabetic characters are case- insensitive. The use of upper or lower case characters to define token strings is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion. 5.1. Lexical Tokens ACP's lexical tokens are "string", "atom", "number", "tag", "response-tag", open and close parentheses, spaces, "+", "*", and CRLF; the compound elements are defined below: ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E ; Any CHAR except ATOM-SPECIALS ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS QUOTED-CHAR = SAFE-CHAR / "\" QUOTED-SPECIALS QUOTED-SPECIALS = <"> / "\" SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-7F ; Any CHAR except CR, LF, or QUOTED-SPECIALS TAG-CHAR = %x21 / %x23-27 / %x2C-39 / %x3B-5B / %x5D-7A / %x7C-7E ; Any ATOM-CHAR except "*", "+", or ":" atom = 1*1024 ATOM-CHAR literal = *literal-partial literal-terminal literal-partial = "{>" number "}" CRLF *OCTET ; The number represents the number of octets literal-terminal = "{" number "}" CRLF *OCTET Earhart [Page 12] Internet DRAFT Application Core Protocol February 1999 ; The number represents the number of octets number = 1*DIGIT quoted = " response-tag = ":" tag update-tag = "*" continuation-tag = "+" tag string = quoted / literal tag = 1*32 TAG-CHAR 5.2. Syntactic Structure Syntactically, ACP is a sequence of commands, responses, updates, and continuations, each a logical single line (although embedded literal strings may stretch this to multiple lines). The syntax is below; the start rule is "session": session = *line line = command / response / update / continuation command = tag SP atom [data] CRLF response = response-tag [data] CRLF update = update-tag SP atom [data] CRLF continuation = continuation-tag SP string CRLF data = 1*(SP datum) datum = atom / number / string / sexpr sexpr = "(" [datum [data]] ")" 5.3. Core Commands, Responses, and Updates Earhart [Page 13] Internet DRAFT Application Core Protocol February 1999 The core ACP commands, responses, and updates are specified as follows (note that these follow the general syntax described above): ; Core commands noop = tag SP "NOOP" CRLF logout = tag SP "LOGOUT" CRLF authenticate = tag SP "AUTHENTICATE" [string] CRLF *("+" SP string CRLF) ; Core responses resp-bad = response-tag SP "BAD" *resp-code SP string CRLF resp-ok = response-tag SP "OK" *resp-code SP string CRLF resp-no = response-tag SP "NO" *resp-code SP string CRLF resp-code = SP atom [SP sexpr] ; Core response codes resp-code-authtooweak = SP "AUTH-TOO-WEAK" resp-code-encryptneeded = SP "ENCRYPT-NEEDED" resp-code-sasl = SP "SASL" SP "(" string ")" resp-code-transition = SP "TRANSITION-NEEDED" resp-code-trylater = SP "TRYLATER" ; Core status updates capabilities = "*" SP "CAPABILITY" *capability CRLF capability = SP atom [SP sexpr] bye = "*" SP "BYE" *resp-code SP string CRLF ; Core capabilities capability-impl = SP "IMPL" SP "(" string ")" capability-sasl = SP "SASL" SP "(" [string *(SP string)] ")" 6. Implementation Considerations Earhart [Page 14] Internet DRAFT Application Core Protocol February 1999 Note that, although ACP looks a little like scheme or lisp, it's a bit more rigid; specifically, whitespace is important. In particular, clients and servers MUST NOT insert extra whitespace, MUST NOT omit required whitespace, and MUST end every line with the two character sequence CR LF--never a solo CR or LF. 7. Extension Considerations Protocols based on this document MAY define commands, responses, status updates, capabilties, or additional response codes. The final response to a given command MUST be a tagged BAD, OK, or NO code, and these MUST only be used for final responses. 8. Security Considerations ACP specifies a command for negotiating SASL, but does not mandate a particular SASL mechanism. Extensions intended to be full-fledged protocols MUST specify a mandatory-to-implement SASL mechanism appropriate to the protocol; it is RECOMMENDED that this mechanism be Digest authentication [DIGEST]. 9. References [ABNF] Crocker, D., and Overell, P., "Augmented BNF for Syntax Speci- fications: ABNF", RFC 2234, November 1997. [CRAM-MD5] Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP AUTHorize Extension for Simple Challenge/Response", RFC 2195, Septem- ber 1997. [DIGEST] Leach, P., and Newman, C., "Using Digest Authentication as a SASL Mechanism", work-in-progress. [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Earhart [Page 15] Internet DRAFT Application Core Protocol February 1999 [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, October 1996. [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. 10. Author's Address Robert H. Earhart Carnegie Mellon 5000 Forbes Ave. Pittsburgh PA, 15213-3890 Email: 11. Copyright The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Copyright (C) The Internet Society 1999. All Rights Reserved. This document and translations of it may be copied and furnished to Earhart [Page 16] Internet DRAFT Application Core Protocol February 1999 others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Expires July 1999 Earhart [Page 17]