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-106