WDIFF

draft-ietf-acap-spec-03.txt --> draft-ietf-acap-spec-04.txt

Network Working Group C. Newman
Internet Draft: ACAP Innosoft
Document: draft-ietf-acap-spec-03.txt draft-ietf-acap-spec-04.txt J. G. Myers
Expire
Netscape
June 1997
Expires in six months March 1997

ACAP -- Application Configuration Access Protocol

Status of this Memo

This document is an Internet Draft. Internet Drafts Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its Areas, areas,
and its Working Groups. working groups. Note that other groups may also distribute
working documents as Internet Drafts.

Internet Drafts Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six
months. Internet Drafts months
and may be updated, replaced, or obsoleted by other documents at any
time. It is not appropriate inappropriate to use Internet
Drafts Internet-Drafts as reference
material or to cite them other than as a
``working draft'' or ``work "work in progress``. progress."

To learn view the current status entire list of any Internet-Draft, current Internet-Drafts, please check the
1id-abstracts.txt
"1id-abstracts.txt" listing contained in the Internet-Drafts Shadow
Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or
munnari.oz.au.

This document suggests a proposed protocol for the Internet
community, and requests discussion and suggestions for improvements.
Distribution of this draft is unlimited.

The protocol discussed in this document is experimental and subject
to change. Persons planning on either implementing ftp.is.co.za (Africa), ftp.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or using this
protocol are STRONGLY URGED to get in touch with the author before
embarking on such a project.
ftp.isi.edu (US West Coast).

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 [Page i]

Internet DRAFT ACAP March 26, June 19, 1997

Table of Contents

Status of this Memo ............................................... i
Abstract .......................................................... i
ACAP Protocol Specification ....................................... 1
0. Changes from version -01 -03 to version -02 -04 .................. 1
0.1. Changes from draft -02 to draft -03 ...................... 2
0.2. Open Issues .............................................. 4 3
1. Introduction ............................................. 3
1.1. Conventions Used in this Document ........................ 3
1.2. ACAP Data Model .......................................... 3
1.3. ACAP Design Goals ........................................ 3
1.4. Validation ............................................... 4
1.5. Definitions .............................................. 4
1.6. ACAP Command Overview .................................... 6
2. Protocol Overview ........................................ 5 Framework ....................................... 6
2.1. Link Level ............................................... 5 6
2.2. Commands and Responses ................................... 5 6
2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 5 6
2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 6
2.3. State and Flow Diagram ................................... 7
2.3. Server States ............................................ 8
2.3.1. Non-Authenticated State .................................. 7 8
2.3.2. Authenticated State ...................................... 7 8
2.3.3. Logout State ............................................. 7 8
2.4. Operational Considerations ............................... 8 9
2.4.1. Untagged Status Updates .................................. 8 9
2.4.2. Response when No Command in Progress ..................... 8 9
2.4.3. Autologout Auto-logout Timer ......................................... 8 ........................................ 9
2.4.4. Multiple Commands in Progress ............................ 9
2.5. Datasets and Entries ..................................... 9
2.6. Predefined Attributes .................................... 9
2.7. Attribute metadata ....................................... 10
2.8. Operational
2.5. Server Command Overview ............................. 11
3. Protocol Elements ........................................ 11
3.1. Continuation Request ...................... 10
2.6. Data Formats ............................................. 12
3.1.1. 10
2.6.1. Atom ..................................................... 12
3.1.2. 11
2.6.2. Number ................................................... 12
3.1.3. 11
2.6.3. String ................................................... 12
3.1.3.1. 11
2.6.3.1. 8-bit and Binary Strings ................................. 13
3.1.4. 12
2.6.4. Parenthesized List ....................................... 13
3.1.5 12
2.6.5. NIL ...................................................... 12
3. Protocol Elements ........................................ 12
3.1. Entries and Attributes ................................... 12
3.1.1. Predefined Attributes .................................... 13
3.2. ACAP
3.1.2. Attribute metadata ....................................... 14
3.2. ACAP URL scheme .......................................... 13 15
3.2.1. ACAP URL User Name and Authentication Mechanism .......... 14 15
3.2.2. Relative ACAP URLs ....................................... 15 16

Newman [Page ii]

Internet DRAFT ACAP June 19, 1997

3.3. Contexts ................................................. 15 16
3.4. Orderings ................................................ 15 Comparators .............................................. 17
3.5. Server Status Responses .................................. 16 Access Control Lists (ACLs) .............................. 18
3.6. Server Command Continuation Request ...................... 17 Response Codes .................................... 20
4. Protocol Specification ................................... 19

Newman [Page iii]

Internet DRAFT ACAP March 26, 1997 Namespace Conventions .................................... 22
4.1. Dataset Namespace ........................................ 22
4.2. Attribute Namespace ...................................... 23
4.3. Formal Syntax for Dataset and Attribute Namespace ........ 23
5. Dataset Management ....................................... 25
5.1. Dataset Inheritance ...................................... 25
5.2. Dataset Attributes ....................................... 25
5.3. Dataset Creation ......................................... 26
5.4. Dataset Class Capabilities ............................... 26
5.5. Dataset Quotas ........................................... 27
6. Command and Response Specifications ...................... 28
6.1. Initial Connection ....................................... 19
4.1.1. 29
6.1.1. ACAP Untagged Response ................................... 19
4.2. 29
6.2. Any State ................................................ 20
4.2.1. 30
6.2.1. NOOP Command ............................................. 20
4.2.2. 30
6.2.2. LANG Command ............................................. 30
6.2.3. LANG Untagged Response ................................... 31
6.2.4. LOGOUT Command ........................................... 21
4.2.3. 31
6.2.5. OK Response .............................................. 21
4.2.4. 31
6.2.6. NO Response .............................................. 21
4.2.5. 32
6.2.7. BAD Response ............................................. 22
4.2.6. 32
6.2.8. BYE Untagged Response .................................... 22
4.3. 33
6.2.9. ALERT Untagged Response .................................. 33
6.3. Non-Authenticated State .................................. 23
4.3.1. 33
6.3.1. AUTHENTICATE Command ..................................... 23
4.4. 34
6.4. Searching ................................................ 25
4.4.1. 35
6.4.1. SEARCH Command ........................................... 25
4.4.2. 35
6.4.2. ENTRY Intermediate Response .............................. 29
4.4.3. 40
6.4.3. MODTIME Intermediate Response ............................ 29
4.4.4. 40
6.4.4. REFER Intermediate Response .............................. 29
4.5. 40
6.5. Contexts ................................................. 30
4.5.1. 41
6.5.1. FREECONTEXT Command ...................................... 30
4.5.2. 41
6.5.2. UPDATECONTEXT Command .................................... 30
4.5.3. 41
6.5.3. ADDTO Untagged Response .................................. 31
4.5.4. 42
6.5.4. REMOVEFROM Untagged Response ............................. 31
4.5.5. 42
6.5.5. CHANGE Untagged Response ................................. 32
4.5.6. 43
6.5.6. MODTIME Untagged Response ................................ 32
4.6. 43
6.6. Dataset modification ..................................... 32
4.6.1. 44
6.6.1. STORE Command ............................................ 33
4.6.2. 44
6.6.2. DELETEDSINCE Command ..................................... 34
4.6.3. 45
6.6.3. DELETED Intermediate Response ............................ 34
4.7. 46
6.7. Access Control Lists ..................................... 34
4.7.1. List Commands ............................. 46
6.7.1. SETACL Command ........................................... 36
4.7.2. 46
6.7.2. DELETEACL Command ........................................ 37
4.7.3. 47

Newman [Page iii]

Internet DRAFT ACAP June 19, 1997

6.7.3. MYRIGHTS Command ......................................... 37
4.7.4. 47
6.7.4. MYRIGHTS Intermediate Response ........................... 38
4.7.5. 48
6.7.5. LISTRIGHTS Command ....................................... 38
4.7.6. 48
6.7.6. LISTRIGHTS Intermediate Response ......................... 38
4.8. 49
6.8. Quotas ................................................... 39
4.8.1. SETQUOTA Command ......................................... 39
4.8.2. 49
6.8.1. GETQUOTA Command ......................................... 40
4.8.3. 49
6.8.3. QUOTA Intermediate Untagged Response .............................. 40
4.9. .................................. 50
6.9. Extensions ............................................... 40
5. Dataset Management ....................................... 41
5.1. Dataset Inheritance ...................................... 41
5.2. Dataset attributes ....................................... 41
6. Namespace conventions .................................... 42
6.1. Dataset Namespace ........................................ 42
6.2. Attribute Namespace ...................................... 42 50
7. Registration procedures Procedures .................................. 42 50
7.1. Ordering Functions ....................................... 43 Comparators .............................................. 51
7.2. ACAP Capabilities ........................................ 43

Newman [Page iv]

Internet DRAFT ACAP March 26, 1997 51
7.3. Dataset ACAP Response Codes ...................................... 52
7.4. Dataset Classes .......................................... 44
7.4. Private Attribute 52
7.5. Vendor Subtree ................................ 44 ........................................... 53
8. Formal Syntax ............................................ 45 53
9. Multi-lingual Considerations ............................. 63
10. Security Considerations .................................. 53
10. 64
11. Acknowledgments .......................................... 64
12. Authors' Addresses ....................................... 53 64
Appendices ........................................................ 54 65
A. References ............................................... 54 65
B. ACAP Keyword Index ....................................... 55 67

Newman [Page v] iv]

Internet DRAFT ACAP March 26, June 19, 1997

ACAP Protocol Specification

0. Changes from version -01 -03 to version -02 -04

1) Added Changed ABNF reference to definitions use new ABNF spec, added UTF-8 syntax
and got rid of MUST, SHOULD, etc. all <description> stuff in grammar.

2) Removed last mention Added length limit of "NIL". 32 on tags.

3) Renamed "name" "ordering function" to "entry". "comparator"

4) Datasets are ordered in a server-determined manner. Put "" around comparator, made "+" / "-" optional.

5) "acl" metadata is read-only. Added SUBSTRING and PREFIX search keys.

6) return error on fetch of undefined metadata. Added multi-valued attributes.

7) Restricted numbers to 32-bit values.

8) Added "subdataset" attribute and discussion description of dataset hierarchy.

8) Changed "request response" to "request", data model and "result response" to
"result" to simplify the text. design goals.

9) Removed "Child Dataset Attributes" and added "Operational Command
Overview" Permit multiple referrals.

10) Restructured document a bit, adding a "protocol elements" section Simplified ACAP URL.

11) Added "*" rule to Noted that UNCHANGEDSINCE with a time of "00000101000000" will
always fail if the RETURN search modifier. entry exists.

12) Added the DEPTH search modifier. Used "base dataset" rather than "inherited dataset"

13) Added predefined orderings. Fixed ABNF to group results for each RETURN item.

14) Added ACAP URL scheme Forbid use of "*" or "%" in attribute name.

15) Removed NOTIFYCONTEXT command, added NOTIFYCONTEXT search
modifier.

16) DELETEDFROM -> intermediate DELETED Added TRYCACHE response code.

16) Clarified that any two STORE operations must result in different
modtimes, even if simultaneous.

17) Added second argument to LIMIT search modifier. recommendation that all servers support the PLAIN SASL
mechanism and SHOULD support an encryption layer or stronger
standards track SASL mechanism.

18) Added "[" and "]" to atom_specials to deal with special
information tokens cleanly; removed "*" and "%"

19) made resp_text into quoted string a bunch of text to simplify parsing. security considerations section after
being warned that the IESG is becoming much more stringent about
security considerations. Comments would be appreciated.

Newman [Page 1]

Internet DRAFT ACAP March 26, June 19, 1997

19) Noted that change responses are not issued for implicit
renumbering.

20) Added SASL list to Capability greeting. Removed ".bin" attribute naming convention.

21) Removed ACL, LISTRIGHTS, GETACL, NOACL in favor of dataset
management attributes partial fetch attribute.

22) Removed "o" ACL bit.

23) Added AND acl-object argument to SEARCH keys and removed parentheses around SEARCH
keys.

23) simplified MYRIGHTS command and result PERMISSION error.

24) Simplified STORE and DELETE using entry-path

25) Remove locking of entire dataset. Add MODTIME intermediate
result Atoms must begin with a letter to LOCK command.

26) Added GETQUOTA and SETQUOTA.

27) Astring is removed distinguish them from the grammar, except numbers.
Added that atoms are used for LOGIN.

28) Changed term "shadow" protocol keywords.

25) Make ALERT a separate untagged response

26) Change NOTIFYCONTEXT to "inherit"

29) MAKECONTEXT [ENUMERATE] [NOTIFY]

27) Added dataset management Multi-lingual considerations section

28) Updated STORE grammar to deal with multiple writable metadata
items and multi-valued attributes.

29) make metadata item names be quoted strings

30) Added sort-hint Fixed LISTRIGHTS, SETACL examples.

31) Added QUOTA and PERMISSION response codes dataset creation section, dataset capabilities section.

32) Added registration procedures NOINHERIT SEARCH modifier.

33) Added dataset namespace conventions

34) TOOMANYCONTEXTS -> TRYFREECONTEXT

0.1. Changes from draft -02 to draft -03

1) Removed sort-hint, LOGIN, createtime, DELETE, LOCK, UNLOCK. DUMB
SASL mechanism will be defined in a separate document.

2) Put NIL back in.

3) Changed STORE command to allow NIL, include conditional store, NOEXIST response code and NOCREATE store multiple entries atomically.

4) Fleshed out "extensions" section a bit.

5) Used parenthesis instead of brackets for special information
tokens. Simplifies parsing. Took "[" modifier.

34) Added LANG command.

35) Added user specific and "]" back out site specific attribute namespaces.

36) Removed SETQUOTA command, added description of atom
specials. /quota dataset
class. SETQUOTA was broken because it didn't fall under the auspices
of ACAP's ACL system.

37) Allow servers to implement schemes to defeat client polling with
UPDATECONTEXT.

38) Forbid duplicate search modifiers, store modifiers, store
entries, store entry attributes, store attribute metadata.

Newman [Page 2]

Internet DRAFT ACAP March 26, June 19, 1997

6) *Changed quoted string to allow UTF-8 characters.

7) kilobytes -> octets

8) Added "time" field to the RANGE search modifier to remove
ambiguity problems with unsolicited notifications.

9) Clarified that a BAD completion result must be returned for a
number of cases (bad metadata, invalid search modifier combinations,
etc).

10) Updated example in ACAP URL section and added rest of description
for the <url-filter> element.

11) Clarified octet collation.

12) Clarified REFER response code. Added REFER intermediate response
to SEARCH.

13) Clarified DEPTH search modifier.

14) Forbid use of "*" in attribute name. Forbid entry name from
beginning with ".".

15) Finished changing "NOTIFYCONTEXT command" to "NOTIFYCONTEXT
search modifier".

16) Changed ACL identifier to permit UTF-8.

17) Added reference to US-ASCII.

18) private. -> vnd. and prs.

19) permit multiple arguments to a capability.

20) Put back LISTRIGHTS command and response.

21) Added "ALL" search key, "HARDLIMIT" search modifier and
"WAYTOOMANY" response code.

22) Allow STORE with no attributes added; SHOULD/MUST rules as
appropriate.

23) Clarify inheritance rules with respect to modtime attribute and
ACL attributes.

24) Added rule about UPDATECONTEXT returning MODTIME if changes.

Newman [Page 3]

Internet DRAFT ACAP March 26, 1997

25) Clarify that ADDTO/REMOVEFROM/CHANGE renumber other entries in
the context.

26) Added editorial clarity note to section 1.

27) Require MODTIME response to successful SEARCH.

28) Allow size to be 0 in value<origin.size>.

0.2. Open Issues

1) Document structure: do you like it?

2) Need to define precise Unicode-based ordering function, if one
exists that isn't a nightmare to implement. If it is a nightmare to
implement, we can make it a SHOULD rather than a MUST.

3) Consider making ACL model more precise. Would like

0.1. Open Issues

1) Consider making ACL model more precise. Would like to pick AFS
semantics over POSIX semantics since AFS semantics are more
intuitive. Need to confer with security area director. Currently both ACL semantics are permitted.

4) Current namespace conventions make certion useful operations
difficult. Other simple conventions appear worse.

2) Need a way to
permit both "list all shared addressbooks" and "list all datasets
owned by more examples.

3) Descriptive comparator naming, including vendor naming.

1. Introduction

1.1. Conventions Used in this user". Ideas include multiple namespaces (e.g.,
"/addressbooks/user/chris" Document

In examples, "C:" and "/user/chris/addressbook" are "S:" indicate lines sent by the
same), out of band dataset class typing, and permitting "*" wild card
in place of a dataset path element.

5) Some people have indicated a desire for multi-valued attributes.

6) Do we need some sort of a "touch" operation?

7) Need to think more about the "subdataset" attribute and
inheritance.

8) Need to think more about the "o" ACL right and inheritance.

9) Need more examples.

1. Conventions Used in this Document

In examples, "C:" and "S:" indicate lines sent by the client 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.

Newman [Page 4]

Internet DRAFT ACAP March 26, 1997

The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT",
and "MAY" in this document are to be interpreted as described in RFC xxxx.

The protocol syntax specification uses the Augmented Backus-Naur Form
(ABNF) notation as specified "Key
words for use in [IMAIL] with one exception; the
delimiter used with RFCs to Indicate Requirement Levels" [KEYWORDS].

1.2. ACAP Data Model

An ACAP server exports a hierarchical tree of entries. Each level of
the "#" construct tree is called a single space (SPACE) dataset, and
not one or more commas.

2. Protocol Overview

2.1. Link Level

The ACAP protocol assumes a reliable data stream such as provided by
TCP. When TCP each dataset is used, an ACAP server listens on port 674.

2.2. Commands and Responses

An ACAP session consists made up of the establishment a list
of entries. Each entry has a client/server
connection, an initial greeting from the server, unique name and client/server
interactions. These client/server interactions consist may contain any number
of a client
command, server data, named attributes. Each attribute within an entry may be single
valued or multi-valued and a server completion result.

All interactions transmitted by client may have associated metadata to assist
access and server are in the form interpretation of
lines; that is, strings that end the value.

The rules with which a CRLF. The protocol receiver
of an ACAP client or server is either reading a line, or is reading interprets the data within a
sequence portion of octets with a known count followed by a line. Both
clients and servers must be capable of handling lines
ACAP's tree 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 (typically a short alphanumeric string,
e.g., A0001, A0002, etc.) entries are called a "tag". A different tag dataset class.

1.3. ACAP Design Goals

ACAP's primary purpose is
generated by the client for each command.

There are two cases in which a line to allow users access to their
configuration data 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
<section>); multiple network-connected computers. Users
can then sit down in the other case, the command arguments require server
feedback (see the AUTHENTICATE command). In some front of these cases, the
server sends a command continuation request if any network-connected computer, run any
ACAP-enabled application and have access to their own configuration
data. Because it is ready for the
next part of the command. This response is prefixed with the token
"+".

Note: If, instead, the hoped that many applications will become ACAP-
enabled, client simplicity was preferred to server detected an error in the 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

Newman [Page 5] 3]

Internet DRAFT ACAP March 26, June 19, 1997

command, it sends a BAD completion response with tag
matching the command (as described below)

are included to reject the
command permit delegation of management and quotas are
included to prevent the client from sending any more of the
command.

It is also possible for the storage abuse. Finally, an ACAP server which is
conformant to send a completion or
intermediate response for some other command (if multiple
commands are this base specification should be able to support most
dataset classes defined in progress), or untagged data. In either
case, the command continuation request future without requiring a server
reconfiguration or upgrade.

ACAP is still pending; 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 takes may
detect changes. In addition, the appropriate action for client may ask the response,
and reads another response from server for a
list of entries which have been removed since it last accessed the
server.

The

ACAP server reads presumes that a command line from the client, parses dataset may be potentially large and/or the
command and its arguments,
client's network connection may be slow, and transmits thus offers server data
sorting, selective fetching and change notification for entries
within a server
command completion result.

2.2.2. Server Protocol Sender dataset.

As required for most Internet protocols, security, scalability and Client Protocol Receiver

Data transmitted by the server
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 client come successful IMAP [IMAP4] protocol framework, with a few minor
simplifications.

1.4. Validation

By default, any value may be stored in four forms:
command continuation requests, command completion results,
intermediate responses, any attribute for which the
user has appropriate permission and untagged responses.

A command continuation request quota. This rule is prefixed with the token "+".

