You are viewing a plain text version of this content. The canonical link for it is here.
Posted to site-dev@james.apache.org by ba...@apache.org on 2007/09/18 02:14:48 UTC
svn commit: r576631 [19/29] - in /james/site/trunk/www/jsieve: ./ apidocs/
apidocs/org/apache/jsieve/ apidocs/org/apache/jsieve/class-use/
apidocs/org/apache/jsieve/commands/
apidocs/org/apache/jsieve/commands/class-use/
apidocs/org/apache/jsieve/comma...
Modified: james/site/trunk/www/jsieve/rfc2244.txt
URL: http://svn.apache.org/viewvc/james/site/trunk/www/jsieve/rfc2244.txt?rev=576631&r1=576630&r2=576631&view=diff
==============================================================================
--- james/site/trunk/www/jsieve/rfc2244.txt (original)
+++ james/site/trunk/www/jsieve/rfc2244.txt Mon Sep 17 17:14:20 2007
@@ -1,4034 +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
- existing contexts, the command fails, returning a
- TRYFREECONTEXT response code in the NO completion response.
-
- The optional "ENUMERATE" and "NOTIFY" arguments may be
- included to request enumeration of the context (for virtual
- scroll bars) or change notifications for the context. If
- "NOTIFY" is not requested, the context represents a snapshot
- of the entries at the time the SEARCH was issued.
-
- ENUMERATE requests that the contents of the context be
- ordered according to the SORT modifier and that sequential
- numbers, starting with one, be assigned to the entries in the
- context. This permits the RANGE modifier to be used to fetch
- portions of the ordered context.
-
-
-
-
-
-Newman & Myers Standards Track [Page 34]
-
-RFC 2244 ACAP November 1997
-
-
- NOTIFY requests that the server send untagged ADDTO,
- REMOVEFROM, CHANGE, and MODTIME responses while the context
- created by this SEARCH command exists. The server MAY issue
- untagged ADDTO, REMOVEFROM, CHANGE and MODTIME notifications
- for a context at any time between the issuing of the SEARCH
- command with MAKECONTEXT NOTIFY and the completion of a
- FREECONTEXT command for the context. Notifications are only
- issued for changes which occur after the server receives the
- SEARCH command which created the context. After issuing a
- sequence of ADDTO, REMOVEFROM or CHANGE notifications, the
- server MUST issue an untagged MODTIME notification indicating
- that the client has all updates to the entries in the context
- up to and including the given modtime value. Servers are
- permitted a reasonable delay to batch change notifications
- before sending them to the client.
-
- The position arguments of the ADDTO, REMOVEFROM and CHANGE
[... 5920 lines stripped ...]