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
<http://www.ietf.org/ietf/1id-abstracts.txt>.
The list of current Internet-Draft Shadow Directories can be accessed
at <http://www.ietf.org/shadow.html>.
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.
<http://www.ietf.org/rfc/rfc2234.txt>
[CRAM-MD5] Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP
AUTHorize Extension for Simple Challenge/Response", RFC 2195, Septem-
ber 1997.
<http://www.ietf.org/rfc/rfc2195.txt>
[DIGEST] Leach, P., and Newman, C., "Using Digest Authentication as a
SASL Mechanism", work-in-progress.
<http://www.ietf.org/internet-drafts/draft-leach-digest-
sasl-01.txt>
[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
<http://www.ietf.org/rfc/rfc2119.txt>
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, October 1996.
<http://www.ietf.org/rfc/rfc2026.txt>
[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
<http://www.ietf.org/rfc/rfc2222.txt>
10. Author's Address
Robert H. Earhart
Carnegie Mellon
5000 Forbes Ave.
Pittsburgh PA, 15213-3890
Email: <mailto:earhart+@cmu.edu>
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]