A command completion result indicates necessary to
allow the success or failure addition of new simple dataset classes without
reconfiguring or upgrading the
operation. It is tagged with the same tag server.

In some cases, such as when the client command
which began the operation. Thus, if more than one command is in
progress, the tag in a server completion response identifies value has special meaning to the
command
server, it is useful to which have 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 enforce validation by
returning the context of INVALID response code to a command STORE command. These cases
MUST be explicitly identified in progress. It is tagged with the
same tag as the client command dataset class specification
which began 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 operation. Thus, if
more than one command is in progress, presence of enforced
validation on the tag in server.

1.5. Definitions

access control list (ACL)
A set of identifier, rights pairs associated with an intermediate
response identifies the command object. An

Newman [Page 4]

Internet DRAFT ACAP June 19, 1997

ACL is used to determine which the response applies. A
tagged response other than "OK", "NO", or "BAD" operations a user is permitted to
perform on that object. See section ###.

attribute
A named value within an intermediate
response.

An untagged response returns data or status messages entry. See section ###.

comparator
A named function which may can be
interpreted outside the used to perform one or more of
three comparison operations: ordering, equality and substring
matching. See section ###.

context
An ordered subset of entries in a dataset, created by a SEARCH
command in progress. It is
prefixed with the token "*". Untagged data may be sent as a result MAKECONTEXT modifier. See section ###.

dataset
One level of a client command, or may be sent unilaterally by hierarchy in ACAP's tree of entries. See section
###.

dataset class specification
The rules which allow a client to interpret the server.
There is no syntactic difference between untagged data that resulted
from within a specific command and untagged data that were sent

Newman [Page 6]

Internet DRAFT ACAP March 26, 1997

unilaterally.

The protocol receiver
portion of an ACAP client reads a response line from
the server. It then takes action on the response based upon the
first token ACAP's tree of the response, which may be a tag, a "*", or a "+" as
described above. entries.

entry
A client MUST be prepared to accept set of attributes with a unique entry name. See section ###.

metadata
Information describing an attribute, its value and any server response at all times.
This includes untagged data access
controls associated with that it may not have requested. attribute. See section ###.

NIL This topic is discussed in greater detail in represents the Server Responses
section.

2.3. State and Flow Diagram non-existence of a particular data item.

NUL A control character encoded as 0 in US-ASCII [US-ASCII].

octet
An ACAP server 8-bit value. On most modern computer systems, an octet is in
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 three states. Most commands are valid in
only certain states. It is a protocol error for the client Universal Character Set
[UTF8]. Note that an incompatible change was made to
attempt a command while the server is in an inappropriate state coded
character set referenced by [UTF8], so 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, purpose of this
document, UTF-8 refers to the user is authenticated UTF-8 encoding as defined by

Newman [Page 5]

Internet DRAFT ACAP June 19, 1997

version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646]
including amendments one through seven.

1.6. ACAP Command Overview

The AUTHENTICATE, NOOP, LANG and most LOGOUT commands
will be permitted. This state provide basic
protocol services. The SEARCH command is entered when acceptable
authentication credentials have been provided.

2.3.3. Logout State

In logout state, the session 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 being terminated, 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 will
close listens on port 674.

2.2. Commands and Responses

An ACAP session consists of the connection. This state can be entered as establishment of a result client/server
connection, an initial greeting from the server, and client/server
interactions. These client/server interactions consist of a client request or by unilateral
command, server decision.

Newman [Page 7]

Internet DRAFT ACAP March 26, 1997

+--------------------------------------+
|initial connection data, and a server greeting|
+--------------------------------------+
|| (1) || (2)
VV ||
+-----------------+ ||
|non-authenticated| ||
+-----------------+ ||
|| (4) || (3) ||
|| VV ||
|| +----------------+ ||
|| | authenticated | ||
|| +----------------+ ||
|| || (4) ||
VV VV VV
+--------------------------------------+
| logout completion result.

All interactions transmitted by client 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 form of the data
does not exceed the underlying transport's available window size, or
(2) use non-blocking writes.

2.4.3. Autologout Timer

If a server has an inactivity autologout timer,
lines; that timer MUST be of
at least 30 minutes' duration. is, strings that end with a CRLF. The receipt protocol receiver
of ANY command from the
client during that interval MUST suffice to reset the autologout
timer.

Newman [Page 8]

Internet DRAFT an ACAP March 26, 1997

2.4.4. Multiple Commands in Progress

The client or server 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, either reading a server line, or is
not required to process reading a command to completion before beginning
processing of the next command, unless an ambiguity would result
because
sequence of octets with a known count 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 that would affect the results begins an operation. Each client command is
prefixed with a identifier (an alphanumeric string of other commands.
If there no more than 32
characters, e.g., A0001, A0002, etc.) called a "tag". A different
tag is such an ambiguity, the server executes commands to
completion in the order given generated by the client.

2.5. Datasets and Entries

The primary data structure client for each command.

There are two cases in ACAP is the "dataset", which is a named
set of entries. Datasets are named hierarchically, with each
component of line from the name preceded by client does not
represent a slash ("/") and containing complete command. In one or
more UTF-8 characters (other than slash).

Each entry in a dataset is case, a set of attribute/value pairs. Each
attribute command argument is a hierarchical name in UTF-8,
quoted with each component of an octet count (see the
name being separated with a period ("."). Each attribute/value pair
may have additional metadata; this is described description of literal in section <section>.
There must be exactly one "entry" attribute, whose value is unique
amongst all entries

Newman [Page 6]

Internet DRAFT ACAP June 19, 1997

###); in the dataset and contains zero or more UTF-8
characters other than slash ("/") or dot (".").

Entries in a dataset are ordered in case, the command arguments require server
feedback (see the AUTHENTICATE command). In some of these cases, the
server sends a server-determined manner.

The value command continuation request if it is ready for the
next part of an attribute the command. This response is a string containing one or more octets.
The semantics of a value are defined by prefixed with the specification of its
attribute. Values of attributes ending token
"+".

Note: If, instead, the server detected an error in ".bin" contain arbitrary
data. Values of other attributes are textual and are restricted to
non-zero UTF-8 characters.

Attribute names are not permitted to contain "*", and entry names are
not permitted to begin with ".". Servers MUST return the
command, it sends a BAD completion result response with tag
matching the command (as described below) to clients which violate this.

2.6. Predefined Attributes

Attribute names which do not contain reject the
command and prevent the client from sending any more of the
command.

It is also possible for the server to send a dot (".") are reserved completion or
intermediate response for
standardized attributes which have meaning in any dataset. The
following attributes some other command (if multiple
commands are defined by in progress), or untagged data. In either
case, the ACAP protocol.

entry Contains command continuation request is still pending;
the name of client takes the entry.

modtime
Contains appropriate action for the date response,
and time, in UTC, any value or acl in reads another response from the

Newman [Page 9]

Internet DRAFT server.

The ACAP March 26, 1997

entry was last modified. This value is automatically updated
by server reads a command line from the client, parses the
command and its arguments, and transmits server data and may not be directly modified a server
command completion result.

2.2.2. Server Protocol Sender and Client Protocol Receiver

Data transmitted by the client.

The value consists of 14 or more US-ASCII digits. The first
four indicate server to the year, client come in four forms:
command continuation requests, command completion results,
intermediate responses, and untagged responses.

A command continuation request is prefixed with the next two indicate token "+".

A command completion result indicates the month, success or failure of the
next two indicate
operation. It is tagged with the day of month, same tag as the next two indicate client command
which began the
hour (0 - 23), operation. Thus, if more than one command is in
progress, the next two indicate tag in a server completion response identifies the minute, and
command to which the next
two indicate 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 second. Any further digits indicate
fractions of a second.

The time, particularly fractions context of a second, need not be
accurate. It is required, however, that any two entries command in a
dataset changed by successive modifications have strictly
ascending modtime values.

subdataset
If this attribute progress. It is set, it indicates tagged with the existence of a
sub-dataset of this entry.

The value consists of a list of CRLF separated relative ACAP
URLs (see section <section> for ACAP URL specification)
same tag as the client command which
may be used to locate where began the sub-dataset operation. Thus, if
more than one command is actually
stored. The base URL for in progress, the subdataset attribute is formed
by appending tag in an intermediate
response identifies the entry name followed by a "/" command to which the end of
the parent dataset name.

For example, if the dataset "/mailboxes/common" has response applies. A
tagged response other than "OK", "NO", or "BAD" is an entry
"public-folder" with a subdataset attribute of ".", then there
exists a dataset "/mailboxes/common/public-folder". If intermediate
response.

Newman [Page 7]

Internet DRAFT ACAP June 19, 1997

An untagged response returns data or status messages which may be
interpreted outside the
value context of the subdataset attribute was instead
"//other.acap.domain//mailboxes/common/public-folder" that
would indicate the dataset is actually located on a different
ACAP server.

A dataset is created by storing a "subdataset" attribute
including ".", and a sub-hierarchy of datasets command in progress. It is deleted by
clearing
prefixed with the value token "*". Untagged data may be sent as a result
of the "subdataset" attribute on the entry
in the upper dataset.

2.7. Attribute metadata

Each attribute/value pair a client command, or may have additional metadata associated
with it. For completeness, be sent unilaterally by the attribute server.
There is no syntactic difference between untagged data that resulted
from a specific command and value themselves are
defined as metadata. untagged data that were sent
unilaterally.

The defined items protocol receiver of metadata associated with

Newman [Page 10]

Internet DRAFT ACAP March 26, 1997 an attribute/value pair are:

attribute
The attribute name. Read-only.

value The value.

value<ORIGIN.SIZE>
A substring of the value. ORIGIN is specified as ACAP client reads a non-
negative decimal number indicating response line from
the octet position of server. It then takes action on the
first desired octet. An ORIGIN of 0 specifies response based upon the
first octet token of the value. SIZE is specified as response, which may be a positive, decimal
number, specifying the maximum number of octets desired. tag, a "*", or a "+" as
described above.

A
SIZE of 0 fetches all octets after the ORiGIN. Read-only.

size The length of the value, in octets. Read-only.

acl The access control list for the attribute/value pair, if one
exists. If the attribute/value pair does client MUST be prepared to accept any server response at all times.
This includes untagged data that it may not have an ACL, NIL requested.

This topic is returned. Read-write. See section <section> for discussed in greater detail in the
contents of an ACL.

myrights
The set Server Responses
section.

2.3. Server States

An ACAP server is in one of rights that three states. Most commands are valid in
only certain states. It is a protocol error for the client has to
attempt a command while the attribute/value
pair. Read-only. See section <section> for the possible
rights.

Additional items of metadata may be defined server is in extensions to an inappropriate state for
that command. In this
protocol. Servers must case, a server will respond to queries of unrecognized metadata
by returning with a BAD command
completion result.

2.8. Operational Command Overview

The AUTHENTICATE, NOOP, 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

2.3.1. Non-Authenticated State

In non-authenticated state, the user must supply authentication
credentials before most 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 will be permitted. This state is used to assist a client in resynchronizing
entered when a cache with connection starts.

2.3.2. Authenticated State

In authenticated state, the server. The SETQUOTA, GETQUOTA, SETACL, DELETEACL user is authenticated and MYRIGHTS most commands are used to examine or modifty quota usages and access
permissions.

3. Protocol Elements
will be permitted. This section defines data formats state is entered when acceptable
authentication credentials have been provided.

2.3.3. Logout State

In logout state, the session is being terminated, and other protocol elements used
throughout the ACAP protocol. server will
close the connection. This state can be entered as a result of a
client request or by unilateral server decision.

Newman [Page 11] 8]

Internet DRAFT ACAP March 26, June 19, 1997

3.1. Data Formats

ACAP uses textual commands

+--------------------------------------+
|initial connection and responses. Data in ACAP 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 be send data that the client did not request.

2.4.2. Response when No Command in one
of four forms: atom, number, string, parenthesized list, or NIL.

3.1.1. Atom

An atom consists of one Progress

Server implementations are permitted to 1024 non-special characters.

3.1.2. Number

A number consists of one or more digit characters, and represents a
numeric value.

3.1.3. String

A string send an untagged response
while there is no command in one progress. Server implementations that
send such responses MUST deal with flow control considerations.
Specifically, they must either (1) verify that the size of two forms: literal and quoted string. The
literal form is the general form 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 string. at least 30 minutes duration. The quoted string form
is an alternative receipt of ANY command from the
client during that avoids interval MUST suffice to reset the overhead auto-logout
timer.

Newman [Page 9]

Internet DRAFT ACAP June 19, 1997

2.4.4. Multiple Commands in Progress

The client is not required to wait for the completion result of processing a literal at
command before sending another command, subject to flow control
constraints on the cost of restrictions of what may be in underlying data stream. Similarly, a quoted string.

A literal server is
not required to process a sequence command to completion before beginning
processing of zero or more octets (including CR and LF),
prefix-quoted with an octet count in the form of next command, unless an open brace ("{"),
the number ambiguity would result
because of octets, close brace ("}"), and CRLF. In a command that would affect the case results of
literals transmitted from other commands.
If there is such an ambiguity, the server executes commands to client,
completion in the CRLF is immediately
followed order given by the octet data.

There are two forms of literals transmitted from client to server. client.

2.5. Server Command Continuation Request

The form where the open brace ("{") and number of octets command continuation request is
immediately followed indicated by a close brace ("}") and CRLF is called a
synchronizing literal. When sending "+" token instead
of a synchronizing literal, tag. This indicates that the
client must wait server is ready to receive accept the
continuation of a command continuation request (described
later from the client.

This response is used in this document) before sending the octet AUTHENTICATE command to transmit server
data (and the
remainder of the command). The other form of literal, to the non-
synchronizing literal, client, and request additional client data. This
response is also used if an argument to transmit any command is a string from
synchronizing literal.

The client is not permitted to
server without waiting for a command continuation request. The non-
synchronizing literal differs from send the octets of a synchronizing
literal by
having a plus ("+") between unless the number of octets and server indicates that it expects it. This permits
the close brace
("}") server to process commands and by having the octet data immediately following the CRLF.

A quoted string is reject errors on a sequence of zero to 1024 octets excluding CR,
LF, double quote (<">), or backslash ("\") with double quote (<">)
characters line-by-line
basis, assuming it checks for non-synchronizing literals at the end
of each end. line. The empty string is respresented as "" (a quoted string with zero

Newman [Page 12]

Internet DRAFT ACAP March 26, 1997

characters between double quotes), as {0} followed by CRLF (a
synchronizing literal with an octet count remainder of 0), or as {0+} followed
by a the command, including the CRLF (a non-synchronizing literal with an octet count that
terminates a command, follows the octets of 0).

Note: Even if the octet count is 0, a client transmitting a
synchronizing literal. If there
are any additional command arguments the literal must wait to receive octets are followed
by a command
continuation request.

3.1.3.1. 8-bit space and Binary Strings

ACAP implementations MAY transmit 8-bit octets 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 literals. Except ACAP can be in the values one
of attributes whose names end five forms: atom, number, string, parenthesized list or NIL.

Newman [Page 10]

Internet DRAFT ACAP June 19, 1997

2.6.1. Atom

An atom consists of one to 1024 non-special characters. It must
begin with ".bin", these octets a letter. Atoms are interpreted as UTF-8 character sequences [UTF-8]. NUL octets used for protocol keywords.

2.6.2. Number

A number consists of one or more digit characters, and represents a
numeric value. Numbers are
only permitted in restricted to the values range of attributes whose names end with
".bin". Servers SHOULD verify that any non-binary an unsigned
32-bit integer: 0 < number < 4,294,967,296.

2.6.3. String

A string sent by the
client has valid UTF-8 syntax before storing it.

3.1.4. Parenthesized List

Data structures are represented as a "parenthesized list"; a sequence is in one of data items, delimited by space, two forms: literal and bounded at each end by
parentheses. A parenthesized list can contain other parenthesized
lists, using multiple levels quoted string. The
literal form is the general form of parentheses to indicate nesting. string. The empty list quoted string form
is represented as () -- an alternative that avoids the overhead of processing a parenthesized list with no
members.

3.1.5 NIL

The special atom "NIL" represents literal at
the non-existence cost of restrictions of what may be in a particular
data item that quoted string.

A literal is represented as a string or parenthesized list, as
distinct from the empty string "" sequence of zero or more octets (including CR and LF),
prefix-quoted with an octet count in the empty parenthesized list ().

3.2. ACAP URL scheme

ACAP URLs are used within the ACAP protocol for form of an open brace ("{"),
the "subdataset"
attribute, referrals number of octets, close brace ("}"), and inheritance. They provide a convenient
syntax for referring CRLF. In the case of
literals transmitted from server to other ACAP datasets. The ACAP URL follows client, the common Internet scheme syntax as defined in [BASIC-URL]. If
:<port> CRLF is omitted, immediately
followed by the port defaults octet data.

There are two forms of literals transmitted from client to 674.

An ACAP URL has the following general form:

url-acap ::= "acap://" url-server "/" url-enc-entry [url-filter]

Newman [Page 13]

Internet DRAFT ACAP March 26, 1997 server.
The <url-server> element (defined below) includes form where the hostname, open brace ("{") and
optional user name, authentication mechanism number of octets is
immediately followed by a close brace ("}") and port number. The
<url-enc-entry> element contains CRLF is called a
synchronizing literal. When sending a synchronizing literal, the name of an entry path encoded
according
client must wait to the rules receive a command continuation request (described
later in [BASIC-URL].

The <url-filter> element is made up this document) before sending the octet data (and the
remainder of up to three components. the command). The
first other form of literal, the
non-synchronizing literal, is used to transmit a <url-attr-list> which specifies string from client
to server without waiting for a list of interesting
attributes. command continuation request. The second is <url-depth> which specifies the DEPTH of
non-synchronizing literal differs from the search. The final element is <url-enc-search> which 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 an
encoded version a sequence of search-criteria. The default values for these
fields are "*", "DEPTH=1", zero to 1024 octets excluding NUL,
CR and "ALL" respectively.

