ACAP -- Application Configuration Access Protocol

ACAP was designed based on the IMAP protocol framework with refinements. The text-based line-oriented protocol design was deliberately chosen to massively simplify protocol debugging.

By default, any value may be stored in any attribute for which the user has permission and quota, without server-side validation. This is required to allow new simple dataset classes to be added without reconfiguring or upgrading servers. Enforced validation is only permitted when the dataset class specification explicitly identifies it.

Client simplicity was explicitly preferred over server or protocol simplicity because many applications were expected to become ACAP-enabled. Features like server-side sorting, selective fetching, change notification, and modification times were added to reduce client complexity in handling potentially large datasets over slow or intermittent connections.

The ACAP URL authentication parameter ';AUTH=' is interpreted as described in the IMAP URL Scheme specification. The '<aauth>' grammar element is treated as part of the user name for relative URL resolution, providing compatibility with IMAP URL conventions.

A client MUST be prepared to accept any server response at all times, including untagged data it did not explicitly request.

ACAP capability names MUST be registered with IANA. Client implementations SHOULD NOT require any capability beyond those defined in this specification and MUST tolerate unknown capability names.

registry

All ACAP implementations MUST implement the CRAM-MD5 SASL mechanism, although they MAY offer a configuration option to disable it for site security policy reasons.

security, crypto

Client implementations MUST tolerate response codes they do not recognize. Additional response codes MUST be registered with IANA.

registry

Clients MUST NOT depend on the presence of enforced server-side validation, since a given ACAP server may be unaware of any particular dataset class specification.

Each STORE command within a dataset (including simultaneous stores from different connections) MUST use different modtime values, and any two entries changed by successive modifications MUST have strictly ascending modtime values.

If a server implements an inactivity auto-logout timer, that timer MUST be of at least 30 minutes duration, and receipt of ANY command from the client during that interval MUST suffice to reset it.

Servers MUST implement the three required comparators: i;octet (byte-by-byte ordering/equality/prefix/substring), i;ascii-casemap (case-insensitive ASCII ordering/equality/prefix/substring), and i;ascii-numeric (decimal integer ordering/equality). Servers MUST respond to unknown or improperly used comparators with a BAD response.

To access any entry, a client must have 'r' rights on the 'entry' attribute. Implementations MUST NOT reveal the existence of an entry for which the client lacks 'r' rights, even via error messages.

security, privacy

When a SEARCH with MAKECONTEXT NOTIFY is active, after issuing a sequence of ADDTO, REMOVEFROM, or CHANGE notifications, the server MUST issue an untagged MODTIME notification indicating the client has all updates up to and including that modtime.

A context is an ordered subset of dataset entries created by a SEARCH command with the MAKECONTEXT modifier. Contexts are session-scoped (discarded on connection close), and a server MUST support at least 100 active contexts per session.

ACAP operates over TCP on port 674. It is a text-based, line-oriented protocol where interactions are sequences of characters ending with CRLF. Both clients and servers must handle lines of arbitrary length.

tcp

Access Control Lists (ACLs) are multi-values of 'identifier TAB rights' pairs. Standard rights are: x (search), r (read), w (write), i (insert), a (administer). Multiple matching identifiers' rights are combined by unioning positive rights and subtracting unioned negative rights (dash-prefixed identifiers).

security

Dataset inheritance allows one dataset to inherit entries and attributes from a base dataset, with the 'dataset.inherit' attribute in the '' entry specifying the base. An overridden attribute can be reset to the inherited value by storing DEFAULT. Servers MUST support at least two levels of inheritance.

Server response codes appear inside parentheses in OK/NO/BAD/ALERT/BYE responses as a slash-separated hierarchy atom with optional arguments. Defined codes include: AUTH-TOO-WEAK, ENCRYPT-NEEDED, INVALID, MODIFIED, NOEXIST, PERMISSION, QUOTA, REFER, SASL, TOOMANY, TOOOLD, TRANSITION-NEEDED, TRYLATER, TRYFREECONTEXT, WAYTOOMANY.

The ACAP URL scheme has the form 'acap://<server>/<entry>[filter][extension]', defaults to port 674, and forbids plaintext passwords. If no authentication mechanism is specified, SASL ANONYMOUS is used by default; if no user name is specified with a mechanism, one should be obtained from the mechanism or the user.

The ALERT untagged response contains a human-generated message that MUST be presented to the user in a fashion that calls attention to it, intended for vital administrator-to-user notices such as imminent server maintenance.

The AUTHENTICATE command uses SASL mechanisms and optionally negotiates a security layer. If a security layer is negotiated, it takes effect immediately after the CRLF completing the authentication exchange on the client side, and after the CRLF of the tagged OK on the server side.

security, crypto

The dataset namespace is a slash-separated hierarchy whose first component is the dataset class (must have a vendor prefix or be standards-track), second component is 'site', 'group', 'host', or 'user', and '~' abbreviates the current user's path. '/byowner/' provides an alternate view by owner.

The SEARCH command retrieves entries from a dataset or context with optional modifiers: DEPTH (tree traversal depth), HARDLIMIT/LIMIT (result capping), MAKECONTEXT [ENUMERATE] [NOTIFY] (create a persistent context with optional ordered enumeration and change notifications), NOINHERIT, RETURN (attribute/metadata selection), and SORT.

The three predefined attributes are: 'entry' (unique entry name, MUST be single-valued), 'modtime' (14+ ASCII digit UTC timestamp auto-maintained by the server, with strictly ascending values across successive modifications in a dataset), and 'subdataset' (list of relative ACAP URLs indicating sub-dataset location).

This document establishes four IANA registries: ACAP Capabilities (section 7.1), ACAP Response Codes (section 7.2), Dataset Classes (section 7.3, requiring standards-track or IESG-approved experimental RFC), and Vendor Subtree (section 7.4, for private attribute and dataset namespaces).

registry

ACAP uses SASL for authentication, with CRAM-MD5 as the mandatory-to-implement mechanism. The AUTH-TOO-WEAK and ENCRYPT-NEEDED response codes allow servers to enforce site security policies by rejecting authentication attempts that do not meet minimum strength requirements. SASL also allows optional negotiation of a security layer for session encryption.

security, crypto

An ACAP server is in one of three states: Non-Authenticated (entered on connection), Authenticated (entered after successful AUTHENTICATE), and Logout (entered via LOGOUT command, server shutdown, or connection close). Commands are only valid in certain states; issuing a command in an inappropriate state results in a BAD response.

Client commands are prefixed with an alphanumeric tag of no more than 32 characters. Server responses are tagged (matching the client command tag), untagged (prefixed with '*'), or command continuation requests (prefixed with '+'). A tagged response other than OK, NO, or BAD is an intermediate response.

Strings are encoded as quoted strings (0–1024 octets, excluding NUL/CR/LF, delimited by double quotes) or literals (octet count in braces followed by CRLF then data). Literals from client to server are either synchronizing (client must await '+' continuation before sending octets) or non-synchronizing ('+' between count and closing brace, octets sent immediately).