Durn. A command-oriented, stateful protocol framework. The opposite,
but equal, of *TP.
Rohit
--============_-1294479272==_============
Content-Id: <v04103600b2d7ca40077d@[128.195.182.217].0.0>
Content-Type: text/plain; name="draft-earhart-ap-spec-01.txt"; charset="us-ascii" ; format="flowed"
Content-Disposition: attachment; filename="draft-earhart-ap-spec-01.txt"
; modification-date="Fri, 29 Jan 1999 12:25:57 -0800"
Network Working Group R. Earhart
Internet Draft: AP Carnegie Mellon
Document: draft-earhart-ap-spec-01.txt January 1998
Expires July 1998
Access Protocol
Status of this Memo
This document is an Internet-Draft. 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".
To learn the current status of any Internet-Draft, please check the
1id-abstracts.txt listing contained in the Internet-Drafts Shadow
Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
ftp.isi.edu (US West Coast).
This document suggests a proposed protocol for the Internet
community, and requests discussion and suggestions for improvements.
Distribution of this draft is unlimited.
The protocol discussed in this document is experimental and subject
to change. Persons planning on either implementing or using this
protocol are STRONGLY URGED to get in touch with the author before
embarking on such a project.
Copyright
Copyright (C) The Internet Society 1998. All Rights Reserved.
Abstract
The Access Protocol defines a standard extensible framework upon
which application-specific protocols may be layered, providing a
piece of infrastructure for a common class of internet protocols.
Earhart [Page 1]
Internet DRAFT Access Protocol January 1998
Attributions
Substantial portions of this protocol and of the text of this
document come from [ACAP], which itself borrows much from [IMAP4].
1. Motivation
There are an increasing number of internet application-level
protocols, solving a wide variety of problems. But as time goes on,
it's becoming increasingly obvious that in the course of their
development, regargless of their application-level purpose, many of
the protocols need to solve the same infrastructure problems, such as
Representation of commands (interleaving, protocol structure)
Representation of command data
Security (Authentication and authorization)
Internationalization (UTF8, language control, etc.)
Error reporting
And a variety of minor issues (inactivity timeouts, etc.)
It's hoped that by defining a common infrastructure between
application-specific command suites and the underlying stream
protocol provided by services such as TCP, a number of these problems
can be solved in a general way, allowing application-specific
protocols to be more rapidly developed and deployed.
In addition, by abstracting the infrastructure from the application,
it's hoped that each will be able to evolve independantly, and that
the state of the art in protocol design will improve and advance
faster than if each new infrastructure-level idea had to be
individually incorporated into each application level protocol.
ASN.1/BER is *not* used, as there is a significant feeling in the
applications area community that the complexity of these standards is
a significant barrier to implementation.
It is recognized that not all application level protocols will fit
into this model; TELNET is a good example of a protocol that does not
belong in this framework. Nevertheless, it is believed that this is
of sufficient utility to enough protocols to be worth advancing as an
IETF standard.
2. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
Earhart [Page 2]
Internet DRAFT Access Protocol January 1998
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 [KEYWORDS].
3. Protocol Overview
3.1. Link Level
The Access Protocol assumes a reliable data stream such as provided
by TCP. The command protocol that uses the AP is responsible for
specifying any parameters to be used in constructing the stream.
3.2. Commands and Responses
An AP session consists of the establishment of a client/server
connection, an initial greeting from the server, and client/server
interactions. These client/server interactions consist of a client
command, server data, and a server completion result.
All interactions transmitted by client and server are in the form of
lines; that is, strings that end with a CRLF. The protocol receiver
of an AP client or server is either reading a line, or is 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.
3.2.1. Client Protocol Sender and Server Protocol Receiver
The client command begins an operation. Each client command is
prefixed with a identifier composed of one to thirty-two characters
(typically a short alphanumeric string, e.g., A0001, A0002, etc.)
called a "tag". A different tag is generated by the client for each
command.
There are two cases in which a line from the client does not
represent a complete command. In one case, a command argument is
quoted with an octet count (see the description of literal in section
4.1.3); in the other case, the command arguments require server
feedback (see the AUTHENTICATE command). In some of these cases, the
server sends a command continuation request if it is ready for the
next part of the command. This response is prefixed with the token
"+".
Note: If, instead, the server detected an error in the command, it
sends a BAD or NO completion response with tag matching the
Earhart [Page 3]
Internet DRAFT Access Protocol January 1998
command (as described below) to reject the command and prevent the
client from sending any more of the command.
It is also possible for the server to send a completion or
intermediate response for some other command (if multiple commands
are in progress), or untagged data. In either case, the command
continuation request is still pending; the client takes the
appropriate action for the response, and reads another response
from the server.
The server reads a command line from the client, parses the command
and its arguments, and transmits server data and a server command
completion result.
3.2.1. Server Protocol Sender and Client Protocol Receiver
Data transmitted by the server to the client come in four forms:
command continuation requests, command completion results,
intermediate responses, and untagged responses.
A command continuation request is prefixed with the token "+".
A command completion result indicates the success or failure of the
operation. It is tagged with the same tag as the client command
which began the operation. Thus, if more than one command is in
progress, the tag in a server completion response identifies the
command to which the response applies. There are three possible
server completion responses: OK (indicating success), NO (indicating
failure), or BAD (indicating protocol error such as unrecognized
command or command syntax error).
An intermediate response returns data which can only be interpreted
within the context of a command in progress. It is tagged with the
same tag as the client command which began the operation. Thus, if
more than one command is in progress, the tag in an intermediate
response identifies the command to which the response applies. A
tagged response other than "OK", "NO", or "BAD" is an intermediate
response.
An untagged response returns data or status messages which may be
interpreted outside the context of a command in progress. It is
prefixed with the token "*". Untagged data may be sent as a result
of a client command, or may be sent unilaterally by the server.
There is no syntactic difference between untagged data that resulted
from a specific command and untagged data that were sent
unilaterally.
Earhart [Page 4]
Internet DRAFT Access Protocol January 1998
The protocol receiver of an AP client reads a response line from the
server. It then takes action on the response based upon the first
token of the response, which may be a tag, a "*", or a "+" as
described above.
A client MUST be prepared to accept any server response at all times.
This includes untagged data that it may not have requested.
This topic is discussed in greater detail in the Server Responses
section.
3.3. State and Flow Diagram
An AP server is in one of at least three states. Most commands are
valid in only certain states. It is a protocol error for the client
to attempt a command while the server is in an inappropriate state
for that command. In this case, a server MUST respond with a BAD
command completion result.
3.3.1. Non-Authenticated State
In non-authenticated state, the user must supply authentication
credentials before most commands will be permitted. This state is
entered when a connection starts.
3.3.2. Authenticated State
In authenticated state, the user is authenticated and most commands
will be permitted. This state is entered when acceptable
authentication credentials have been provided.
3.3.3. Logout State
In logout state, the session is being terminated, and the server will
close the connection. This state can be entered as a result of a
client request or by unilateral server decision.
3.3.4. Other States
Protocols using AP MAY define more states, as desired. These states
MUST only be reachable from the authenticated state, and MUST only
transition between themselves, to the authenticated state, or to the
logout state.
Earhart [Page 5]
Internet DRAFT Access Protocol January 1998
Protocol-specific states MUST only affect the operation of commands
defined in those protocols, or in extensions to those protocols. In
particular, the NOOP and LOGOUT commands MUST always be available.
Protocols MAY define new commands which transition to the logout
state.
+--------------------------------------+
|initial connection and server greeting|
+--------------------------------------+
|| (1) (2) ||
VV ||
+-----------------+ ||
|non-authenticated| ||
+-----------------+ ||
|| (4) || (3) ||
|| VV ||
|| +----------------+ ||
|| | authenticated |<=++ ||
|| +----------------+ || ||
|| || (4) || (5) || (5) ||
|| || VV || ||
|| || +------------+ || ||
|| || |other states|==++ ||
|| || +------------+ ||
|| || || (4) ||
VV VV VV VV
+--------------------------------------+
| logout and close connection |
+--------------------------------------+
(1) connection (AP greeting)
(2) rejected connection (BYE greeting)
(3) successful AUTHENTICATE command
(4) LOGOUT or other closing command, server shutdown,
or connection closed.
(5) State-transition command defined by protocol using AP
3.4. Operational Considerations
3.4.1. Untagged Status Updates
At any time, a server MAY send data that the client did not request.
It is recognized that this will cause perfectly good TCP connections
to be torn down if the network is unavailable for some transient
reason; nevertheless, this is better than forcing the client to poll
Earhart [Page 6]
Internet DRAFT Access Protocol January 1998
the server for update information.
3.4.2. Response when No Command in Progress
Server implementations are permitted to send an untagged response
while there is no command in progress. Server implementations that
send such responses MUST deal with flow control considerations.
Specifically, they must either (1) verify that the size of the data
does not exceed the underlying transport's available window size, or
(2) use non-blocking writes.
3.4.3. Autologout Timer
Servers MAY implement an inactivity autologout timer. If such a
timer is implemented, that timer MUST be at least 30 minutes'
duration. The receipt of ANY data from the client during that
interval MUST suffice to reset the autologout timer.
Open Issue: is this really necessary? I'd rather forbid timers
and the NOOP command, and say that it's the responsibility of the
underlying stream protocol to ensure that the other side's still
alive...)
3.4.4. Multiple Commands in Progress
The client is not required to wait for the completion result of a
command before sending another command, subject to flow control
constraints on the underlying data stream. Similarly, a server is
not required to process a command to completion before beginning
processing of the next command, although the server MUST compute the
results of a command as though any changes caused by previous
commands had taken place, and as though any changes caused by
subsequent commands have not yet taken place.
Protocols which use this protocol as their basis SHOULD NOT define
commands in such a way as to create an ambiguity when results from
seperate commands are interlaced or reordered.
4. Protocol Elements
4.1. Data Formats
AP uses textual commands and responses. Data in AP can be in one of
four forms: atom, number, string, parenthesized list, or NIL.
Earhart [Page 7]
Internet DRAFT Access Protocol January 1998
4.1.1. Atom
An atom consists of one to 1024 non-special characters.
4.1.2. Number
A number consists of one or more digit characters, and represents a
numeric value.
4.1.3. String
A string is in one of two forms: literal and quoted string. The
literal form is the general form of string. The quoted string form
is an alternative that avoids the overhead of processing a literal at
the cost of restrictions of 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. In the case of
literals transmitted from server to client, the CRLF is immediately
followed by the octet data.
There are two forms of literals transmitted from client to server.
The form where the open brace ("{") and number of octets is
immediately followed by a close brace ("}") and CRLF is called a
synchronizing literal. When sending a synchronizing literal, the
client must wait to receive a command continuation request (described
later in this document) before sending the octet data (and the
remainder of the command). The other form of literal, the non-
synchronizing literal, is used to transmit a string from client to
server without waiting for a command continuation request. The non-
synchronizing literal differs from the synchronizing literal by
having a plus ("+") between the number of octets and the close brace
("}") and by having the octet data immediately following the CRLF.
A quoted string is a sequence of zero to 1024 octets excluding CR,
LF, double quote (<">), or backslash ("\") with double quote (<">)
characters at each end.
The empty string is respresented as "" (a quoted string with zero
characters between double quotes), as {0} followed by CRLF (a
synchronizing literal with an octet count of 0), or as {0+} followed
by a CRLF (a non-synchronizing literal with an octet count of 0).
Note: Even if the octet count is 0, a client transmitting a
synchronizing literal MUST wait to receive a command continuation
Earhart [Page 8]
Internet DRAFT Access Protocol January 1998
request.
4.1.4. Parenthesized List
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.
4.1.5. NIL
The special atom "NIL" represents the non-existence of a particular
data item that is represented as a string or parenthesized list, as
distinct from the empty string "" or the empty parenthesized list ().
4.2. Server Status Responses
Server status responses (defined in the ABNF as "status-response")
MAY include an optional response code. A response code consists of
data inside parentheses in the form of an atom, possibly followed by
a space and arguments (defined in the ABNF as "resp-code"). The
response code contains additional information or status codes for
client software beyond the condition triggering the status response,
and are defined when there is a specific action that a client can
take based upon the additional information.
The currently defined response codes are:
AUTH-TOO-WEAK
This response code is returned on a tagged NO result
from an AUTHENTICATE command. It indicates that site
security policy forbids the use of the requested
mechanism for the specified authentication identity.
ENCRYPT-NEEDED
This response code is returned on a tagged 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.
Earhart [Page 9]
Internet DRAFT Access Protocol January 1998
SASL This response code can occur in the tagged OK response
to a successful AUTHENTICATE command and includes the
optional final server response data from the server as
specified by SASL [SASL].
TRANSITION-NEEDED
This response code occurs on a NO response to an
AUTHENTICATE command. 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 A command failed due to a temporary server failure. The
client MAY continue using local information and try the
command later.
Additional response codes MAY be defined by protocols layered on top
of AP or by particular client or server implementations of those
protocols. Additional response codes not defined in standards-track
documents MUST be prefixed with an "X". Client implementations MUST
ignore response codes that they do not recognize.
4.3. Server Command Continuation Request
The command continuation request is indicated by a "+" token instead
of a tag. This indicates that the server is ready to accept the
continuation of a command from the client. The remainder of this
response is a line of text.
This response is used in the AUTHENTICATE command to transmit server
data to the client, and request additional client data. This
response is also used if an argument to any command is a
synchronizing literal. Protocols layered upon this protocol may
define additional commands which use continuations, although these
should be few and far between.
The client is not permitted to send the octets of a synchronizing
literal unless the server indicates that it expects it. This permits
the server to process commands and reject errors on a line-by-line
basis, assuming it checks for non-synchronizing literals at the end
of each line. The remainder of the command, including the CRLF that
terminates a command, follows the octets of the literal. If there
Earhart [Page 10]
Internet DRAFT Access Protocol January 1998
are any additional command arguments the literal octets are followed
by a space and those arguments.
5. Protocol Specification
5.1. Initial Connection
Upon session startup, the server sends one of two untagged responses:
AP or BYE. The BYE response is documented in section 5.2.8.
Open Issue: I'm tempted to change this a little - have the client
send its capabilities list in its greeting, and have the server
send back a tagged OK, NO, BAD, or BYE response. This would cause
negligable network load when used with TCP (the data could be
carried in the initial TCP SYN packet which has to be sent
anyway), and would allow the server to discover what the client's
capable of, at the expense of changing the state diagram a little,
hosing backwards compatibility, and adding an additional step for
people accessing servers via telnet.
5.1.1. AP Untagged Response
Data: capability list
The untagged AP response indicates that the session is ready to
accept commands and contains a space-separated listing of
capbilities that the server supports. Each capability is an atom
name, possibly followed by an argument in parenthesis (the
argument MAY contain parenthesis, but the parenthesis MUST be
balanced).
AP capability names MUST be defined in a standards track or IESG
approved experimental RFC and registered with IANA according to
the rules in section <section>.
Client implementations MAY require any capability names, but MUST
ignore any unknown capability names. It is recommended that
clients require as few capabilities as possible.
The following initial capabilities are defined:
IMPLEMENTATION
The IMPLEMENTATION capability has one argument which is
a string describing the server implementation. AP
clients MUST NOT alter their behavior based on this
value. It is intended primarily for debugging purposes.
Earhart [Page 11]
Internet DRAFT Access Protocol January 1998
SASL The SASL capability includes a list of the
authentication mechanisms supported by the server. See
[SASL] for more information.
Example: S: * AP IMPLEMENTATION ("ACME v3.5") SASL ("GSSAPI")
5.2. Any State
The following commands and responses are valid in any state.
5.2.1 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 does nothing. It can be
used to reset any inactivity autologout timer on the server.
Example: C: a002 NOOP
S: a002 OK "NOOP completed"
5.2.2 LANG Command
Arguments: list of language preferences
Data: intermediate response: LANG
Result: OK - lang completed
NO - no matching language available
BAD - command unknown or arguments invalid
One or more arguments are supplied to indicate the client's
preferred languages [LANG-TAGS] for error messages. The server
will match each client preference in order against its internal
table of available error string languages. For a client
preference to match a server language, the client's language tag
MUST be a prefix of the server's tag and match up to a "-" or the
end of string. If a match is found, the server returns an
intermediate LANG response and an OK response. The LANG response
indicates the actual language selected.
Earhart [Page 12]
Internet DRAFT Access Protocol January 1998
If no LANG command is issued, all error text strings MUST be in
the registered language "i-default" [CHARSET-LANG-POLICY],
intended for an international audience.
Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk"
S: A003 LANG "fr-ca"
S: A003 OK "Bonjour"
5.2.3 LANG Intermediate Response
Data: language for error responses
The LANG response indicates the language which will be used for
responses (in the ABNF, the final "quoted" element of resp-body).
5.2.4 LOGOUT Command
Arguments: none
Data: mandatory untagged response: BYE
Result: OK - logout completed
BAD - command unknown or arguments invalid
The LOGOUT command informs the server that the client is done with
the session. The server must send a BYE untagged response before
the (tagged) OK response, and then close the network connection.
Example: C: A023 LOGOUT
S: * BYE "Server logging out"
S: A023 OK "LOGOUT completed"
(Server and client then close the connection)
5.2.5. OK Response
Data: optional response code
human-readable text
The OK response indicates an information message from the server.
When tagged, it indicates successful completion of the associated
command. The human-readable text may be presented to the user as
an information message. The untagged form indicates an
information-only message; the nature of the information may be
Earhart [Page 13]
Internet DRAFT Access Protocol January 1998
indicated by a response code.
Example: S: * OK "Main disk is back on-line"
5.2.6. NO Response
Data: optional response code
human-readable text
The NO response indicates an operational error message from the
server. When tagged, it indicates unsuccessful completion of the
associated command. The untagged form indicates a warning; the
command may still complete successfully. The human-readable text
describes the condition.
Example: C: A222 AUTHENTICATE "FOOBAR"
S: A222 NO "Unknown SASL mechanism"
5.2.7 BAD Response
Data: optional response code
human-readable text
The BAD response indicates an error message from the server. When
tagged, it reports a protocol-level error in the client's command;
the tag indicates the command that caused the error. The untagged
form indicates a protocol-level error for which the associated
command can not be determined; it may also indicate an internal
server failure. The human-readable text describes the condition.
Example: C: ...empty line...
S: * BAD "Empty command line"
C: A443 BLURDYBLOOP
S: A443 BAD "Unknown command"
C: A444 NOOP Hello
S: A444 BAD "invalid arguments"
5.2.8. BYE Untagged Response
Data: optional response code
human-readable text
The untagged BYE response indicates that the server is about to
close the connection. The human-readable text may be displayed to
the user in a status report by the client. The BYE response may
Earhart [Page 14]
Internet DRAFT Access Protocol January 1998
be sent as part of a normal logout sequence, or as a panic
shutdown announcement by the server. It SHOULD also used by
server implementations as an announcement of an inactivity
autologout.
This response is also used as one of two possible greetings at
session startup. As a greeting, it indicates that the server is
not willing to accept a session from this client.
Example: S: * BYE "Autologout; idle for too long"
5.2.9. ALERT Untagged Response
Data: optional response code
human-readable text
The human-readable text contains a special human generated alert
message that MUST be presented to the user in a fashion that calls
the user's attention to the message. This is intended to be used
for vital messages from the server administrator to the user, such
as a warning that the server will soon be shut down for
maintenance.
Example: S: * ALERT "This server will be shut down in 10 minutes
for system maintenance."
5.3. Non-Authenticated State
In non-authenticated state, the AUTHENTICATE command establishes
authentication and enters authenticated state. The AUTHENTICATE
command provides a general mechanism for a variety of authentication
techniques.
Server implementations may allow non-authenticated access to certain
information. The convention is to use an AUTHENTICATE command with
the SASL ANONYMOUS mechanism [ANON].
Once authenticated (including as anonymous), it is not possible to
re-enter non-authenticated state.
In addition to the universal commands (NOOP and LOGOUT), the only
command valid in non-authenticated state is AUTHENTICATE.
5.3.1 AUTHENTICATE Command
Earhart [Page 15]
Internet DRAFT Access Protocol January 1998
Arguments: SASL mechanism name
optional initial response
Data: continuation data may be requested
Result: OK - authenticate completed, now in authenticated state
NO - authenticate failure: unsupported authentication
mechanism, credentials rejected
BAD - command unknown or arguments invalid,
authentication exchange cancelled
The AUTHENTICATE command indicates a SASL [SASL] authentication
mechanism to the server. If the server supports the requested
authentication mechanism, it performs an authentication protocol
exchange to authenticate and identify the user. Optionally, it
also negotiates a security layer for subsequent protocol
interactions. If the requested authentication mechanism is not
supported, 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
command 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
argument 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
"ap".
If a security layer is negotiated through the SASL authentication
exchange, it takes effect immediately following the CRLF that
concludes the authentication exchange for the client, and the CRLF
of the tagged OK response for the server.
Earhart [Page 16]
Internet DRAFT Access Protocol January 1998
All AP implementations MUST implement the CRAM-MD5 SASL mechanism
[CRAM-MD5], although 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: * OK IMPLEMENTATION ("Blorfysoft v3.5")
SASL ("CRAM-MD4" "KERBEROS_V4")
C: A001 AUTHENTICATE "CRAM-MD5"
S: + "1896.697170952@postoffice.reston.mci.net>"
C: "tim b913a602c7eda7a495b4e6e7334d3890"
S: A001 OK "CRAM-MD5 authentication successful"
Note: the line breaks in the first client answer are for
editorial clarity and are not in real authenticators.
5.3. Authenticated State
In the authenticated state, the universal commands (NOOP and LOGOUT)
are valid, in addition to any commands defined by protocols that use
AP as their foundation.
6. Design Philosophy
Protocols layered on top of AP SHOULD define a set of commands to be
valid in the authenticated state. In addition, protocols MAY define
an atom to be returned in the initial AP greeting, possibly allowing
multiple protocols to be used over the same connection.
Ideally, protocols should limit themselves as much as possible to a
simple, uncomplicated suite of commands that relate to each other.
Where possible, protocols should be broken up into orthogonal
components, such that the components may be reused in other
protocols.
Example: Instead of defining an advisory lock mechanism, advisory
locking should be split into a seperate extension, useable
by whatever protocols happen to require it.
Quota management is another set of commands that could be
written as an extension and made available to all protocols
Earhart [Page 17]
Internet DRAFT Access Protocol January 1998
that involve quotas.
New commands and responses SHOULD only be defined for the
Authenticated state.
Responses to commands SHOULD be tagged. This is essential for
allowing multiple commands to execute simultaneously, and experience
shows that this leads to much simpler implementations for both
clients and servers.
Where textual data is exchanged, protocols SHOULD use UTF8 [UTF8]
whenever possible, for internationalization.
New command completion responses MUST NOT be defined -- every command
MUST be completed by an "OK", "NO", or "BAD" response.
7. Formal Syntax
The following syntax specification uses the augmented Backus-Naur
Form (BNF) 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.
Protocols based on AP should refer to this formal syntax, and augment
selected parts via the ABNF "=/" operator, as indicated in the
comments.
The client produces a sequence of octets matching "command-client";
the server consumes these, and returns a sequence of octets matching
"response-server".
Protocols using AP MAY augment "capability" (subject to the
requirement that "capability" MUST match "capability-generic"),
"command" (subject to the requirement that "command" MUST match
"command-generic"), "response" (subject to the requirement that
"response" MUST match "response-generic"), "resp-code" (subject to
the requirement that "resp-code" MUST match "resp-code-generic"), or
"status-response" (subject to the requirement that "status-response"
MUST match "status-response-generic"). Other syntax elements SHOULD
NOT be redefined.
For readability, rules which MAY be augmented are defined using the
Earhart [Page 18]
Internet DRAFT Access Protocol January 1998
"=/" operator; all other rules are defined using "=".
A number of symbols are defined solely for use by protocols using AP.
ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E
; Any CHAR except ATOM-SPECIALS
ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS
DIGIT-NZ = %x31-39
; 1-9
QUOTED-CHAR = SAFE-UTF8-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
SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 /
UTF8-5 / UTF8-6
TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E
; Any ATOM-CHAR except "*" or "+"
TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS
UTF8-1 = %x80-BF
UTF8-2 = %xC0-DF UTF8-1
UTF8-3 = %xE0-EF 2UTF8-1
UTF8-4 = %xF0-F7 3UTF8-1
UTF8-5 = %xF8-FB 4UTF8-1
UTF8-6 = %xFC-FD 5UTF8-1
UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF
argument = atom
/ string
/ number
/ "(" [argument *(SP argument)] ")"
atom = 1*1024ATOM-CHAR
Earhart [Page 19]
Internet DRAFT Access Protocol January 1998
auth-type = <"> auth-type-name <">
auth-type-name = iana-token
; As defined in [SASL]
capability =/ "IMPLEMENTATION" SP "(" quoted ")"
capability =/ "SASL" SP "(" auth-type *(SP auth-type) ")"
; Other capabilities MAY be defined by protocols using AP,
; but MUST syntactically match capability-generic
capability-arg = atom
/ quoted
/ "(" [capability-arg *(SP capability-arg)] ")"
capability-generic = atom [SP "(" [capability-arg] ")"]
command-client = tag SP command CRLF
command =/ "NOOP"
command =/ "LOGOUT"
command =/ "AUTHENTICATE" SP auth-type
[SP string] *(CRLF string)
; Other commands MAY be defined by protocols using AP,
; but MUST syntactically match command-generic
command-generic = atom *(SP argument)
iana-token = atom
; MUST be registered with IANA
literal = "{" number [ "+" ] "}" CRLF *OCTET
; The number represents the number of octets
literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR
; The number represents the number of octets,
; not the number of characters
nil = "NIL"
number = 1*DIGIT
nz-number = DIGIT-NZ *DIGIT
Earhart [Page 20]
Internet DRAFT Access Protocol January 1998
quoted = <"> *QUOTED-CHAR <">
resp-argument = atom
/ quoted
/ number
/ "(" [resp-argument *(SP resp-argument)] ")"
resp-body = SP ["(" resp-code ")" SP] quoted
resp-code =/ "AUTH-TOO-WEAK"
resp-code =/ "ENCRYPT-NEEDED"
resp-code =/ "SASL"
resp-code =/ "TRANSITION-NEEDED"
resp-code =/ "TRYLATER"
; Other resp-codes MAY be defined by protocols using AP,
; but MUST syntactically match resp-code-generic
resp-code-generic = atom *(SP resp-argument)
response =/ "AP" *(SP capability)
response =/ status-response
; Other responses MAY be defined by protocols using AP,
; but MUST syntactically match response-generic
response-generic = atom *(SP argument)
response-server = (tag / "*") response CRLF
status-response =/ "OK" resp-body
status-response =/ "NO" resp-body
status-response =/ "BAD" resp-body
status-response =/ "BYE" resp-body
status-response =/ "ALERT" resp-body
; Other status-responses MAY be defined by protocols using AP,
; but MUST syntactically match status-response-generic
Earhart [Page 21]
Internet DRAFT Access Protocol January 1998
status-response-generic = atom resp-body
string = quoted / literal
string-utf8 = quoted / literal-utf8
tag = 1*32TAG-CHAR
8. Security Considerations
AP protocol transactions are sent in the clear over the network
unless some form of privacy protection is negotiated in the
AUTHENTICATE command.
AP's security is defined by [SASL], and thus has the same security
considerations.
9. References
[ABNF] Crocker, D., and Overell, P., "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
<url:ftp://ds.internic.net/rfc/rfc2234.txt>
[ACAP] Myers, J., and Newman, C., "Application Configuration Access
Protocol (ACAP)", RFC 2244, November 1997.
<url:ftp://ds.internic.net/rfc/rfc2244.txt>
[ANON] Newman, C., "Anonymous SASL Mechanism", RFC 2245, November
1997.
<url:ftp://ds.internic.net/rfc/rfc2245.txt>
[CHARSET-LANG-POLICY] Alvestrand, H., "IETF Policy on Character Sets
and Languages", work in progress.
[COMPARATOR] Newman, C., Myers, J., "Comparators", work in progress.
[CRAM-MD5] Klensin, J., Catoe, R., and Krumviede, P., "IMAP/POP
AUTHorize Extension for Simple Challenge/Response", RFC 2195,
September 1997.
<url:ftp://ds.internic.net/rfc/rfc2195.txt>
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version
Earhart [Page 22]
Internet DRAFT Access Protocol January 1998
4rev1", RFC 2060, December 1996.
<url:ftp://ds.internic.net/rfc/rfc2060.txt>
[LANG-TAGS] Alvestrand, H., "Tags for the Identification of
Languages", RFC 1766, March 1995.
<url:ftp://ds.internic.net/rfc/rfc1766.txt>
[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
<url:ftp://ds.internic.net/rfc/rfc2222.txt>
[UTF8] Yergeau, F., "UTF-8, a transformation format of Unicode and
ISO 10646", RFC 2044, October 1996.
<url:ftp://ds.internic.net/rfc/rfc2044.txt>
10. Full Copyright Statement
Copyright (C) The Internet Society 1998. All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation 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.
Earhart [Page 23]
Internet DRAFT Access Protocol January 1998
11. Author's Address
Robert H. Earhart
Carnegie Mellon
5000 Forbes Ave.
Pittsburgh PA, 15213-3890
Email: earhart+@cmu.edu
Expires July 1998
Earhart [Page 24]
--============_-1294479272==_============--