Note that unsafe or reserved LF, with double quote (<">) characters such 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 be
encoded according wait to the rules defined in [BASIC-URL]. Note that
octets encoded receive a command
continuation request.

Newman [Page 11]

Internet DRAFT ACAP June 19, 1997

2.6.3.1. 8-bit and Binary Strings

Most strings in the %A0 format with the high bit set ACAP are
interpreted according restricted to UTF-8 [UTF8].

3.2.1. ACAP URL User Name characters and Authentication Mechanism

A user name and/or authentication mechanism may be supplied. They not
contain NUL octets. Attribute values MAY contain any octets
including NUL.

2.6.4. Parenthesized List

Data structures 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 user name "anonymous" is used with the SASL XXX
mechanism and the password is supplied represented as the Internet e-mail address a "parenthesized list"; a sequence
of the end user accessing the resource. If the URL supplies just a
user name, the program interpreting the ACAP URL SHOULD request a
password from the user if necessary.

An authentication mechanism can be expressed data items, delimited by adding
";AUTH=<enc_auth_type>" to the space, and bounded at each end by
parentheses. A parenthesized list can contain other parenthesized
lists, using multiple levels of the user name. When such an
<enc_auth_type> parentheses to indicate nesting.

The empty list is indicated, represented as () -- a parenthesized list with no
members.

2.6.5. NIL

The special atom "NIL" represents the client SHOULD request appropriate
credentials from non-existence of a particular
data item that mechanism and use the "AUTHENTICATE" command.
If no user name is specified, one SHOULD be obtained from the
mechanism represented as a string or requested parenthesized list, as
distinct from the user as appropriate.

The empty string ";AUTH=*" indicates that "" or the client SHOULD select an
appropriate authentication mechanism. It MAY use any mechanism
listed in empty parenthesized list ().

3. Protocol Elements

This section defines data formats and other protocol elements used
throughout the initial ACAP response. If no user name is specified protocol.

3.1. Entries and no appropriate authentication mechanisms are available, the
client SHOULD fall back to anonymous login as described above. This
allows Attributes

Within a URL which grants read-write access to authorized users, and
read-only anonymous access to other users.

Note that if unsafe dataset, each entry name is made up of zero or reserved more UTF-8
characters such as " " or ";" are
present in other than slash ("/"). A slash separated list of
entries, one at each level of the user name or authentication mechanism, they MUST be
encoded as described in BASE-URL [BASE-URL].

Newman [Page 14]

Internet DRAFT ACAP March 26, 1997

3.2.2. Relative ACAP URLs

Because ACAP uses "/" as the hierarchy separator for dataset paths,
it works well with hierarchy, forms the relative URL rules defined in REL-URL [REL-
URL].

The <aauth> grammar element full path to
an entry.

Each entry is considered part made up of the user name for
purposes a set of resolving relative ACAP URLs.

The base URL for attributes. Each attribute has a relative URL stored
hierarchical name in UTF-8, with each component of the name separated
by a period (".").

The value of an attribute's attribute is either single or multi-valued. A single
value is
formed by taking the path to the dataset containing that attribute,
appending NIL (has no value), or a "/" followed by the entry name string of the entry containing
that attribute followed by "/".

3.3. Contexts zero or more octets. A context
multi-value is an ordered subset a list of entries 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 dataset, created by a
SEARCH command with a MAKECONTEXT modifier. Context BAD response. Entry names
are
client-generated strings and must not start permitted to begin with the "." or contain slash ('/')
character.

Contexts only have scope within the ("/") and MUST
be valid UTF-8 strings which do not contain NUL. Invalid entry names

Newman [Page 12]

Internet DRAFT ACAP session June 19, 1997

in which they were
created. There is a server-imposed limit on the number entry field of contexts
that may exist at one time within a session. The minimum value for
this limit is 100, if the server supports a larger limit it must
advertise it command result in a CONTEXTLIMIT capability.

3.4. Orderings

An ordering BAD response.

Use of non-visible UTF-8 characters in attribute and entry names is a named collation function
discouraged.

3.1.1. Predefined Attributes

Attribute names which takes two input
strings and determines whether they are greater than, less than, or
equal to each other. Orderings do not contain a dot (".") are used both for simple equality
searching, for ordinal comparision searching and reserved for sorting of
attributes. An ordering is prefixed by either "+" or "-". If
prefixed by "-", then the order is reversed. In all collation
functions, NIL is always less than any other value and is equal only
to itself.

Additional ordering functions may be registered with IANA according
to the rules
standardized attributes which have meaning in section <section>. any dataset. The
following ordering functions attributes are defined by this standard:

octet The octet ordering function interprets the value ACAP protocol.

entry
Contains the name of an the entry. MUST be single valued.
Attempts to use illegal or multi-valued values for the entry
attribute as are protocol errors and MUST result in a series of unsigned octets with ordinal values
from 0 to 255. Each octet pair BAD
completion response. This is compared a special case.

modtime
Contains the date and time any read-write metadata in sequence
until the octets are unequal or entry
was last modified. This value MUST be in UTC, MUST be
automatically updated by the end server.

The value consists of 14 or more US-ASCII digits. The first
four indicate the string is
reached. When collating year, the next two strings where indicate the shorter is a

Newman [Page 15]

Internet DRAFT ACAP March 26, 1997

prefix of month, the longer,
next two indicate the shorter string is interpreted as
having a smaller ordinal value. The +octet form collates
smaller ordinal values earlier, and the -octet form collates
larger ordinal values earlier. For non-binary values, the
+octet ordering is equivalent to the ANSI C strcmp()
function applied to C string representations day of month, the values.

en-nocase
The en-nocase ordering function first applies a mapping to next two indicate 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
hour (0 - 23), the
octet ordering function as described above. With this
function next two indicate the values "hello" minute, and "HELLO" have the same
ordinal value and are considered equal.

numeric next
two indicate the second. Any further digits indicate fractions
of a second.

The numeric ordering function assigns ordinal values based
on time, particularly fractions of a US-ASCII encoded decimal positive integer
interpretation. With the numeric function, all values which
do second, need not begin with be
accurate. It is REQUIRED, however, that any two entries in a digit are considered equal
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 MUST result in a NO response with an
ordinal
INVALID response code.

subdataset
If this attribute is set, it indicates the existence of a sub-
dataset of this entry.

The value consists of -1. Otherwise, all US-ASCII digits (octet
values 0x30 a list of relative ACAP URLs (see section
###) which may be used to 0x39) are interpreted starting from locate the
beginning of sub-dataset. The base URL
is the string full path to the first non-digit or the end of
the string.

3.5. Server Status Responses

An OK, NO or BAD response from the server, whether tagged or
untagged, is considered a status response. Status responses may
include an optional response code. A response code consists of data
inside parentheses in the form of an atom, possibly entry followed by a
space and arguments. The response code contains additional
information or status codes for client software beyond the OK/NO/BAD
condition, and are defined when there is a specific action that a
client can take based upon the additional information.

The currently defined response codes are:

ALERT slash ("/"). The human-readable text contains a special alert
that MUST be presented to the user in a fashion
that calls the user's attention to the message.

MODIFIED This response code
value "." indicates that a conditional
store failed because the MODTIME on the entry subdataset is
later than the modtime specified with the STORE located directly under this

Newman [Page 16] 13]

Internet DRAFT ACAP March 26, June 19, 1997

command.

PERMISSION A STORE, SETQUOTA, or SETACL command failed due to
insufficient permission.

QUOTA A STORE command which would have increased the size

one. Multiple values indicate replicated copies of the
subdataset.

For example, if the dataset failed due to insufficient quota.

REFER This response code may be returned in "/folder/site/" has an entry
"public-folder" with a tagged NO
response to any command that takes subdataset attribute of ".", then there
exists a dataset name
as a parameter. It has one argument with "/folder/site/public-folder/". If the
syntax value of a relative URL. It is a referral,
indicating that
the command should be retried using subdataset attribute was instead
"//other.acap.domain//folder/site/public-folder/" that would
indicate the dataset named in the relative URL.

TOOMANY This response code may be returned in a tagged OK
response to is actually located on a SEARCH command which includes the
LIMIT modifier. The argument returns the number of
matching entries.

TRYFREECONTEXT This response code may different ACAP
server.

A dataset can be returned in created by storing a tagged NO
respose to "subdataset" attribute
including ".", and a SEARCH command which includes the
MAKECONTEXT modifier. It indicates that sub-hierarchy of datasets is deleted by
storing a new
context may not be created due NIL value to the server's
limit "subdataset" attribute on the number of existing contexts.

WAYTOOMANY This response code may be returned entry
in a tagged OK
response the parent dataset.

This attribute has enforced syntax validation. Specifically, if
an attempt is made to STORE a SEARCH command which includes a
HARDLIMIT search modifier. It indicates that the
SEARCH would have returned more entries single-value (other than NIL), an
empty list, or one of the
hardlimit permitted.

Additional values does not follow the URL syntax
rules [BASIC-URL], then this will result in a NO response codes defined by particular client or server
implementations should be prefixed with
an "X" until they are
added to a revision of this protocol. Client implementations MUST
ignore INVALID response codes that they do not recognize.

3.6. Server Command Continuation Request

The command continuation request code.

3.1.2. Attribute metadata

Each attribute is indicated by a "+" token instead made up of a tag. This indicates metadata items which describe that
attribute, its value and any associated access controls. Metadata
items may be either read-only in which case the server client is ready never
permitted to accept modify the
continuation of a command from item, or read-write, in which case the client. The remainder of this
response is a line of text.

This response is used 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 AUTHENTICATE command to transmit server
data to attribute, if one exists. If
the client, and request additional client data. This
response attribute does not have an ACL, NIL is also used if returned.
Read-write. See section ### for the contents of an argument ACL.

attribute
The attribute name. Read-only.

myrights
The set of rights that the client has to any command the attribute.
Read-only. See section ### for the possible rights.

size This is the length of the value. In the case of a
synchronizing literal.

Newman [Page 17] 14]

Internet DRAFT ACAP March 26, June 19, 1997

multi-value, this is a list of lengths for each of the values.

value The client value. For a multi-value, this is not permitted a list of single
values.

Additional items of metadata may be defined in extensions to send the octets this
protocol. Servers MUST respond to queries of unrecognized metadata
by returning a synchronizing
literal unless BAD command completion result.

3.2. ACAP URL scheme

ACAP URLs are used within the server indicates that it expects it. This permits ACAP protocol for the server to process commands "subdataset"
attribute, referrals and reject errors on inheritance. They provide a line-by-line
basis, assuming it checks convenient
syntax for non-synchronizing literals at the end
of each line. referring to other ACAP datasets. The remainder of the command, including the CRLF that
terminates a command, ACAP URL follows
the octets of the literal. common Internet scheme syntax as defined in [BASIC-URL]. If there
are any additional command arguments
:<port> is omitted, the literal octets are followed
by a space and those arguments.

Newman [Page 18]

Internet DRAFT ACAP March 26, 1997

4. Protocol Specification port defaults to 674.

An ACAP commands URL has the following general form:

url-acap = "acap://" url-server "/" url-enc-entry [url-filter]

The <url-server> element includes the hostname, and responses are described in this section. Commands
are organized first by optional user
name, authentication mechanism and port number. The <url-enc-entry>
element contains the state in which name of an entry path encoded according to the command
rules in [BASIC-URL].

The <url-filter> element is permitted,
then by a general category an optional list of command type.

Command arguments, identified by "Arguments:" in interesting attribute
names. If omitted, the command
descriptions below, are described by function, not by syntax. The
precise syntax URL refers to all attributes of command arguments is the named
entry.

Note that unsafe or reserved characters such as " " or "?" MUST be
hex encoded as described in the Formal Syntax
section.

Some commands cause specific server data 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 returned; these supplied. They
are
identified by "Data:" used in the "AUTHENTICATE" command descriptions below. See the
response descriptions in after making the Responses section for information on
these responses, and connection to
the Formal Syntax section for ACAP server. If no user name or authentication mechanism is
supplied, then the precise syntax
of these responses. It SASL ANONYMOUS [SASL-ANON] mechanism 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 used by
default. If the possible
tagged status responses to URL supplies just a command, and any special interpretation
of these status responses.

4.1. Initial Connection

Upon session startup, user name, the program
interpreting the server sends one of two untagged responses:
ACAP or BYE. The untagged BYE response is described in section
<section>.

4.1.1. ACAP Untagged Response

Data: capability list

The untagged ACAP response indicates URL SHOULD request a password from the session is ready user if
necessary.

An authentication mechanism can be expressed by adding
";AUTH=<enc_auth_type>" to
accept commands and contains a space-separated listing the end of
capabilities that the server supports. Each capability is user name. When such an atom
name, possibly followed by a string argument in parenthesis.

ACAP capability names MUST be defined in a standards track or IESG
approved experimental RFC and registered with IANA according to
<enc_auth_type> is indicated, the rules in section <section>.

Client implementations client SHOULD NOT require any capability name, request appropriate
credentials from that mechanism and
MUST ignore any unknown capability names. use the "AUTHENTICATE" command.

Newman [Page 19] 15]

Internet DRAFT ACAP March 26, June 19, 1997

The following initial capabilities are defined:

CONTEXTLIMIT
The CONTEXTLIMIT capability has one argument which

If no user name is a
number describing specified, one SHOULD be obtained from the maximum number of contexts
mechanism or requested from the server
supports per connection. user as appropriate.

The number 0 indicates string ";AUTH=*" indicates that the server
has client SHOULD select an
appropriate authentication mechanism. It MAY use any mechanism
listed in the initial ACAP response. If no limit, otherwise this number MUST be greater than
100.

IMPLEMENTATION
The IMPLEMENTATION capability has one argument which user name is specified
and no appropriate authentication mechanisms are available, the
client SHOULD fall back to anonymous login as described above. This
allows a
string describing URL which grants read-write access to authorized users, and
read-only anonymous access to other users.

Note that if unsafe or reserved characters such as " " or ";" are
present in the server implementation. ACAP clients user name or authentication mechanism, they MUST NOT alter their behavior based on this value. It is
intended primarily be
encoded as described in the URL specification [BASIC-URL].

3.2.2. Relative ACAP URLs

Because ACAP uses "/" as the hierarchy separator for debugging purposes.

ORDERINGS dataset paths,
it works well with the relative URL rules defined in the relative URL
specification [REL-URL].

The ORDERINGS capability includes a list <aauth> grammar element is considered part of the
ordering/comparison functions which the server supports.
See section <section> user name for a description
purposes of
ordering/comparison functions.

SASL resolving relative ACAP URLs.

The SASL capability includes base URL for a list of relative URL stored in an attribute's value is
formed by taking the authentication
mechanisms supported path to the dataset containing that attribute,
appending a "/" followed by the server. See [SASL] for more
information.

Example: S: * OK IMPLEMENTATION("ACME v3.5") SASL("CRAM-MD5"
"GSSAPI")

4.2. Any State

The following commands and responses are valid in any state.

4.2.1. NOOP Command

Arguments: none

Data: no specific data for this command (but see below)

Result: OK - noop completed
BAD - command unknown entry name of the entry containing
that attribute followed by "/".

3.3. Contexts

A context is subset of entries in a dataset or arguments invalid

The NOOP datasets, created by a
SEARCH command always succeeds. It does nothing. It can be 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 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 [Page 20] 16]

Internet DRAFT ACAP March 26, June 19, 1997

3.4. Comparators

A comparator is a named function which takes two input values and can
be used to reset any inactivity autologout timer on the server.

Example: C: a002 NOOP
S: a002 OK "NOOP completed"

4.2.2. LOGOUT Command

Arguments: none

Data: mandatory untagged response: BYE

Result: OK - logout completed
BAD - command unknown perform one or arguments invalid more of three comparison operations:
ordering, equality and substring matching.

The LOGOUT command informs the server that the client ordering operation is done with used both for the session. The server must send a BYE untagged response before SORT search modifier and
the (tagged) OK response, COMPARE and then close COMPARESTRICT search keys. Ordering comparators can
determine 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)

4.2.3. 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 ordinal precedence of the associated
command. The human-readable text may any two values. When used for
ordering, a comparator's name can be presented prefixed with "+" or "-" to
indicate that the user 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 information message. The untagged form indicates an
information-only message; the nature 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 information may be
indicated by a response code.

Example: S: * OK (ALERT) "System shutdown in 10 minutes"

4.2.4. NO Response

Data: optional response code
human-readable text

The NO response indicates comparator
definition specifies otherwise, multi-values and NIL values have an operational error message from
undefined ordinal precedence.

The equality operation is used for the
server. EQUAL search modifier, and
simply determines if the two values are considered equal under the
comparator function. When tagged, it indicates unsuccessful completion comparing a single value to a multi-value,
the two are considered equal if any one of the
associated command. The untagged form indicates a warning; multiple values is
equal to the

Newman [Page 21]

Internet DRAFT ACAP March 26, 1997

command may still complete successfully. single value.

The human-readable text
describes substring match operation is used for the condition.

Example: C: A001 NOOP
S: * NO (ALERT) "Dataset '/addressbook/user/fred' PREFIX and SUBSTRING
search modifiers, and simply determines if search value is at
98% a prefix
or a substring of quota"
S: A001 OK "NOOP"
...
C: A222 STORE ("/mailboxes/comp.mail.misc"
"mailbox.creation-time"
"19951206103412")
S: A222 NO (PERMISSION) "Permission denied"

4.2.5. 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 item being searched. In the error. The untagged
form indicates case of substring
search on 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 multi-valued attribute, 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"

4.2.6. BYE Untagged Response

Data: optional response code
human-readable text

The untagged BYE response indicates that match is successful if the server
value is about to
close a prefix or substring of any one of the connection. The human-readable text multiple values.

Additional comparators may be displayed registered with the Internet Assigned
Number Authority (IANA) according to the user rules in a status report by the client. The BYE response may
be sent as part of a normal logout sequence, section ###.
Servers MUST respond to unknown or as improperly used comparators with a panic
shutdown announcement
BAD command completion result.

The following comparators are defined by this standard:

octet
Operations: Ordering, Equality, Substring match

For collation, the server. It is also used by some
server implementations as an announcement octet comparator interprets the value of
an inactivity
autologout.

This response is also used attribute as one a series of unsigned octets with ordinal
values from 0 to 255. When ordering two possible greetings at

Newman [Page 22]

Internet DRAFT ACAP March 26, 1997

session startup. It indicates that the server is not willing to
accept a session from this client.

Example: S: * BYE "Autologout; idle for too long"

4.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. The convention is to use an AUTHENTICATE command with
the userid "anonymous" with the SASL XXX mechanism.

Once authenticated (including as anonymous), it strings, each octet
pair is not possible to
re-enter non-authenticated state.

In addition to the universal commands (NOOP and LOGOUT), compared in sequence until the
following commands octets are valid in non-authenticated state:
AUTHENTICATE.

4.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 unequal or arguments invalid,
authentication exchange cancelled

The AUTHENTICATE command indicates an 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 end of the requested authentication mechanism string is not supported, the
server rejects reached. When collating two strings
where the AUTHENTICATE command by sending a tagged NO
response.

The authentication protocol exchange consists of shorter is a series prefix of the longer, the shorter

Newman [Page 23] 17]

Internet DRAFT ACAP March 26, June 19, 1997

server challenges

string is interpreted as having a smaller ordinal value. The
"octet" or "+octet" forms collate smaller ordinal values
earlier, 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
BASE64 encoded string. The client answer consists of a line
consisting of a BASE64 encoded string. If "-octet" form collates larger ordinal values
earlier.

For the client wishes to
cancel an authentication exchange, it should issue a line with a
single "*". If equality function, two strings are equal if they are
the server receives such an answer, it must reject same length and contain the AUTHENTICATE command by sending a tagged BAD response.

The optional initial-response argument to same octets in the AUTHENTICATE command same
order. NIL is used equal only to save a round trip when using authentication mechanisms
that are defined itself.

For non-binary, non-nil single values, octet ordering is
equivalent to send no data in the initial challenge. When the initial-response argument is used with such a mechanism, ANSI C [ISO-C] strcmp() function applied to
C string representations of the
initial empty challenge values. For non-binary,
non-nil single values, octet substring match is not sent equivalent to
the client and the server
uses the data in the initial-response argument as if it were sent
in response ANSI C strstr() function applied to the empty challenge. If C string
representations of the initial-response
argument values.

en-nocase
Operations: Ordering, Equality, Substring match

The en-nocase comparator first applies a mapping to the AUTHENTICATE command is used with a mechanism
that sends data in
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 initial challenge, octet
comparator as described above. With this function the server rejects values
"hello" and "HELLO" have the
AUTHENTICATE command by sending a tagged NO response. same ordinal value and are
considered equal.

numeric
Operations: Ordering, Equality

The service name specified by this protocol's profile of SASL is
"acap".

If numeric comparator interprets strings as decimal positive
integers represented as US-ASCII digits. All values which do
not begin with a security layer is negotiated through the SASL authentication
exchange, it takes effect immediately following US-ASCII digit are considered equal with an
ordinal value higher than all non-NIL single-valued
attributes. Otherwise, all US-ASCII digits (octet values
0x30 to 0x39) are interpreted starting from the CRLF that
concludes beginning of
the authentication exchange for string to the client, and first non-digit or the CRLF end of the tagged OK response for the server.

The server string.

3.5. Access Control Lists (ACLs)

An access control list is not required a set of identifier,rights pairs used to support any particular
authentication mechanism, nor are authentication mechanisms
required
restrict access to support any protection mechanisms. If a given dataset, attribute or attribute within an AUTHENTICATE
command fails
entry. An ACL is represented by a multi-value with each value
containing the identifier followed by a NO response, tab character followed by the client may try another
authentication mechanism
rights. The syntax is defined by issuing another AUTHENTICATE command.
In other words, the client may request authentication types "acl" rule in
decreasing order of preference.

Example: S: * OK IMPLEMENTATION("Blorfysoft v3.5")
SASL(KERBEROS_V4)
C: A001 AUTHENTICATE KERBEROS_V4
S: + AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: A001 OK "Kerberos V4 authentication successful"

Note: the line breaks formal syntax
in the first client answer are for section ###.

Newman [Page 24] 18]

Internet DRAFT ACAP March 26, June 19, 1997

editorial clarity and are not in real authenticators.

4.4. Searching

This section describes the SEARCH command, for retrieving data from
datasets.

4.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

Identifier is a dataset and
returns information on that subset UTF-8 string. The identifier "anyone" is reserved to
refer to the client.

The first argument universal identity (all authentications, including
anonymous). All user name strings accepted by the AUTHENTICATE
command to SEARCH identifies what is authenticate to be searched.
If the string begins ACAP server are reserved as
identifiers for the corresponding user. Identifiers starting with a slash ("/"), it
dash ("-") are reserved for "negative rights", described below. All
other identifier strings have implementation-defined meanings.

Rights is the name of a
dataset to be searched, otherwise it is string listing a name (possibly empty) set of alphanumeric
characters, each character listing a context that
was created 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 SEARCH command given previously in the session.

