james-server-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@apache.org
Subject svn commit: r534834 [2/5] - in /james/mailet: ./ lib/ src/ src/main/ src/main/java/ src/site/ src/site/resources/ src/site/resources/images/ src/site/xdoc/ src/site/xdoc/images/ src/site/xdoc/stylesheets/ src/test/ src/test/java/ src/test/resources/
Date Thu, 03 May 2007 12:59:55 GMT
Added: james/mailet/src/site/resources/rfc2244.txt
URL: http://svn.apache.org/viewvc/james/mailet/src/site/resources/rfc2244.txt?view=auto&rev=534834
==============================================================================
--- james/mailet/src/site/resources/rfc2244.txt (added)
+++ james/mailet/src/site/resources/rfc2244.txt Thu May  3 05:59:54 2007
@@ -0,0 +1,4034 @@
+
+
+
+
+
+Network Working Group                                          C. Newman
+Request for Comments: 2244                                      Innosoft
+Category: Standards Track                                    J. G. Myers
+                                                                Netscape
+                                                           November 1997
+
+
+           ACAP -- Application Configuration Access Protocol
+
+
+Status of this Memo
+
+   This document specifies an Internet standards track protocol for the
+   Internet community, and requests discussion and suggestions for
+   improvements.  Please refer to the current edition of the "Internet
+   Official Protocol Standards" (STD 1) for the standardization state
+   and status of this protocol.  Distribution of this memo is unlimited.
+
+Copyright Notice
+
+   Copyright (C) The Internet Society 1997.  All Rights Reserved.
+
+Abstract
+
+   The Application Configuration Access Protocol (ACAP) is designed to
+   support remote storage and access of program option, configuration
+   and preference information.  The data store model is designed to
+   allow a client relatively simple access to interesting data, to allow
+   new information to be easily added without server re-configuration,
+   and to promote the use of both standardized data and custom or
+   proprietary data.  Key features include "inheritance" which can be
+   used to manage default values for configuration settings and access
+   control lists which allow interesting personal information to be
+   shared and group information to be restricted.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page i]
+
+RFC 2244                          ACAP                     November 1997
+
+
+
+
+
+                           Table of Contents
+
+
+
+Status of this Memo ...............................................    i
+Copyright Notice ..................................................    i
+Abstract ..........................................................    i
+ACAP Protocol Specification .......................................    1
+1.       Introduction .............................................    1
+1.1.     Conventions Used in this Document ........................    1
+1.2.     ACAP Data Model ..........................................    1
+1.3.     ACAP Design Goals ........................................    1
+1.4.     Validation ...............................................    2
+1.5.     Definitions ..............................................    2
+1.6.     ACAP Command Overview ....................................    4
+2.       Protocol Framework .......................................    4
+2.1.     Link Level ...............................................    4
+2.2.     Commands and Responses ...................................    4
+2.2.1.   Client Protocol Sender and Server Protocol Receiver ......    4
+2.2.2.   Server Protocol Sender and Client Protocol Receiver ......    5
+2.3.     Server States ............................................    6
+2.3.1.   Non-Authenticated State ..................................    6
+2.3.2.   Authenticated State ......................................    6
+2.3.3.   Logout State .............................................    6
+2.4.     Operational Considerations ...............................    7
+2.4.1.   Untagged Status Updates ..................................    7
+2.4.2.   Response when No Command in Progress .....................    7
+2.4.3.   Auto-logout Timer ........................................    7
+2.4.4.   Multiple Commands in Progress ............................    8
+2.5.     Server Command Continuation Request ......................    8
+2.6.     Data Formats .............................................    8
+2.6.1.   Atom .....................................................    9
+2.6.2.   Number ...................................................    9
+2.6.3.   String ...................................................    9
+2.6.3.1. 8-bit and Binary Strings .................................   10
+2.6.4.   Parenthesized List .......................................   10
+2.6.5.   NIL ......................................................   10
+3.       Protocol Elements ........................................   10
+3.1.     Entries and Attributes ...................................   10
+3.1.1.   Predefined Attributes ....................................   11
+3.1.2.   Attribute Metadata .......................................   12
+3.2.     ACAP URL scheme ..........................................   13
+3.2.1.   ACAP URL User Name and Authentication Mechanism ..........   13
+3.2.2.   Relative ACAP URLs .......................................   14
+3.3.     Contexts .................................................   14
+
+
+
+Newman & Myers              Standards Track                    [Page ii]
+
+RFC 2244                          ACAP                     November 1997
+
+
+3.4.     Comparators ..............................................   15
+3.5.     Access Control Lists (ACLs) ..............................   17
+3.6.     Server Response Codes ....................................   18
+4.       Namespace Conventions ....................................   21
+4.1.     Dataset Namespace ........................................   21
+4.2.     Attribute Namespace ......................................   21
+4.3.     Formal Syntax for Dataset and Attribute Namespace ........   22
+5.       Dataset Management .......................................   23
+5.1.     Dataset Inheritance ......................................   23
+5.2.     Dataset Attributes .......................................   24
+5.3.     Dataset Creation .........................................   25
+5.4.     Dataset Class Capabilities ...............................   25
+5.5.     Dataset Quotas ...........................................   26
+6.       Command and Response Specifications ......................   26
+6.1.     Initial Connection .......................................   26
+6.1.1.   ACAP Untagged Response ...................................   26
+6.2.     Any State ................................................   27
+6.2.1.   NOOP Command .............................................   27
+6.2.2.   LANG Command .............................................   28
+6.2.3.   LANG Intermediate Response ...............................   28
+6.2.4.   LOGOUT Command ...........................................   29
+6.2.5.   OK Response ..............................................   29
+6.2.6.   NO Response ..............................................   29
+6.2.7.   BAD Response .............................................   30
+6.2.8.   BYE Untagged Response ....................................   30
+6.2.9.   ALERT Untagged Response ..................................   31
+6.3.     Non-Authenticated State ..................................   31
+6.3.1.   AUTHENTICATE Command .....................................   31
+6.4.     Searching ................................................   33
+6.4.1.   SEARCH Command ...........................................   33
+6.4.2.   ENTRY Intermediate Response ..............................   37
+6.4.3.   MODTIME Intermediate Response ............................   38
+6.4.4.   REFER Intermediate Response ..............................   38
+6.4.5.   Search Examples ..........................................   38
+6.5.     Contexts .................................................   39
+6.5.1.   FREECONTEXT Command ......................................   39
+6.5.2.   UPDATECONTEXT Command ....................................   40
+6.5.3.   ADDTO Untagged Response ..................................   40
+6.5.4.   REMOVEFROM Untagged Response .............................   41
+6.5.5.   CHANGE Untagged Response .................................   41
+6.5.6.   MODTIME Untagged Response ................................   42
+6.6.     Dataset modification .....................................   42
+6.6.1.   STORE Command ............................................   42
+6.6.2.   DELETEDSINCE Command .....................................   45
+6.6.3.   DELETED Intermediate Response ............................   45
+6.7.     Access Control List Commands .............................   45
+6.7.1.   SETACL Command ...........................................   46
+6.7.2.   DELETEACL Command ........................................   46
+
+
+
+Newman & Myers              Standards Track                   [Page iii]
+
+RFC 2244                          ACAP                     November 1997
+
+
+6.7.3.   MYRIGHTS Command .........................................   47
+6.7.4.   MYRIGHTS Intermediate Response ...........................   47
+6.7.5.   LISTRIGHTS Command .......................................   47
+6.7.6.   LISTRIGHTS Intermediate Response .........................   48
+6.8.     Quotas ...................................................   48
+6.8.1.   GETQUOTA Command .........................................   48
+6.8.3.   QUOTA Untagged Response ..................................   49
+6.9.     Extensions ...............................................   49
+7.       Registration Procedures ..................................   49
+7.1.     ACAP Capabilities ........................................   50
+7.2.     ACAP Response Codes ......................................   50
+7.3.     Dataset Classes ..........................................   51
+7.4.     Vendor Subtree ...........................................   51
+8.       Formal Syntax ............................................   52
+9.       Multi-lingual Considerations .............................   61
+10.      Security Considerations ..................................   62
+11.      Acknowledgments ..........................................   63
+12.      Authors' Addresses .......................................   63
+Appendices ........................................................   64
+A.       References ...............................................   64
+B.       ACAP Keyword Index .......................................   66
+C.       Full Copyright Statement
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page iv]
+RFC 2244                          ACAP                     November 1997
+
+
+ACAP Protocol Specification
+
+1.       Introduction
+
+1.1.     Conventions Used in this Document
+
+   In examples, "C:" and "S:" indicate lines sent by the client and
+   server respectively.  If such lines are wrapped without a new "C:" or
+   "S:" label, then the wrapping is for editorial clarity and is not
+   part of the command.
+
+   The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
+   and "MAY" in this document are to be interpreted as described in "Key
+   words for use in RFCs to Indicate Requirement Levels" [KEYWORDS].
+
+1.2.     ACAP Data Model
+
+   An ACAP server exports a hierarchical tree of entries.  Each level of
+   the tree is called a dataset, and each dataset is made up of a list
+   of entries.  Each entry has a unique name and may contain any number
+   of named attributes.  Each attribute within an entry may be single
+   valued or multi-valued and may have associated metadata to assist
+   access and interpretation of the value.
+
+   The rules with which a client interprets the data within a portion of
+   ACAP's tree of entries are called a dataset class.
+
+1.3.     ACAP Design Goals
+
+   ACAP's primary purpose is to allow users access to their
+   configuration data from multiple network-connected computers.  Users
+   can then sit down in front of any network-connected computer, run any
+   ACAP-enabled application and have access to their own configuration
+   data.  Because it is hoped that many applications will become ACAP-
+   enabled, client simplicity was preferred to server or protocol
+   simplicity whenever reasonable.
+
+   ACAP is designed to be easily manageable.  For this reason, it
+   includes "inheritance" which allows one dataset to inherit default
+   attributes from another dataset.  In addition, access control lists
+   are included to permit delegation of management and quotas are
+   included to control storage.  Finally, an ACAP server which is
+   conformant to this base specification should be able to support most
+   dataset classes defined in the future without requiring a server
+   reconfiguration or upgrade.
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 1]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   ACAP is designed to operate well with a client that only has
+   intermittent access to an ACAP server.  For this reason, each entry
+   has a server maintained modification time so that the client may
+   detect changes.  In addition, the client may ask the server for a
+   list of entries which have been removed since it last accessed the
+   server.
+
+   ACAP presumes that a dataset may be potentially large and/or the
+   client's network connection may be slow, and thus offers server
+   sorting, selective fetching and change notification for entries
+   within a dataset.
+
+   As required for most Internet protocols, security, scalability and
+   internationalization were important design goals.
+
+   Given these design goals, an attempt was made to keep ACAP as simple
+   as possible.  It is a traditional Internet text based protocol which
+   massively simplifies protocol debugging.  It was designed based on
+   the successful IMAP [IMAP4] protocol framework, with a few
+   refinements.
+
+1.4.     Validation
+
+   By default, any value may be stored in any attribute for which the
+   user has appropriate permission and quota.  This rule is necessary to
+   allow the addition of new simple dataset classes without
+   reconfiguring or upgrading the server.
+
+   In some cases, such as when the value has special meaning to the
+   server, it is useful to have the server enforce validation by
+   returning the INVALID response code to a STORE command. These cases
+   MUST be explicitly identified in the dataset class specification
+   which SHOULD include specific fixed rules for validation.  Since a
+   given ACAP server may be unaware of any particular dataset class
+   specification, clients MUST NOT depend on the presence of enforced
+   validation on the server.
+
+1.5.     Definitions
+
+
+   access control list (ACL)
+        A set of identifier, rights pairs associated with an object.  An
+        ACL is used to determine which operations a user is permitted to
+        perform on that object.  See section 3.5.
+
+   attribute
+        A named value within an entry.  See section 3.1.
+
+
+
+
+Newman & Myers              Standards Track                     [Page 2]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   comparator
+        A named function which can be used to perform one or more of
+        three comparison operations: ordering, equality and substring
+        matching.  See section 3.4.
+
+   context
+        An ordered subset of entries in a dataset, created by a SEARCH
+        command with a MAKECONTEXT modifier.  See section 3.3.
+
+   dataset
+        One level of hierarchy in ACAP's tree of entries.
+
+   dataset class specification
+        The rules which allow a client to interpret the data within a
+        portion of ACAP's tree of entries.
+
+   entry
+        A set of attributes with a unique entry name.  See section 3.1.
+
+   metadata
+        Information describing an attribute, its value and any access
+        controls associated with that attribute.  See section 3.1.2.
+
+   NIL  This represents the non-existence of a particular data item.
+
+   NUL  A control character encoded as 0 in US-ASCII [US-ASCII].
+
+   octet
+        An 8-bit value.  On most modern computer systems, an octet is
+        one byte.
+
+   SASL Simple Authentication and Security Layer [SASL].
+
+   UTC  Universal Coordinated Time as maintained by the Bureau
+        International des Poids et Mesures (BIPM).
+
+   UTF-8
+        An 8-bit transformation format of the Universal Character Set
+        [UTF8].  Note that an incompatible change was made to the coded
+        character set referenced by [UTF8], so for the purpose of this
+        document, UTF-8 refers to the UTF-8 encoding as defined by
+        version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646]
+        including amendments one through seven.
+
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 3]
+
+RFC 2244                          ACAP                     November 1997
+
+
+1.6.     ACAP Command Overview
+
+   The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic
+   protocol services.  The SEARCH command is used to select, sort, fetch
+   and monitor changes to attribute values and metadata.  The
+   UPDATECONTEXT and FREECONTEXT commands are also used to assist in
+   monitoring changes in attribute values and metadata.  The STORE
+   command is used to add, modify and delete entries and attributes.
+   The DELETEDSINCE command is used to assist a client in
+   re-synchronizing a cache with the server.  The GETQUOTA, SETACL,
+   DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine
+   storage quotas and examine or modify access permissions.
+
+2.       Protocol Framework
+
+2.1.     Link Level
+
+   The ACAP protocol assumes a reliable data stream such as provided by
+   TCP.  When TCP is used, an ACAP server listens on port 674.
+
+2.2.     Commands and Responses
+
+   An ACAP 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.
+
+   ACAP is a text-based line-oriented protocol.  In general,
+   interactions transmitted by clients and servers are in the form of
+   lines; that is, sequences of characters that end with a CRLF.  The
+   protocol receiver of an ACAP client or server is either reading a
+   line, or is reading a sequence of octets with a known count (a
+   literal) followed by a line.  Both clients and servers must be
+   capable of handling lines of arbitrary length.
+
+2.2.1.   Client Protocol Sender and Server Protocol Receiver
+
+   The client command begins an operation.  Each client command is
+   prefixed with a identifier (an alphanumeric string of no more than 32
+   characters, e.g., A0001, A0002, etc.) called a "tag".  A different
+   tag SHOULD be 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
+   2.6.3); in the other case, the command arguments require server
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 4]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   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 a
+        command, it sends a BAD completion response with tag
+        matching the 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 ACAP server reads a command line from the client, parses the
+   command and its arguments, and transmits server data and a server
+   command completion result.
+
+2.2.2.   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.
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 5]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   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.
+
+   The protocol receiver of an ACAP 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.
+
+2.3.     Server States
+
+   An ACAP server is in one of 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 will respond with a BAD command
+   completion result.
+
+2.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.
+
+2.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.
+
+2.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.
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 6]
+
+RFC 2244                          ACAP                     November 1997
+
+
+            +--------------------------------------+
+            |initial connection and server greeting|
+            +--------------------------------------+
+                      || (1)                  || (2)
+                      VV                      ||
+            +-----------------+               ||
+            |non-authenticated|               ||
+            +-----------------+               ||
+             || (4)      || (3)               ||
+             ||          VV                   ||
+             ||          +----------------+   ||
+             ||          | authenticated  |   ||
+             ||          +----------------+   ||
+             ||            || (4)             ||
+             VV            VV                 VV
+            +--------------------------------------+
+            |     logout and close connection      |
+            +--------------------------------------+
+
+         (1) connection (ACAP greeting)
+         (2) rejected connection (BYE greeting)
+         (3) successful AUTHENTICATE command
+         (4) LOGOUT command, server shutdown, or connection closed
+
+2.4.     Operational Considerations
+
+2.4.1.   Untagged Status Updates
+
+   At any time, a server can send data that the client did not request.
+
+2.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.
+
+2.4.3.   Auto-logout Timer
+
+   If a server has an inactivity auto-logout timer, that timer MUST be
+   of at least 30 minutes duration.  The receipt of ANY command from the
+   client during that interval MUST suffice to reset the auto-logout
+   timer.
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 7]
+
+RFC 2244                          ACAP                     November 1997
+
+
+2.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, unless an ambiguity would result
+   because of a command that would affect the results of other commands.
+   If there is such an ambiguity, the server executes commands to
+   completion in the order given by the client.
+
+2.5.     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.
+
+   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 (see section 2.6.3).
+
+   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
+   are any additional command arguments the literal octets are followed
+   by a space and those arguments.
+
+   Example:    C: A099 FREECONTEXT {10}
+               S: + "Ready for additional command text"
+               C: FRED
+               C: FOOB
+               S: A099 OK "FREECONTEXT completed"
+               C: A044 BLURDYBLOOP {102856}
+               S: A044 BAD "No such command as 'BLURDYBLOOP'"
+
+
+2.6.     Data Formats
+
+   ACAP uses textual commands and responses.  Data in ACAP can be in one
+   of five forms: atom, number, string, parenthesized list or NIL.
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                     [Page 8]
+
+RFC 2244                          ACAP                     November 1997
+
+
+2.6.1.   Atom
+
+   An atom consists of one to 1024 non-special characters.  It must
+   begin with a letter.  Atoms are used for protocol keywords.
+
+2.6.2.   Number
+
+   A number consists of one or more digit characters, and represents a
+   numeric value.  Numbers are restricted to the range of an unsigned
+   32-bit integer: 0 < number < 4,294,967,296.
+
+2.6.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 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 NUL,
+   CR and LF, with double quote (<">) characters at each end.
+
+   The empty string is represented 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 request.
+
+
+
+Newman & Myers              Standards Track                     [Page 9]
+
+RFC 2244                          ACAP                     November 1997
+
+
+2.6.3.1. 8-bit and Binary Strings
+
+   Most strings in ACAP are restricted to UTF-8 characters and may not
+   contain NUL octets.  Attribute values MAY contain any octets
+   including NUL.
+
+2.6.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.
+
+2.6.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 ().
+
+3.       Protocol Elements
+
+   This section defines data formats and other protocol elements used
+   throughout the ACAP protocol.
+
+3.1.     Entries and Attributes
+
+   Within a dataset, each entry name is made up of zero or more UTF-8
+   characters other than slash ("/").  A slash separated list of
+   entries, one at each level of the hierarchy, forms the full path to
+   an entry.
+
+   Each entry is made up of a set of attributes.  Each attribute has a
+   hierarchical name in UTF-8, with each component of the name separated
+   by a period (".").
+
+   The value of an attribute is either single or multi-valued.  A single
+   value is NIL (has no value), or a string of zero or more octets.  A
+   multi-value is a list of zero or more strings, each of zero or more
+   octets.
+
+   Attribute names are not permitted to contain asterisk ("*") or
+   percent ("%") and MUST be valid UTF-8 strings which do not contain
+   NUL.  Invalid attribute names result in a BAD response.  Entry names
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 10]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   are not permitted to begin with "." or contain slash ("/") and MUST
+   be valid UTF-8 strings which do not contain NUL.  Invalid entry names
+   in the entry field of a command result in a BAD response.
+
+   Use of non-visible UTF-8 characters in attribute and entry names is
+   discouraged.
+
+3.1.1.   Predefined Attributes
+
+   Attribute names which do not contain a dot (".") are reserved for
+   standardized attributes which have meaning in any dataset.  The
+   following attributes are defined by the ACAP protocol.
+
+   entry
+        Contains the name of the entry.  MUST be single valued.
+        Attempts to use illegal or multi-valued values for the entry
+        attribute are protocol errors and MUST result in a BAD
+        completion response.  This is a special case.
+
+   modtime
+        Contains the date and time any read-write metadata in the entry
+        was last modified.  This value MUST be in UTC, MUST be
+        automatically updated by the server.
+
+        The value consists of 14 or more US-ASCII digits.  The first
+        four indicate the year, the next two indicate the month, the
+        next two indicate the day of month, the next two indicate the
+        hour (0 - 23), the next two indicate the minute, and the next
+        two indicate the second.  Any further digits indicate fractions
+        of a second.
+
+        The time, particularly fractions of a second, need not be
+        accurate.  It is REQUIRED, however, that any two entries in a
+        dataset changed by successive modifications have strictly
+        ascending modtime values.  In addition, each STORE command
+        within a dataset (including simultaneous stores from different
+        connections) MUST use different modtime values.
+
+        This attribute has enforced validation, so any attempt to STORE
+        a value in this attribute MAY result in a NO response with an
+        INVALID response code.
+
+   subdataset
+        If this attribute is set, it indicates the existence of a sub-
+        dataset of this entry.
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 11]
+
+RFC 2244                          ACAP                     November 1997
+
+
+        The value consists of a list of relative ACAP URLs (see section
+        3.2) which may be used to locate the sub-dataset.  The base URL
+        is the full path to the entry followed by a slash ("/").  The
+        value "." indicates a subdataset is located directly under this
+        one.  Multiple values indicate replicated copies of the
+        subdataset.
+
+        For example, if the dataset "/folder/site/" has an entry
+        "public-folder" with a subdataset attribute of ".", then there
+        exists a dataset "/folder/site/public-folder/".  If the value of
+        the subdataset attribute was instead
+        "//other.acap.domain//folder/site/public-folder/", that would
+        indicate the dataset is actually located on a different ACAP
+        server.
+
+        A dataset can be created by storing a "subdataset" attribute
+        including ".", and a sub-hierarchy of datasets is deleted by
+        storing a NIL value to the "subdataset" attribute on the entry
+        in the parent dataset.
+
+        This attribute has enforced syntax validation.  Specifically, if
+        an attempt is made to STORE a non-list value (other than NIL),
+        an empty list, or one of the values does not follow the URL
+        syntax rules [BASIC-URL, REL-URL], then this will result in a NO
+        response with an INVALID response code.
+
+3.1.2.   Attribute Metadata
+
+   Each attribute is made up of metadata items which describe that
+   attribute, its value and any associated access controls.  Metadata
+   items may be either read-only, in which case the client is never
+   permitted to modify the item, or read-write, in which case the client
+   may modify the item if the access control list (ACL) permits.
+
+   The following metadata items are defined in this specification:
+
+   acl    The access control list for the attribute, if one exists.  If
+          the attribute does not have an ACL, NIL is returned.
+          Read-write.  See section 3.5 for the contents of an ACL.
+
+   attribute
+          The attribute name.  Read-only.
+
+   myrights
+          The set of rights that the client has to the attribute.
+          Read-only.  See section 3.5 for the possible rights.
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 12]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   size   This is the length of the value.  In the case of a
+          multi-value, this is a list of lengths for each of the values.
+          Read-only.
+
+   value  The value.  For a multi-value, this is a list of single
+          values.  Read-write.
+
+   Additional items of metadata may be defined in extensions to this
+   protocol.  Servers MUST respond to unrecognized metadata by returning
+   a BAD command completion result.
+
+3.2.     ACAP URL scheme
+
+   ACAP URLs are used within the ACAP protocol for the "subdataset"
+   attribute, referrals and inheritance.  They provide a convenient
+   syntax for referring to other ACAP datasets.  The ACAP URL follows
+   the common Internet scheme syntax as defined in [BASIC-URL] except
+   that plaintext passwords are not permitted.  If :<port> is omitted,
+   the port defaults to 674.
+
+   An ACAP URL has the following general form:
+
+   url-acap  = "acap://" url-server "/" url-enc-entry [url-filter]
+               [url-extension]
+
+   The <url-server> element includes the hostname, and optional user
+   name, authentication mechanism and port number.  The <url-enc-entry>
+   element contains the name of an entry path encoded according to the
+   rules in [BASIC-URL].
+
+   The <url-filter> element is an optional list of interesting attribute
+   names.  If omitted, the URL refers to all attributes of the named
+   entry.  The <url-extension> element is reserved for extensions to
+   this URL scheme.
+
+   Note that unsafe or reserved characters such as " " or "?" MUST be
+   hex encoded as described in the URL specification [BASIC-URL].  Hex
+   encoded octets are interpreted according to UTF-8 [UTF8].
+
+3.2.1.   ACAP URL User Name and Authentication Mechanism
+
+   A user name and/or authentication mechanism may be supplied.  They
+   are used in the "AUTHENTICATE" command after making the connection to
+   the ACAP server.  If no user name or authentication mechanism is
+   supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by
+   default.  If an authentication mechanism is supplied without a user
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 13]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   name, then one SHOULD be obtained from the specified mechanism or
+   requested from the user as appropriate.  If a user name is supplied
+   without an authentication mechanism then ";AUTH=*" is assumed.
+
+   The ";AUTH=" authentication parameter is interpreted as described in
+   the IMAP URL Scheme [IMAP-URL].
+
+   Note that if unsafe or reserved characters such as " " or ";" are
+   present in the user name or authentication mechanism, they MUST be
+   encoded as described in the URL specification [BASIC-URL].
+
+3.2.2.   Relative ACAP URLs
+
+   Because ACAP uses "/" as the hierarchy separator for dataset paths,
+   it works well with the relative URL rules defined in the relative URL
+   specification [REL-URL].
+
+   The <aauth> grammar element is considered part of the user name for
+   purposes of resolving relative ACAP URLs.
+
+   The base URL for a relative URL stored in an attribute's value is
+   formed by taking the path to the dataset containing that attribute,
+   appending a "/" followed by the entry name of the entry containing
+   that attribute followed by "/".
+
+3.3.     Contexts
+
+   A context is subset of entries in a dataset or datasets, created by a
+   SEARCH command with a MAKECONTEXT modifier.  Context names are
+   client-generated strings and must not start with the slash ('/')
+   character.
+
+   When a client creates a context, it may request automatic
+   notification of changes.  A client may also request enumeration of
+   entries within a context.  Enumeration simplifies the implementation
+   of a "virtual scrollbar" by the client.
+
+   A context exists only within the ACAP session in which it was
+   created.  When the connection is closed, all contexts associated with
+   that connection are automatically discarded.  A server is required to
+   support at least 100 active contexts within a session.  If the server
+   supports a larger limit it must advertise it in a CONTEXTLIMIT
+   capability.
+
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 14]
+
+RFC 2244                          ACAP                     November 1997
+
+
+3.4.     Comparators
+
+   A comparator is a named function which takes two input values and can
+   be used to perform one or more of four comparison operations:
+   ordering, equality, prefix and substring matching.
+
+   The ordering operation is used both for the SORT search modifier and
+   the COMPARE and COMPARESTRICT search keys.  Ordering comparators can
+   determine the ordinal precedence of any two values.  When used for
+   ordering, a comparator's name can be prefixed with "+" or "-" to
+   indicate that the ordering should be normal order or reversed order
+   respectively.  If no prefix is included, "+" is assumed.
+
+   For the purpose of ordering, a comparator may designate certain
+   values as having an undefined ordinal precedence.  Such values always
+   collate with equal value after all other values regardless of whether
+   normal or reversed ordering is used.  Unless the comparator
+   definition specifies otherwise, multi-values and NIL values have an
+   undefined ordinal precedence.
+
+   The equality operation is used for the EQUAL search modifier, and
+   simply determines if the two values are considered equal under the
+   comparator function.  When comparing a single value to a multi-value,
+   the two are considered equal if any one of the multiple values is
+   equal to the single value.
+
+   The prefix match operation is used for the PREFIX search modifier,
+   and simply determines if the search value is a prefix of the item
+   being searched.  In the case of prefix search on a multi-value, the
+   match is successful if the value is a prefix of any one of the
+   multiple values.
+
+   The substring match operation is used for the SUBSTRING search
+   modifier, and simply determines if search value is a substring of the
+   item being searched.  In the case of substring search on a multi-
+   value, the match is successful if the value is a substring of any one
+   of the multiple values.
+
+   Rules for naming and registering comparators will be defined in a
+   future specification.  Servers MUST respond to unknown or improperly
+   used comparators with a BAD command completion result.
+
+
+
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 15]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   The following comparators are defined by this standard and MUST be
+   implemented:
+
+      i;octet
+           Operations: Ordering, Equality, Prefix match, Substring match
+
+           For collation, the i;octet comparator interprets the value of
+           an attribute as a series of unsigned octets with ordinal
+           values from 0 to 255.  When ordering two strings, each octet
+           pair is compared in sequence until the octets are unequal or
+           the end of the string is reached.  When collating two strings
+           where the shorter is a prefix of the longer, the shorter
+           string is interpreted as having a smaller ordinal value.  The
+           "i;octet" or "+i;octet" forms collate smaller ordinal values
+           earlier, and the "-i;octet" form collates larger ordinal
+           values earlier.
+
+           For the equality function, two strings are equal if they are
+           the same length and contain the same octets in the same
+           order.  NIL is equal only to itself.
+
+           For non-binary, non-nil single values, i;octet ordering is
+           equivalent to the ANSI C [ISO-C] strcmp() function applied to
+           C string representations of the values.  For non-binary,
+           non-nil single values, i;octet substring match is equivalent
+           to the ANSI C strstr() function applied to the C string
+           representations of the values.
+
+      i;ascii-casemap
+           Operations: Ordering, Equality, Prefix match, Substring match
+
+           The i;ascii-casemap comparator first applies a mapping to the
+           attribute values which translates all US-ASCII letters to
+           uppercase (octet values 0x61 to 0x7A are translated to octet
+           values 0x41 to 0x5A respectively), then applies the i;octet
+           comparator as described above.  With this function the values
+           "hello" and "HELLO" have the same ordinal value and are
+           considered equal.
+
+      i;ascii-numeric
+           Operations: Ordering, Equality
+
+           The i;ascii-numeric comparator interprets strings as decimal
+           positive integers represented as US-ASCII digits.  All values
+           which do not begin with a US-ASCII digit are considered equal
+           with an ordinal value higher than all non-NIL single-valued
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 16]
+
+RFC 2244                          ACAP                     November 1997
+
+
+           attributes.  Otherwise, all US-ASCII digits (octet values
+           0x30 to 0x39) are interpreted starting from the beginning of
+           the string to the first non-digit or the end of the string.
+
+
+3.5.     Access Control Lists (ACLs)
+
+   An access control list is a set of identifier, rights pairs used to
+   restrict access to a given dataset, attribute or attribute within an
+   entry.  An ACL is represented by a multi-value with each value
+   containing an identifier followed by a tab character followed by the
+   rights.  The syntax is defined by the "acl" rule in the formal syntax
+   in section 8.
+
+   Identifier is a UTF-8 string.  The identifier "anyone" is reserved to
+   refer to the universal identity (all authentications, including
+   anonymous).  All user name strings accepted by the AUTHENTICATE
+   command to authenticate to the ACAP server are reserved as
+   identifiers for the corresponding user.  Identifiers starting with a
+   slash ("/") character are reserved for authorization groups which
+   will be defined in a future specification.  Identifiers MAY be
+   prefixed with a dash ("-") to indicate a revocation of rights.  All
+   other identifiers have implementation-defined meanings.
+
+   Rights is a string listing a (possibly empty) set of alphanumeric
+   characters, each character listing a set of operations which is being
+   controlled.  Letters are reserved for "standard" rights, listed
+   below.  The set of standard rights may only be extended by a
+   standards-track or IESG approved experimental RFC.  Digits are
+   reserved for implementation or site defined rights.  The currently
+   defined standard rights are:
+
+   x - search (use EQUAL search key with i;octet comparator)
+   r - read (access with SEARCH command)
+   w - write (modify with STORE command)
+   i - insert (perform STORE on a previously NIL value)
+   a - administer (perform SETACL or STORE on ACL attribute/metadata)
+
+   An implementation may force rights to always or never be granted.  In
+   particular, implementations are expected to grant implicit read and
+   administer rights to a user's personal dataset storage in order to
+   avoid denial of service problems.  Rights are never tied, unlike the
+   IMAP ACL extension [IMAP-ACL].
+
+   It is possible for multiple identifiers in an access control list to
+   apply to a given user (or other authentication identity).  For
+   example, an ACL may include rights to be granted to the identifier
+   matching the user, one or more implementation-defined identifiers
+
+
+
+Newman & Myers              Standards Track                    [Page 17]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   matching groups which include the user, and/or the identifier
+   "anyone".  These rights are combined by taking the union of all
+   positive rights which apply to a given user and subtracting the union
+   of all negative rights which apply to that user.  A client MAY avoid
+   this calculation by using the MYRIGHTS command and metadata items.
+
+   Each attribute of each entry of a dataset may potentially have an
+   ACL.  If an attribute in an entry does not have an ACL, then access
+   is controlled by a default ACL for that attribute in the dataset, if
+   it exists.  If there is no default ACL for that attribute in the
+   dataset, access is controlled by a default ACL for that dataset.  The
+   default ACL for a dataset must exist.
+
+   In order to perform any access or manipulation on an entry in a
+   dataset, the client must have 'r' rights on the "entry" attribute of
+   the entry.  Implementations should take care not to reveal via error
+   messages the existence of an entry for which the client does not have
+   'r' rights.  A client does not need access to the "subdataset"
+   attribute of the parent dataset in order to access the contents of a
+   dataset.
+
+   Many of the ACL commands and responses include an "acl object"
+   parameter, for specifying what the ACL applies to.  This is a
+   parenthesized list.  The list contains just the dataset name when
+   referring to the default ACL for a dataset.  The list contains a
+   dataset name and an attribute name when referring to the default ACL
+   for an attribute in a dataset.  The list contains a dataset name, an
+   attribute name, and an entry name when referring to the ACL for an
+   attribute of an entry of a dataset.
+
+
+3.6.     Server Response Codes
+
+   An OK, NO, BAD, ALERT or BYE response from the server MAY contain a
+   response code to describe the event in a more detailed machine
+   parsable fashion.  A response code consists of data inside
+   parentheses in the form of an atom, possibly followed by a space and
+   arguments.  Response codes are defined when there is a specific
+   action that a client can take based upon the additional information.
+   In order to support future extension, the response code is
+   represented as a slash-separated hierarchy with each level of
+   hierarchy representing increasing detail about the error.  Clients
+   MUST tolerate additional hierarchical response code detail which they
+   don't understand.
+
+   The currently defined response codes are:
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 18]
+
+RFC 2244                          ACAP                     November 1997
+
+
+      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.
+
+      INVALID
+           This response code indicates that a STORE command included
+           data which the server implementation does not permit.  It
+           MUST NOT be used unless the dataset class specification for
+           the attribute in question explicitly permits enforced server
+           validation.  The argument is the attribute which was invalid.
+
+      MODIFIED
+           This response code indicates that a conditional store failed
+           because the modtime on the entry is later than the modtime
+           specified with the STORE command UNCHANGEDSINCE modifier.
+           The argument is the entry which had been modified.
+
+      NOEXIST
+           This response code indicates that a search or NOCREATE store
+           failed because a specified dataset did not exist.  The
+           argument is the dataset which does not exist.
+
+      PERMISSION
+           A command failed due to insufficient permission based on the
+           access control list or implicit rights.  The argument is the
+           acl-object which caused the permission failure.
+
+      QUOTA
+           A STORE or SETACL command which would have increased the size
+           of the dataset failed due to insufficient quota.
+
+      REFER
+           This response code may be returned in a tagged NO response to
+           any command that takes a dataset name as a parameter.  It has
+           one or more arguments with the syntax of relative URLs.  It
+           is a referral, indicating that the command should be retried
+           using one of the relative URLs.
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 19]
+
+RFC 2244                          ACAP                     November 1997
+
+
+      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].
+
+      TOOMANY
+           This response code may be returned in a tagged OK response to
+           a SEARCH command which includes the LIMIT modifier.  The
+           argument returns the total number of matching entries.
+
+      TOOOLD
+           The modtime specified in the DELETEDSINCE command is too old,
+           so deletedsince information is no longer available.
+
+      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.
+
+      TRYFREECONTEXT
+           This response code may be returned in a tagged NO response to
+           a SEARCH command which includes the MAKECONTEXT modifier.  It
+           indicates that a new context may not be created due to the
+           server's limit on the number of existing contexts.
+
+      WAYTOOMANY
+           This response code may be returned in a tagged NO response to
+           a SEARCH command which includes a HARDLIMIT search modifier.
+           It indicates that the SEARCH would have returned more entries
+           than the HARDLIMIT permitted.
+
+      Additional response codes MUST be registered with IANA according
+      to the proceedures in section 7.2.  Client implementations MUST
+      tolerate response codes that they do not recognize.
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 20]
+
+RFC 2244                          ACAP                     November 1997
+
+
+4.       Namespace Conventions
+
+4.1.     Dataset Namespace
+
+   The dataset namespace is a slash-separated hierarchy.  The first
+   component of the dataset namespace is a dataset class.  Dataset
+   classes MUST have a vendor prefix (vendor.<vendor/product>) or be
+   specified in a standards track or IESG approved experimental RFC.
+   See section 7.3 for the registration template.
+
+   The second component of the dataset name is "site", "group", "host",
+   or "user" referring to server-wide data, administrative group data,
+   per-host data and per-user data respectively.
+
+   For "group", "host", and "user" areas, the third component of the
+   path is the group name, the fully qualified host domain name, or the
+   user name.  A path of the form "/<dataset-class>/~/" is a convenient
+   abbreviation for "/<dataset-class>/user/<current-user>/".
+
+   Dataset names which begin with "/byowner/" are reserved as an
+   alternate view of the namespace.  This provides a way to see all the
+   dataset classes which a particular owner uses.  For example,
+   "/byowner/~/<dataset-class>/" is an alternate name for
+   "/<dataset-class>/~/".  Byowner provides a way to view a list of
+   dataset classes owned by a given user; this is done using the dataset
+   "/byowner/user/<current-user>/" with the NOINHERIT SEARCH modifier.
+
+   The dataset "/" may be used to find all dataset classes visible to
+   the current user.  A dataset of the form "/<dataset-class>/user/" may
+   be used to find all users which have made a dataset or entry of that
+   class visible to the current user.
+
+   The formal syntax for a dataset name is defined by the "dataset-name"
+   rule in section 4.3.
+
+4.2.     Attribute Namespace
+
+   Attribute names which do not contain a dot (".") are reserved for
+   standardized attributes which have meaning in any dataset.  In order
+   to simplify client implementations, the attribute namespace is
+   intended to be unique across all datasets.  To achieve this,
+   attribute names are prefixed with the dataset class name followed by
+   a dot (".").  Attributes which affect management of the dataset are
+   prefixed with "dataset.".  In addition, a subtree of the "vendor."
+   attribute namespace may be registered with IANA according to the
+   rules in section 7.4.  ACAP implementors are encouraged to help
+   define interoperable dataset classes specifications rather than using
+   the private attribute namespace.
+
+
+
+Newman & Myers              Standards Track                    [Page 21]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   Some users or sites may wish to add their own private attributes to
+   certain dataset classes.  In order to enable this, the "user.<user-
+   name>." and "site." subtrees of the attribute namespace are reserved
+   for user-specific and site-specific attributes respectively and will
+   not be standardized.  Such attributes are not interoperable so are
+   discouraged in favor of defining standard attributes.  A future
+   extension is expected to permit discovery of syntax for user or
+   site-specific attributes.  Clients wishing to support display of user
+   or site-specific attributes should display the value of any non-NIL
+   single-valued "user.<user-name>." or "site."  attribute which has
+   valid UTF-8 syntax.
+
+   The formal syntax for an attribute name is defined by the
+   "attribute-name" rule in the next section.
+
+4.3.     Formal Syntax for Dataset and Attribute Namespace
+
+   The naming conventions for datasets and attributes are defined by the
+   following ABNF.   Note that this grammar is not part of the ACAP
+   protocol syntax in section 8, as dataset names and attribute names
+   are encoded as strings within the ACAP protocol.
+
+   attribute-dacl  = "dataset.acl" *("." name-component)
+
+   attribute-dset  = dataset-std 1*("." name-component)
+                     ;; MUST be defined in a dataset class specification
+
+   attribute-name  = attribute-std / attr-site / attr-user / vendor-name
+
+   attribute-std   = "entry" / "subdataset" / "modtime" /
+                     "dataset.inherit" / attribute-dacl / attribute-dset
+
+   attr-site       = "site" 1*("." name-component)
+
+   attr-user       = "user." name-component 1*("." name-component)
+
+   byowner         = "/byowner/" owner "/"
+                     [dataset-class "/" dataset-sub]
+
+   dataset-class   = dataset-std / vendor-name
+
+   dataset-normal  = "/" [dataset-class "/"
+                     (owner-prefix / dataset-tail)]
+
+   dataset-name    = byowner / dataset-normal
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 22]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   dataset-std     = name-component
+                     ;; MUST be registered with IANA and the spec MUST
+                     ;; be published as a standards track or
+                     ;; IESG-approved experimental RFC
+
+   dataset-sub     = *(dname-component "/")
+                     ;; The rules for this portion of the namespace may
+                     ;; be further restricted by the dataset class
+                     ;; specification.
+
+   dataset-tail    = owner "/" dataset-sub
+
+   dname-component = 1*UTF8-CHAR
+                     ;; MUST NOT begin with "." or contain "/"
+
+   name-component  = 1*UTF8-CHAR
+                     ;; MUST NOT contain ".", "/", "%", or "*"
+
+   owner           = "site" / owner-host / owner-group /
+                     owner-user / "~"
+
+   owner-group     = "group/" dname-component
+
+   owner-host      = "host/" dname-component
+
+   owner-prefix    = "group/" / "host/" / "user/"
+
+   owner-user      = "user/" dname-component
+
+   vendor-name     = vendor-token *("." name-component)
+
+   vendor-token    = "vendor." name-component
+                     ;; MUST be registered with IANA
+
+5.       Dataset Management
+
+   The entry with an empty name ("") in the dataset is used to hold
+   management information for the dataset as a whole.
+
+5.1.     Dataset Inheritance
+
+   It is possible for one dataset to inherit data from another.  The
+   dataset from which the data is inherited is called the base dataset.
+   Data in the base dataset appears in the inheriting dataset, except
+   when overridden by a STORE to the inheriting dataset.
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 23]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   The base dataset is usually a system-wide or group-wide set of
+   defaults.  A system-wide dataset usually has one inheriting dataset
+   per user, allowing each user to add to or modify the defaults as
+   appropriate.
+
+   An entry which exists in both the inheriting and base dataset
+   inherits a modtime equal to the greater of the two modtimes.  An
+   attribute in such an entry is inherited from the base dataset if it
+   was never modified by a STORE command in the inheriting dataset or if
+   DEFAULT was stored to that attribute.  This permits default entries
+   to be amended rather than replaced in the inheriting dataset.
+
+   The "subdataset" attribute is not directly inherited.  If the base
+   dataset includes a "subdataset" attribute and the inheriting dataset
+   does not, then the "subdataset" attribute will inherit a virtual
+   value of a list containing a ".".  The subdataset at that node is
+   said to be a "virtual" dataset as it is simply a virtual copy of the
+   appropriate base dataset with all "subdataset" attributes changed to
+   a list containing a ".".  A virtual dataset is not visible if
+   NOINHERIT is specified on the SEARCH command.
+
+   Servers MUST support at least two levels of inheritance.  This
+   permits a user's dataset such as "/options/user/fred/common" to
+   inherit from a group dataset such as "/options/group/dinosaur
+   operators/common" which in turn inherits from a server-wide dataset
+   such as "/options/site/common".
+
+5.2.     Dataset Attributes
+
+   The following attributes apply to management of the dataset when
+   stored in the "" entry of a dataset.  These attributes are not
+   inherited.
+
+   dataset.acl
+        This holds the default access control list for the dataset.
+        This attribute is validated, so an invalid access control list
+        in a STORE command will result in a NO response with an INVALID
+        response code.
+
+   dataset.acl.<attribute>
+        This holds the default access control list for an attribute
+        within the dataset.  This attribute is validated, so an invalid
+        access control list in a STORE command will result in a NO
+        response with an INVALID response code.
+
+   dataset.inherit
+        This holds the name of a dataset from which to inherit according
+        to the rules in the previous section.  This attribute MAY refer
+
+
+
+Newman & Myers              Standards Track                    [Page 24]
+
+RFC 2244                          ACAP                     November 1997
+
+
+        to a non-existent dataset, in which case nothing is inherited.
+        This attribute is validated, so illegal dataset syntax or an
+        attempt to store a multi-value will result in a NO response with
+        an INVALID response code.
+
+5.3.     Dataset Creation
+
+   When a dataset is first created (by storing a "." in the subdataset
+   attribute or storing an entry in a previously non-existent dataset),
+   the dataset attributes are initialized with the values from the
+   parent dataset in the "/byowner/" hierarchy.  In the case of the
+   "dataset.inherit" attribute, the appropriate hierarchy component is
+   added.  For example, given the following entry (note that \t refers
+   to the US-ASCII horizontal tab character):
+
+   entry path        "/byowner/user/joe/"
+   dataset.acl       ("joe\txrwia" "fred\txr")
+   dataset.inherit   "/byowner/site"
+
+   If a new dataset class "/byowner/user/joe/new" is created, it will
+   have the following dataset attributes:
+
+   entry path        "/byowner/user/joe/new/"
+   dataset.acl       ("joe\txrwia" "fred\txr")
+   dataset.inherit   "/byowner/site/new"
+
+   Note that the dataset "/byowner/user/joe/new/" is equivalent to
+   "/new/user/joe/".
+
+5.4.     Dataset Class Capabilities
+
+   Certain dataset classes or dataset class features may only be useful
+   if there is an active updating client or integrated server support
+   for the feature.  The dataset class "capability" is reserved to allow
+   clients or servers to advertise such features.  The "entry" attribute
+   within this dataset class is the name of the dataset class whose
+   features are being described.  The attributes are prefixed with
+   "capability.<dataset-class>." and are defined by the appropriate
+   dataset class specification.
+
+   Since it is possible for an unprivileged user to run an active client
+   for himself, a per-user capability dataset is useful.  The dataset
+   "/capability/~/" holds information about all features available to
+   the user (via inheritance), and the dataset "/capability/site/" holds
+   information about all features supported by the site.
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 25]
+
+RFC 2244                          ACAP                     November 1997
+
+
+5.5.     Dataset Quotas
+
+   Management and scope of quotas is implementation dependent.  Clients
+   can check the applicable quota limit and usage (in bytes) with the
+   GETQUOTA command.  Servers can notify the client of a low quota
+   situation with the QUOTA untagged response.
+
+6.       Command and Response Specifications
+
+   ACAP commands and responses are described in this section.  Commands
+   are organized first by the state in which the command is permitted,
+   then by a general category of command type.
+
+   Command arguments, identified by "Arguments:" in the command
+   descriptions below, are described by function, not by syntax.  The
+   precise syntax of command arguments is described in the Formal Syntax
+   section.
+
+   Some commands cause specific server data to be returned; these are
+   identified by "Data:" in the command descriptions below.  See the
+   response descriptions in the Responses section for information on
+   these responses, and the Formal Syntax section for the precise syntax
+   of these responses.  It is possible for server data to be transmitted
+   as a result of any command; thus, commands that do not specifically
+   require server data specify "no specific data for this command"
+   instead of "none".
+
+   The "Result:" in the command description refers to the possible
+   tagged status responses to a command, and any special interpretation
+   of these status responses.
+
+6.1.     Initial Connection
+
+   Upon session startup, the server sends one of two untagged responses:
+   ACAP or BYE.  The untagged BYE response is described in section
+   6.2.8.
+
+6.1.1.   ACAP Untagged Response
+
+   Data:       capability list
+
+      The untagged ACAP response indicates the session is ready to
+      accept commands and contains a space-separated listing of
+      capabilities that the server supports.  Each capability is
+      represented by a list containing the capability name optionally
+      followed by capability specific string arguments.
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 26]
+
+RFC 2244                          ACAP                     November 1997
+
+
+      ACAP capability names MUST be registered with IANA according to
+      the rules in section 7.1.
+
+      Client implementations SHOULD NOT require any capability name
+      beyond those defined in this specification, and MUST tolerate any
+      unknown capability names.  A client implementation MAY be
+      configurable to require SASL mechanisms other than CRAM-MD5
+      [CRAM-MD5] for site security policy reasons.
+
+      The following initial capabilities are defined:
+
+      CONTEXTLIMIT
+            The CONTEXTLIMIT capability has one argument which is a
+            number describing the maximum number of contexts the server
+            supports per connection.  The number 0 indicates the server
+            has no limit, otherwise this number MUST be greater than
+            100.
+
+      IMPLEMENTATION
+            The IMPLEMENTATION capability has one argument which is a
+            string describing the server implementation.  ACAP clients
+            MUST NOT alter their behavior based on this value.  It is
+            intended primarily for debugging purposes.
+
+      SASL  The SASL capability includes a list of the authentication
+            mechanisms supported by the server.  See section 6.3.1.
+
+
+   Example:    S: * ACAP (IMPLEMENTATION "ACME v3.5")
+                         (SASL "CRAM-MD5") (CONTEXTLIMIT "200")
+
+6.2.     Any State
+
+   The following commands and responses are valid in any state.
+
+6.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 auto-logout timer on the server.
+
+   Example:    C: a002 NOOP
+
+
+
+Newman & Myers              Standards Track                    [Page 27]
+
+RFC 2244                          ACAP                     November 1997
+
+
+               S: a002 OK "NOOP completed"
+
+
+6.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 and appropriate comparators
+      for use with the languages listed in the LANG command.
+
+      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" "i;octet" "i;ascii-numeric"
+                       "i;ascii-casemap" "en;primary" "fr;primary"
+               S: A003 OK "Bonjour"
+
+
+6.2.3.   LANG Intermediate Response
+
+   Data:       language for error responses
+               appropriate comparators
+
+      The LANG response indicates the language which will be used for
+      error responses and the comparators which are appropriate for the
+      languages listed in the LANG command.  The comparators SHOULD be
+      in approximate order from most efficient (usually "i;octet") to
+      most appropriate for human text in the preferred language.
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 28]
+
+RFC 2244                          ACAP                     November 1997
+
+
+6.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 "ACAP Server logging out"
+               S: A023 OK "LOGOUT completed"
+               (Server and client then close the connection)
+
+
+6.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
+      indicated by a response code.
+
+   Example:    S: * OK "Master ACAP server is back up"
+
+
+6.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: A010 SEARCH "/addressbook/" DEPTH 3 RETURN ("*")
+                       EQUAL "entry" "+i;octet" "bozo"
+               S: * NO "Master ACAP server is down, your data may
+
+
+
+Newman & Myers              Standards Track                    [Page 29]
+
+RFC 2244                          ACAP                     November 1997
+
+
+                        be out of date."
+               S: A010 OK "search done"
+                  ...
+               C: A222 STORE ("/folder/site/comp.mail.misc"
+                              "folder.creation-time" "19951206103412")
+               S: A222 NO (PERMISSION ("/folder/site/")) "Permission
+               denied"
+
+
+6.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"
+
+
+6.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
+      be sent as part of a normal logout sequence, or as a panic
+      shutdown announcement by the server.  It is also used by some
+      server implementations as an announcement of an inactivity auto-
+      logout.
+
+      This response is also used as one of two possible greetings at
+      session startup.  It indicates that the server is not willing to
+      accept a session from this client.
+
+   Example:    S: * BYE "Auto-logout; idle for too long"
+
+
+
+
+Newman & Myers              Standards Track                    [Page 30]
+
+RFC 2244                          ACAP                     November 1997
+
+
+6.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 ACAP server will be shut down in
+                           10 minutes for system maintenance."
+
+
+6.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 by supporting the SASL ANONYMOUS [SASL-ANON] mechanism.
+
+   Once authenticated (including as anonymous), it is not possible to
+   re-enter non-authenticated state.
+
+   Only the any-state commands (NOOP, LANG and LOGOUT) and the
+   AUTHENTICATE command are valid in non-authenticated state.
+
+
+6.3.1.   AUTHENTICATE Command
+
+   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
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 31]
+
+RFC 2244                          ACAP                     November 1997
+
+
+      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
+      "acap".
+
+      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.
+
+      All ACAP 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.
+
+
+
+Newman & Myers              Standards Track                    [Page 32]
+
+RFC 2244                          ACAP                     November 1997
+
+
+   Example:    S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5")
+                         (SASL "CRAM-MD5" "KERBEROS_V4")
+               C: A001 AUTHENTICATE "CRAM-MD5"
+               S: + "<1896.697170952@postoffice.reston.mci.net>"
+               C: "tim b913a602c7eda7a495b4e6e7334d3890"
+               S: A001 OK "CRAM-MD5 authentication successful"
+
+
+6.4.     Searching
+
+   This section describes the SEARCH command, for retrieving data from
+   datasets.
+
+
+6.4.1.   SEARCH Command
+
+   Arguments:  dataset or context name
+               optional list of modifiers
+               search criteria
+
+   Data:       intermediate responses: ENTRY, MODTIME, REFER
+               untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME
+
+   Result:     OK - search completed
+               NO - search failure: can't perform search
+               BAD - command unknown or arguments invalid
+
+      The SEARCH command identifies a subset of entries in a dataset and
+      returns information on that subset to the client.  Inherited
+      entries and attributes are included in the search unless the
+      NOINHERIT search modifier is included or the user does not have
+      permission to read the attributes in the base dataset.
+
+      The first argument to SEARCH identifies what is to be searched.
+      If the string begins with a slash ("/"), it is the name of a
+      dataset to be searched, otherwise it is a name of a context that
+      was created by a SEARCH command given previously in the session.
+
+      A successful SEARCH command MAY result in intermediate ENTRY
+      responses and MUST result in a MODTIME intermediate response.
+
+      Following that are zero or more modifiers to the search.  Each
+      modifier may be specified at most once.  The defined modifiers
+      are:
+
+
+
+
+
+
+
+Newman & Myers              Standards Track                    [Page 33]
+
+RFC 2244                          ACAP                     November 1997
+
+
+      DEPTH number
+           The SEARCH command will traverse the dataset tree up to the
+           specified depth.  ENTRY responses will include the full path
+           to the entry.  A value of "0" indicates that the search
+           should traverse the entire tree.  A value of "1" is the
+           default and indicates only the specified dataset should be
+           searched.  If a dataset is traversed which is not located on
+           the current server, then a REFER intermediate response is
+           returned for that subtree and the search continues.
+
+      HARDLIMIT number
+           If the SEARCH command would result in more than number
+           entries, the SEARCH fails with a NO completion result with a
+           WAYTOOMANY response code.
+
+      LIMIT number number
+           Limits the number of intermediate ENTRY responses that the
+           search may generate.  The first numeric argument specifies
+           the limit, the second number specifies the number of entries
+           to return if the number of matches exceeds the limit.  If the
+           limit is exceeded, the SEARCH command still succeeds,
+           returning the total number of matches in a TOOMANY response
+           code in the tagged OK response.
+
+      MAKECONTEXT [ENUMERATE] [NOTIFY] context
+           Causes the SEARCH command to create a context with the name
+           given in the argument to refer to the matching entries.  If
+           the SEARCH is successful, the context name may then be given
+           as an argument to subsequent SEARCH commands to search the
+           set of matching entries.  If a context with the specified
+           name already exists, it is first freed.  If a new context may
+           not be created due to the server's limit on the number of

[... 1927 lines stripped ...]


---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org


Mime
View raw message