You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by da...@apache.org on 2007/05/03 14:59:55 UTC
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/
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: + "<18...@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