A successful SEARCH command MUST result in a MODTIME intermediate
response.

Following that
standards-track or IESG approved experimental RFC. Digits are zero
reserved for implementation or more modifiers to the search. Each
modifier may be specified at most once. site defined rights. The currently
defined modifiers standard rights are:

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

r - read
w - write
i - insert (perform store on a previously NIL value)
a - administer (perform store on ACL attribute/metadata)

An implementation may force rights to always or never be
searched. If granted. In
particular, implementations are expected to grant implicit read and
administer rights to a user's personal dataset is traversed which is not
located on storage in order to
avoid denial of service problems. Rights are never tied, unlike the current server, then a REFER
intermediate response
IMAP ACL extension [IMAP-ACL].

It is returned possible for that subtree
and the search continues.

Newman [Page 25]

Internet DRAFT ACAP March 26, 1997

If this is used multiple identifiers in combination with an access control list to
apply to a SORT or
MAKECONTEXT operator, given user (or other authentication identity). For
example, an ACL may include rights to be granted to the server MUST return a BAD
command completion result.

HARDLIMIT number
If identifier
matching the SEARCH command would result in user, one or more than
number entries, implementation-defined identifiers
matching groups which include the SEARCH fails with a NO
completion result with a WAYTOOMANY response code.

LIMIT number number
Limits user, and/or the number of intermediate ENTRY responses
that identifier
"anyone". How these rights are combined to determine the search user's
access is implementation-defined. An implementation may generate. The first numeric
argument specifies the limit, the second number
specifies the number of entries choose, for
example, to return if use the
number union of matches exceeds the limit. If rights granted to 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 context
The SEARCH command creates a context with the name
given in the argument applicable
identifiers. An implementation may instead choose, for example, to refer
only use those rights granted to the matching
entries.

If the SEARCH is successful, most specific identifier present
in the context name ACL. A client may
then be given as an argument to subsequent SEARCH
commands to search determine the set of matching entries.

If rights granted to the
logged-in user for a context with given mailbox by using the specified name already
exists, it is first freed. If MYRIGHTS command.

When an identifier in an ACL starts with a new context may
not be created due dash ("-"), that indicates
that associated rights are to be removed from the server's limit on identifier that is
prefixed by the
number of existing contexts, dash. For example, if the command fails,
returning a TRYFREECONTEXT response code in identifier "-fred" is
granted the
tagged NO response.

Contexts are discussed in more detail in section
<section>.

NOTIFYCONTEXT Requests "w" right, that indicates that the server send untagged ADDTO,
REMOVEFROM, CHANGE, and MODTIME responses while "w" right is to be
removed from users matching the
context created or referenced by this SEARCH
command exists. The server MAY issue untagged
ADDTO, REMOVEFROM, CHANGE and MODTIME notifications
for identifier "fred". Implementations
need not support having identifiers which start with a context at any time between the issuing dash in ACLs.

Each attribute of
the SEARCH command with NOTIFYCONTEXT and the
completion each entry of a FREECONTEXT command for the
context. After issuing a sequence of ADDTO,
REMOVEFROM or CHANGE notifications, the server MUST dataset may potentially have an

Newman [Page 26] 19]

Internet DRAFT ACAP March 26, June 19, 1997

issue

ACL. If an untagged MODTIME notification indicating attribute in an entry does not have an ACL, then access
is controlled by a default ACL for that attribute in the client has all updates to the entries dataset, if
it exists. If there is no default ACL for that attribute in the context up
dataset, access is controlled by a default ACL for that dataset. The
default ACL for a dataset must exist.

In order to and including perform any access or manipulation on an entry in a
dataset, the given modtime
value.

The client MAY issue a subsequent SEARCH must have 'r' rights on the
context with a NOTIFYCONTEXT modifier, and this MAY
be used "entry" attribute of
the entry. Implementations should take care not to change reveal via error
messages the list existence of attributes and
metadata included an entry for which the client does not have
attribute of the parent dataset in ADDTO order to access the contents of a
dataset.

Many of the ACL commands and CHANGE responses include an "acl object"
parameter, for
the context.

RETURN (metadata...)
Specifies specifying what is to be returned in intermediate
ENTRY responses. If this modifier is not
specified, no intermediate ENTRY responses are
returned.

Inside the parentheses ACL applies to. This is a list of attributes,
each optionally followed by a
parenthesized list. The list of
metadata. If contains just the parenthesized list of metadata is
not specified, it defaults to "(value)".

An attribute dataset name with when
referring to the default ACL for a trailing "*" requests all
attributes with that prefix. A "*" by itself
requests all attributes. If the parenthesized dataset. The list
of metadata is not specified for contains a
dataset name and an attribute with
a trailing "*", it defaults to "(attribute value)".

Following the last intermediate ENTRY response, the
server returns a single intermediate MODTIME
response.

SORT (attribute ordering...)
Specifies the order in which any resulting ENTRY
replies are to be returned name when referring to the client. The SORT
modifier takes as default ACL
for an argument attribute in a parenthesized dataset. The list
of one or more attribute/ordering pairs. Attribute
lists the contains a dataset name, an
attribute to sort on, ordering specifies
the name, and an entry name of the collation rule to apply when referring to the
values 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 attribute. Successive
attribute/ordering pairs are used server MAY contain a
response code to order two
entries only when all preceeding pairs indicate describe the
two entries collate the same.

If the SORT modifier is used event in conjunction with
the MAKECONTEXT modifier, the SORT modifier
specifies the ordering a more detailed machine
parsable fashion. A response code consists of entries data inside
parentheses in the created
context.

Newman [Page 27]

Internet DRAFT ACAP March 26, 1997

If no SORT modifier is specified, or none form of the
attribute/ordering pairs indicates an order for the
two entries, the server uses the order of the
entries that exists in the context or dataset being
searched.

Following the modifiers 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 search criteria. Searching
criteria consist of one or more search keys. Search keys may be
combined using the AND, and OR search keys. For example, the
criteria (the newline is for readability and not part of the
criteria):
AND COMPARE modtime +octet "19951206103400"
COMPARE modtime -octet "19960112000000"
refers to all entries modified between 10:34 December 6 1995 and
midnight January 12, 1996 UTC. additional information.

The currently defined search keys are as follows.

ALL response codes are:

ENCRYPT-NEEDED
This matches all entries.

AND search-key1 search-key2
Entries response code is returned on a tagged NO result from an
AUTHENTICATE command. It indicates that match both search keys.

COMPARE attribute ordering value
Entries for which site security policy
requires the specified attribute collates using use of a strong encryption mechanism for the
specified ordering authentication identity.

INVALID
This response code indicates that a STORE command included
data which the same or later than server implementation does not permit. It
MUST NOT be used unless the specified
value.

COMPARESTRICT attribute ordering value
Entries dataset class specification for which
the specified attribute collates using the
specified ordering later than in question explicitly permits enforced server

Newman [Page 20]

Internet DRAFT ACAP June 19, 1997

validation. The argument is the specified value.

EQUAL attribute ordering value
Entries for which was invalid.

MODIFIED
This response code indicates that a conditional store failed
because the specified attribute collates using modtime on the entry is later than the modtime
specified ordering with the same as STORE command UNCHANGEDSINCE modifier.
The argument is the specified value.

NOT search-key
Entries entry which had been modified.

NOEXIST
This response code indicates that do a search or NOCREATE store
failed because a specified dataset did not match exist. The
argument is the specified search key.

OR search-key1 search-key2
Entries that match either search key.

RANGE start end time
Entries dataset which are within the specified range of does not exist.

PERMISSION
A command failed due to insufficient permission based on the context's
ordering.
access control list or implicit rights. The lowest-ordered entry in the context argument is
assigned number one, the next lowest entry is assigned number
two, and so on. The numeric arguments specify
acl-object which caused the lowest and

Newman [Page 28]

Internet DRAFT ACAP March 26, 1997

highest numbers to match. The time specifies permission failure.

PLAINTEXT-DENIED
This response code is returned on a tagged NO result from an
AUTHENTICATE PLAIN command. It indicates that site security
policy forbids the client
has processed notifications use of plain text passwords for the context up to the
specified time. If authentication identity.

QUOTA
A STORE command which would have increased the context has been modified since then, size of the server MUST either return
dataset failed due to insufficient quota.

REFER
This response code may be returned in a tagged NO with a MODIFIED response
code, or return the results to
any command that takes a dataset name as a parameter. It has
one or more arguments with the SEARCH would have
returned if none syntax of the changes since that time had been
made.

RANGE is only permitted on contexts. If RANGE relative URLs. It
is used with a
dataset, referral, indicating that the server MUST return a BAD command completion
result.

Example: C: [TODO - write examples]

4.4.2. ENTRY Intermediate Response

Data: entry name
entry data

The ENTRY intermediate should be retried
using one of the relative URLs.

TOOMANY
This response occurs as code may be returned in a result of tagged OK response to
a SEARCH
command. This is the means by command which dataset entries are returned
to includes the client. LIMIT modifier. The entry with the given name matches the search.
Following
argument returns the entry name is a set total number of zero or more strings, each
containing the respective metadata, contained in the entry, that
was specified in the RETURN search modifier.

4.4.3. MODTIME Intermediate Response

Data: modtime value

The MODTIME intermediate matching entries.

TRANSITION-NEEDED
This response code occurs as on a result of NO response to an AUTHENTICATE
command with a SEARCH
command. mechanism other than PLAIN or ANONYMOUS. It
indicates that the just created context or the
previously returned ENTRY responses include all updates PLAIN SASL [SASL-PLAIN] mechanism is
needed prior to using the
returned entries up stronger mechanism requested.

TRYCACHE
A STORE or SETACL command failed due to and including a temporary server

Newman [Page 21]

Internet DRAFT ACAP June 19, 1997

failure. If the modtime value in client caches the
argument.

4.4.4. REFER Intermediate Response

Data: dataset path
ACAP URL

The REFER intermediate command, it may succeed
during a later cache replay.

TRYFREECONTEXT
This response occurs as code may be returned in a result of tagged NO response to
a multi-
level SEARCH where one of command which includes the levels is located on a different
server. The reponse MAKECONTEXT modifier. It
indicates the dataset which is that a new context may not located be created due to the
server's limit on the current server and an ACAP URL for where that dataset number of existing contexts.

WAYTOOMANY
This response code may be
found.

Newman [Page 29]

Internet DRAFT ACAP March 26, 1997

4.5. Contexts

The following commands use contexts created by returned in a tagged NO response to
a SEARCH command with which includes a MAKECONTEXT HARDLIMIT search modifier.

4.5.1. FREECONTEXT Command

Arguments: context name

Data: no specific data for this command

Result: OK - freecontext completed
NO - freecontext failure: no such context
BAD - command unknown or arguments invalid

The FREECONTEXT command causes
It indicates that the server to free all state
associated SEARCH would have returned more entries
than the HARDLIMIT permitted.

Additional response codes MUST be registered with IANA according
to the named context. proceedures in section ###. Client implementations MUST
ignore response codes that they do not recognize.

4. Namespace Conventions

4.1. Dataset Namespace

The context may no longer be
searched and dataset namespace is a slash-separated hierarchy. The first
component of the server will no longer issue any untagged
responses dataset namespace is a dataset class. Dataset
classes MUST have a vendor prefix (vendor.<vendor/product>) or be
standards track or IESG approved experimental RFCs. See section ###
for the context. registration template.

The context is no longer counted
against second component of the server's limit on 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 number of contexts.

Example: C: A683 FREECONTEXT "blurdybloop"
S: A683 OK "Freecontext completed"

4.5.2. UPDATECONTEXT Command

Arguments: list third component of context names

Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME

Result: OK - Updatecontext completed: all updates completed
NO - Updatecontext failed: no such context
BAD - command unknown the
path is the group name, the fully qualified host domain name, or arguments invalid

The UPDATECONTEXT command causes the server to ensure that
user name. A path of the
client form "/<dataset-class>/~/" is notified a convenient
abbreviation for "/<dataset-class>/user/<current-user>/".

Dataset names which begin with "/byowner/" are reserved as an
alternate view of all changes to the contexts listed as
arguments up namespace. This provides a way to see all the current time. The contexts listed in the
arguments must have been previously given
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 successful SEARCH
command with list of dataset classes
owned by a NOTIFYCONTEXT modifier. A MODTIME untagged
response MUST be returned if any read-write metadata in given user; this is done using the dataset changed since
"/byowner/user/<current-user>/" with the last MODTIME on that context. This
includes metadata which is not listed in NOINHERIT SEARCH modifier.

The dataset "/" may be used to find all dataset classes visible to
the RETURN modifier on current user. A dataset of the last SEARCH command with a NOTIFYCONTEXT modifier for this
context.

While a server form "/<dataset-class>/user/" may issue untagged ADDTO, REMOVEFROM, CHANGE, and

Newman [Page 30] 22]

Internet DRAFT ACAP March 26, June 19, 1997

MODTIME at any time, the UPDATECONTEXT command is used to "prod"
the server to send any notifications it has not sent yet.

The UPDATECONTEXT command SHOULD NOT

be used to poll for updates.

Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl"
S: Z4S9 OK "client has been notified of find all changes"

4.5.3. ADDTO Untagged Response

Data: context name users which have made a dataset or entry name
position
metadata list

The untagged ADDTO response informs the client of that an entry has
been added
class visible to a context. The response includes the position
number of the added entry (the first entry in the context current user.

The formal syntax for a dataset name is
numbered 1) and those metadata contained in the entry which match defined by the RETURN statement specified "dataset-name"
terminal in the last SEARCH command on the
context with section ###.

4.2. Attribute Namespace

Attribute names which do not contain a NOTIFYCONTEXT search modifier.

The ADDTO response implicitly adds one to the position of all
members of the context dot (".") are reserved for
standardized attributes which had position numbers that were
greater than or equal to the ADDTO position number.

Example: S: * ADDTO "blurdybloop" "fred" 15 ("addressbook.email"
"fred@rock.org")

4.5.4. REMOVEFROM Untagged Response

Data: context name
entry name
old position

The untagged REMOVEFROM response informs the client that an entry
has been removed from a context. The response includes the
position number that the removed entry used to have (the first
entry meaning in any dataset. In order
to simplify implementations, the context attribute namespace is numbered 1).

The REMOVEFROM response implicity subtracts one from the position
numbers of intended to
be unique across all members of the context which had position numbers
greater than datasets. To achieve this, attribute names are
prefixed with the REMOVEFROM position number.

Example: S: * REMOVEFROM "blurdybloop" "fred" 15

Newman [Page 31]

Internet DRAFT ACAP March 26, 1997

4.5.5. CHANGE Untagged Response

Data: context name
entry dataset class name
old position
new position
metadata list

The untagged CHANGE response informs the client that an entry in followed by a
context has either changed position in the context or has changed
the values of one or more dot (".").
Attributes which effect management of the attributes specified in the last
SEARCH command dataset are prefixed with
"dataset.". In addition, a NOTIFYCONTEXT search modifier for subtree of the
context.

The response includes "vendor." attribute
namespace may be registered with IANA according to the previous rules in
section ###. ACAP implementors are encouraged to help define
interoperable dataset classes specifications rather than using the
private attribute namespace.

Finally, the "user.<user-name>." and current position numbers "site." subtrees of the entry (the first entry in the context is numbered 1)
attribute namespace are reserved for user-specific and those
attribute/value pairs contained in the entry which match site-specific
attributes specified respectively. Such attributes are not interoperable so
are discouraged in the last SEARCH command with a
NOTIFYCONTEXT search modifier favor of defining standard attributes. A future
extension is expected to permit discovery of syntax for the context.

The CHANGE reponse implicitly changes the position numbers user or
site-specific attributes. Clients wishing to support display of all
entries which had position numbers between user
or site-specific attributes should display the old and new
position. If old position is less than new position, than one is
subtracted from all entries value of any non-NIL
single-valued "user.<user-name>." or "site." attribute which had position numbers in that
range. Otherwise one has
valid UTF-8 syntax.

The formal syntax for an attribute name is added to all entries which had position
numbers defined by the
"attribute-name" terminal in that range. If the old position next section.

4.3. Formal Syntax for Dataset and new position are
the same, then no implicit position renumbering occurs.

Example: S: * CHANGE "blurdybloop" "fred" 15 10
("addressbook.email" "fred@stone.org")

4.5.6. MODTIME Untagged Response

Data: context name
modtime value Attribute Namespace

The untagged MODTIME response informs naming conventions for datasets and attributes are defined by the client
following ABNF. Note that it has
recieved all updates to entries in the context which have modtime
values less than or equal to this grammar is not part of the modtime value ACAP
protocol syntax in the argument.

Example: S: * MODTIME mycontext "19970320162338"

4.6. Dataset modification

The following commands section ###, as dataset names and responses handle modification of datasets.

Newman [Page 32]

Internet DRAFT attribute names
are encoded as strings within the ACAP March 26, 1997

4.6.1. STORE Command

Arguments: entry store list

Data: no specific data for this command

Result: OK - store completed
NO - store failure: can't store that name
UNCHANGEDSINCE specified and entry changed
BAD - command unknown or arguments invalid
invalid UTF-8 syntax

Creates, modifies or deletes the named entries 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

Newman [Page 23]

Internet DRAFT ACAP June 19, 1997

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

dataset-std = name-component
;; MUST be registered with IANA and the named
datasets. spec MUST
;; be published as a standards track or
;; IESG-approved experimental RFC

dataset-sub = *(dname-component "/")
;; The values rules for this portion of metadata not specified in the command are
not changed. Setting namespace may
;; be further restricted by the "value" metadata of 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

Newman [Page 24]

Internet DRAFT ACAP June 19, 1997

5. Dataset Management

The entry with an attribute to NIL
removes that attribute from the entry. Setting empty name ("") in the "value"
metadata of dataset is used to hold
management information for the "entry" attribute dataset as a whole.

5.1. Dataset Inheritance

It is possible for one dataset to NIL removes that entry inherit data from another. The
dataset from which the data is inherited is called the base dataset. Changing
Data in the value of base dataset appears in the "entry" attribute
indicates a request to rename inheriting dataset, except
where overridden by data in the entry.

For each entry listed, an "UNCHANGEDSINCE" time may be included.
If the "modtime" inheriting dataset.

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 is later than the unchangedsince
time, then which exists in both the store fails with inheriting and inherited dataset
has a MODIFIED response code. Clients
writing modtime equal to a shared dataset SHOULD use UNCHANGEDSINCE when
modifying an existing entry.

The server MUST either make all the changes specified or make none greater of them. If the STORE modtimes for the purposes
of a SEARCH command includes and context notification. Inheritance has no metadata for an entry,
effect on the STORE command, except that entry's MODTIME MUST NOT be updated. if NIL is stored to an
attribute and there is a default value in a base dataset, then an
ENTRY response is returned to notify the client of the change.

The reserved "subdataset" attribute "modtime" may is not be included in directly inherited. If the
metadata list, but will automatically be updated.

Example: C: A342 STORE ("/addressbook/user/fred/ABC547"
"addressbook.phone" "555-1234"
"addressbook.Common Name"
"Barney Rubble" "addressbook.email" NIL)
S: A342 OK "Store completed"
C: A343 STORE ("/addressbook/group/Tech/ABD42"
UNCHANGEDSINCE "19970320162338"
"addressbook.prs.hair-length" "10 inches")
S: A343 NO (MODIFIED) "'ABD42' has been changed by
somebody else."
C: A344 STORE ("/addressbook/group/Tech/ACD54" "entry"
NIL)
S: A344 OK "Store completed"

Newman [Page 33]

Internet DRAFT ACAP March 26, 1997

4.6.2. DELETEDSINCE Command

Arguments: base
dataset name
time

Data: intermediate response: DELETED

Result: OK - DELETED completed
NO - DELETED failure: can't read includes a "subdataset" attribute and the inheriting dataset
date too far in
does not, then the past
BAD - command unknown or arguments invalid

The DELETEDSINCE command returns in intermediate DELETED replies
the names "subdataset" attribute will inherit a virtual
value of entries a list containing a ".". The subdataset at that have been deleted from the named node is
said to be a "virtual" dataset
since the given time.

Servers may impose as it is simply a limit on the number or age virtual copy of deleted entry
names they keep track of. If the server does not have information
going back
appropriate base dataset with all "subdataset" attributes changed to the
a list containing a ".". A virtual dataset is not visible if
NOINHERIT is specified time, on the command fails, returning SEARCH command.

Servers MUST support at least two levels of inheritance. This
permits a
TOOOLD response code in the tagged NO response.

Example: C: Z4S9 DELETEDSINCE "/mailboxes/common" 19951205103412
S: Z4S9 DELETED "blurdybloop"
S: Z4S9 DELETED "anteaters"
S: Z4S9 OK "DELETEDSINCE completed"
C: Z4U3 DELETEDSINCE "/mailboxes/common" 19951009040854
S: Z4U3 NO (TOOOLD) "Don't have that information"

4.6.3. DELETED Intermediate Response

Data: entry name

The untagged DELETED response occurs user's dataset such as "/options/user/fred/common" to
inherit from a result of a DELETEDSINCE
command. It returns an entry that has been deleted 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 specified when
stored in the DELETEDSINCE command.

Example: S: Z4S9 DELETED "blurdybloop"

4.7. Access Control Lists

An access control list is a tab-separated set "" entry of identifier,rights
pairs.

Identifier is a UTF-8 string. The identifier anyone is reserved to
refer to dataset. These attributes are not
inherited.

Newman [Page 25]

Internet DRAFT ACAP June 19, 1997

dataset.acl
This holds the universal identity (all authentications, including
anonymous). All user name strings accepted default access control list for the dataset. It
can not be modified by the AUTHENTICATE
command to authenticate to STORE command, only by the ACAP server are reserved as

Newman [Page 34]

Internet DRAFT ACAP March 26, 1997

identifiers SETACL and
DELETEACL commands.

dataset.acl.<attribute>
This holds the default access control list for an attribute
within the corresponding user. Identifiers starting with dataset. It can not be modified by the STORE command,
only by the SETACL and DELETEACL commands.

dataset.inherit
This holds the name of a
dash ("-") are reserved for "negative rights", described below. All
other identifier strings have implementation-defined semantics.

Rights dataset to inherit according to the
rules in section ###. This attribute may refer to a non-
existent dataset, in which case nothing is inherited.

5.3. Dataset Creation

When a string listing dataset is first created (by storing a (possibly empty) set of alphanumeric
characters, each character listing "." in the subdataset
attribute or storing an entry in a set of operations which is being
controlled. Letters previously non-existent dataset),
the dataset attributes are reserved for ``standard'' rights, listed
below. The set initialized with the values from the
parent dataset in the "/byowner/" hierarchy. In the case of standard rights the
"dataset.inherit" attribute, the appropriate hierarchy component is
added. For example, given the following entry:

entry path "/byowner/user/joe/"
dataset.acl ("joe" "rwia")
dataset.inherit "/byowner/site"

If a new dataset class "/byowner/~/new" is created, it will have the
following dataset attributes:

entry path "/byowner/user/joe/new/"
dataset.acl ("joe" "rwia")
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 extended by a
standards-track useful
if there is an active updating client or IESG approved experimental RFC. Digits are
reserved integrated server support
for implementation or site defined rights. the feature. The currently
defined standard rights are:

r - read
w - write
i - insert (store a new value)
o - override (see section <section>)
a - administer (perform store on ACL attribute/metadata)

An implementation may force rights dataset class "capability" is reserved to always allow
clients or never be granted.
Rights servers to advertise such features. The "entry" attribute
within this dataset class is the name of the dataset class whose
features are never tied, unlike being described. The attributes are prefixed with
"capability.<dataset-class>." and are defined by the IMAP ACL extension [IMAP-ACL].

It appropriate

Newman [Page 26]

Internet DRAFT ACAP June 19, 1997

dataset class specification.

Since it is possible for multiple identifiers in an access control list to
apply to a given unprivileged user (or other authentication identity). For
example, an ACL may include rights to be granted run an active client
for himself, a per-user capability dataset is useful. The dataset
"/capability/~/" holds information about all features available to
the identifier
matching the user, one or more implementation-defined identifiers
matching groups which include the user, and/or user (via inheritance), and the identifier
"anyone". How these rights are combined to determine dataset "/capability/site/" holds
information about all features supported by the user's
access site.

5.5. Dataset Quotas

The dataset class "quota" is implementation-defined. An implementation may choose, reserved for
example, to use the union quota management. Each
node of the rights granted to the applicable
identifiers. An implementation may instead choose, for example, to
only use those rights granted to "/byowner" view of the most specific identifier present ACAP namespace MAY have an
associated entry in the ACL. quota dataset class. A client may determine quota root is a quota
limit and usage listed in the set of rights granted "quota" dataset class which applies to the
logged-in user for
a given mailbox by using sub-tree of the MYRIGHTS command.

When an identifier in an ACL starts ACAP "/byowner" name-space exempting all parts of
that sub-tree with their own quota root.

A quota limit specifies the total number of bytes a dash ("-"), that indicates
that associated rights are to be removed from sub-tree of the identifier
ACAP name-space may consume exempting all parts of that sub-tree with
their own quota roots. The actual number of bytes which a dataset or
entry consumes is
prefixed by implementation dependent. However two rules are
necessary to promote interoperability:

1) Removing an entry or dataset MUST reduce the dash. For example, quota usage.

2) A STORE command MUST NOT fail with a quota error if for all entry
modifications under a given quota root the identifier "-fred" is
granted sum of the "w" right, that indicates that lengths of the "w" right
attribute names and values is to less then the quota limit minus the
quota usage. For some implementations, it MAY be
removed from users matching necessary to allow
the identifier "fred". Implementations
need quota usage to exceed the quota limit in order to satisfy this
rule. Note that a STORE command MAY succeed even if there does not support having identifiers which start with
appear to be enough space.

The algorithm for locating a dash in ACLs.

Each attribute of each entry of quota root for a dataset may potentially have an
ACL. If an attribute in an entry is as follows.
First, if the dataset name does not have an ACL, begin with "/byowner", then access the
name is controlled by mapped appropriately. Second, the "/byowner" is replaced
with "/quota". Third, any trailing "/" is removed. If the resulting
entry-path contains a default ACL for "quota.limit" attribute, that attribute in is the dataset, if
it exists. If there quota
root. Otherwise, the last component of the entry path is no default ACL for that attribute in removed,
and the
dataset, access previous step is controlled by a default ACL for that dataset. repeated. The
default ACL for a dataset must exist. GETQUOTA command implements
this algorithm in order to simplify ACAP clients.

The quota dataset class itself is exempt from quota management. ACAP
implementations SHOULD apply a very restrictive default ACL to quota
datasets.

The creation of a new quota root SHOULD NOT be automatically linked
to the creation of a dataset. Quota roots MAY be completely

Newman [Page 35] 27]

Internet DRAFT ACAP March 26, June 19, 1997

In order to perform any manipulation on an entry in a dataset, the
client must have 'r' rights on

independent, or MAY reduce the "entry" attribute limit of the entry.
Implementations their parent quota root on
creation. Quota roots SHOULD NOT be nested -- modifying data should take care not to reveal via error messages the
existence of an entry for which
only effect the client does not have 'r' rights.
A client does not need access usage within one quota root. When a quota limit is
removed (by storing NIL in quota.limit), its usage is added to the "subdataset" attribute of the
parent dataset in order quota root, and its limit MAY be added to access the contents of a dataset.

Many of parent quota
root.

The following attributes are defined within the ACL commands and responses include an ``acl object''
parameter, quota dataset class:

quota.limit
This is single-valued. The syntax for specifying what this value follows the ACL applies to.
"number" rule defined below. This represents the quota limit,
in bytes, as defined in section ###.

quota.usage
This is a
parenthesized list. single-valued. The list contains just syntax for this value follows the dataset name when
referring to
"number" rule defined below. This is the default ACL for a dataset. The list contains a
dataset name and an attribute name when referring to quota usage in bytes.
It MAY be greater than the default ACL quota limit.

Because it can require excessive computation for an attribute in a dataset. The list contains a dataset name, an
attribute name, and an entry name when referring some
implementations, ACAP servers MAY respond with NO to the ACL for an
attribute of an entry of a dataset.

4.7.1. SETACL Command

Arguments: acl object
authentication identifier
access rights

Data: no specific data for this command

Result: OK - setacl completed
NO - setacl failure: can't set acl
BAD - command unknown or arguments invalid

The SETACL SEARCH command changes the access control list on the
specified object so that
requesting context notification for the specified identifier is granted quota.usage attribute.

6. Command and Response Specifications

ACAP commands and responses are described in this section. Commands
are organized first by the
permissions enumerated state in rights. If which the object did not
previously have an access control list, one command is created.

Example: C: A123 SETACL ("/addressbook/user/joe/public") anyone r
S: A123 OK "Setacl complete"
C: A124 SETACL ("/mailboxes/common") B1FF rwa
S: A124 NO (PERMISSION) "'B1FF' not permitted to modify
access rights
for '/mailboxes/common'"

Newman [Page 36]

Internet DRAFT ACAP March 26, 1997

4.7.2. DELETEACL permitted,
then by a general category of command type.

Command

Arguments: acl object
optional authentication identifier

Data: no specific data for this arguments, identified by "Arguments:" in the command

Result: OK - deleteacl completed
NO - deleteacl failure: can't delete acl
BAD -
descriptions below, are described by function, not by syntax. The
precise syntax of command unknown or arguments invalid

If given is described in the optional identifier argument, Formal Syntax
section.

Some commands cause specific server data to be returned; these are
identified by "Data:" in the DELETEACL command
removes any portion of descriptions below. See the access control list on
response descriptions in the specified
object Responses section for information on
these responses, and the specified identifier.

If not given the optional identifier argument, the DELETEACL
command removes the ACL from Formal Syntax section for the object entirely, causing access precise syntax
of these responses. It is possible for server data to be controlled by transmitted
as a higher-level default ACL. This form result of the
DELETEACL command is any command; thus, commands that do not permitted on the default ACL specifically
require server data specify "no specific data for a
dataset and servers MUST return a BAD.

Example: C: A223 DELETEACL ("/addressbook/user/joe/public") anyone
S: A223 OK "Deleteacl complete"
C: A224 DELETEACL ("/mailboxes/common")
S: A224 BAD "Can't delete ACL from dataset"
C: A225 DELETEACL ("/addressbook/user/fred"
"addressbook.email" "barney")
S: A225 OK "Deleteacl complete"

4.7.3. MYRIGHTS Command

Arguments: acl object

Data: intermediate responses: MYRIGHTS

Result: OK - myrights completed
NO - myrights failure: can't get rights
BAD - command unknown or arguments invalid

The MYRIGHTS command returns the set this command"
instead of rights that "none".

The "Result:" in the client has command description refers to the given dataset or dataset attribute.

Example: C: A003 MYRIGHTS ("/mailboxes/common")
S: A003 MYRIGHTS "r" possible
tagged status responses to a command, and any special interpretation
of these status responses.

Newman [Page 37] 28]

Internet DRAFT ACAP March 26, June 19, 1997

S: A003 OK "Myrights complete"

4.7.4. MYRIGHTS Intermediate

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.1.1. ACAP Untagged Response

Data: rights capability list

The MYRIGHTS untagged ACAP response occurs as a result of a MYRIGHTS command.
The argument is indicates the set of rights session is ready to
accept commands and contains a space-separated listing of
capabilities that the client has for server supports. Each capability is
represented by a list containing the
object referred capability name optionally
followed by capability specific string arguments.

ACAP capability names MUST be defined in a standards track or IESG
approved experimental RFC and registered with IANA according to
the rules in section ###.

Client implementations SHOULD NOT require any capability name, and
MUST ignore any unknown capability names.

The following initial capabilities are defined:

COMPARATORS
The COMPARATORS capability includes a list of the MYRIGHTS command.

4.7.5. LISTRIGHTS comparator
functions which the server supports. See section ### for a
description of comparators.

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 ###.

Example: S: * ACAP (IMPLEMENTATION "ACME v3.5")
(SASL "CRAM-MD5" "PLAIN") (CONTEXTLIMIT "200")

Newman [Page 29]

Internet DRAFT ACAP June 19, 1997

6.2. Any State

The following commands and responses are valid in any state.

6.2.1. NOOP Command

Arguments: acl object
authentication identifier none

Data: untagged responses: LISTRIGHTS no specific data for this command (but see below)

Result: OK - listrights noop completed
NO - listrights failure: can't get rights list
BAD - command unknown or arguments invalid

The LISTRIGHTS NOOP command takes an object and an identifier and
returns information about what rights may always succeeds. It does nothing. It can be granted
used to reset any inactivity auto-logout timer on the
identifier in the ACL for the object. server.

Example: C: a001 LISTRIGHTS ("/mailboxes") smith
S: a001 LISTRIGHTS ("/mailboxes") smith r w
S: a001 OK Listrights completed

C: a005 LISTRIGHTS ("/mailboxes" archive.imap) anyone
S: a005 LISTRIGHTS ("/mailboxes" archive.imap) anyone ""
r w a002 NOOP
S: a005 a002 OK Listrights completed

4.7.6. LISTRIGHTS Intermediate Response

Data: acl object
identifier
required rights
list of "NOOP completed"

6.2.2. LANG Command

Arguments: optional rights

The LISTRIGHTS response occurs as a result of a LISTRIGHTS

Newman [Page 38]

Internet DRAFT ACAP March 26, 1997

command. The first two arguments are the object and identifier
for which this rights list applies. Following the identifier is a
string containing the (possibly empty) set of rights the
identifier will always be granted on the dataset or attribute.

Following this are zero or more strings each containing a single
right the identifier may be granted in the dataset or attribute.

The same right may not be listed more than once in the LISTRIGHTS
response.

4.8. Quotas

Quotas are used to manage storage consumed by ACAP datasets. A quota
root is a place where a resource limit may be set which applies to an
implementation dependant subset of datasets.

4.8.1. SETQUOTA Command

Arguments: quota root
resource limit in octets or NIL language preferences

Data: intermediate responses: QUOTA untagged response: LANG

Result: OK - Quota root resource limit modified lang completed
NO - Quota failure: can't modify resourse limit no matching language available
BAD - command unknown or arguments invalid

The SETQUOTA LANG command takes the name of a quota root and with no arguments generates an untagged LANG
response including a number
indicating the desired resource limit in octets on all datasets
within that root. A value list of "0" indicates no resource limit is
desired. A value languages which the server supports
for localized error text strings. If one or more arguments are
supplied they indicate the client's preferred languages for error
messages. The server will match each client preference in order
against its internal table of NIL indicates available error strings languages.
For a client preference to match a server language table, the quota root should
client's language tag MUST be
removed.

If a prefix of the named quota root did not previously exist server's tag and
match up to a value other
than NIL "-" or the end of string. If a match is specified, found, the
server returns an implementation SHOULD create it. OK response. If no match is found, the
quota root exists and server
returns an untagged LANG response followed by a value of NIL NO response.

If no LANG command is specified, an
implementation SHOULD delete issued, all error text strings MUST be in
English. This rule is necessary because the quota root. default error text
has to be in a language which is understandable by any pair of
client and server vendors (since both have to diagnose problems).
In either case the
implementation may change addition, the quota root which applies default language for errors has to any use the

Newman [Page 30]

Internet DRAFT ACAP June 19, 1997

US-ASCII subset of UTF-8, since it can be displayed on the largest
number of datasets. computers.

Example: C: A042 SETQUOTA "/user/fred" 1048576
S: A042 QUOTA "/user/fred" 1048576 0 A003 LANG "fr-ca" "fr" "en-ca" "en-uk"
S: A042 A003 OK "Setquota completed" "Bonjour"

6.2.3. LANG Untagged Response

Data: list of supported language tags

The LANG response indicates the languages supported for server
error messages.

Example: C: A043 SETQUOTA "/usr/fred" NIL N004 LANG
S: A043 * LANG "fr-ca" "en-ca"
S: N004 OK "Setquota "LANG completed"

Newman [Page 39]

Internet DRAFT ACAP March 26, 1997

4.8.2. GETQUOTA

6.2.4. LOGOUT Command

Arguments: dataset none

Data: intermediate responses: QUOTA mandatory untagged response: BYE

Result: OK - Quota information returned
NO - Quota failure: can't access resourse limit logout completed
BAD - command unknown or arguments invalid

The GETQUOTA LOGOUT command takes the name of a dataset, and returns in
an intermediate QUOTA response informs the name of server that the quota root, client is done with
the
amount of session. The server must send a BYE untagged response before
the resource limit on that root (tagged) OK response, and then close the amount of that
resource limit which is used. network connection.

Example: C: A043 GETQUOTA "/option/user/fred/common" A023 LOGOUT
S: A043 QUOTA "/user/fred" 1024 50 * BYE "ACAP Server logging out"
S: A043 A023 OK "Getquota "LOGOUT completed"

4.8.3. QUOTA Intermediate
(Server and client then close the connection)

6.2.5. OK Response

Data: quota root
resource limit in octets
amount of resource limit used optional response code
human-readable text

The QUOTA intermediate OK response is generated as a result of a
SETQUOTA or GETQUOTA command. It includes indicates an information message from the name server.
When tagged, it indicates successful completion of the quota
root, the resource limit in octets and the amount of resource
limit used.

4.9. Extensions

In order associated
command. The human-readable text may be presented to simplify the process of extending the protocol, clients
MUST ignore unknown server responses which meet user as
an information message. The untagged form indicates an
information-only message; the syntax nature of
response-extend. In addition, clients MUST ignore server response
codes which meet the syntax of resp-code-ext. Availability of new
commands MUST information may be announced via

Newman [Page 31]

Internet DRAFT ACAP June 19, 1997

indicated by a capability on the initial greeting
line and such commands SHOULD meet response code.

Example: S: * OK "XXX - need good example"

6.2.6. NO Response

Data: optional response code
human-readable text

The NO response indicates an operational error message from the syntax of command-extend.

Servers MUST respond to unknown commands with a BAD command
server. When tagged, it indicates unsuccessful completion result. Servers MUST skip over non-synchronizing literals
contained in an extension of the
associated command. This The untagged form indicates a warning; the
command may still complete successfully. The human-readable text
describes the condition.

Example: C: A010 SEARCH ...
S: * NO "Master ACAP server is down, your data may
be done by assuming out of date."
S: A010 OK "search done"
...
C: A222 STORE ("/folder/comp.mail.misc"
"folder.creation-time" "19951206103412")
S: A222 NO (PERMISSION ("/folder/")) "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
unknown command matches that caused the command-extend syntax, or by reading a
line at error. The untagged
form indicates a time and checking protocol-level error for which the non-synchronizing literal syntax
at the end of associated
command can not be determined; it may also indicate an internal
server failure. The human-readable text describes the line. 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"

Newman [Page 40] 32]

Internet DRAFT ACAP March 26, June 19, 1997

5. Dataset Management

6.2.8. BYE Untagged Response

Data: optional response code
human-readable text

The entry with an empty name in untagged BYE response indicates that the dataset server is used about to hold
management information for
close the dataset as a whole.

5.1. Dataset Inheritance

It is possible for a dataset connection. The human-readable text may be displayed to inherit data from another. Data in
the inherited dataset appears user in a status report by the inheriting dataset, except where
explicitly overridden by data in the inheriting dataset. client. The inherited dataset specifies which values BYE response may
be overridden in sent as part of a normal logout sequence, or as a panic
shutdown announcement by the
inheriting datasets. If server. It is also used by some
server implementations as an inherited dataset has a non-NIL value for
any given attribute in announcement of an entry, inactivity auto-
logout.

This response is also used as one of two possible greetings at
session startup. It indicates that the ACL server is not willing to
accept a session from this client.

Example: S: * BYE "Auto-logout; idle for that attribute in that
entry must grant too long"

6.2.9. ALERT Untagged Response

Data: optional response code
human-readable text

The human-readable text contains a user special human generated alert
message that MUST be presented to the 'o' right user in order for a fashion that calls
the user user's attention to store
a corresponding value in an inheriting dataset.

The inherited dataset the message. This is usually a system-wide or group-wide set of
defaults. The system-wide dataset usually has one inheriting dataset
per user, allowing each user intended to add be used
for vital messages from the server administrator to or modify the defaults user, such
as
appropriate.

An entry which exists in both the inheriting and inherited dataset
has a modtime equal to the greator of warning that the modtimes 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 purposes
of a SEARCH AUTHENTICATE command establishes
authentication and context notification. Inheritance has no
effect on the STORE enters authenticated state. The AUTHENTICATE
command other than that specified by the 'o'
right.

Servers MUST support at least two levels of inheritance. This
permits a user's dataset such as "/options/user/fred/common" to
inherit from provides a group dataset such as "/options/group/dinosaur
operators/common" which in turn inherits from general mechanism for a server-wide dataset
such as "/options/common/common".

5.2. Dataset attributes

The following attributes apply to management of the dataset when
stored in the "" entry variety of a dataset.

dataset.acl
This holds the default authentication
techniques.

Server implementations may allow non-authenticated access control list for the dataset. It
can not be modified by the STORE command, only to certain
information by supporting the SETACL and
DELETEACL commands.

dataset.acl.<attribute>
This holds the default access control list for an attribute
within the dataset. It can SASL ANONYMOUS [SASL-ANON] mechanism.

Once authenticated (including as anonymous), it is not be modified by the STORE command, possible to
re-enter non-authenticated state.

Newman [Page 41] 33]

Internet DRAFT ACAP March 26, June 19, 1997

only by

Only the SETACL any-state commands (NOOP, LANG and LOGOUT) and DELETEACL commands.

dataset.inherit
This holds the
AUTHENTICATE command are valid in non-authenticated state.

6.3.1. AUTHENTICATE Command

Arguments: SASL mechanism name of a dataset to inherit according to the
rules
optional initial response

Data: continuation data may be requested

Result: OK - authenticate completed, now in section <section>.

6. Namespace conventions

6.1. Dataset Namespace authenticated state
NO - authenticate failure: unsupported authentication
mechanism, credentials rejected
BAD - command unknown or arguments invalid,
authentication exchange cancelled

The dataset namespace is a slash-separated hierarchy. By convention, AUTHENTICATE command indicates an authentication mechanism to
the first component of server. If the dataset namespace is a dataset class. A
dataset class SHOULD be published as an RFC which includes predefined
set of attributes and their meanings. The second component of server supports the
dataset name is "common", "group", or "user" for server-wide, group-
wide, or per-user datasets respectively. For group or user datasets, requested authentication
mechanism, it performs an authentication protocol exchange to
authenticate and identify the third component of user. Optionally, it also
negotiates a security layer for subsequent protocol interactions.
If the dataset name requested authentication mechanism is not supported, the name of the group or
server rejects the AUTHENTICATE identifier for the user. Other components command by sending a tagged NO
response.

The authentication protocol exchange consists of the
dataset name a series of
server challenges and client answers that are specific to the dataset class.

Dataset classes MUST be registered with IANA according to the rules
in section <section>. Dataset classes which are intended for
interoperable use MUST be published as a standards track or IESG
approved experimental RFC.

6.2. Attribute Namespace

Attribute names which do not contain
authentication mechanism. A server challenge consists of a dot (".") are reserved for
standardized attributes which have meaning in any dataset. In order
to simplify implementations, the attribute namespace is intended to
be unique across all datasets. To achieve this, attribute names are
prefixed
command continuation request with the dataset class name "+" token followed by a dot (".").
Attributes which effect management
BASE64 encoded string. The client answer consists of the dataset are prefixed with
"dataset.". In addition, a subtree line
consisting of a BASE64 encoded string. If the "vnd." or "prs."
namespaces may be registered client wishes to
cancel an authentication exchange, it should issue a line with IANA according a
single "*". 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 rules in
section <section>. ACAP implementors are encouraged AUTHENTICATE command
is used to help define
interoperable dataset classes rather than save a round trip when using authentication mechanisms
that are defined to send no data in the private attribute
namespaces.

7. Registration procedures

ACAP's usefulness comes from providing initial challenge. When
the initial-response argument is used with such a structured storage model for
all sorts of configuration data. However, for its potential mechanism, the
initial empty challenge is not sent to be
achieved, 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 important used with a mechanism
that sends data in the Internet community strives for initial challenge, the
following goals: server rejects the
AUTHENTICATE command by sending a tagged NO response.

The service name specified by this protocol's profile of SASL is

Newman [Page 42] 34]

Internet DRAFT ACAP March 26, June 19, 1997

(1) Standardization. It

"acap".

If a security layer is very important to standardize dataset
classes. The authors hope that ACAP achieves negotiated through the success SASL authentication
exchange, it takes effect immediately following the CRLF that SNMP
has seen with
concludes the definition of numerous standards track MIBs.

(2) Community Review. In authentication exchange for the absence of standardization, it is
important to get community review on a proposal to improve client, and the
engineering quality. Community review is strongly recommended prior
to registration. The ACAP developers mailing list <ietf-
acap@andrew.cmu.edu> may be used for this purpose.

(3) Registration. Registration serves a two-fold purpose. First it
prevents use CRLF
of the same name tagged OK response for different purposes, and second it
provides the server.

All ACAP implementations MUST support the PLAIN SASL mechanism
[SASL-PLAIN], although they MAY offer a one-stop list which can be used to locate existing
extensions.

The following registration templates may be used configuration option to register
disable plaintext passwords if site security policy dictates.
ACAP
protocol elements.

7.1. Ordering Functions

Additional ordering functions may be registered with IANA on a
first-come, first-served basis. Ordering functions intended for
interoperable use implementations SHOULD be defined as support an external encryption service
or a stronger standards track or IESG
approved experimental RFC.

To: XXX@XXX.XXX
Subject: Registration of new ACAP ordering function

Ordering name:

Scope: Any Dataset / Specific Dataset class / Specific locality

Published Specification(s):

(If SASL mechanism.

If an AUTHENTICATE command fails with a NO response, the published specification is not standards track, or no
published specifiction is referenced then client
may try another authentication mechanism by issuing another
AUTHENTICATE command. In other words, the ordering function is
assumed to be for limited use)

Person and email address to contact for further information:

7.2. ACAP Capabilities

New client may request
authentication types in decreasing order of preference.

Example: S: * ACAP capabilities MUST be standards track or IESG approved
experimental RFCs. Registration provides a simple way to locate all
extensions. Careful consideration should be made before extending (IMPLEMENTATION "Blorfysoft v3.5")
(SASL "PLAIN" "KERBEROS_V4")
C: A001 AUTHENTICATE KERBEROS_V4
S: + AmFYig==
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: A001 OK "Kerberos V4 authentication successful"

6.4. Searching

This section describes the protocol, as it can lead to complexity or interoperability
problems. SEARCH command, for retrieving data from
datasets.

Newman [Page 43] 35]

Internet DRAFT ACAP March 26, June 19, 1997

To: XXX@XXX.XXX
Subject: Registration

6.4.1. SEARCH Command

Arguments: dataset or context name
optional list of ACAP capability

Capability name:

Capability keyword:

Capability arguments:

standards track/IESG-approved experimental RFC number:

7.3. Dataset Classes

A dataset class provides 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 core set subset of attributes for use entries in a
specified hierarchy. It may also define rules for the dataset
hierarchy underneath and
returns information on that class. Community review of dataset classes subset to the client.

The first argument to SEARCH identifies what is strongly encouraged. Classes intended for interoperable use
should to be written as standards track or IESG approved experimental
RFCs.

To: XXX@XXX.XXX
Subject: Registration searched.
If the string begins with a slash ("/"), it is the name of ACAP a
dataset class

Dataset class name/attribute prefix:

Purpose:

Required attributes:

Optional attributes:

Published Specification(s):

(The published specification must to be freely available on searched, otherwise it is a name of a context that
was created by a SEARCH command given previously in the
Internet session.

A successful SEARCH command MUST result in a MODTIME intermediate
response.

Following that are zero or included with more modifiers to the registration. It should include ABNF
[as search. Each
modifier may be specified at most once. The defined in RFC 822] for modifiers
are:

DEPTH number
The SEARCH command will traverse the dataset tree up to the
specified attributes.)

Person and email address depth. ENTRY responses will include the full path
to contact for further information:

7.4. Private Attribute Subtree the entry. A private attribute subtree may be registered on a first come, first
serve basis. Private attributes may be used to store information
specific to a particular client within an ACAP entry value of any "0" indicates that the search
should traverse the entire tree. A value of "1" is the
default and indicates only the specified dataset
class. Whenever possible, private attributes should be avoided
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
favor more than number
entries, the SEARCH fails with a NO completion result with a
WAYTOOMANY response code.

LIMIT number number
Limits the number of improving interoperable dataset class definitions. 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

Newman [Page 44] 36]

Internet DRAFT ACAP March 26, June 19, 1997

To: XXX@XXX.XXX
Subject: Registration

limit is exceeded, the SEARCH command still succeeds,
returning the total number of ACAP private prefix

Private Prefix: vnd.<company/product>. or prs.<person>.

Person and email address to contact for further information:

(company names and addresses should be included when appropriate)

8. Formal Syntax matches in a TOOMANY response
code in the tagged OK response.

MAKECONTEXT [ENUMERATE] [NOTIFY] context
The following syntax specification uses SEARCH command creates a context with the augmented Backus-Naur
Form (BNF) notation as specified name given in [IMAIL] with one exception;
the
delimiter used with argument to refer to the matching entries. If the "#" construct SEARCH
is a single space (SPACE) and
not one or more commas.

Except successful, the context name may then be given as noted otherwise, all alphabetic characters are case-
insensitive. 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.

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.

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
notifications are 0 if ENUMERATE is not requested.

NOINHERIT
This causes the SEARCH command to operate without
inheritance. It can be used to tell which values are
explicit overrides. If MAKECONTEXT is also specified, the

Newman [Page 37]

Internet DRAFT ACAP June 19, 1997

created context is also not effected by inheritance.

RETURN (metadata...)
Specifies what is to be returned in intermediate ENTRY
responses. If this modifier is not specified, no
intermediate ENTRY responses are returned.

Inside the parentheses is a list of attributes, each
optionally followed by a parenthesized list of metadata. If
the parenthesized list of metadata is not specified, it
defaults to "(value)".

An attribute name with a trailing "*" requests all attributes
with that prefix. A "*" by itself requests all attributes.
If the parenthesized list of metadata is not specified for an
attribute with a trailing "*", it defaults to "(attribute
value)".

Following the last intermediate ENTRY response, the server
returns a single intermediate MODTIME response.

SORT (attribute comparator ...)
Specifies the order in which any resulting ENTRY replies are
to be returned to the client. The SORT modifier takes as an
argument a parenthesized list of one or more
attribute/comparator pairs. Attribute lists the attribute to
sort on, comparator specifies the name of the collation rule
to apply to the values of the attribute. Successive
attribute/comparator pairs are used to order two entries only
when all preceding pairs indicate the two entries collate the
same.

If the SORT modifier is used in conjunction with the
MAKECONTEXT modifier, the SORT modifier specifies the
ordering of entries in the created context.

If no SORT modifier is specified, or none of the
attribute/comparator pairs indicates an order for the two
entries, the server uses the order of the entries that exists
in the context or dataset being searched.

Following the modifiers is the search criteria. Searching
criteria consist of one or more search keys. Search keys may be
combined using the AND, and OR search keys. For example, the
criteria (the newline is for readability and not part of the
criteria):

Newman [Page 38]

Internet DRAFT ACAP June 19, 1997

AND COMPARE "modtime" "+octet" "19951206103400"
COMPARE "modtime" "-octet" "19960112000000"
refers to all entries modified between 10:34 December 6 1995 and
midnight January 12, 1996 UTC.

The currently defined search keys are as follows.

ALL This matches all entries.

AND search-key1 search-key2
Entries that match both search keys.

COMPARE attribute comparator value
Entries for which the value of the specified attribute
collates using the specified comparator the same or later
than the specified value.

COMPARESTRICT attribute comparator value
Entries for which the specified attribute collates using the
specified comparator later than the specified value.

EQUAL attribute comparator value
Entries for which the value of the attribute is equal to the
specified value using the specified comparator.

NOT search-key
Entries that do not match the specified search key.

OR search-key1 search-key2
Entries that match either search key.

PREFIX attribute comparator value
Entries which begin with the specified value using the
specified comparator. If the specified comparator doesn't
support substring matching, a BAD response is returned.

RANGE start end time
Entries which are within the specified range of the
enumerated context's ordering. The lowest-ordered entry in
the context is assigned number one, the next lowest entry is
assigned number two, and so on. The numeric arguments
specify the lowest and highest numbers to match. The time
specifies that the client has processed notifications for the
context up to the specified time. If the context has been
modified since then, the server MUST either return a NO with
a MODIFIED response code, or return the results that the
SEARCH would have returned if none of the changes since that
time had been made.

Newman [Page 39]

Internet DRAFT ACAP June 19, 1997

RANGE is only permitted on contexts. If RANGE is used with a
dataset, the server MUST return a BAD response.

SUBSTRING attribute comparator value
Entries which contain the specified value, using the
specified comparator. If the specified comparator doesn't
support substring matching, a BAD response is returned.

Example: C: [TODO - write examples]

6.4.2. ENTRY Intermediate Response

Data: entry name
entry data

The ENTRY intermediate response occurs as a result of a SEARCH
command. This is the means by which dataset entries are returned
to the client. The entry with the given name matches the search.
Following the entry name is a set of zero or more lists, one for
each item in the RETURN search modifier, each containing the
requested metadata for the requested attribute(s) within the
entry.

6.4.3. MODTIME Intermediate Response

Data: modtime value

The MODTIME intermediate response occurs as a result of a SEARCH
command. It indicates that the just created context or the
previously returned ENTRY responses include all updates to the
returned entries up to and including the modtime value in the
argument.

6.4.4. REFER Intermediate Response

Data: dataset path
ACAP URL

The REFER intermediate response occurs as a result of a
multi-level SEARCH where one of the levels is located on a
different server. The response indicates the dataset which is not
located on the current server and an ACAP URL for where that
dataset may be found.

Newman [Page 40]

Internet DRAFT ACAP June 19, 1997

6.5. Contexts

The following commands use contexts created by a SEARCH command with
a MAKECONTEXT modifier.

6.5.1. FREECONTEXT Command

Arguments: context name

Data: no specific data for this command

Result: OK - freecontext completed
NO - freecontext failure: no such context
BAD - command unknown or arguments invalid

The FREECONTEXT command causes the server to free all state
associated with the named context. The context may no longer be
searched and the server will no longer issue any untagged
responses for the context. The context is no longer counted
against the server's limit on the number of contexts.

Example: C: A683 FREECONTEXT "blurdybloop"
S: A683 OK "Freecontext completed"

6.5.2. UPDATECONTEXT Command

Arguments: list of context names

Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME

Result: OK - Updatecontext completed: all updates completed
NO - Updatecontext failed: no such context
not a notify context
BAD - command unknown or arguments invalid

The UPDATECONTEXT command causes the server to ensure that the
client is notified of all changes to the contexts listed as
arguments up to the current time. The contexts listed in the
arguments must have been previously given to a successful SEARCH
command with a MAKECONTEXT NOTIFY modifier. A MODTIME untagged
response MUST be returned if any read-write metadata in the
context changed since the last MODTIME for that context. This
includes metadata which is not listed in the RETURN modifier for
the context.

While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and

Newman [Page 41]

Internet DRAFT ACAP June 19, 1997

MODTIME at any time, the UPDATECONTEXT command is used to "prod"
the server to send any notifications it has not sent yet.

The UPDATECONTEXT command SHOULD NOT be used to poll for updates.
If two or more UPDATECONTEXT commands occur between the delay
period the server uses to generate unsolicited change
notifications, then the server MAY treat all UPDATECONTEXT
commands after the first as NOOP commands to discourage client
polling.

Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl"
S: Z4S9 OK "client has been notified of all changes"

6.5.3. ADDTO Untagged Response

Data: context name
entry name
position
metadata list

The untagged ADDTO response informs the client that an entry has
been added to a context. The response includes the position
number of the added entry (the first entry in the context is
numbered 1) and those metadata contained in the entry which match
the RETURN statement when the context was created.

The ADDTO response implicitly adds one to the position of all
members of the context which had position numbers that were
greater than or equal to the ADDTO position number.

Example: S: * ADDTO "blurdybloop" "fred" 15
("addressbook.email" "fred@rock.org")

6.5.4. REMOVEFROM Untagged Response

Data: context name
entry name
old position

The REMOVEFROM response implicitly subtracts one from the position
numbers of all members of the context which had position numbers

Newman [Page 42]

Internet DRAFT ACAP June 19, 1997

greater than the REMOVEFROM position number.

Example: S: * REMOVEFROM "blurdybloop" "fred" 15

6.5.5. CHANGE Untagged Response

Data: context name
entry name
old position
new position
metadata list

The untagged CHANGE response informs the client that an entry in a
context has either changed position in the context or has changed
the values of one or more of the attributes specified in the
RETURN modifier when the context was created.

The response includes the previous and current position numbers of
the entry (if ENUMERATE was specified on the context) and the
attribute metadata requested in the RETURN modifier when the
context was created.

The CHANGE response implicitly changes the position numbers of all
entries which had position numbers between the old and new
position. If old position is less than new position, than one is
subtracted from all entries which had position numbers in that
range. Otherwise one is added to all entries which had position
numbers in that range. If the old position and new position are
the same, then no implicit position renumbering occurs.

CHANGE responses are not issued for entries which have changed
position implicitly due to another ADDTO, REMOVEFROM or CHANGE
response.

Example: S: * CHANGE "blurdybloop" "fred" 15 10
("addressbook.email" "fred@stone.org")

6.5.6. MODTIME Untagged Response

Data: context name
modtime value

The untagged MODTIME response informs the client that it has
received all updates to entries in the context which have modtime
values less than or equal to the modtime value in the argument.

Newman [Page 43]

Internet DRAFT ACAP June 19, 1997

Example: S: * MODTIME mycontext "19970320162338"

6.6. Dataset modification

The following commands and responses handle modification of datasets.

6.6.1. STORE Command

Arguments: entry store list

Data: intermediate responses: ENTRY

Result: OK - store completed
NO - store failure: can't store that name
UNCHANGEDSINCE specified and entry changed
BAD - command unknown or arguments invalid
invalid UTF-8 syntax in attribute name

Creates, modifies or deletes the named entries in the named
datasets. The values of metadata not specified in the command are
not changed. Setting the "value" metadata of an attribute to NIL
removes that attribute from the entry. Setting the "value" of the
"entry" attribute to NIL removes that entry from the dataset.
Changing the value of the "entry" attribute renames the entry.

The STORE command is followed by one or more entry store lists.
Each entry store list begins with an entry path followed by STORE
modifiers, followed by zero or more attribute store items. Each
attribute store item is made up of the attribute name followed by
a NIL (to remove the attribute's value), a single value (to set
the attribute's single value), or a list of metadata items to
modify. The following STORE modifiers may be specified:

NOCREATE
By default, the server MUST create any datasets necessary to
store the entry. If NOCREATE is specified, the STORE command
will fail with a NOEXIST error unless the containing dataset
already exists.

UNCHANGEDSINCE
If the "modtime" of the entry is later than the
unchangedsince time, then the store fails with a MODIFIED
response code. Use of UNCHANGEDSINCE with a time of
"00000101000000" will always fail if the entry exists.
Clients writing to a shared dataset are encouraged to use
UNCHANGEDSINCE when modifying an existing entry.

Newman [Page 44]

Internet DRAFT ACAP June 19, 1997

The server MUST either make all the changes specified or make none
of them. If successful, the server MUST update the "modtime"
attribute for every entry which was changed.

It is illegal to list any metadata item within an attribute twice,
any attribute within an entry twice or to any entry path twice.
The server MUST return a BAD response if this happens. If the
"modtime" attribute is included in the STORE command, then the
server MUST return a NO response with an ILLEGAL response code.

When NIL is stored to an attribute, and there is an inherited
default value, then an ENTRY intermediate response is generated to
notify the client of this change, this response includes the
attribute name and value metadata for each attribute which
reverted to a non-NIL inherited setting.

Example: C: A342 STORE ("/addressbook/user/fred/ABC547"
"addressbook.phone" "555-1234"
"addressbook.CommonName" "Barney Rubble"
"addressbook.email" NIL)
S: A342 OK "Store completed"
C: A343 STORE ("/addressbook/user/joe/ABD42"
UNCHANGEDSINCE "19970320162338"
"user.joe.hair-length" "10 inches")
S: A343 NO (MODIFIED) "'ABD42' has been changed
by somebody else."
C: A344 STORE ("/addressbook/group/Tech/ACD54"
"entry" NIL)
S: A344 OK "Store completed"
C: A345 STORE ("/option/~/mail/SMTPserver" "value" NIL)
S: A345 ENTRY "SMTPserver" "value" "smtp.server.do.main"
S: A345 OK "Store completed"

6.6.2. DELETEDSINCE Command

Arguments: dataset name
time

Data: intermediate response: DELETED

Result: OK - DELETED completed
NO - DELETED failure: can't read dataset
date too far in the past
BAD - command unknown or arguments invalid

The DELETEDSINCE command returns in intermediate DELETED replies

Newman [Page 45]

Internet DRAFT ACAP June 19, 1997

the names of entries that have been deleted from the named dataset
since the given time.

Servers may impose a limit on the number or age of deleted entry
names they keep track of. If the server does not have information
going back to the specified time, the command fails, returning a
TOOOLD response code in the tagged NO response.

Example: C: Z4S9 DELETEDSINCE "/folder/site" 19951205103412
S: Z4S9 DELETED "blurdybloop"
S: Z4S9 DELETED "anteaters"
S: Z4S9 OK "DELETEDSINCE completed"
C: Z4U3 DELETEDSINCE "/folder/site" 19951009040854
S: Z4U3 NO (TOOOLD) "Don't have that information"

6.6.3. DELETED Intermediate Response

Data: entry name

The intermediate DELETED response occurs as a result of a
DELETEDSINCE command. It returns an entry that has been deleted
from the dataset specified in the DELETEDSINCE command.

Example: S: Z4S9 DELETED "blurdybloop"

6.7. Access Control List Commands

The commands in this section are used to manage access control lists.

6.7.1. SETACL Command

Arguments: acl object
authentication identifier
access rights

Data: no specific data for this command

Result: OK - setacl completed
NO - setacl failure: can't set acl
BAD - command unknown or arguments invalid

The SETACL command changes the access control list on the
specified object so that the specified identifier is granted the
permissions enumerated in rights. If the object did not
previously have an access control list, one is created.

Newman [Page 46]

Internet DRAFT ACAP June 19, 1997

Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r"
S: A123 OK "Setacl complete"
C: A124 SETACL ("/folder/site/") "B1FF" "rwa"
S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not
permitted to modify access rights
for '/folder/site/'"

6.7.2. DELETEACL Command

Arguments: acl object
optional authentication identifier

Data: no specific data for this command

Result: OK - deleteacl completed
NO - deleteacl failure: can't delete acl
BAD - command unknown or arguments invalid

If given the optional identifier argument, the DELETEACL command
removes any portion of the access control list on the specified
object for the specified identifier.

If not given the optional identifier argument, the DELETEACL
command removes the ACL from the object entirely, causing access
to be controlled by a higher-level default ACL. This form of the
DELETEACL command is not permitted on the default ACL for a
dataset and servers MUST return a BAD.

Example: C: A223 DELETEACL ("/addressbook/~/public") "anyone"
S: A223 OK "Deleteacl complete"
C: A224 DELETEACL ("/folder/site")
S: A224 BAD "Can't delete ACL from dataset"
C: A225 DELETEACL ("/addressbook/user/fred"
"addressbook.email" "barney")
S: A225 OK "Deleteacl complete"

Newman [Page 47]

Internet DRAFT ACAP June 19, 1997

6.7.3. MYRIGHTS Command

Arguments: acl object

Data: intermediate responses: MYRIGHTS

Result: OK - myrights completed
NO - myrights failure: can't get rights
BAD - command unknown or arguments invalid

The MYRIGHTS command returns the set of rights that the client has
to the given dataset or dataset attribute.

Example: C: A003 MYRIGHTS ("/folder/site")
S: A003 MYRIGHTS "r"
S: A003 OK "Myrights complete"

6.7.4. MYRIGHTS Intermediate Response

Data: rights

The MYRIGHTS response occurs as a result of a MYRIGHTS command.
The argument is the set of rights that the client has for the
object referred to in the MYRIGHTS command.

6.7.5. LISTRIGHTS Command

Arguments: acl object
authentication identifier

Data: untagged responses: LISTRIGHTS

Result: OK - listrights completed
NO - listrights failure: can't get rights list
BAD - command unknown or arguments invalid

The LISTRIGHTS command takes an object and an identifier and
returns information about what rights may be granted to the
identifier in the ACL for the object.

Example: C: a001 LISTRIGHTS ("/folder") "smith"
S: a001 LISTRIGHTS "r" "w"
S: a001 OK Listrights completed
C: a005 LISTRIGHTS ("/folder/archive.imap") "anyone"

Newman [Page 48]

Internet DRAFT ACAP June 19, 1997

S: a005 LISTRIGHTS "" "r" "w"
S: a005 OK Listrights completed

6.7.6. LISTRIGHTS Intermediate Response

Data: required rights
list of optional rights

The LISTRIGHTS response occurs as a result of a LISTRIGHTS
command. The first argument is a string containing the (possibly
empty) set of rights the identifier will always be granted on the
dataset or attribute.

Following this are zero or more strings each containing a single
right the identifier may be granted in the dataset or attribute.

The same right MUST NOT be listed more than once in the LISTRIGHTS
response.

6.8. Quotas

The section defines the commands and responses relating to quotas.

6.8.1. GETQUOTA Command

Arguments: dataset

Data: untagged responses: QUOTA

Result: OK - Quota information returned
NO - Quota failure: can't access resource limit
no resource limit
BAD - command unknown or arguments invalid

The GETQUOTA command takes the name of a dataset, and returns in
an untagged QUOTA response the name of the dataset, its quota
root, the quota limit on that root and the quota usage within that
root.

Example: C: A043 GETQUOTA "/option/user/fred/common"
S: * QUOTA "/option/user/fred/common" "/quota/user/fred"
1048576 2475
S: A043 OK "Getquota completed"

Newman [Page 49]

Internet DRAFT ACAP June 19, 1997

6.8.3. QUOTA Untagged Response

Data: dataset
quota root
quota limit in bytes
amount of quota limit used

The QUOTA untagged response is generated as a result of a GETQUOTA
command or MAY be generated by the server in response to a SEARCH
or STORE command to warn about high usage of a quota. It includes
the name of the applicable dataset, the quota root, the quota
limit in bytes and the quota usage.

6.9. Extensions

In order to simplify the process of extending the protocol, clients
MUST ignore unknown server responses which meet the syntax of
response-extend. In addition, clients MUST ignore server response
codes which meet the syntax of resp-code-ext. Availability of new
commands MUST be announced via a capability on the initial greeting
line and such commands SHOULD meet the syntax of command-extend.

Servers MUST respond to unknown commands with a BAD command
completion result. Servers MUST skip over non-synchronizing literals
contained in an unknown command. This may be done by assuming the
unknown command matches the command-extend syntax, or by reading a
line at a time and checking for the non-synchronizing literal syntax
at the end of the line.

7. Registration Procedures

ACAP's usefulness comes from providing a structured storage model for
all sorts of configuration data. However, for its potential to be
achieved, it is important that the Internet community strives for the
following goals:

(1) Standardization. It is very important to standardize dataset
classes. The authors hope that ACAP achieves the success that SNMP
has seen with the definition of numerous standards track MIBs.

(2) Community Review. In the absence of standardization, it is
important to get community review on a proposal to improve its
engineering quality. Community review is strongly recommended prior
to registration. The ACAP implementors mailing list
<ietf-acap@andrew.cmu.edu> should be used for this purpose.

(3) Registration. Registration serves a two-fold purpose. First it
prevents use of the same name for different purposes, and second it

Newman [Page 50]

Internet DRAFT ACAP June 19, 1997

provides a one-stop list which can be used to locate existing
extensions or dataset classes to prevent duplicate work.

The following registration templates may be used to register ACAP
protocol elements.

7.1. Comparators

Additional comparators may be registered with IANA on a first-come,
first-served basis. Comparators intended for interoperable use MUST
be defined as a standards-track or IESG-approved-experimental RFC.

To: XXX@XXX.XXX
Subject: Registration of new comparator

Comparator name:

Scope:

(Describe any limitations on intended use in terms of standards scope,
dataset classes, and specific locales.)

Operations: Ordering, Equality, Substring match

Published Specification(s):

(If the published specification is not standards track, or no
published specification is referenced then the comparator is
assumed to be for limited use.)

Person and email address to contact for further information:

7.2. ACAP Capabilities

New ACAP capabilities MUST be standards track or IESG approved
experimental RFCs. Registration provides a simple way to locate all
extensions. Careful consideration should be made before extending
the protocol, as it can lead to complexity or interoperability
problems.

To: XXX@XXX.XXX
Subject: Registration of ACAP capability

Capability name:

Capability keyword:

Capability arguments:

Newman [Page 51]

Internet DRAFT ACAP June 19, 1997

Published Specification(s):

(Standards track or IESG approved experimental RFC)

Person and email address to contact for further information:

7.3. ACAP Response Codes

ACAP response codes are registered on a first come, first served
basis. Proposals SHOULD be reviewed by the acap implementors mailing
list mentioned above.

To: XXX@XXX.XXX
Subject: Registration of ACAP response code

Response Code:

Arguments:

Purpose:

Published Specification(s):

(Optional, but encouraged)

Person and email address to contact for further information:

7.4. Dataset Classes

A dataset class provides a core set of attributes for use in a
specified hierarchy. It may also define rules for the dataset
hierarchy underneath that class. Dataset class specifications must
be standards track or IESG approved experimental RFCs.

To: XXX@XXX.XXX
Subject: Registration of ACAP dataset class

Dataset class name/attribute prefix:

Purpose:

Published Specification(s):

(Standards track or IESG approved experimental RFC)

Person and email address to contact for further information:

Newman [Page 52]

Internet DRAFT ACAP June 19, 1997

7.5. Vendor Subtree

Vendors may reserve a portion of the ACAP namespace for private use.
Dataset class names beginning with "vendor.<company/product name>."
are reserved for use by that company or product. In addition, all
attribute names beginning with "vendor.<company/product name>." are
reserved for use by that company or product. Registration is on a
first come, first served basis. Whenever possible, private
attributes and dataset classes should be avoided in favor of
improving interoperable dataset class definitions.

To: XXX@XXX.XXX
Subject: Registration of ACAP vendor subtree

Private Prefix: vendor.<company/product name>.

Person and email address to contact for further information:

(company names and addresses should be included when appropriate)

8. Formal Syntax

The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in [ABNF].

Except as noted otherwise, all alphabetic characters are
case-insensitive. The use of upper or lower case characters to
define token strings is for editorial clarity only. Implementations
MUST accept these strings in a case-insensitive fashion.

ALPHA ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" /
"J" / "K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" /
"S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z" /
"a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" /
"j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" /
"s" / "t" / "u" / "v" these strings in a case-insensitive fashion.

The "command" rule below defines the syntax for commands sent by the
client. The "response" rule below defines the syntax for responses
sent by the server.

ALPHA = %x41..5A / "w" %x61..7A
;; alphabetic letters

ATOM-CHAR = "!" / "x" %x23..27 / "y" %x2A..5B / "z" %x5D..7A / %x7C..7E
;; Case-sensitive

ATOM-CHAR ::= <any Any CHAR except ATOM-SPECIALS> ATOM-SPECIALS ::=

ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS

BASE64-CHAR ::= = ALPHA / DIGIT / "+" / "/"
;; case-sensitive

CHAR ::= <any 7-bit US-ASCII character except NUL, 0x01 - 0x7f>

CHAR8 ::= <any 8-bit octet except NUL, 0x01 - 0xff> = %x01..7F

CR ::= <ASCII CR, carriage return, 0x0C> = %x0C

Newman [Page 53]

Internet DRAFT ACAP June 19, 1997

CRLF ::= = CR LF

CTL ::= <any ASCII control character and DEL, 0x00-0x1f, 0x7f> = %x00..1F / %x7F

DIGIT ::= = "0" / DIGIT-NZ

DIGIT-NZ ::= "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9"

Newman [Page 45]

Internet DRAFT ACAP March 26, 1997 = %x31..39
; non-zero digits ("1" - "9")

LF ::= <ASCII LF, line feed, 0x0A> = %x0A

OCTET ::= <any octet value 0x00 - 0xFF> = %x00..FF

QUOTED-CHAR ::= <any TEXT-UTF8-CHAR except QUOTED-SPECIALS> = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS

QUOTED-SPECIALS ::= = <"> / "\"

SAFE-CHAR = %x01..09 / %x0B..0C / %x0E..21 /
%x23..5B / %x5D..7F
;; any TEXT-CHAR except QUOTED-SPECIALS

SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 /
UTF8-5 / UTF8-6

SPACE ::= <ASCII SP, space, 0x20> = %x20

TAG-CHAR = %x21 / %x23..27 / %x2C..5B / %x5D..7A / %x7C..7E
;; Any ATOM-CHAR except "*" or "+"

TEXT-CHAR ::= <any = %x01..09 / %x0B..0C / %x0E..7F
;; any CHAR except CR and LF> LF

TEXT-UTF8-CHAR ::= <any = SAFE-UTF8-CHAR / QUOTED-SPECIALS

UTF8-1 = %x80..BF

UTF8-2 = %xC0..DF UTF8-1

UTF8-3 = %xE0..EF 2UTF8-1

UTF8-4 = %xF0..F7 3UTF8-1

UTF8-5 = %xF8..FB 4UTF8-1

UTF8-6 = %xFC..FD 5UTF8-1

UTF8-CHAR except = TEXT-UTF8-CHAR / CR and LF>

UTF8-CHAR ::= <TODO: UTF-8 character> / LF

Newman [Page 54]

Internet DRAFT ACAP June 19, 1997

acl = "(" *acl-identrights ")"

acl-identifier ::= string = string-utf8
;; MUST NOT contain TAB

acl-identrights = string-utf8
;; The identifier followed by a TAB, followed by
;; the rights.

acl-object ::= = "(" dataset [SPACE attribute [SPACE entry-name]] ")"

acl-rights ::= = quoted

atom ::= 1*1024ATOM-CHAR = ALPHA *1023ATOM-CHAR

attribute ::= string = string-utf8
;; dot-separated attribute name
;; ends in ".bin" if value not textual
;; MUST NOT contain "*" or "%"

attribute-store = attribute SPACE (value-nil /
"(" 1*(metadata-write-q SPACE value-store) ")")
;; MUST NOT include the same metadata twice

auth-type ::= atom = iana-token
;; as defined in SASL [SASL]

base64-token ::= = *(4BASE64-CHAR) [base64-terminal]

base64-terminal ::= = (2BASE64-CHAR "==") / (3BASE64-CHAR "=")

command ::= = tag SPACE (command-any / command-auth /
command-nonauth) CRLF
;; Modal based on state

command-authent ::= = "AUTHENTICATE" SPACE atom auth-type [SPACE base64-token]
*(CRLF base64-token)

command-any ::= = "NOOP"

Newman [Page 46]

Internet DRAFT ACAP March 26, 1997 / command-lang / "LOGOUT"

command-auth ::= = command-delacl / command-dsince /
command-freectx / command-getquota /
command-lrights / command-myrights /
command-search / command-setacl /
command-setquota /
command-store
;; only valid in authenticaticated authenticated state

command-delacl ::= = "DELETEACL" SPACE acl-object [SPACE acl-identifier]

command-delete ::= "DELETE" SPACE entry-path

Newman [Page 55]

Internet DRAFT ACAP June 19, 1997

command-dsince ::= = "DELETEDSINCE" SPACE dataset SPACE time

command-extend ::= atom = extend-token [SPACE #extension-data] extension-data]

command-freectx ::= = "FREECONTEXT" SPACE context

command-getquota ::= = "GETQUOTA" SPACE dataset

command-lang = "LANG" *(SPACE lang-tag)

command-lrights ::= = "LISTRIGHTS" SPACE acl-object

command-myrights ::= = "MYRIGHTS" SPACE acl-object

command-nonauth ::= = command-authent
;; only valid in non-authenticated state

command-search ::= = "SEARCH" SPACE (dataset / context)
*(SPACE search-modifier)
SPACE search-criteria
;; MUST NOT include same search-modifier twice

command-setacl ::= = "SETACL" SPACE acl-object SPACE acl-identifier
SPACE acl-rights

command-setquota ::= "SETQUOTA" SPACE quota-root SPACE (number / nil)

command-store ::= = "STORE" SPACE 1#store-entry store-entry-list

comparator = <"> comparator-name <">

comparator-name = ["+" / "-"] iana-token

context ::= string = string-utf8
;; MUST NOT begin with slash ("/")

continue-req ::= "+" SPACE (resp-text / base64-token)

dataset ::= string = string-utf8
;; slash-separated dataset name
;; begins with slash

entry ::= = entry-name / entry-path

Newman [Page 47]

Internet DRAFT ACAP March 26, 1997

entry-name ::= string = string-utf8
;; entry name MUST NOT contain slash
;; MUST NOT begin with "."

entry-path ::= string = string-utf8
;; slash-separated path to entry
;; begins with slash

Newman [Page 56]

Internet DRAFT ACAP June 19, 1997

entry-relative ::= string = string-utf8
;; potentially relative path to entry

extend-token = atom
;; MUST be defined by a standards track or
;; IESG approved experimental protocol extension

extension-data ::= = extension-item *(SPACE extension-item)

extension-item = extend-token / string / number /
"(" #extension-data [extension-data] ")"

iana-token = atom
;; MUST be registered with IANA

initial-greeting ::= = "*" SPACE "ACAP" *(SPACE init-capability) "(" init-capability ")") CRLF

init-capability ::= atom [ "(" 1#string ")" ] = init-cap-compare / init-cap-context /
init-cap-extend / init-cap-implem / init-cap-sasl

init-cap-compare = "COMPARATORS" SPACE string-list

init-cap-context = "CONTEXTLIMIT" SPACE string

init-cap-extend = iana-token [SPACE string-list]

init-cap-implem = "IMPLEMENTATION" SPACE string

init-cap-sasl = "SASL" SPACE string-list

lang-tag = <"> Language-Tag <">
;; Language-Tag rule is defined in [LANG-TAGS]

literal ::= = "{" number [ "+" ] "}" CRLF *OCTET
;; The number represents the number of octets
;; MUST be literal-utf8 except for values of
;; attributes whose names end in ".bin"

literal-utf8 ::= = "{" number [ "+" ] "}" CRLF *UTF8-CHAR
;; The number represents the number of octets
;; not the number of characters

metadata ::= = attribute [ "(" 1#metadata-type metadata-type-list ")" ]

metadata-partial ::= "value<" number "." number ">"

metadata-store ::= 1#(attribute ["(" metadata-write ")"] SPACE
nstring)
;; attribute MAY end in "*" as wildcard.

metadata-list = metadata *(SPACE metadata)

metadata-type ::= "acl" / = "attribute" / "myrights" / "size" /
metadata-partial
"count" / metadata-write

Newman [Page 57]

Internet DRAFT ACAP June 19, 1997

metadata-type-q = <"> metadata-type <">

metadata-type-list = metadata-type-q *(SPACE metadata-type-q)

metadata-write ::= = "value" / "acl"

metadata-write-q = <"> metadata-write <">

nil ::= = "NIL"

nstring ::= = nil / string

number ::= 1*DIGIT = *DIGIT
;; A 32-bit unsigned number.
;; (0 <= n < 4,294,967,296)

nz-number ::= = DIGIT-NZ *DIGIT

ordering ::= ("+" / "-") atom
;; A 32-bit unsigned non-zero number.
;; (0 < n < 4,294,967,296)

position = number
;; "0" if context is not enumerated
;; otherwise this is non-zero

quota-limit = number

quota-root ::= dataset

Newman [Page 48]

Internet DRAFT ACAP March 26, 1997 = entry-path

quota-usage = number

quoted ::= = <"> *QUOTED-CHAR <">
;; limited to 1024 octets between the <">s

response ::= *response-data = response-addto / response-alert / response-bye /
response-change / response-cont /
response-deleted / response-done / response-entry /
response-extend / response-listr /
response-lang / response-mtimei / response-mtimeu /
response-myright / response-quota /
response-refer / response-remove / response-stat

response-addto ::= = "*" SPACE "ADDTO" SPACE context SPACE entry-name
SPACE number position SPACE return-data-list

response-alert = "*" SPACE "ALERT" SPACE #return-data resp-body CRLF
;; Client MUST display alert text to user

Newman [Page 58]

Internet DRAFT ACAP June 19, 1997

response-bye ::= = "*" SPACE "BYE" SPACE resp-body CRLF
;; Server will disconnect condition

response-change ::= = "*" SPACE "CHANGE" SPACE context SPACE entry-name
SPACE number position SPACE number position SPACE #return-data

response-data ::= response-change / response-deleted /
response-entry / response-implic /
response-mtimei / response-mtimeu /
response-myright / response-refer /
response-remove / response-stat return-data-list

response-cont = "+" SPACE (quoted / response-bye base64-token)

response-deleted ::= = tag SPACE "DELETED" SPACE entry-name

response-done ::= = tag SPACE resp-cond-state CRLF

response-entry ::= = tag SPACE "ENTRY" SPACE entry SPACE #return-data return-data-list

response-extend ::= tag = (tag / "*") SPACE atom extend-token [SPACE 1#extension-data]

response-implic ::= extension-data]

response-lang = "*" SPACE "LANG" SPACE lang-tag *(SPACE lang-tag)

response-listr = tag SPACE "LISTRIGHTS" SPACE acl-rights
0*(SPACE
*(SPACE acl-rights)

response-mtimei ::= = tag SPACE "MODTIME" SPACE time

response-mtimeu ::= = "*" SPACE "MODTIME" SPACE context SPACE time

response-myright ::= = tag SPACE "MYRIGHTS" SPACE acl-rights

response-quota = "*" SPACE "QUOTA" SPACE dataset SPACE quota-root
SPACE quota-limit SPACE quota-usage

response-refer ::= = tag SPACE "REFER" SPACE dataset SPACE 1*(SPACE
<"> url-relative <"> <">)

response-remove ::= = "*" SPACE "REMOVEFROM" SPACE context SPACE
entry-name SPACE number position

response-stat ::= = "*" SPACE resp-cond-state CRLF

resp-body ::= = ["(" resp-code ")" SPACE] quoted

Newman [Page 49]

Internet DRAFT ACAP March 26, 1997

resp-code ::= "ALERT" = "ENCRYPT-NEEDED" / "MODIFIED" resp-code-inval / "PERMISSION"
resp-code-many / resp-code-mod /
resp-code-noexist / resp-code-perm /
"PLAINTEXT-DENIED" / "QUOTA" / resp-code-refer / resp-code-many
"TRANSITION-NEEDED" / "TRYCACHE" /
"TRYFREECONTEXT" / resp-code-way / resp-code-ext

Newman [Page 59]

Internet DRAFT ACAP June 19, 1997

resp-code-ext ::= atom = iana-token [SPACE 1#extension-data] extension-data]
;; extension-data MUST NOT contain "]" unknown response codes are ignored by the client.

resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute)

resp-code-many ::= = "TOOMANY" SPACE nz_number nz-number

resp-code-mod = "MODIFIED" SPACE entry-path

resp-code-noexist = "NOEXIST" SPACE dataset

resp-code-perm = "PERMISSION" SPACE acl-object

resp-code-refer ::= = "REFER" SPACE 1#(<"> 1*(SPACE <"> url-relative <">)

resp-code-way = "WAYTOOMANY"

resp-cond-state ::= = ("OK" / "NO" / "BAD") SPACE resp-body
;; Status condition

return-data ::= nstring = "(" return-metadata *(SPACE return-metadata) ")"
;; one return-data list is included per item in
;; the RETURN statement

return-data-list = return-data *(SPACE return-data)

return-metadata = nil / number string / value-list / acl

searchkey-equal ::= = "EQUAL" SPACE attribute SPACE ordering comparator
SPACE value value-nil

searchkey-comp ::= = "COMPARE" SPACE attribute SPACE ordering comparator SPACE value

searchkey-strict ::= "COMPARESTRICT"

searchkey-prefix = "PREFIX" SPACE attribute SPACE ordering comparator SPACE value

searchkey-range ::= = "RANGE" SPACE nz-number SPACE nz-number
SPACE time

searchkey-strict = "COMPARESTRICT" SPACE attribute SPACE comparator
SPACE value

searchkey-substr = "SUBSTRING" SPACE attribute SPACE comparator
SPACE value

searchmod-depth ::= = "DEPTH" SPACE number

searchmod-hard ::= = "HARDLIMIT" SPACE nz-number

Newman [Page 60]

Internet DRAFT ACAP June 19, 1997

searchmod-limit ::= = "LIMIT" SPACE number SPACE number

searchmod-make ::= = "MAKECONTEXT" [SPACE "ENUMERATE"]
[SPACE "NOTIFY"] SPACE context

searchmod-notify ::= "NOTIFYCONTEXT"

searchmod-ninh = "NOINHERIT"

searchmod-return ::= = "RETURN" SPACE "(" #metadata [metadata-list] ")"

searchmod-sort ::= = "SORT" SPACE "(" 1#(attribute SPACE ordering) sort-list ")"

search-criteria ::= = "ALL" / searchkey-equal / searchkey-comp /
searchkey-strict / searchkey-range /
searchkey-prefix / searchkey-substr /
"NOT" SPACE search-criteria /
"OR" SPACE search-criteria SPACE search-criteria /
"AND" SPACE search-criteria SPACE search-criteria

search-modifier = searchmod-depth / searchmod-hard /
searchmod-limit / searchmod-make / searchmod-ninh /
searchmod-return / searchmod-sort

sort-list = sort-item *(SPACE sort-item)

sort-item = attribute SPACE comparator

store-entry = "(" entry-path *(SPACE store-modifier)
*(SPACE attribute-store) ")"
;; MUST NOT include the same store-modifier twice
;; MUST NOT include the same attribute twice

store-entry-list = store-entry *(SPACE store-entry)
;; MUST NOT include the same entry twice

store-modifier = store-mod-unchang / store-mod-nocreate

store-mod-nocreate = "NOCREATE"

store-mod-unchang = "UNCHANGEDSINCE" SPACE time

string = quoted / literal

string-list = string *(SPACE string)

string-utf8 = quoted / literal-utf8

tag = 1*32TAG-CHAR

Newman [Page 61]

Internet DRAFT ACAP June 19, 1997

time = <"> time-year time-month time-day time-hour
time-minute time-second time-subsecond <">
;; Timestamp in UTC

time-day = 2DIGIT ;; 01-31

time-hour = 2DIGIT ;; 00-23

time-minute = 2DIGIT ;; 00-59

time-month = 2DIGIT ;; 01-12

time-second = 2DIGIT ;; 00-60

time-subsecond = *DIGIT

time-year = 4DIGIT

value = string

value-any = value-nil / value-list

value-list = "(" [value *(SPACE value)] ")"

value-nil = value / nil

value-store = value-any / acl

url-acap = "acap://" url-server "/" url-enc-entry [url-filter]
;; url-enc-entry interpreted relative to "/"

url-attr-list = url-enc-attr *("&" url-enc-attr)

url-auth = ";AUTH=" ("*" / url-enc-auth)

url-achar = uchar / "&" / "=" / "~"
;; See RFC 1738 for definition of "uchar"

url-char = uchar / "=" / "~" / ":" / "@" / "/"
;; See RFC 1738 for definition of "uchar"

url-enc-attr = 1*url-char
;; encoded version of attribute name

url-enc-auth = 1*url-achar
;; encoded version of auth-type above

Newman [Page 50] 62]

Internet DRAFT ACAP March 26, June 19, 1997

search-modifier ::= searchmod-depth / searchmod-hard /
searchmod-limit / searchmod-make /
searchmod-notify / searchmod-return /
searchmod-sort

store-cond ::= SPACE "UNCHANGEDSINCE" SPACE time

store-entry ::= "(" entry-path [store-cond]
*(SPACE metadata-store) ")"

string ::= quoted / literal

tag ::= 1*<any ATOM-CHAR except "+" or "*">

time ::= <"> time-year time-month time-day time-hour
time-minute time-second time-subsecond <">

time-day ::= 2DIGIT ;; 00-31

time-hour ::= 2DIGIT ;; 00-23

time-minute ::= 2DIGIT ;; 00-59

time-month ::= 2DIGIT

url-enc-entry = 1*url-char
;; 01-12

time-second ::= 2DIGIT encoded version of entry-relative above

url-enc-user = *url-achar
;; 00-60

time-subsecond ::= *DIGIT

time-year ::= 4DIGIT

value ::= nstring encoded version of login userid

url-filter = "?" url-attr-list

url-relative = url-acap ::= "acap://" url-server "/" url-enc-entry / [url-enc-entry] [url-filter]
;; url-enc-entry interpreted is relative to "/"

url-attr-list ::= url-enc-attr *("&" url-enc-attr)

url-auth ::= ";AUTH=" ("*" / auth-type)

url-achar ::= uchar / "&" / "=" / "~"
;; See RFC 1738 for definition base URL

url-server = [url-user [url-auth] "@"] hostport
;; See RFC 1738 for definition of "hostport"

9. Multi-lingual Considerations

The IAB charset workshop [IAB-CHARSET] came to a number of
conclusions which influenced the design of ACAP. The decision to use
UTF-8 as the character encoding scheme was based on that work. The
LANG command to negotiate a language for error messages is also
included.

Section 3.4.5 of the IAB charset workshop report states that there
should be a way to identify the natural language for human readable
strings. Several promising proposals have been made for use within
ACAP, but no clear consensus on a single method is apparent at this
stage. The following rules are likely to permit the addition of
multi-lingual support in the future:

(1) A work in progress called Multi-Lingual String Format (MLSF)
proposes a layer on top of UTF-8 which uses otherwise illegal UTF-8
sequences to store language tags. In order to permit its addition to
a future version of this standard, client-side UTF-8 interpreters
SHOULD silently ignore illegal multi-byte UTF-8 characters, and treat
illegal single-byte UTF-8 characters as end of string markers.
Servers, for the time being, MUST silently accept illegal UTF-8
characters, except in attribute names and entry names. Clients MUST
NOT send illegal UTF-8 characters to the server unless a future
standard changes this rule.

(2) There is a proposal to add language tags to Unicode. To support
this, servers MUST be able to store UTF-8 characters of "uchar"

url-char ::= uchar / "=" / "~" / ":" / "@" / "/"
;; See RFC 1738 for definition up to 20 bits
of "uchar"

url-depth ::= "DEPTH=" number data.

(3) The metadata item "language" is reserved for future use.

(4) The ";" character in attribute names is reserved for future use.

Newman [Page 51] 63]

Internet DRAFT ACAP March 26, June 19, 1997

url-enc-attr ::= 1*url-char
;; encoded version of attribute name

url-enc-auth ::= 1*url-achar
;; encoded version

10. Security Considerations

The AUTHENTICATE command uses SASL [SASL] to provide basic
authentication, authorization, integrity and privacy services. This
is described in section ###. The security considerations for the
PLAIN SASL mechanism [SASL-PLAIN] also apply.

ACAP protocol transactions are susceptible to passive observers or
man in the middle attacks which alter the data, unless the optional
encryption and integrity services of auth-type above

url-enc-entry ::= 1*url-char
;; encoded version the AUTHENTICATE command are
offered, or an external security mechanism is used for protection.
It may be useful to allow configuration of entry-relative above

url-enc-search ::= 1*url-char
;; encoded version both clients and servers
to refuse to transfer sensitive information in the absence of search-criteria above

url-enc-user ::= *url-achar
;; encoded version strong
encryption.

ACAP access control lists provide fine grained authorization for
access to attributes. A number of login userid

url-filter ::= "?" url-attr-list ["?" url-depth ["?" url-enc-search]]

url-relative ::= url-acap / [url-enc-entry] [url-filter]
;; url-enc-entry is relative related security issues are
described in section ###.

ACAP clients are encouraged to base URL

url-server ::= [url-user [url-auth] "@"] hostport
;; See RFC 1738 consider the security problems
involved with a lab computer situation. Specifically, a client cache
of ACAP configuration information MUST NOT allow access by an
unauthorized user. One way to assure this is for definition of "hostport"

Newman [Page 52]

Internet DRAFT an ACAP March 26, 1997

9. Security Considerations client to
be able to completely flush any non-public cached configuration data
when a user leaves.

As laptop computers can be easily stolen and a cache of configuration
data may contain sensitive information, a disconnected mode ACAP protocol transactions, including address book
client may wish to encrypt and option data,
are sent in password protect cached configuration
information.

11. Acknowledgments

Many thanks to the clear follow people who helped design ACAP over the network unless the optional privacy
protection is negotiated in the AUTHENTICATE command.

Additional security considerations are discussed in the section
discussing past
four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob Earhart,
Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, Steve Hole,
Steve Hubert, Dave Roberts, Bart Schaefer, Matt Wall and other
participants of the AUTHENTICATE command.

10. IETF ACAP working group.

12. Authors' Addresses

Chris Newman
Innosoft International, Inc.
1050 East Garvey Ave. South Lakes Drive
West Covina, CA 91790 USA

Email: chris.newman@innosoft.com

John G. Myers

Email: jgm+@cmu.edu

Newman [Page 53] 64]

Internet DRAFT ACAP March 26, June 19, 1997

John Gardiner Myers
Netscape Communications
501 East Middlefield Road
Mail Stop MV-029
Mountain View, CA 94043

Email: jgmyers@netscape.com

Appendices

A. References

[ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF",
Work in progress: draft-ietf-drums-abnf-xx.txt

[BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of
Minnesota, December 1994.

<ftp://ds.internic.net/rfc/rfc1738.txt>

[IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson,
Crispin, Svanberg, "The Report of the IAB Character Set Workshop held
29 February - 1 March, 1996", RFC 2130, April 1997.

<ftp://ds.internic.net/rfc/rfc2130.txt>

[IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, University of Washington, December 1996.

<ftp://ds.internic.net/rfc/rfc2060.txt>

[IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie
Mellon, January 1997.

<ftp://ds.internic.net/rfc/rfc2086.txt>

[ISO-10646] ISO/IEC 10646-1:1993(E) "Information Technology--
Universal Multiple-octet Coded Character Set (UCS)." See also
amendments 1 through 7, plus editorial corrections.

[ISO-C] "Programming languages -- C", ISO/IEC 9899:1990,
International Organization for Standardization. This is effectively
the same as ANSI C standard X3.159-1989.

Newman [Page 65]

Internet DRAFT ACAP June 19, 1997

[KEYWORDS] Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, Harvard University, March 1997.

<ftp://ds.internic.net/rfc/rfc2119.txt>

[LANG-TAGS] Alvestrand, H., "Tags for the Identification of
Languages", RFC 1766.

<ftp://ds.internic.net/rfc/rfc1766.txt>

[REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808,
UC Irvine, June 1995.

<ftp://ds.internic.net/rfc/rfc1808.txt>

[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
Work in progress: draft-myers-auth-sasl-xx.txt

[IMAIL] Crocker, D., "Standard for the Format of ARPA Internet Text
Messages", STD 11, RFC 822, University of Delaware, August 1982.

<ftp://ds.internic.net/rfc/rfc822.txt>

[UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode

[SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress:
draft-newman-sasl-anon-xx.txt.

[SASL-PLAIN] Newman, "Plaintext Password SASL Mechanism and ISO
10646", RFC 2044, Alis Technologies, October
Transition Codes", Work in progress: draft-newman-sasl-plaintrans-
xx.txt.

[UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version
2.0", Addison-Wesley, 1996.

<ftp://ds.internic.net/rfc/rfc2044.txt> ISBN 0-201-48345-9.

[US-ASCII] "USA Standard Code for Information Interchange," X3.4.
American National Standards Institute: New York (1968).

[BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Coproration, University

[UTF8] Yergeau, F. "UTF-8, a transformation format of
Minnesota, December 1994.

<ftp://ds.internic.net/rfc/rfc1738.txt>

[REL-URL] Fielding, "Relative Uniform Resource Locators", Unicode and ISO
10646", RFC 1808,
UC Irvine, June 1995.

<ftp://ds.internic.net/rfc/rfc1808.txt> 2044, Alis Technologies, October 1996.

<ftp://ds.internic.net/rfc/rfc2044.txt>

Newman [Page 54] 66]

Internet DRAFT ACAP March 26, June 19, 1997

B. ACAP Keyword Index

ACAP (untagged response) ................................... 19 29
ADDTO (untagged response) .................................. 31 42
ALERT (response code) ...................................... 16 (untagged response) .................................. 33
ALL (search keyword) ....................................... 28 39
AND (search keyword) ....................................... 28 39
AUTHENTICATE (command) ..................................... 23 34
BAD (response) ............................................. 22 32
BYE (untagged response) .................................... 22 33
CHANGE (untagged response) ................................. 32 43
COMPARATORS (ACAP capability) .............................. 29
COMPARE (search keyword) ................................... 28 39
COMPARESTRICT (search keyword) ............................. 28 39
CONTEXTLIMIT (ACAP capability) ............................. 20 29
DELETEACL (command) ........................................ 37 47
DELETED (intermediate response) ............................ 34 46
DELETEDSINCE (command) ..................................... 34 45
DEPTH (search modifier) .................................... 25 36
ENCRYPT-NEEDED (response code) ............................. 20
ENTRY (intermediate response) .............................. 29 40
EQUAL (search keyword) ..................................... 28 39
FREECONTEXT (command) ...................................... 30 41
GETQUOTA (command) ......................................... 40 49
HARDLIMIT (search modifier) ................................ 26 36
IMPLEMENTATION (ACAP capability) ........................... 29
INVALID (response code) .................................... 20
LANG (command) ............................................. 30
LANG (untagged response) ................................... 31
LIMIT (search modifier) .................................... 26 36
LISTRIGHTS (command) ....................................... 38 48
LISTRIGHTS (intermediate response) ......................... 38 49
LOGOUT (command) ........................................... 21 31
MAKECONTEXT (search modifier) .............................. 26 37
MODIFIED (response code) ................................... 16 21
MODTIME (intermediate response) ............................ 29 40
MODTIME (untagged response) ................................ 32 43
MYRIGHTS (command) ......................................... 37 47
MYRIGHTS (intermediate response) ........................... 38 48
NO (response) .............................................. 32
NOCREATE (store modifier) .................................. 44
NOEXIST (response code) .................................... 21
NOINHERIT (search modifier) ................................ 37
NOOP (command) ............................................. 20 30
NOT (search keyword) ....................................... 28
NOTIFYCONTEXT (search modifier) ............................ 26 39
OK (response) .............................................. 21 31
OR (search keyword) ........................................ 28
ORDERINGS (ACAP capability) ................................ 20 39
PERMISSION (response code) ................................. 17
QUOTA (intermediate response) .............................. 40 21

Newman [Page 67]

Internet DRAFT ACAP June 19, 1997

PLAINTEXT-DENIED (response code) ........................... 21
PREFIX (search keyword) .................................... 39
QUOTA (response code) ...................................... 17 21
QUOTA (untagged response) .................................. 50
RANGE (search keyword) ..................................... 28 39
REFER (intermediate response) .............................. 29 40
REFER (response code) ...................................... 17 21
REMOVEFROM (untagged response) ............................. 31

Newman [Page 55]

Internet DRAFT ACAP March 26, 1997 42
RETURN (search modifier) ................................... 27 38
SASL (ACAP capability) ..................................... 20 29
SEARCH (command) ........................................... 25 35
SETACL (command) ........................................... 36
SETQUOTA (command) ......................................... 39 46
SORT (search keyword) ...................................... 27 modifier) ..................................... 38
STORE (command) ............................................ 33 44
SUBSTRING (search keyword) ................................. 40
TOOMANY (response code) .................................... 17 21
TRANSITION-NEEDED (response code) .......................... 21
TRYCACHE (response code) ................................... 21
TRYFREECONTEXT (response code) ............................. 17 22
UNCHANGEDSINCE (STORE (store modifier) ............................ 33 44
UPDATECONTEXT (command) .................................... 30 41
WAYTOOMANY (response code) ................................. 17 22
acl (attribute metadata) ................................... 11 14
anyone (ACL identifier) .................................... 34 19
attribute (attribute metadata) ............................. 11 14
dataset.acl (dataset attribute) ............................ 41 26
dataset.acl.<attribute> (dataset attribute) ................ 41 26
dataset.inherit (dataset attribute) ........................ 42 26
en-nocase (ordering function) .............................. 16 (comparator) ..................................... 18
entry (predefined attribute) ............................... 9 13
modtime (predefined attribute) ............................. 9 13
myrights (attribute metadata) .............................. 11 14
numeric (ordering function) ................................ 16 (comparator) ....................................... 18
octet (ordering function) .................................. 15 (comparator) ......................................... 17
quota.limit (predefined attribute) ......................... 28
quota.usage (predefined attribute) ......................... 28
size (attribute metadata) .................................. 11 14
subdataset (predefined attribute) .......................... 10 13
value (attribute metadata) ................................. 11
value<ORIGIN.SIZE> (attribute metadata) .................... 11 15

Newman [Page 56] 68]

----