< draft-ietf-acap-spec-05.txt   draft-ietf-acap-spec-06.txt >
Network Working Group C. Newman Network Working Group C. Newman
Internet Draft: ACAP Innosoft Internet Draft: ACAP Innosoft
Document: draft-ietf-acap-spec-05.txt J. G. Myers Document: draft-ietf-acap-spec-06.txt J. G. Myers
Netscape Netscape
July 1997 August 1997
Expires in six months Expires in six months
ACAP -- Application Configuration Access Protocol ACAP -- Application Configuration Access Protocol
Status of this Memo Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas, documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts. working documents as Internet-Drafts.
skipping to change at page 1, line 38 skipping to change at page 1, line 38
ftp.isi.edu (US West Coast). ftp.isi.edu (US West Coast).
Abstract Abstract
The Application Configuration Access Protocol (ACAP) is designed to The Application Configuration Access Protocol (ACAP) is designed to
support remote storage and access of program option, configuration support remote storage and access of program option, configuration
and preference information. The data store model is designed to and preference information. The data store model is designed to
allow a client relatively simple access to interesting data, to allow allow a client relatively simple access to interesting data, to allow
new information to be easily added without server re-configuration, new information to be easily added without server re-configuration,
and to promote the use of both standardized data and custom or and to promote the use of both standardized data and custom or
proprietary data. Key features include "inheritance" which can be proprietary data. Key features include 'inheritance' which can be
used to manage default values for configuration settings and access used to manage default values for configuration settings and access
control lists which allow interesting personal information to be control lists which allow interesting personal information to be
shared and group information to be restricted. shared and group information to be restricted.
Internet DRAFT ACAP August 1997
Table of Contents Table of Contents
Status of this Memo ............................................... i Status of this Memo ............................................... i
Abstract .......................................................... i Abstract .......................................................... i
ACAP Protocol Specification ....................................... 1 ACAP Protocol Specification ....................................... 1
0. Changes from version -04 to version -05 .................. 1 1. Introduction ............................................. 1
1. Introduction ............................................. 2 1.1. Conventions Used in this Document ........................ 1
1.1. Conventions Used in this Document ........................ 2 1.2. ACAP Data Model .......................................... 1
1.2. ACAP Data Model .......................................... 2 1.3. ACAP Design Goals ........................................ 1
1.3. ACAP Design Goals ........................................ 2 1.4. Validation ............................................... 2
1.4. Validation ............................................... 3 1.5. Definitions .............................................. 2
1.5. Definitions .............................................. 3 1.6. ACAP Command Overview .................................... 3
1.6. ACAP Command Overview .................................... 5 2. Protocol Framework ....................................... 4
2. Protocol Framework ....................................... 5 2.1. Link Level ............................................... 4
2.1. Link Level ............................................... 5 2.2. Commands and Responses ................................... 4
2.2. Commands and Responses ................................... 5 2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 4
2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 5 2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 5
2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 6 2.3. Server States ............................................ 6
2.3. Server States ............................................ 7 2.3.1. Non-Authenticated State .................................. 6
2.3.1. Non-Authenticated State .................................. 7 2.3.2. Authenticated State ...................................... 6
2.3.2. Authenticated State ...................................... 7 2.3.3. Logout State ............................................. 6
2.3.3. Logout State ............................................. 7 2.4. Operational Considerations ............................... 7
2.4. Operational Considerations ............................... 8 2.4.1. Untagged Status Updates .................................. 7
2.4.1. Untagged Status Updates .................................. 8 2.4.2. Response when No Command in Progress ..................... 7
2.4.2. Response when No Command in Progress ..................... 8 2.4.3. Auto-logout Timer ........................................ 7
2.4.3. Auto-logout Timer ........................................ 8 2.4.4. Multiple Commands in Progress ............................ 8
2.4.4. Multiple Commands in Progress ............................ 9 2.5. Server Command Continuation Request ...................... 8
2.5. Server Command Continuation Request ...................... 9 2.6. Data Formats ............................................. 8
2.6. Data Formats ............................................. 9 2.6.1. Atom ..................................................... 9
2.6.1. Atom ..................................................... 10 2.6.2. Number ................................................... 9
2.6.2. Number ................................................... 10 2.6.3. String ................................................... 9
2.6.3. String ................................................... 10 2.6.3.1. 8-bit and Binary Strings ................................. 10
2.6.3.1. 8-bit and Binary Strings ................................. 11 2.6.4. Parenthesized List ....................................... 10
2.6.4. Parenthesized List ....................................... 11 2.6.5. NIL ...................................................... 10
2.6.5. NIL ...................................................... 11 3. Protocol Elements ........................................ 10
3. Protocol Elements ........................................ 11 3.1. Entries and Attributes ................................... 10
3.1. Entries and Attributes ................................... 11 3.1.1. Predefined Attributes .................................... 11
3.1.1. Predefined Attributes .................................... 12 3.1.2. Attribute Metadata ....................................... 12
3.1.2. Attribute Metadata ....................................... 13 3.2. ACAP URL scheme .......................................... 13
3.2. ACAP URL scheme .......................................... 14 3.2.1. ACAP URL User Name and Authentication Mechanism .......... 13
3.2.1. ACAP URL User Name and Authentication Mechanism .......... 14 3.2.2. Relative ACAP URLs ....................................... 14
3.2.2. Relative ACAP URLs ....................................... 15 3.3. Contexts ................................................. 14
3.3. Contexts ................................................. 15 3.4. Comparators .............................................. 14
3.4. Comparators .............................................. 15 Internet DRAFT ACAP August 1997
3.5. Access Control Lists (ACLs) .............................. 17
3.6. Server Response Codes .................................... 19 3.5. Access Control Lists (ACLs) .............................. 16
4. Namespace Conventions .................................... 21 3.6. Server Response Codes .................................... 18
4.1. Dataset Namespace ........................................ 21 4. Namespace Conventions .................................... 20
4.2. Attribute Namespace ...................................... 22 4.1. Dataset Namespace ........................................ 20
4.2. Attribute Namespace ...................................... 21
4.3. Formal Syntax for Dataset and Attribute Namespace ........ 22 4.3. Formal Syntax for Dataset and Attribute Namespace ........ 22
5. Dataset Management ....................................... 24 5. Dataset Management ....................................... 23
5.1. Dataset Inheritance ...................................... 24 5.1. Dataset Inheritance ...................................... 23
5.2. Dataset Attributes ....................................... 24 5.2. Dataset Attributes ....................................... 24
5.3. Dataset Creation ......................................... 25 5.3. Dataset Creation ......................................... 24
5.4. Dataset Class Capabilities ............................... 25 5.4. Dataset Class Capabilities ............................... 25
5.5. Dataset Quotas ........................................... 26 5.5. Dataset Quotas ........................................... 25
6. Command and Response Specifications ...................... 26 6. Command and Response Specifications ...................... 25
6.1. Initial Connection ....................................... 26 6.1. Initial Connection ....................................... 26
6.1.1. ACAP Untagged Response ................................... 27 6.1.1. ACAP Untagged Response ................................... 26
6.2. Any State ................................................ 27 6.2. Any State ................................................ 27
6.2.1. NOOP Command ............................................. 28 6.2.1. NOOP Command ............................................. 27
6.2.2. LANG Command ............................................. 28 6.2.2. LANG Command ............................................. 27
6.2.3. LANG Intermediate Response ............................... 29 6.2.3. LANG Intermediate Response ............................... 28
6.2.4. LOGOUT Command ........................................... 29 6.2.4. LOGOUT Command ........................................... 28
6.2.5. OK Response .............................................. 29 6.2.5. OK Response .............................................. 29
6.2.6. NO Response .............................................. 30 6.2.6. NO Response .............................................. 29
6.2.7. BAD Response ............................................. 30 6.2.7. BAD Response ............................................. 29
6.2.8. BYE Untagged Response .................................... 31 6.2.8. BYE Untagged Response .................................... 30
6.2.9. ALERT Untagged Response .................................. 31 6.2.9. ALERT Untagged Response .................................. 30
6.3. Non-Authenticated State .................................. 31 6.3. Non-Authenticated State .................................. 31
6.3.1. AUTHENTICATE Command ..................................... 32 6.3.1. AUTHENTICATE Command ..................................... 31
6.4. Searching ................................................ 33 6.4. Searching ................................................ 32
6.4.1. SEARCH Command ........................................... 33 6.4.1. SEARCH Command ........................................... 33
6.4.2. ENTRY Intermediate Response .............................. 38 6.4.2. ENTRY Intermediate Response .............................. 37
6.4.3. MODTIME Intermediate Response ............................ 38 6.4.3. MODTIME Intermediate Response ............................ 37
6.4.4. REFER Intermediate Response .............................. 38 6.4.4. REFER Intermediate Response .............................. 37
6.4.5. Search Examples ....................................... 39 6.4.5. Search Examples .......................................... 38
6.5. Contexts ................................................. 40 6.5. Contexts ................................................. 39
6.5.1. FREECONTEXT Command ...................................... 40 6.5.1. FREECONTEXT Command ...................................... 39
6.5.2. UPDATECONTEXT Command .................................... 40 6.5.2. UPDATECONTEXT Command .................................... 39
6.5.3. ADDTO Untagged Response .................................. 41 6.5.3. ADDTO Untagged Response .................................. 40
6.5.4. REMOVEFROM Untagged Response ............................. 41 6.5.4. REMOVEFROM Untagged Response ............................. 40
6.5.5. CHANGE Untagged Response ................................. 42 6.5.5. CHANGE Untagged Response ................................. 41
6.5.6. MODTIME Untagged Response ................................ 43 6.5.6. MODTIME Untagged Response ................................ 42
6.6. Dataset modification ..................................... 43 6.6. Dataset modification ..................................... 42
6.6.1. STORE Command ............................................ 43 6.6.1. STORE Command ............................................ 42
6.6.2. DELETEDSINCE Command ..................................... 45 6.6.2. DELETEDSINCE Command ..................................... 44
6.6.3. DELETED Intermediate Response ............................ 46 6.6.3. DELETED Intermediate Response ............................ 45
6.7. Access Control List Commands ............................. 46 6.7. Access Control List Commands ............................. 45
6.7.1. SETACL Command ........................................... 46 6.7.1. SETACL Command ........................................... 45
6.7.2. DELETEACL Command ........................................ 47 6.7.2. DELETEACL Command ........................................ 45
6.7.3. MYRIGHTS Command ......................................... 47 6.7.3. MYRIGHTS Command ......................................... 46
6.7.4. MYRIGHTS Intermediate Response ........................... 48 Internet DRAFT ACAP August 1997
6.7.5. LISTRIGHTS Command ....................................... 48
6.7.6. LISTRIGHTS Intermediate Response ......................... 48
6.8. Quotas ................................................... 49
6.8.1. GETQUOTA Command ......................................... 49
6.8.3. QUOTA Untagged Response .................................. 49
6.9. Extensions ............................................... 50
7. Registration Procedures .................................. 50
7.1. ACAP Capabilities ........................................ 50
7.2. ACAP Response Codes ...................................... 51
7.3. Dataset Classes .......................................... 51
7.4. Vendor Subtree ........................................... 52
8. Formal Syntax ............................................ 52
9. Multi-lingual Considerations ............................. 62
10. Security Considerations .................................. 63
11. Acknowledgments .......................................... 63
12. Authors' Addresses ....................................... 64
Appendices ........................................................ 64
A. References ............................................... 64
B. ACAP Keyword Index ....................................... 66
ACAP Protocol Specification
0. Changes from version -04 to version -05
1) Disallow syntax for DELETEACL with dataset level ACL.
2) TRYCACHE -> TRYLATER.
3) PLAINTEXT-DENIED -> AUTH-TOO-WEAK.
4) ENCRYPT-NEEDED also based on mechanism.
5) Documented TOOOLD in grammar and response code summary (it was
missing).
6) extensions: *unknown* server response codes ignored by client.
7) removed quota management stuff.
8) Updated LANG default language text to better match proposed IESG
rules.
9) Require AFS-style semantics on ACLs.
10) Added extension slot to URL scheme and reference IMAP URL spec to
avoid a bunch of duplicate text for ;AUTH= meaning and security
issues.
11) Added DEFAULT token and cleaned up associated inheritance
language.
12) Clarified entry-path vs. entry-name for ENTRY responses.
13) Deferred comparator naming and registration for a future
specification.
14) Changed LANG response to return language selected and list of
appropriate comparators. Removed COMPARATORS item from the
capability list.
15) Added "snapshot" sentence to MAKECONTEXT.
16) Permit STORE to re-order multi-values.
17) Added note that SEARCH returns inherited attributes unless
NOINHERIT or the user doesn't have permission to read attributes in
base dataset.
18) Changed .. to - in ABNF.
19) Made response codes hierarchical (likely to be an issue for
TRYLATER).
20) Changed ENTRY grammar to remove unnecessary parentheses. 6.7.4. MYRIGHTS Intermediate Response ........................... 47
6.7.5. LISTRIGHTS Command ....................................... 47
6.7.6. LISTRIGHTS Intermediate Response ......................... 47
6.8. Quotas ................................................... 48
6.8.1. GETQUOTA Command ......................................... 48
6.8.3. QUOTA Untagged Response .................................. 48
6.9. Extensions ............................................... 48
7. Registration Procedures .................................. 49
7.1. ACAP Capabilities ........................................ 49
7.2. ACAP Response Codes ...................................... 50
7.3. Dataset Classes .......................................... 50
7.4. Vendor Subtree ........................................... 51
8. Formal Syntax ............................................ 51
9. Multi-lingual Considerations ............................. 61
10. Security Considerations .................................. 61
11. Acknowledgments .......................................... 62
12. Authors' Addresses ....................................... 63
Appendices ........................................................ 63
A. References ............................................... 63
B. ACAP Keyword Index ....................................... 66
Internet DRAFT ACAP August 1997
21) Added examples. ACAP Protocol Specification
1. Introduction 1. Introduction
1.1. Conventions Used in this Document 1.1. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. If such lines are wrapped without a new "C:" or server respectively. If such lines are wrapped without a new "C:" or
"S:" label, then the wrapping is for editorial clarity and is not "S:" label, then the wrapping is for editorial clarity and is not
part of the command. part of the command.
skipping to change at page 3, line 4 skipping to change at page 1, line 203
can then sit down in front of any network-connected computer, run any can then sit down in front of any network-connected computer, run any
ACAP-enabled application and have access to their own configuration ACAP-enabled application and have access to their own configuration
data. Because it is hoped that many applications will become ACAP- data. Because it is hoped that many applications will become ACAP-
enabled, client simplicity was preferred to server or protocol enabled, client simplicity was preferred to server or protocol
simplicity whenever reasonable. simplicity whenever reasonable.
ACAP is designed to be easily manageable. For this reason, it ACAP is designed to be easily manageable. For this reason, it
includes "inheritance" which allows one dataset to inherit default includes "inheritance" which allows one dataset to inherit default
attributes from another dataset. In addition, access control lists attributes from another dataset. In addition, access control lists
are included to permit delegation of management and quotas are are included to permit delegation of management and quotas are
included to prevent storage abuse. Finally, an ACAP server which is included to control storage. Finally, an ACAP server which is
conformant to this base specification should be able to support most conformant to this base specification should be able to support most
dataset classes defined in the future without requiring a server dataset classes defined in the future without requiring a server
reconfiguration or upgrade. reconfiguration or upgrade.
ACAP is designed to operate well with a client that only has ACAP is designed to operate well with a client that only has
intermittent access to an ACAP server. For this reason, each entry intermittent access to an ACAP server. For this reason, each entry
Internet DRAFT ACAP August 1997
has a server maintained modification time so that the client may has a server maintained modification time so that the client may
detect changes. In addition, the client may ask the server for a detect changes. In addition, the client may ask the server for a
list of entries which have been removed since it last accessed the list of entries which have been removed since it last accessed the
server. server.
ACAP presumes that a dataset may be potentially large and/or the ACAP presumes that a dataset may be potentially large and/or the
client's network connection may be slow, and thus offers server client's network connection may be slow, and thus offers server
sorting, selective fetching and change notification for entries sorting, selective fetching and change notification for entries
within a dataset. within a dataset.
skipping to change at page 4, line 11 skipping to change at page 3, line 4
access control list (ACL) access control list (ACL)
A set of identifier, rights pairs associated with an object. An A set of identifier, rights pairs associated with an object. An
ACL is used to determine which operations a user is permitted to ACL is used to determine which operations a user is permitted to
perform on that object. See section 3.5. perform on that object. See section 3.5.
attribute attribute
A named value within an entry. See section 3.1. A named value within an entry. See section 3.1.
comparator comparator
A named function which can be used to perform one or more of A named function which can be used to perform one or more of
Internet DRAFT ACAP August 1997
three comparison operations: ordering, equality and substring three comparison operations: ordering, equality and substring
matching. See section 3.4. matching. See section 3.4.
context context
An ordered subset of entries in a dataset, created by a SEARCH An ordered subset of entries in a dataset, created by a SEARCH
command with a MAKECONTEXT modifier. See section 3.3. command with a MAKECONTEXT modifier. See section 3.3.
dataset dataset
One level of hierarchy in ACAP's tree of entries. One level of hierarchy in ACAP's tree of entries.
skipping to change at page 5, line 10 skipping to change at page 4, line 4
character set referenced by [UTF8], so for the purpose of this character set referenced by [UTF8], so for the purpose of this
document, UTF-8 refers to the UTF-8 encoding as defined by document, UTF-8 refers to the UTF-8 encoding as defined by
version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646] version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646]
including amendments one through seven. including amendments one through seven.
1.6. ACAP Command Overview 1.6. ACAP Command Overview
The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic
protocol services. The SEARCH command is used to select, sort, fetch protocol services. The SEARCH command is used to select, sort, fetch
and monitor changes to attribute values and metadata. The and monitor changes to attribute values and metadata. The
Internet DRAFT ACAP August 1997
UPDATECONTEXT and FREECONTEXT commands are also used to assist in UPDATECONTEXT and FREECONTEXT commands are also used to assist in
monitoring changes in attribute values and metadata. The STORE monitoring changes in attribute values and metadata. The STORE
command is used to add, modify and delete entries and attributes. command is used to add, modify and delete entries and attributes.
The DELETEDSINCE command is used to assist a client in The DELETEDSINCE command is used to assist a client in
re-synchronizing a cache with the server. The GETQUOTA, SETACL, re-synchronizing a cache with the server. The GETQUOTA, SETACL,
DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine
storage quotas and examine or modify access permissions. storage quotas and examine or modify access permissions.
2. Protocol Framework 2. Protocol Framework
skipping to change at page 5, line 32 skipping to change at page 4, line 29
The ACAP protocol assumes a reliable data stream such as provided by The ACAP protocol assumes a reliable data stream such as provided by
TCP. When TCP is used, an ACAP server listens on port 674. TCP. When TCP is used, an ACAP server listens on port 674.
2.2. Commands and Responses 2.2. Commands and Responses
An ACAP session consists of the establishment of a client/server An ACAP session consists of the establishment of a client/server
connection, an initial greeting from the server, and client/server connection, an initial greeting from the server, and client/server
interactions. These client/server interactions consist of a client interactions. These client/server interactions consist of a client
command, server data, and a server completion result. command, server data, and a server completion result.
All interactions transmitted by client and server are in the form of ACAP is a text-based line-oriented protocol. In general,
lines; that is, strings that end with a CRLF. The protocol receiver interactions transmitted by clients and servers are in the form of
of an ACAP client or server is either reading a line, or is reading a lines; that is, sequences of characters that end with a CRLF. The
sequence of octets with a known count followed by a line. Both protocol receiver of an ACAP client or server is either reading a
clients and servers must be capable of handling lines of arbitrary line, or is reading a sequence of octets with a known count (a
length. literal) followed by a line. Both clients and servers must be
capable of handling lines of arbitrary length.
2.2.1. Client Protocol Sender and Server Protocol Receiver 2.2.1. Client Protocol Sender and Server Protocol Receiver
The client command begins an operation. Each client command is The client command begins an operation. Each client command is
prefixed with a identifier (an alphanumeric string of no more than 32 prefixed with a identifier (an alphanumeric string of no more than 32
characters, e.g., A0001, A0002, etc.) called a "tag". A different characters, e.g., A0001, A0002, etc.) called a "tag". A different
tag is generated by the client for each command. tag SHOULD be generated by the client for each command.
There are two cases in which a line from the client does not There are two cases in which a line from the client does not
represent a complete command. In one case, a command argument is represent a complete command. In one case, a command argument is
quoted with an octet count (see the description of literal in section quoted with an octet count (see the description of literal in section
2.6.3); in the other case, the command arguments require server 2.6.3); in the other case, the command arguments require server
feedback (see the AUTHENTICATE command). In some of these cases, the feedback (see the AUTHENTICATE command). In some of these cases, the
server sends a command continuation request if it is ready for the server sends a command continuation request if it is ready for the
next part of the command. This response is prefixed with the token next part of the command. This response is prefixed with the token
"+". "+".
Note: If, instead, the server detected an error in the Note: If, instead, the server detected an error in a
command, it sends a BAD completion response with tag command, it sends a BAD completion response with tag
Internet DRAFT ACAP August 1997
matching the command (as described below) to reject the matching the command (as described below) to reject the
command and prevent the client from sending any more of the command and prevent the client from sending any more of the
command. command.
It is also possible for the server to send a completion or It is also possible for the server to send a completion or
intermediate response for some other command (if multiple intermediate response for some other command (if multiple
commands are in progress), or untagged data. In either commands are in progress), or untagged data. In either
case, the command continuation request is still pending; case, the command continuation request is still pending;
the client takes the appropriate action for the response, the client takes the appropriate action for the response,
and reads another response from the server. and reads another response from the server.
skipping to change at page 7, line 4 skipping to change at page 5, line 51
same tag as the client command which began the operation. Thus, if same tag as the client command which began the operation. Thus, if
more than one command is in progress, the tag in an intermediate more than one command is in progress, the tag in an intermediate
response identifies the command to which the response applies. A response identifies the command to which the response applies. A
tagged response other than "OK", "NO", or "BAD" is an intermediate tagged response other than "OK", "NO", or "BAD" is an intermediate
response. response.
An untagged response returns data or status messages which may be An untagged response returns data or status messages which may be
interpreted outside the context of a command in progress. It is interpreted outside the context of a command in progress. It is
prefixed with the token "*". Untagged data may be sent as a result prefixed with the token "*". Untagged data may be sent as a result
of a client command, or may be sent unilaterally by the server. of a client command, or may be sent unilaterally by the server.
There is no syntactic difference between untagged data that resulted There is no syntactic difference between untagged data that resulted
from a specific command and untagged data that were sent from a specific command and untagged data that were sent
unilaterally. unilaterally.
Internet DRAFT ACAP August 1997
The protocol receiver of an ACAP client reads a response line from The protocol receiver of an ACAP client reads a response line from
the server. It then takes action on the response based upon the the server. It then takes action on the response based upon the
first token of the response, which may be a tag, a "*", or a "+" as first token of the response, which may be a tag, a "*", or a "+" as
described above. described above.
A client MUST be prepared to accept any server response at all times. A client MUST be prepared to accept any server response at all times.
This includes untagged data that it may not have requested. This includes untagged data that it may not have requested.
This topic is discussed in greater detail in the Server Responses This topic is discussed in greater detail in the Server Responses
section. section.
skipping to change at page 8, line 5 skipping to change at page 7, line 5
In authenticated state, the user is authenticated and most commands In authenticated state, the user is authenticated and most commands
will be permitted. This state is entered when acceptable will be permitted. This state is entered when acceptable
authentication credentials have been provided. authentication credentials have been provided.
2.3.3. Logout State 2.3.3. Logout State
In logout state, the session is being terminated, and the server will In logout state, the session is being terminated, and the server will
close the connection. This state can be entered as a result of a close the connection. This state can be entered as a result of a
client request or by unilateral server decision. client request or by unilateral server decision.
Internet DRAFT ACAP August 1997
+--------------------------------------+ +--------------------------------------+
|initial connection and server greeting| |initial connection and server greeting|
+--------------------------------------+ +--------------------------------------+
|| (1) || (2) || (1) || (2)
VV || VV ||
+-----------------+ || +-----------------+ ||
|non-authenticated| || |non-authenticated| ||
+-----------------+ || +-----------------+ ||
|| (4) || (3) || || (4) || (3) ||
|| VV || || VV ||
skipping to change at page 9, line 5 skipping to change at page 8, line 5
does not exceed the underlying transport's available window size, or does not exceed the underlying transport's available window size, or
(2) use non-blocking writes. (2) use non-blocking writes.
2.4.3. Auto-logout Timer 2.4.3. Auto-logout Timer
If a server has an inactivity auto-logout timer, that timer MUST be If a server has an inactivity auto-logout timer, that timer MUST be
of at least 30 minutes duration. The receipt of ANY command from the of at least 30 minutes duration. The receipt of ANY command from the
client during that interval MUST suffice to reset the auto-logout client during that interval MUST suffice to reset the auto-logout
timer. timer.
Internet DRAFT ACAP August 1997
2.4.4. Multiple Commands in Progress 2.4.4. Multiple Commands in Progress
The client is not required to wait for the completion result of a The client is not required to wait for the completion result of a
command before sending another command, subject to flow control command before sending another command, subject to flow control
constraints on the underlying data stream. Similarly, a server is constraints on the underlying data stream. Similarly, a server is
not required to process a command to completion before beginning not required to process a command to completion before beginning
processing of the next command, unless an ambiguity would result processing of the next command, unless an ambiguity would result
because of a command that would affect the results of other commands. because of a command that would affect the results of other commands.
If there is such an ambiguity, the server executes commands to If there is such an ambiguity, the server executes commands to
completion in the order given by the client. completion in the order given by the client.
2.5. Server Command Continuation Request 2.5. Server Command Continuation Request
The command continuation request is indicated by a "+" token instead The command continuation request is indicated by a "+" token instead
of a tag. This indicates that the server is ready to accept the of a tag. This indicates that the server is ready to accept the
continuation of a command from the client. continuation of a command from the client.
This response is used in the AUTHENTICATE command to transmit server This response is used in the AUTHENTICATE command to transmit server
data to the client, and request additional client data. This data to the client, and request additional client data. This
response is also used if an argument to any command is a response is also used if an argument to any command is a
synchronizing literal. synchronizing literal (see section 2.6.3).
The client is not permitted to send the octets of a synchronizing The client is not permitted to send the octets of a synchronizing
literal unless the server indicates that it expects it. This permits literal unless the server indicates that it expects it. This permits
the server to process commands and reject errors on a line-by-line the server to process commands and reject errors on a line-by-line
basis, assuming it checks for non-synchronizing literals at the end basis, assuming it checks for non-synchronizing literals at the end
of each line. The remainder of the command, including the CRLF that of each line. The remainder of the command, including the CRLF that
terminates a command, follows the octets of the literal. If there terminates a command, follows the octets of the literal. If there
are any additional command arguments the literal octets are followed are any additional command arguments the literal octets are followed
by a space and those arguments. by a space and those arguments.
skipping to change at page 10, line 5 skipping to change at page 9, line 5
C: FOOB C: FOOB
S: A099 OK "FREECONTEXT completed" S: A099 OK "FREECONTEXT completed"
C: A044 BLURDYBLOOP {102856} C: A044 BLURDYBLOOP {102856}
S: A044 BAD "No such command as 'BLURDYBLOOP'" S: A044 BAD "No such command as 'BLURDYBLOOP'"
2.6. Data Formats 2.6. Data Formats
ACAP uses textual commands and responses. Data in ACAP can be in one ACAP uses textual commands and responses. Data in ACAP can be in one
of five forms: atom, number, string, parenthesized list or NIL. of five forms: atom, number, string, parenthesized list or NIL.
Internet DRAFT ACAP August 1997
2.6.1. Atom 2.6.1. Atom
An atom consists of one to 1024 non-special characters. It must An atom consists of one to 1024 non-special characters. It must
begin with a letter. Atoms are used for protocol keywords. begin with a letter. Atoms are used for protocol keywords.
2.6.2. Number 2.6.2. Number
A number consists of one or more digit characters, and represents a A number consists of one or more digit characters, and represents a
numeric value. Numbers are restricted to the range of an unsigned numeric value. Numbers are restricted to the range of an unsigned
32-bit integer: 0 < number < 4,294,967,296. 32-bit integer: 0 < number < 4,294,967,296.
skipping to change at page 10, line 33 skipping to change at page 9, line 35
A literal is a sequence of zero or more octets (including CR and LF), A literal is a sequence of zero or more octets (including CR and LF),
prefix-quoted with an octet count in the form of an open brace ("{"), prefix-quoted with an octet count in the form of an open brace ("{"),
the number of octets, close brace ("}"), and CRLF. In the case of the number of octets, close brace ("}"), and CRLF. In the case of
literals transmitted from server to client, the CRLF is immediately literals transmitted from server to client, the CRLF is immediately
followed by the octet data. followed by the octet data.
There are two forms of literals transmitted from client to server. There are two forms of literals transmitted from client to server.
The form where the open brace ("{") and number of octets is The form where the open brace ("{") and number of octets is
immediately followed by a close brace ("}") and CRLF is called a immediately followed by a close brace ("}") and CRLF is called a
synchronizing literal. When sending a synchronizing literal, the synchronizing literal. When sending a synchronizing literal, the
client must wait to receive a command continuation request (described client must wait to receive a command continuation request before
later in this document) before sending the octet data (and the sending the octet data (and the remainder of the command). The other
remainder of the command). The other form of literal, the form of literal, the non-synchronizing literal, is used to transmit a
non-synchronizing literal, is used to transmit a string from client string from client to server without waiting for a command
to server without waiting for a command continuation request. The continuation request. The non-synchronizing literal differs from the
non-synchronizing literal differs from the synchronizing literal by synchronizing literal by having a plus ("+") between the number of
having a plus ("+") between the number of octets and the close brace octets and the close brace ("}") and by having the octet data
("}") and by having the octet data immediately following the CRLF. immediately following the CRLF.
A quoted string is a sequence of zero to 1024 octets excluding NUL, A quoted string is a sequence of zero to 1024 octets excluding NUL,
CR and LF, with double quote (<">) characters at each end. CR and LF, with double quote (<">) characters at each end.
The empty string is represented as "" (a quoted string with zero The empty string is represented as "" (a quoted string with zero
characters between double quotes), as {0} followed by CRLF (a characters between double quotes), as {0} followed by CRLF (a
synchronizing literal with an octet count of 0), or as {0+} followed 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). 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 Note: Even if the octet count is 0, a client transmitting a
synchronizing literal must wait to receive a command synchronizing literal must wait to receive a command
continuation request. continuation request.
Internet DRAFT ACAP August 1997
2.6.3.1. 8-bit and Binary Strings 2.6.3.1. 8-bit and Binary Strings
Most strings in ACAP are restricted to UTF-8 characters and may not Most strings in ACAP are restricted to UTF-8 characters and may not
contain NUL octets. Attribute values MAY contain any octets contain NUL octets. Attribute values MAY contain any octets
including NUL. including NUL.
2.6.4. Parenthesized List 2.6.4. Parenthesized List
Data structures are represented as a "parenthesized list"; a sequence Data structures are represented as a "parenthesized list"; a sequence
of data items, delimited by space, and bounded at each end by of data items, delimited by space, and bounded at each end by
skipping to change at page 12, line 4 skipping to change at page 11, line 4
The value of an attribute is either single or multi-valued. A single The value of an attribute is either single or multi-valued. A single
value is NIL (has no value), or a string of zero or more octets. A value is NIL (has no value), or a string of zero or more octets. A
multi-value is a list of zero or more strings, each of zero or more multi-value is a list of zero or more strings, each of zero or more
octets. octets.
Attribute names are not permitted to contain asterisk ("*") or Attribute names are not permitted to contain asterisk ("*") or
percent ("%") and MUST be valid UTF-8 strings which do not contain percent ("%") and MUST be valid UTF-8 strings which do not contain
NUL. Invalid attribute names result in a BAD response. Entry names NUL. Invalid attribute names result in a BAD response. Entry names
are not permitted to begin with "." or contain slash ("/") and MUST are not permitted to begin with "." or contain slash ("/") and MUST
be valid UTF-8 strings which do not contain NUL. Invalid entry names be valid UTF-8 strings which do not contain NUL. Invalid entry names
Internet DRAFT ACAP August 1997
in the entry field of a command result in a BAD response. in the entry field of a command result in a BAD response.
Use of non-visible UTF-8 characters in attribute and entry names is Use of non-visible UTF-8 characters in attribute and entry names is
discouraged. discouraged.
3.1.1. Predefined Attributes 3.1.1. Predefined Attributes
Attribute names which do not contain a dot (".") are reserved for Attribute names which do not contain a dot (".") are reserved for
standardized attributes which have meaning in any dataset. The standardized attributes which have meaning in any dataset. The
following attributes are defined by the ACAP protocol. following attributes are defined by the ACAP protocol.
skipping to change at page 12, line 41 skipping to change at page 11, line 44
of a second. of a second.
The time, particularly fractions of a second, need not be The time, particularly fractions of a second, need not be
accurate. It is REQUIRED, however, that any two entries in a accurate. It is REQUIRED, however, that any two entries in a
dataset changed by successive modifications have strictly dataset changed by successive modifications have strictly
ascending modtime values. In addition, each STORE command ascending modtime values. In addition, each STORE command
within a dataset (including simultaneous stores from different within a dataset (including simultaneous stores from different
connections) MUST use different modtime values. connections) MUST use different modtime values.
This attribute has enforced validation, so any attempt to STORE This attribute has enforced validation, so any attempt to STORE
a value in this attribute MUST result in a NO response with an a value in this attribute MAY result in a NO response with an
INVALID response code. INVALID response code.
subdataset subdataset
If this attribute is set, it indicates the existence of a sub- If this attribute is set, it indicates the existence of a sub-
dataset of this entry. dataset of this entry.
The value consists of a list of relative ACAP URLs (see section The value consists of a list of relative ACAP URLs (see section
3.2) which may be used to locate the sub-dataset. The base URL 3.2) which may be used to locate the sub-dataset. The base URL
is the full path to the entry followed by a slash ("/"). The is the full path to the entry followed by a slash ("/"). The
value "." indicates a subdataset is located directly under this value "." indicates a subdataset is located directly under this
Internet DRAFT ACAP August 1997
one. Multiple values indicate replicated copies of the one. Multiple values indicate replicated copies of the
subdataset. subdataset.
For example, if the dataset "/folder/site/" has an entry For example, if the dataset "/folder/site/" has an entry
"public-folder" with a subdataset attribute of ".", then there "public-folder" with a subdataset attribute of ".", then there
exists a dataset "/folder/site/public-folder/". If the value of exists a dataset "/folder/site/public-folder/". If the value of
the subdataset attribute was instead the subdataset attribute was instead
"//other.acap.domain//folder/site/public-folder/" that would "//other.acap.domain//folder/site/public-folder/", that would
indicate the dataset is actually located on a different ACAP indicate the dataset is actually located on a different ACAP
server. server.
A dataset can be created by storing a "subdataset" attribute A dataset can be created by storing a "subdataset" attribute
including ".", and a sub-hierarchy of datasets is deleted by including ".", and a sub-hierarchy of datasets is deleted by
storing a NIL value to the "subdataset" attribute on the entry storing a NIL value to the "subdataset" attribute on the entry
in the parent dataset. in the parent dataset.
This attribute has enforced syntax validation. Specifically, if This attribute has enforced syntax validation. Specifically, if
an attempt is made to STORE a single-value (other than NIL), an an attempt is made to STORE a non-list value (other than NIL),
empty list, or one of the values does not follow the URL syntax an empty list, or one of the values does not follow the URL
rules [BASIC-URL], then this will result in a NO response with syntax rules [BASIC-URL, REL-URL], then this will result in a NO
an INVALID response code. response with an INVALID response code.
3.1.2. Attribute Metadata 3.1.2. Attribute Metadata
Each attribute is made up of metadata items which describe that Each attribute is made up of metadata items which describe that
attribute, its value and any associated access controls. Metadata attribute, its value and any associated access controls. Metadata
items may be either read-only, in which case the client is never items may be either read-only, in which case the client is never
permitted to modify the item, or read-write, in which case the client permitted to modify the item, or read-write, in which case the client
may modify the item if the access control list (ACL) permits. may modify the item if the access control list (ACL) permits.
The following metadata items are defined in this specification: The following metadata items are defined in this specification:
skipping to change at page 14, line 4 skipping to change at page 12, line 52
attribute attribute
The attribute name. Read-only. The attribute name. Read-only.
myrights myrights
The set of rights that the client has to the attribute. The set of rights that the client has to the attribute.
Read-only. See section 3.5 for the possible rights. Read-only. See section 3.5 for the possible rights.
size This is the length of the value. In the case of a size This is the length of the value. In the case of a
multi-value, this is a list of lengths for each of the values. multi-value, this is a list of lengths for each of the values.
Read-only. Read-only.
Internet DRAFT ACAP August 1997
value The value. For a multi-value, this is a list of single value The value. For a multi-value, this is a list of single
values. Read-write. values. Read-write.
Additional items of metadata may be defined in extensions to this Additional items of metadata may be defined in extensions to this
protocol. Servers MUST respond to unrecognized metadata by returning protocol. Servers MUST respond to unrecognized metadata by returning
a BAD command completion result. a BAD command completion result.
3.2. ACAP URL scheme 3.2. ACAP URL scheme
ACAP URLs are used within the ACAP protocol for the "subdataset" ACAP URLs are used within the ACAP protocol for the "subdataset"
attribute, referrals and inheritance. They provide a convenient attribute, referrals and inheritance. They provide a convenient
syntax for referring to other ACAP datasets. The ACAP URL follows syntax for referring to other ACAP datasets. The ACAP URL follows
skipping to change at page 15, line 8 skipping to change at page 14, line 5
the ACAP server. If no user name or authentication mechanism is the ACAP server. If no user name or authentication mechanism is
supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by
default. If an authentication mechanism is supplied without a user default. If an authentication mechanism is supplied without a user
name, then one SHOULD be obtained from the specified mechanism or name, then one SHOULD be obtained from the specified mechanism or
requested from the user as appropriate. If a user name is supplied requested from the user as appropriate. If a user name is supplied
without an authentication mechanism then ";AUTH=*" is assumed. without an authentication mechanism then ";AUTH=*" is assumed.
The ";AUTH=" authentication parameter is interpreted as described in The ";AUTH=" authentication parameter is interpreted as described in
the IMAP URL Scheme [IMAP-URL]. the IMAP URL Scheme [IMAP-URL].
Internet DRAFT ACAP August 1997
Note that if unsafe or reserved characters such as " " or ";" are Note that if unsafe or reserved characters such as " " or ";" are
present in the user name or authentication mechanism, they MUST be present in the user name or authentication mechanism, they MUST be
encoded as described in the URL specification [BASIC-URL]. encoded as described in the URL specification [BASIC-URL].
3.2.2. Relative ACAP URLs 3.2.2. Relative ACAP URLs
Because ACAP uses "/" as the hierarchy separator for dataset paths, Because ACAP uses "/" as the hierarchy separator for dataset paths,
it works well with the relative URL rules defined in the relative URL it works well with the relative URL rules defined in the relative URL
specification [REL-URL]. specification [REL-URL].
skipping to change at page 16, line 7 skipping to change at page 15, line 4
A comparator is a named function which takes two input values and can A comparator is a named function which takes two input values and can
be used to perform one or more of four comparison operations: be used to perform one or more of four comparison operations:
ordering, equality, prefix and substring matching. ordering, equality, prefix and substring matching.
The ordering operation is used both for the SORT search modifier and The ordering operation is used both for the SORT search modifier and
the COMPARE and COMPARESTRICT search keys. Ordering comparators can the COMPARE and COMPARESTRICT search keys. Ordering comparators can
determine the ordinal precedence of any two values. When used for determine the ordinal precedence of any two values. When used for
ordering, a comparator's name can be prefixed with "+" or "-" to ordering, a comparator's name can be prefixed with "+" or "-" to
indicate that the ordering should be normal order or reversed order indicate that the ordering should be normal order or reversed order
Internet DRAFT ACAP August 1997
respectively. If no prefix is included, "+" is assumed. respectively. If no prefix is included, "+" is assumed.
For the purpose of ordering, a comparator may designate certain For the purpose of ordering, a comparator may designate certain
values as having an undefined ordinal precedence. Such values always values as having an undefined ordinal precedence. Such values always
collate with equal value after all other values regardless of whether collate with equal value after all other values regardless of whether
normal or reversed ordering is used. Unless the comparator normal or reversed ordering is used. Unless the comparator
definition specifies otherwise, multi-values and NIL values have an definition specifies otherwise, multi-values and NIL values have an
undefined ordinal precedence. undefined ordinal precedence.
The equality operation is used for the EQUAL search modifier, and The equality operation is used for the EQUAL search modifier, and
simply determines if the two values are considered equal under the simply determines if the two values are considered equal under the
comparator function. When comparing a single value to a multi-value, comparator function. When comparing a single value to a multi-value,
the two are considered equal if any one of the multiple values is the two are considered equal if any one of the multiple values is
equal to the single value. equal to the single value.
The prefix match operation is used for the PREFIX search modifier, The prefix match operation is used for the PREFIX search modifier,
and simply determines if search value is a prefix of the item being and simply determines if the search value is a prefix of the item
searched. In the case of prefix search on a multi-valued, the match being searched. In the case of prefix search on a multi-value, the
is successful if the value is a prefix of any one of the multiple match is successful if the value is a prefix of any one of the
values. multiple values.
The substring match operation is used for the SUBSTRING search The substring match operation is used for the SUBSTRING search
modifier, and simply determines if search value is a substring of the modifier, and simply determines if search value is a substring of the
item being searched. In the case of substring search on a multi- item being searched. In the case of substring search on a multi-
value, the match is successful if the value is a substring of any one value, the match is successful if the value is a substring of any one
of the multiple values. of the multiple values.
Rules for naming and registering comparators will be defined in a Rules for naming and registering comparators will be defined in a
future specification. Servers MUST respond to unknown or improperly future specification. Servers MUST respond to unknown or improperly
used comparators with a BAD command completion result. used comparators with a BAD command completion result.
The following comparators are defined by this standard: The following comparators are defined by this standard and MUST be
implemented:
i;octet i;octet
Operations: Ordering, Equality, Prefix match, Substring match Operations: Ordering, Equality, Prefix match, Substring match
For collation, the i;octet comparator interprets the value of For collation, the i;octet comparator interprets the value of
an attribute as a series of unsigned octets with ordinal an attribute as a series of unsigned octets with ordinal
values from 0 to 255. When ordering two strings, each octet values from 0 to 255. When ordering two strings, each octet
pair is compared in sequence until the octets are unequal or pair is compared in sequence until the octets are unequal or
the end of the string is reached. When collating two strings the end of the string is reached. When collating two strings
where the shorter is a prefix of the longer, the shorter where the shorter is a prefix of the longer, the shorter
string is interpreted as having a smaller ordinal value. The string is interpreted as having a smaller ordinal value. The
"i;octet" or "+i;octet" forms collate smaller ordinal values "i;octet" or "+i;octet" forms collate smaller ordinal values
earlier, and the "-i;octet" form collates larger ordinal earlier, and the "-i;octet" form collates larger ordinal
values earlier. values earlier.
Internet DRAFT ACAP August 1997
For the equality function, two strings are equal if they are For the equality function, two strings are equal if they are
the same length and contain the same octets in the same the same length and contain the same octets in the same
order. NIL is equal only to itself. order. NIL is equal only to itself.
For non-binary, non-nil single values, i;octet ordering is For non-binary, non-nil single values, i;octet ordering is
equivalent to the ANSI C [ISO-C] strcmp() function applied to equivalent to the ANSI C [ISO-C] strcmp() function applied to
C string representations of the values. For non-binary, C string representations of the values. For non-binary,
non-nil single values, i;octet substring match is equivalent non-nil single values, i;octet substring match is equivalent
to the ANSI C strstr() function applied to the C string to the ANSI C strstr() function applied to the C string
representations of the values. representations of the values.
en;nocase;octet i;ascii-casemap
Operations: Ordering, Equality, Prefix match, Substring match Operations: Ordering, Equality, Prefix match, Substring match
The en;nocase;octet comparator first applies a mapping to the The i;ascii-casemap comparator first applies a mapping to the
attribute values which translates all US-ASCII letters to attribute values which translates all US-ASCII letters to
uppercase (octet values 0x61 to 0x7A are translated to octet uppercase (octet values 0x61 to 0x7A are translated to octet
values 0x41 to 0x5A respectively), then applies the i;octet values 0x41 to 0x5A respectively), then applies the i;octet
comparator as described above. With this function the values comparator as described above. With this function the values
"hello" and "HELLO" have the same ordinal value and are "hello" and "HELLO" have the same ordinal value and are
considered equal. considered equal.
i;numeric i;ascii-numeric
Operations: Ordering, Equality Operations: Ordering, Equality
The i;numeric comparator interprets strings as decimal The i;ascii-numeric comparator interprets strings as decimal
positive integers represented as US-ASCII digits. All values positive integers represented as US-ASCII digits. All values
which do not begin with a US-ASCII digit are considered equal which do not begin with a US-ASCII digit are considered equal
with an ordinal value higher than all non-NIL single-valued with an ordinal value higher than all non-NIL single-valued
attributes. Otherwise, all US-ASCII digits (octet values attributes. Otherwise, all US-ASCII digits (octet values
0x30 to 0x39) are interpreted starting from the beginning of 0x30 to 0x39) are interpreted starting from the beginning of
the string to the first non-digit or the end of the string. the string to the first non-digit or the end of the string.
3.5. Access Control Lists (ACLs) 3.5. Access Control Lists (ACLs)
An access control list is a set of identifier, rights pairs used to An access control list is a set of identifier, rights pairs used to
skipping to change at page 18, line 10 skipping to change at page 17, line 4
entry. An ACL is represented by a multi-value with each value entry. An ACL is represented by a multi-value with each value
containing an identifier followed by a tab character followed by the containing an identifier followed by a tab character followed by the
rights. The syntax is defined by the "acl" rule in the formal syntax rights. The syntax is defined by the "acl" rule in the formal syntax
in section 8. in section 8.
Identifier is a UTF-8 string. The identifier "anyone" is reserved to Identifier is a UTF-8 string. The identifier "anyone" is reserved to
refer to the universal identity (all authentications, including refer to the universal identity (all authentications, including
anonymous). All user name strings accepted by the AUTHENTICATE anonymous). All user name strings accepted by the AUTHENTICATE
command to authenticate to the ACAP server are reserved as command to authenticate to the ACAP server are reserved as
identifiers for the corresponding user. Identifiers starting with a identifiers for the corresponding user. Identifiers starting with a
Internet DRAFT ACAP August 1997
slash ("/") character are reserved for authorization groups which slash ("/") character are reserved for authorization groups which
will be defined in a future specification. Identifiers MAY be will be defined in a future specification. Identifiers MAY be
prefixed with a dash ("-") to indicate a revocation of rights. All prefixed with a dash ("-") to indicate a revocation of rights. All
other identifier strings have implementation-defined meanings. other identifiers have implementation-defined meanings.
Rights is a string listing a (possibly empty) set of alphanumeric Rights is a string listing a (possibly empty) set of alphanumeric
characters, each character listing a set of operations which is being characters, each character listing a set of operations which is being
controlled. Letters are reserved for "standard" rights, listed controlled. Letters are reserved for "standard" rights, listed
below. The set of standard rights may only be extended by a below. The set of standard rights may only be extended by a
standards-track or IESG approved experimental RFC. Digits are standards-track or IESG approved experimental RFC. Digits are
reserved for implementation or site defined rights. The currently reserved for implementation or site defined rights. The currently
defined standard rights are: defined standard rights are:
r - read x - search (use EQUAL search key with i;octet comparator)
w - write r - read (access with SEARCH command)
i - insert (perform store on a previously NIL value) w - write (modify with STORE command)
a - administer (perform store on ACL attribute/metadata) i - insert (perform STORE on a previously NIL value)
a - administer (perform SETACL or STORE on ACL attribute/metadata)
An implementation may force rights to always or never be granted. In An implementation may force rights to always or never be granted. In
particular, implementations are expected to grant implicit read and particular, implementations are expected to grant implicit read and
administer rights to a user's personal dataset storage in order to administer rights to a user's personal dataset storage in order to
avoid denial of service problems. Rights are never tied, unlike the avoid denial of service problems. Rights are never tied, unlike the
IMAP ACL extension [IMAP-ACL]. IMAP ACL extension [IMAP-ACL].
It is possible for multiple identifiers in an access control list to It is possible for multiple identifiers in an access control list to
apply to a given user (or other authentication identity). For apply to a given user (or other authentication identity). For
example, an ACL may include rights to be granted to the identifier example, an ACL may include rights to be granted to the identifier
skipping to change at page 19, line 8 skipping to change at page 18, line 4
it exists. If there is no default ACL for that attribute in the it exists. If there is no default ACL for that attribute in the
dataset, access is controlled by a default ACL for that dataset. The dataset, access is controlled by a default ACL for that dataset. The
default ACL for a dataset must exist. default ACL for a dataset must exist.
In order to perform any access or manipulation on an entry in a In order to perform any access or manipulation on an entry in a
dataset, the client must have 'r' rights on the "entry" attribute of dataset, the client must have 'r' rights on the "entry" attribute of
the entry. Implementations should take care not to reveal via error the entry. Implementations should take care not to reveal via error
messages the existence of an entry for which the client does not have messages the existence of an entry for which the client does not have
'r' rights. A client does not need access to the "subdataset" 'r' rights. A client does not need access to the "subdataset"
attribute of the parent dataset in order to access the contents of a attribute of the parent dataset in order to access the contents of a
Internet DRAFT ACAP August 1997
dataset. dataset.
Many of the ACL commands and responses include an "acl object" Many of the ACL commands and responses include an "acl object"
parameter, for specifying what the ACL applies to. This is a parameter, for specifying what the ACL applies to. This is a
parenthesized list. The list contains just the dataset name when parenthesized list. The list contains just the dataset name when
referring to the default ACL for a dataset. The list contains a referring to the default ACL for a dataset. The list contains a
dataset name and an attribute name when referring to the default ACL dataset name and an attribute name when referring to the default ACL
for an attribute in a dataset. The list contains a dataset name, an for an attribute in a dataset. The list contains a dataset name, an
attribute name, and an entry name when referring to the ACL for an attribute name, and an entry name when referring to the ACL for an
attribute of an entry of a dataset. attribute of an entry of a dataset.
skipping to change at page 19, line 30 skipping to change at page 18, line 29
An OK, NO, BAD, ALERT or BYE response from the server MAY contain a An OK, NO, BAD, ALERT or BYE response from the server MAY contain a
response code to describe the event in a more detailed machine response code to describe the event in a more detailed machine
parsable fashion. A response code consists of data inside parsable fashion. A response code consists of data inside
parentheses in the form of an atom, possibly followed by a space and parentheses in the form of an atom, possibly followed by a space and
arguments. Response codes are defined when there is a specific arguments. Response codes are defined when there is a specific
action that a client can take based upon the additional information. action that a client can take based upon the additional information.
In order to support future extension, the response code is In order to support future extension, the response code is
represented as a slash-separated hierarchy with each level of represented as a slash-separated hierarchy with each level of
hierarchy representing increasing detail about the error. Clients hierarchy representing increasing detail about the error. Clients
MUST ignore additional hierarchical response code detail which they MUST tolerate additional hierarchical response code detail which they
don't understand. don't understand.
The currently defined response codes are: The currently defined response codes are:
AUTH-TOO-WEAK AUTH-TOO-WEAK
This response code is returned on a tagged NO result from an This response code is returned on a tagged NO result from an
AUTHENTICATE command. It indicates that site security policy AUTHENTICATE command. It indicates that site security policy
forbids the use of the requested mechanism for the specified forbids the use of the requested mechanism for the specified
authentication identity. authentication identity.
skipping to change at page 20, line 5 skipping to change at page 19, line 4
This response code is returned on a tagged NO result from an This response code is returned on a tagged NO result from an
AUTHENTICATE command. It indicates that site security policy AUTHENTICATE command. It indicates that site security policy
requires the use of a strong encryption mechanism for the requires the use of a strong encryption mechanism for the
specified authentication identity and mechanism. specified authentication identity and mechanism.
INVALID INVALID
This response code indicates that a STORE command included This response code indicates that a STORE command included
data which the server implementation does not permit. It data which the server implementation does not permit. It
MUST NOT be used unless the dataset class specification for MUST NOT be used unless the dataset class specification for
the attribute in question explicitly permits enforced server the attribute in question explicitly permits enforced server
Internet DRAFT ACAP August 1997
validation. The argument is the attribute which was invalid. validation. The argument is the attribute which was invalid.
MODIFIED MODIFIED
This response code indicates that a conditional store failed This response code indicates that a conditional store failed
because the modtime on the entry is later than the modtime because the modtime on the entry is later than the modtime
specified with the STORE command UNCHANGEDSINCE modifier. specified with the STORE command UNCHANGEDSINCE modifier.
The argument is the entry which had been modified. The argument is the entry which had been modified.
NOEXIST NOEXIST
This response code indicates that a search or NOCREATE store This response code indicates that a search or NOCREATE store
skipping to change at page 20, line 34 skipping to change at page 19, line 36
A STORE or SETACL command which would have increased the size A STORE or SETACL command which would have increased the size
of the dataset failed due to insufficient quota. of the dataset failed due to insufficient quota.
REFER REFER
This response code may be returned in a tagged NO response to This response code may be returned in a tagged NO response to
any command that takes a dataset name as a parameter. It has any command that takes a dataset name as a parameter. It has
one or more arguments with the syntax of relative URLs. It one or more arguments with the syntax of relative URLs. It
is a referral, indicating that the command should be retried is a referral, indicating that the command should be retried
using one of the relative URLs. using one of the relative URLs.
SASL This response code can occur in the tagged OK response to a
successful AUTHENTICATE command and includes the optional
final server response data from the server as specified by
SASL [SASL].
TOOMANY TOOMANY
This response code may be returned in a tagged OK response to This response code may be returned in a tagged OK response to
a SEARCH command which includes the LIMIT modifier. The a SEARCH command which includes the LIMIT modifier. The
argument returns the total number of matching entries. argument returns the total number of matching entries.
TOOOLD TOOOLD
The modtime specified in the DELETEDSINCE command is too old, The modtime specified in the DELETEDSINCE command is too old,
so deletedsince information is no longer available. so deletedsince information is no longer available.
TRANSITION-NEEDED TRANSITION-NEEDED
This response code occurs on a NO response to an AUTHENTICATE This response code occurs on a NO response to an AUTHENTICATE
command with a mechanism other than PLAIN or ANONYMOUS. It command. It indicates that the user name is valid, but the
indicates that the PLAIN SASL [SASL-PLAIN] mechanism is entry in the authentication database needs to be updated in
needed prior to using the stronger mechanism requested. order to permit authentication with the specified mechanism.
Internet DRAFT ACAP August 1997
This can happen if a user has an entry in a system
authentication database such as Unix /etc/passwd, but does
not have credentials suitable for use by the specified
mechanism.
TRYLATER TRYLATER
A command failed due to a temporary server failure. The A command failed due to a temporary server failure. The
client MAY continue using local information and try the client MAY continue using local information and try the
command later. command later.
TRYFREECONTEXT TRYFREECONTEXT
This response code may be returned in a tagged NO response to This response code may be returned in a tagged NO response to
a SEARCH command which includes the MAKECONTEXT modifier. It a SEARCH command which includes the MAKECONTEXT modifier. It
indicates that a new context may not be created due to the indicates that a new context may not be created due to the
server's limit on the number of existing contexts. server's limit on the number of existing contexts.
WAYTOOMANY WAYTOOMANY
This response code may be returned in a tagged NO response to This response code may be returned in a tagged NO response to
a SEARCH command which includes a HARDLIMIT search modifier. a SEARCH command which includes a HARDLIMIT search modifier.
It indicates that the SEARCH would have returned more entries It indicates that the SEARCH would have returned more entries
than the HARDLIMIT permitted. than the HARDLIMIT permitted.
Additional response codes MUST be registered with IANA according Additional response codes MUST be registered with IANA according
to the proceedures in section 7.2. Client implementations MUST to the proceedures in section 7.2. Client implementations MUST
ignore response codes that they do not recognize. tolerate response codes that they do not recognize.
4. Namespace Conventions 4. Namespace Conventions
4.1. Dataset Namespace 4.1. Dataset Namespace
The dataset namespace is a slash-separated hierarchy. The first The dataset namespace is a slash-separated hierarchy. The first
component of the dataset namespace is a dataset class. Dataset component of the dataset namespace is a dataset class. Dataset
classes MUST have a vendor prefix (vendor.<vendor/product>) or be classes MUST have a vendor prefix (vendor.<vendor/product>) or be
specified in a standards track or IESG approved experimental RFC. specified in a standards track or IESG approved experimental RFC.
See section 7.3 for the registration template. See section 7.3 for the registration template.
skipping to change at page 21, line 44 skipping to change at page 21, line 4
per-host data and per-user data respectively. per-host data and per-user data respectively.
For "group", "host", and "user" areas, the third component of the For "group", "host", and "user" areas, the third component of the
path is the group name, the fully qualified host domain name, or the path is the group name, the fully qualified host domain name, or the
user name. A path of the form "/<dataset-class>/~/" is a convenient user name. A path of the form "/<dataset-class>/~/" is a convenient
abbreviation for "/<dataset-class>/user/<current-user>/". abbreviation for "/<dataset-class>/user/<current-user>/".
Dataset names which begin with "/byowner/" are reserved as an Dataset names which begin with "/byowner/" are reserved as an
alternate view of the namespace. This provides a way to see all the alternate view of the namespace. This provides a way to see all the
dataset classes which a particular owner uses. For example, dataset classes which a particular owner uses. For example,
"/byowner/~/<dataset-class>/" is an alternate name for "/<dataset-
class>/~/". Byowner provides a way to view a list of dataset classes Internet DRAFT ACAP August 1997
owned by a given user; this is done using the dataset
"/byowner/~/<dataset-class>/" is an alternate name for
"/<dataset-class>/~/". Byowner provides a way to view a list of
dataset classes owned by a given user; this is done using the dataset
"/byowner/user/<current-user>/" with the NOINHERIT SEARCH modifier. "/byowner/user/<current-user>/" with the NOINHERIT SEARCH modifier.
The dataset "/" may be used to find all dataset classes visible to The dataset "/" may be used to find all dataset classes visible to
the current user. A dataset of the form "/<dataset-class>/user/" may the current user. A dataset of the form "/<dataset-class>/user/" may
be used to find all users which have made a dataset or entry of that be used to find all users which have made a dataset or entry of that
class visible to the current user. class visible to the current user.
The formal syntax for a dataset name is defined by the "dataset-name" The formal syntax for a dataset name is defined by the "dataset-name"
terminal in section 4.3. rule in section 4.3.
4.2. Attribute Namespace 4.2. Attribute Namespace
Attribute names which do not contain a dot (".") are reserved for Attribute names which do not contain a dot (".") are reserved for
standardized attributes which have meaning in any dataset. In order standardized attributes which have meaning in any dataset. In order
to simplify client implementations, the attribute namespace is to simplify client implementations, the attribute namespace is
intended to be unique across all datasets. To achieve this, intended to be unique across all datasets. To achieve this,
attribute names are prefixed with the dataset class name followed by attribute names are prefixed with the dataset class name followed by
a dot ("."). Attributes which effect management of the dataset are a dot ("."). Attributes which affect management of the dataset are
prefixed with "dataset.". In addition, a subtree of the "vendor." prefixed with "dataset.". In addition, a subtree of the "vendor."
attribute namespace may be registered with IANA according to the attribute namespace may be registered with IANA according to the
rules in section 7.4. ACAP implementors are encouraged to help rules in section 7.4. ACAP implementors are encouraged to help
define interoperable dataset classes specifications rather than using define interoperable dataset classes specifications rather than using
the private attribute namespace. the private attribute namespace.
Finally, the "user.<user-name>." and "site." subtrees of the Some users or sites may wish to add their own private attributes to
attribute namespace are reserved for user-specific and site-specific certain dataset classes. In order to enable this, the "user.<user-
attributes respectively. Such attributes are not interoperable so name>." and "site." subtrees of the attribute namespace are reserved
are discouraged in favor of defining standard attributes. A future for user-specific and site-specific attributes respectively and will
not be standardized. Such attributes are not interoperable so are
discouraged in favor of defining standard attributes. A future
extension is expected to permit discovery of syntax for user or extension is expected to permit discovery of syntax for user or
site-specific attributes. Clients wishing to support display of user site-specific attributes. Clients wishing to support display of user
or site-specific attributes should display the value of any non-NIL or site-specific attributes should display the value of any non-NIL
single-valued "user.<user-name>." or "site." attribute which has single-valued "user.<user-name>." or "site." attribute which has
valid UTF-8 syntax. valid UTF-8 syntax.
The formal syntax for an attribute name is defined by the The formal syntax for an attribute name is defined by the
"attribute-name" terminal in the next section. "attribute-name" rule in the next section.
Internet DRAFT ACAP August 1997
4.3. Formal Syntax for Dataset and Attribute Namespace 4.3. Formal Syntax for Dataset and Attribute Namespace
The naming conventions for datasets and attributes are defined by the The naming conventions for datasets and attributes are defined by the
following ABNF. Note that this grammar is not part of the ACAP following ABNF. Note that this grammar is not part of the ACAP
protocol syntax in section 8, as dataset names and attribute names protocol syntax in section 8, as dataset names and attribute names
are encoded as strings within the ACAP protocol. are encoded as strings within the ACAP protocol.
attribute-dacl = "dataset.acl" *("." name-component) attribute-dacl = "dataset.acl" *("." name-component)
skipping to change at page 23, line 37 skipping to change at page 23, line 5
dataset-tail = owner "/" dataset-sub dataset-tail = owner "/" dataset-sub
dname-component = 1*UTF8-CHAR dname-component = 1*UTF8-CHAR
;; MUST NOT begin with "." or contain "/" ;; MUST NOT begin with "." or contain "/"
name-component = 1*UTF8-CHAR name-component = 1*UTF8-CHAR
;; MUST NOT contain ".", "/", "%", or "*" ;; MUST NOT contain ".", "/", "%", or "*"
owner = "site" / owner-host / owner-group / owner-user / "~" owner = "site" / owner-host / owner-group / owner-user / "~"
Internet DRAFT ACAP August 1997
owner-group = "group/" dname-component owner-group = "group/" dname-component
owner-host = "host/" dname-component owner-host = "host/" dname-component
owner-prefix = "group/" / "host/" / "user/" owner-prefix = "group/" / "host/" / "user/"
owner-user = "user/" dname-component owner-user = "user/" dname-component
vendor-name = vendor-token *("." name-component) vendor-name = vendor-token *("." name-component)
skipping to change at page 24, line 40 skipping to change at page 24, line 4
dataset includes a "subdataset" attribute and the inheriting dataset dataset includes a "subdataset" attribute and the inheriting dataset
does not, then the "subdataset" attribute will inherit a virtual does not, then the "subdataset" attribute will inherit a virtual
value of a list containing a ".". The subdataset at that node is value of a list containing a ".". The subdataset at that node is
said to be a "virtual" dataset as it is simply a virtual copy of the said to be a "virtual" dataset as it is simply a virtual copy of the
appropriate base dataset with all "subdataset" attributes changed to appropriate base dataset with all "subdataset" attributes changed to
a list containing a ".". A virtual dataset is not visible if a list containing a ".". A virtual dataset is not visible if
NOINHERIT is specified on the SEARCH command. NOINHERIT is specified on the SEARCH command.
Servers MUST support at least two levels of inheritance. This Servers MUST support at least two levels of inheritance. This
permits a user's dataset such as "/options/user/fred/common" to permits a user's dataset such as "/options/user/fred/common" to
Internet DRAFT ACAP August 1997
inherit from a group dataset such as "/options/group/dinosaur inherit from a group dataset such as "/options/group/dinosaur
operators/common" which in turn inherits from a server-wide dataset operators/common" which in turn inherits from a server-wide dataset
such as "/options/site/common". such as "/options/site/common".
5.2. Dataset Attributes 5.2. Dataset Attributes
The following attributes apply to management of the dataset when The following attributes apply to management of the dataset when
stored in the "" entry of a dataset. These attributes are not stored in the "" entry of a dataset. These attributes are not
inherited. inherited.
dataset.acl dataset.acl
This holds the default access control list for the dataset. It This holds the default access control list for the dataset.
can not be modified by the STORE command, only by the SETACL and This attribute is validated, so an invalid access control list
DELETEACL commands. in a STORE command will result in a NO response with an INVALID
response code.
dataset.acl.<attribute> dataset.acl.<attribute>
This holds the default access control list for an attribute This holds the default access control list for an attribute
within the dataset. It can not be modified by the STORE command, within the dataset. This attribute is validated, so an invalid
only by the SETACL and DELETEACL commands. access control list in a STORE command will result in a NO
response with an INVALID response code.
dataset.inherit dataset.inherit
This holds the name of a dataset from which to inherit according This holds the name of a dataset from which to inherit according
to the rules in the previous section. This attribute MAY refer to the rules in the previous section. This attribute MAY refer
to a non-existent dataset, in which case nothing is inherited. to a non-existent dataset, in which case nothing is inherited.
This attribute is validated, so illegal dataset syntax or an
attempt to store a multi-value will result in a NO response with
an INVALID response code.
5.3. Dataset Creation 5.3. Dataset Creation
When a dataset is first created (by storing a "." in the subdataset When a dataset is first created (by storing a "." in the subdataset
attribute or storing an entry in a previously non-existent dataset), attribute or storing an entry in a previously non-existent dataset),
the dataset attributes are initialized with the values from the the dataset attributes are initialized with the values from the
parent dataset in the "/byowner/" hierarchy. In the case of the parent dataset in the "/byowner/" hierarchy. In the case of the
"dataset.inherit" attribute, the appropriate hierarchy component is "dataset.inherit" attribute, the appropriate hierarchy component is
added. For example, given the following entry: added. For example, given the following entry (note that \t refers
to the US-ASCII horizontal tab character):
entry path "/byowner/user/joe/" entry path "/byowner/user/joe/"
dataset.acl ("joe" "rwia") dataset.acl ("joe\txrwia" "fred\txr")
dataset.inherit "/byowner/site" dataset.inherit "/byowner/site"
If a new dataset class "/byowner/~/new" is created, it will have the If a new dataset class "/byowner/user/joe/new" is created, it will
following dataset attributes: have the following dataset attributes:
entry path "/byowner/user/joe/new/" entry path "/byowner/user/joe/new/"
dataset.acl ("joe" "rwia")
Internet DRAFT ACAP August 1997
dataset.acl ("joe\txrwia" "fred\txr")
dataset.inherit "/byowner/site/new" dataset.inherit "/byowner/site/new"
Note that the dataset "/byowner/user/joe/new/" is equivalent to Note that the dataset "/byowner/user/joe/new/" is equivalent to
"/new/user/joe/". "/new/user/joe/".
5.4. Dataset Class Capabilities 5.4. Dataset Class Capabilities
Certain dataset classes or dataset class features may only be useful Certain dataset classes or dataset class features may only be useful
if there is an active updating client or integrated server support if there is an active updating client or integrated server support
for the feature. The dataset class "capability" is reserved to allow for the feature. The dataset class "capability" is reserved to allow
skipping to change at page 26, line 14 skipping to change at page 25, line 32
dataset class specification. dataset class specification.
Since it is possible for an unprivileged user to run an active client Since it is possible for an unprivileged user to run an active client
for himself, a per-user capability dataset is useful. The dataset for himself, a per-user capability dataset is useful. The dataset
"/capability/~/" holds information about all features available to "/capability/~/" holds information about all features available to
the user (via inheritance), and the dataset "/capability/site/" holds the user (via inheritance), and the dataset "/capability/site/" holds
information about all features supported by the site. information about all features supported by the site.
5.5. Dataset Quotas 5.5. Dataset Quotas
Management and scope of quotas is implementation dependent. Clients Management and scope of quotas is implementation dependent. Clients
can check the applicable quota limit and usage (in bytes) with the can check the applicable quota limit and usage (in bytes) with the
GETQUOTA command. Servers can notify the client of a low quota GETQUOTA command. Servers can notify the client of a low quota
situation with the QUOTA untagged response. situation with the QUOTA untagged response.
6. Command and Response Specifications 6. Command and Response Specifications
ACAP commands and responses are described in this section. Commands ACAP commands and responses are described in this section. Commands
are organized first by the state in which the command is permitted, are organized first by the state in which the command is permitted,
then by a general category of command type. then by a general category of command type.
skipping to change at page 26, line 37 skipping to change at page 26, line 4
precise syntax of command arguments is described in the Formal Syntax precise syntax of command arguments is described in the Formal Syntax
section. section.
Some commands cause specific server data to be returned; these are Some commands cause specific server data to be returned; these are
identified by "Data:" in the command descriptions below. See the identified by "Data:" in the command descriptions below. See the
response descriptions in the Responses section for information on response descriptions in the Responses section for information on
these responses, and the Formal Syntax section for the precise syntax these responses, and the Formal Syntax section for the precise syntax
of these responses. It is possible for server data to be transmitted of these responses. It is possible for server data to be transmitted
as a result of any command; thus, commands that do not specifically as a result of any command; thus, commands that do not specifically
require server data specify "no specific data for this command" require server data specify "no specific data for this command"
Internet DRAFT ACAP August 1997
instead of "none". instead of "none".
The "Result:" in the command description refers to the possible The "Result:" in the command description refers to the possible
tagged status responses to a command, and any special interpretation tagged status responses to a command, and any special interpretation
of these status responses. of these status responses.
6.1. Initial Connection 6.1. Initial Connection
Upon session startup, the server sends one of two untagged responses: Upon session startup, the server sends one of two untagged responses:
ACAP or BYE. The untagged BYE response is described in section ACAP or BYE. The untagged BYE response is described in section
skipping to change at page 27, line 19 skipping to change at page 26, line 33
The untagged ACAP response indicates the session is ready to The untagged ACAP response indicates the session is ready to
accept commands and contains a space-separated listing of accept commands and contains a space-separated listing of
capabilities that the server supports. Each capability is capabilities that the server supports. Each capability is
represented by a list containing the capability name optionally represented by a list containing the capability name optionally
followed by capability specific string arguments. followed by capability specific string arguments.
ACAP capability names MUST be defined in a standards track or IESG ACAP capability names MUST be defined in a standards track or IESG
approved experimental RFC and registered with IANA according to approved experimental RFC and registered with IANA according to
the rules in section 7.1. the rules in section 7.1.
Client implementations SHOULD NOT require any capability name, and Client implementations SHOULD NOT require any capability name
MUST ignore any unknown capability names. beyond those defined in this specification, and MUST tolerate any
unknown capability names. A client implementation MAY be
configurable to require SASL mechanisms other than CRAM-MD5
[CRAM-MD5] for site security policy reasons.
The following initial capabilities are defined: The following initial capabilities are defined:
CONTEXTLIMIT CONTEXTLIMIT
The CONTEXTLIMIT capability has one argument which is a The CONTEXTLIMIT capability has one argument which is a
number describing the maximum number of contexts the server number describing the maximum number of contexts the server
supports per connection. The number 0 indicates the server supports per connection. The number 0 indicates the server
has no limit, otherwise this number MUST be greater than has no limit, otherwise this number MUST be greater than
100. 100.
IMPLEMENTATION IMPLEMENTATION
The IMPLEMENTATION capability has one argument which is a The IMPLEMENTATION capability has one argument which is a
string describing the server implementation. ACAP clients string describing the server implementation. ACAP clients
MUST NOT alter their behavior based on this value. It is MUST NOT alter their behavior based on this value. It is
Internet DRAFT ACAP August 1997
intended primarily for debugging purposes. intended primarily for debugging purposes.
SASL The SASL capability includes a list of the authentication SASL The SASL capability includes a list of the authentication
mechanisms supported by the server. See section 6.3.1. mechanisms supported by the server. See section 6.3.1.
Example: S: * ACAP (IMPLEMENTATION "ACME v3.5") Example: S: * ACAP (IMPLEMENTATION "ACME v3.5")
(SASL "CRAM-MD5" "PLAIN") (CONTEXTLIMIT "200") (SASL "CRAM-MD5") (CONTEXTLIMIT "200")
6.2. Any State 6.2. Any State
The following commands and responses are valid in any state. The following commands and responses are valid in any state.
6.2.1. NOOP Command 6.2.1. NOOP Command
Arguments: none Arguments: none
Data: no specific data for this command (but see below) Data: no specific data for this command (but see below)
skipping to change at page 28, line 33 skipping to change at page 27, line 47
Data: intermediate response: LANG Data: intermediate response: LANG
Result: OK - lang completed Result: OK - lang completed
NO - no matching language available NO - no matching language available
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
One or more arguments are supplied to indicate the client's One or more arguments are supplied to indicate the client's
preferred languages for error messages. The server will match preferred languages for error messages. The server will match
each client preference in order against its internal table of each client preference in order against its internal table of
available error strings languages. For a client preference to available error string languages. For a client preference to
match a server language table, the client's language tag MUST be a match a server language, the client's language tag MUST be a
prefix of the server's tag and match up to a "-" or the end of prefix of the server's tag and match up to a "-" or the end of
string. If a match is found, the server returns an intermediate string. If a match is found, the server returns an intermediate
LANG response and an OK response. The LANG response indicates the LANG response and an OK response. The LANG response indicates the
actual language selected and appropriate comparators for use with actual language selected and appropriate comparators for use with
that language.
Internet DRAFT ACAP August 1997
the languages listed in the LANG command.
If no LANG command is issued, all error text strings MUST be in If no LANG command is issued, all error text strings MUST be in
technical English intended for an international audience. This English intended for an international audience. This rule is
rule is necessary because the default error text has to be in a necessary because the default error text has to be in a language
language which is most likely to be useful to any pair of client which is most likely to be useful to any pair of client and server
and server vendors (since both have to diagnose problems). In vendors (since both have to diagnose problems). In addition, the
addition, the default language for errors has to use the US-ASCII default language for errors has to use the US-ASCII subset of
subset of UTF-8, since it can be displayed on the largest number UTF-8, since it can be displayed on the largest number of
of computers. Explicitly negotiating "en" or a dialect such as computers. Explicitly negotiating "en" is the same as the default
"en-us" indicates a preference for messages intended for the end language, but MAY be different from explicitly negotiating "en-US"
user and MAY be different from the default language. or "en-UK".
Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk"
C: A003 LANG "fr-ca" "i;octet" "i;numeric" C: A003 LANG "fr-ca" "i;octet" "i;ascii-numeric"
"fr;nocase;octet" "i;ascii-casemap" "en;primary" "fr;primary"
S: A003 OK "Bonjour" S: A003 OK "Bonjour"
6.2.3. LANG Intermediate Response 6.2.3. LANG Intermediate Response
Data: language for error responses Data: language for error responses
list of appropriate comparators appropriate comparators
The LANG response indicates the language which will be used for The LANG response indicates the language which will be used for
error responses and a list of comparators which are appropriate error responses and the comparators which are appropriate for the
for that language. The list of comparators should be in languages listed in the LANG command. The comparators SHOULD be
approximate order from most efficient (usually "i;octet") to most in approximate order from most efficient (usually "i;octet") to
appropriate for human text. most appropriate for human text in the preferred language.
6.2.4. LOGOUT Command 6.2.4. LOGOUT Command
Arguments: none Arguments: none
Data: mandatory untagged response: BYE Data: mandatory untagged response: BYE
Result: OK - logout completed Result: OK - logout completed
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
The LOGOUT command informs the server that the client is done with The LOGOUT command informs the server that the client is done with
the session. The server must send a BYE untagged response before the session. The server must send a BYE untagged response before
the (tagged) OK response, and then close the network connection. the (tagged) OK response, and then close the network connection.
Example: C: A023 LOGOUT Example: C: A023 LOGOUT
S: * BYE "ACAP Server logging out" S: * BYE "ACAP Server logging out"
S: A023 OK "LOGOUT completed" S: A023 OK "LOGOUT completed"
(Server and client then close the connection) (Server and client then close the connection)
Internet DRAFT ACAP August 1997
6.2.5. OK Response 6.2.5. OK Response
Data: optional response code Data: optional response code
human-readable text human-readable text
The OK response indicates an information message from the server. The OK response indicates an information message from the server.
When tagged, it indicates successful completion of the associated When tagged, it indicates successful completion of the associated
command. The human-readable text may be presented to the user as command. The human-readable text may be presented to the user as
an information message. The untagged form indicates an an information message. The untagged form indicates an
information-only message; the nature of the information MAY be information-only message; the nature of the information MAY be
skipping to change at page 30, line 40 skipping to change at page 30, line 4
6.2.7. BAD Response 6.2.7. BAD Response
Data: optional response code Data: optional response code
human-readable text human-readable text
The BAD response indicates an error message from the server. When The BAD response indicates an error message from the server. When
tagged, it reports a protocol-level error in the client's command; tagged, it reports a protocol-level error in the client's command;
the tag indicates the command that caused the error. The untagged the tag indicates the command that caused the error. The untagged
form indicates a protocol-level error for which the associated form indicates a protocol-level error for which the associated
command can not be determined; it may also indicate an internal command can not be determined; it may also indicate an internal
Internet DRAFT ACAP August 1997
server failure. The human-readable text describes the condition. server failure. The human-readable text describes the condition.
Example: C: ...empty line... Example: C: ...empty line...
S: * BAD "Empty command line" S: * BAD "Empty command line"
C: A443 BLURDYBLOOP C: A443 BLURDYBLOOP
S: A443 BAD "Unknown command" S: A443 BAD "Unknown command"
C: A444 NOOP Hello C: A444 NOOP Hello
S: A444 BAD "invalid arguments" S: A444 BAD "invalid arguments"
6.2.8. BYE Untagged Response 6.2.8. BYE Untagged Response
skipping to change at page 31, line 39 skipping to change at page 31, line 5
The human-readable text contains a special human generated alert The human-readable text contains a special human generated alert
message that MUST be presented to the user in a fashion that calls message that MUST be presented to the user in a fashion that calls
the user's attention to the message. This is intended to be used the user's attention to the message. This is intended to be used
for vital messages from the server administrator to the user, such for vital messages from the server administrator to the user, such
as a warning that the server will soon be shut down for as a warning that the server will soon be shut down for
maintenance. maintenance.
Example: S: * ALERT "This ACAP server will be shut down in Example: S: * ALERT "This ACAP server will be shut down in
10 minutes for system maintenance." 10 minutes for system maintenance."
Internet DRAFT ACAP August 1997
6.3. Non-Authenticated State 6.3. Non-Authenticated State
In non-authenticated state, the AUTHENTICATE command establishes In non-authenticated state, the AUTHENTICATE command establishes
authentication and enters authenticated state. The AUTHENTICATE authentication and enters authenticated state. The AUTHENTICATE
command provides a general mechanism for a variety of authentication command provides a general mechanism for a variety of authentication
techniques. techniques.
Server implementations may allow non-authenticated access to certain Server implementations may allow non-authenticated access to certain
information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism. information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism.
skipping to change at page 32, line 34 skipping to change at page 31, line 49
exchange to authenticate and identify the user. Optionally, it exchange to authenticate and identify the user. Optionally, it
also negotiates a security layer for subsequent protocol also negotiates a security layer for subsequent protocol
interactions. If the requested authentication mechanism is not interactions. If the requested authentication mechanism is not
supported, the server rejects the AUTHENTICATE command by sending supported, the server rejects the AUTHENTICATE command by sending
a tagged NO response. a tagged NO response.
The authentication protocol exchange consists of a series of The authentication protocol exchange consists of a series of
server challenges and client answers that are specific to the server challenges and client answers that are specific to the
authentication mechanism. A server challenge consists of a authentication mechanism. A server challenge consists of a
command continuation request with the "+" token followed by a command continuation request with the "+" token followed by a
BASE64 encoded string. The client answer consists of a line string. The client answer consists of a line consisting of a
consisting of a BASE64 encoded string. If the client wishes to string. If the client wishes to cancel an authentication
cancel an authentication exchange, it should issue a line with a exchange, it should issue a line with a single unquoted "*". If
single "*". If the server receives such an answer, it must reject the server receives such an answer, it must reject the
the AUTHENTICATE command by sending a tagged BAD response. AUTHENTICATE command by sending a tagged BAD response.
Internet DRAFT ACAP August 1997
The optional initial-response argument to the AUTHENTICATE command The optional initial-response argument to the AUTHENTICATE command
is used to save a round trip when using authentication mechanisms is used to save a round trip when using authentication mechanisms
that are defined to send no data in the initial challenge. When that are defined to send no data in the initial challenge. When
the initial-response argument is used with such a mechanism, the the initial-response argument is used with such a mechanism, the
initial empty challenge is not sent to the client and the server initial empty challenge is not sent to the client and the server
uses the data in the initial-response argument as if it were sent uses the data in the initial-response argument as if it were sent
in response to the empty challenge. If the initial-response in response to the empty challenge. If the initial-response
argument to the AUTHENTICATE command is used with a mechanism argument to the AUTHENTICATE command is used with a mechanism that
that sends data in the initial challenge, the server rejects the sends data in the initial challenge, the server rejects the
AUTHENTICATE command by sending a tagged NO response. AUTHENTICATE command by sending a tagged NO response.
The service name specified by this protocol's profile of SASL is The service name specified by this protocol's profile of SASL is
"acap". "acap".
If a security layer is negotiated through the SASL authentication If a security layer is negotiated through the SASL authentication
exchange, it takes effect immediately following the CRLF that exchange, it takes effect immediately following the CRLF that
concludes the authentication exchange for the client, and the CRLF concludes the authentication exchange for the client, and the CRLF
of the tagged OK response for the server. of the tagged OK response for the server.
All ACAP implementations MUST support the PLAIN SASL mechanism All ACAP implementations MUST implement the CRAM-MD5 SASL
[SASL-PLAIN], although they MAY offer a configuration option to mechanism [CRAM-MD5], although they MAY offer a configuration
disable plaintext passwords if site security policy dictates. option to disable it if site security policy dictates. CRAM-MD5
ACAP implementations SHOULD support an external encryption service uses the HMAC-MD5 [HMAC] Keyed-Hashing construction. The example
or a stronger standards track SASL mechanism. below is the same example described in the CRAM-MD5 specification.
If an AUTHENTICATE command fails with a NO response, the client If an AUTHENTICATE command fails with a NO response, the client
may try another authentication mechanism by issuing another may try another authentication mechanism by issuing another
AUTHENTICATE command. In other words, the client may request AUTHENTICATE command. In other words, the client may request
authentication types in decreasing order of preference. authentication types in decreasing order of preference.
Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5") Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5")
(SASL "PLAIN" "KERBEROS_V4") (SASL "CRAM-MD5" "KERBEROS_V4")
C: A001 AUTHENTICATE KERBEROS_V4 C: A001 AUTHENTICATE "CRAM-MD5"
S: + AmFYig== S: + "<1896.697170952@postoffice.reston.mci.net>"
C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT C: "tim b913a602c7eda7a495b4e6e7334d3890"
+nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd S: A001 OK "CRAM-MD5 authentication successful"
WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh
S: + or//EoAADZI=
C: DiAF5A4gA+oOIALuBkAAmw==
S: A001 OK "Kerberos V4 authentication successful"
6.4. Searching 6.4. Searching
This section describes the SEARCH command, for retrieving data from This section describes the SEARCH command, for retrieving data from
datasets. datasets.
Internet DRAFT ACAP August 1997
6.4.1. SEARCH Command 6.4.1. SEARCH Command
Arguments: dataset or context name Arguments: dataset or context name
optional list of modifiers optional list of modifiers
search criteria search criteria
Data: intermediate responses: ENTRY, MODTIME, REFER Data: intermediate responses: ENTRY, MODTIME, REFER
untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME
Result: OK - search completed Result: OK - search completed
skipping to change at page 35, line 4 skipping to change at page 34, line 4
the current server, then a REFER intermediate response is the current server, then a REFER intermediate response is
returned for that subtree and the search continues. returned for that subtree and the search continues.
HARDLIMIT number HARDLIMIT number
If the SEARCH command would result in more than number If the SEARCH command would result in more than number
entries, the SEARCH fails with a NO completion result with a entries, the SEARCH fails with a NO completion result with a
WAYTOOMANY response code. WAYTOOMANY response code.
LIMIT number number LIMIT number number
Limits the number of intermediate ENTRY responses that the Limits the number of intermediate ENTRY responses that the
Internet DRAFT ACAP August 1997
search may generate. The first numeric argument specifies search may generate. The first numeric argument specifies
the limit, the second number specifies the number of entries the limit, the second number specifies the number of entries
to return if the number of matches exceeds the limit. If the to return if the number of matches exceeds the limit. If the
limit is exceeded, the SEARCH command still succeeds, limit is exceeded, the SEARCH command still succeeds,
returning the total number of matches in a TOOMANY response returning the total number of matches in a TOOMANY response
code in the tagged OK response. code in the tagged OK response.
MAKECONTEXT [ENUMERATE] [NOTIFY] context MAKECONTEXT [ENUMERATE] [NOTIFY] context
The SEARCH command creates a context with the name given in Causes the SEARCH command to create a context with the name
the argument to refer to the matching entries. If the SEARCH given in the argument to refer to the matching entries. If
is successful, the context name may then be given as an the SEARCH is successful, the context name may then be given
argument to subsequent SEARCH commands to search the set of as an argument to subsequent SEARCH commands to search the
matching entries. If a context with the specified name set of matching entries. If a context with the specified
already exists, it is first freed. If a new context may not name already exists, it is first freed. If a new context may
be created due to the server's limit on the number of not be created due to the server's limit on the number of
existing contexts, the command fails, returning a existing contexts, the command fails, returning a
TRYFREECONTEXT response code in the NO completion response. TRYFREECONTEXT response code in the NO completion response.
The optional "ENUMERATE" and "NOTIFY" arguments may be The optional "ENUMERATE" and "NOTIFY" arguments may be
included to request enumeration of the context (for virtual included to request enumeration of the context (for virtual
scroll bars) or change notifications for the context. If scroll bars) or change notifications for the context. If
"NOTIFY" is not requested, the context represents a snapshot "NOTIFY" is not requested, the context represents a snapshot
of the entries at the time the SEARCH was issued. of the entries at the time the SEARCH was issued.
ENUMERATE requests that the contents of the context be ENUMERATE requests that the contents of the context be
skipping to change at page 36, line 4 skipping to change at page 35, line 4
issued for changes which occur after the server receives the issued for changes which occur after the server receives the
SEARCH command which created the context. After issuing a SEARCH command which created the context. After issuing a
sequence of ADDTO, REMOVEFROM or CHANGE notifications, the sequence of ADDTO, REMOVEFROM or CHANGE notifications, the
server MUST issue an untagged MODTIME notification indicating server MUST issue an untagged MODTIME notification indicating
that the client has all updates to the entries in the context that the client has all updates to the entries in the context
up to and including the given modtime value. Servers are up to and including the given modtime value. Servers are
permitted a reasonable delay to batch change notifications permitted a reasonable delay to batch change notifications
before sending them to the client. before sending them to the client.
The position arguments of the ADDTO, REMOVEFROM and CHANGE The position arguments of the ADDTO, REMOVEFROM and CHANGE
Internet DRAFT ACAP August 1997
notifications are 0 if ENUMERATE is not requested. notifications are 0 if ENUMERATE is not requested.
NOINHERIT NOINHERIT
This causes the SEARCH command to operate without This causes the SEARCH command to operate without
inheritance. It can be used to tell which values are inheritance. It can be used to tell which values are
explicit overrides. If MAKECONTEXT is also specified, the explicit overrides. If MAKECONTEXT is also specified, the
created context is also not effected by inheritance. created context is also not affected by inheritance.
RETURN (metadata...) RETURN (metadata...)
Specifies what is to be returned in intermediate ENTRY Specifies what is to be returned in intermediate ENTRY
responses. If this modifier is not specified, no responses. If this modifier is not specified, no
intermediate ENTRY responses are returned. intermediate ENTRY responses are returned.
Inside the parentheses is an optional list of attributes, Inside the parentheses is an optional list of attributes,
each optionally followed by a parenthesized list of metadata. each optionally followed by a parenthesized list of metadata.
If the parenthesized list of metadata is not specified, it If the parenthesized list of metadata is not specified, it
defaults to "(value)". defaults to "(value)".
skipping to change at page 37, line 5 skipping to change at page 36, line 5
If the SORT modifier is used in conjunction with the If the SORT modifier is used in conjunction with the
MAKECONTEXT modifier, the SORT modifier specifies the MAKECONTEXT modifier, the SORT modifier specifies the
ordering of entries in the created context. ordering of entries in the created context.
If no SORT modifier is specified, or none of the If no SORT modifier is specified, or none of the
attribute/comparator pairs indicates an order for the two attribute/comparator pairs indicates an order for the two
entries, the server uses the order of the entries that exists entries, the server uses the order of the entries that exists
in the context or dataset being searched. in the context or dataset being searched.
Internet DRAFT ACAP August 1997
Following the modifiers is the search criteria. Searching Following the modifiers is the search criteria. Searching
criteria consist of one or more search keys. Search keys may be criteria consist of one or more search keys. Search keys may be
combined using the AND, and OR search keys. For example, the combined using the AND, and OR search keys. For example, the
criteria (the newline is for readability and not part of the criteria (the newline is for readability and not part of the
criteria): criteria):
AND COMPARE "modtime" "+i;octet" "19951206103400" AND COMPARE "modtime" "+i;octet" "19951206103400"
COMPARE "modtime" "-i;octet" "19960112000000" COMPARE "modtime" "-i;octet" "19960112000000"
refers to all entries modified between 10:34 December 6 1995 and refers to all entries modified between 10:34 December 6 1995 and
midnight January 12, 1996 UTC. midnight January 12, 1996 UTC.
skipping to change at page 38, line 4 skipping to change at page 37, line 4
specified comparator. If the specified comparator doesn't specified comparator. If the specified comparator doesn't
support substring matching, a BAD response is returned. support substring matching, a BAD response is returned.
RANGE start end time RANGE start end time
Entries which are within the specified range of the Entries which are within the specified range of the
enumerated context's ordering. The lowest-ordered entry in enumerated context's ordering. The lowest-ordered entry in
the context is assigned number one, the next lowest entry is the context is assigned number one, the next lowest entry is
assigned number two, and so on. The numeric arguments assigned number two, and so on. The numeric arguments
specify the lowest and highest numbers to match. The time specify the lowest and highest numbers to match. The time
specifies that the client has processed notifications for the specifies that the client has processed notifications for the
Internet DRAFT ACAP August 1997
context up to the specified time. If the context has been context up to the specified time. If the context has been
modified since then, the server MUST either return a NO with modified since then, the server MUST either return a NO with
a MODIFIED response code, or return the results that the a MODIFIED response code, or return the results that the
SEARCH would have returned if none of the changes since that SEARCH would have returned if none of the changes since that
time had been made. time had been made.
RANGE is only permitted on contexts. If RANGE is used with a RANGE is only permitted on enumerated contexts. If RANGE is
dataset, the server MUST return a BAD response. used with a dataset or non-enumerated context, the server
MUST return a BAD response.
SUBSTRING attribute comparator value SUBSTRING attribute comparator value
Entries which contain the specified value, using the Entries which contain the specified value, using the
specified comparator. If the specified comparator doesn't specified comparator. If the specified comparator doesn't
support substring matching, a BAD response is returned. support substring matching, a BAD response is returned.
6.4.2. ENTRY Intermediate Response 6.4.2. ENTRY Intermediate Response
Data: entry name Data: entry name
entry data entry data
The ENTRY intermediate response occurs as a result of a SEARCH or The ENTRY intermediate response occurs as a result of a SEARCH or
STORE command. This is the means by which dataset entries are STORE command. This is the means by which dataset entries are
returned to the client. returned to the client.
The ENTRY response beings with the entry name, if a SEARCH command The ENTRY response begins with the entry name, if a SEARCH command
without the DEPTH modifier was issued, or the entry path in other without the DEPTH modifier was issued, or the entry path in other
cases. This is followed by a set of zero or more items, one for cases. This is followed by a set of zero or more items, one for
each metadata item in the RETURN search modifier. Results each metadata item in the RETURN search modifier. Results
matching an attribute pattern are grouped in parentheses. matching an attribute pattern or returning multiple metadata items
are grouped in parentheses.
6.4.3. MODTIME Intermediate Response 6.4.3. MODTIME Intermediate Response
Data: modtime value Data: modtime value
The MODTIME intermediate response occurs as a result of a SEARCH The MODTIME intermediate response occurs as a result of a SEARCH
command. It indicates that the just created context or the command. It indicates that the just created context or the
previously returned ENTRY responses include all updates to the previously returned ENTRY responses include all updates to the
returned entries up to and including the modtime value in the returned entries up to and including the modtime value in the
argument. argument.
6.4.4. REFER Intermediate Response 6.4.4. REFER Intermediate Response
Data: dataset path Data: dataset path
ACAP URL relative ACAP URLs
Internet DRAFT ACAP August 1997
The REFER intermediate response occurs as a result of a The REFER intermediate response occurs as a result of a
multi-level SEARCH where one of the levels is located on a multi-level SEARCH where one of the levels is located on a
different server. The response indicates the dataset which is not different server. The response indicates the dataset which is not
located on the current server and an ACAP URL for where that located on the current server and one or more relative ACAP URLs
dataset may be found. for where that dataset may be found.
6.4.5. Search Examples 6.4.5. Search Examples
Here are some SEARCH command exchanges between the client and server: Here are some SEARCH command exchanges between the client and server:
C: A046 SEARCH "/addressbook/" DEPTH 3 RETURN ("addressbook.Alias" C: A046 SEARCH "/addressbook/" DEPTH 3 RETURN ("addressbook.Alias"
"addressbook.Email" "addressbook.List") OR NOT EQUAL "addressbook.Email" "addressbook.List") OR NOT EQUAL
"addressbook.Email" "i;octet" NIL NOT EQUAL "addressbook.List" "addressbook.Email" "i;octet" NIL NOT EQUAL "addressbook.List"
"i;octet" NIL "i;octet" NIL
S: A046 ENTRY "/addressbook/user/joe/A0345" "fred" S: A046 ENTRY "/addressbook/user/joe/A0345" "fred"
"fred@stone.org" NIL "fred@stone.org" NIL
S: A046 ENTRY "/addressbook/user/fred/A0537" "joe" "joe@stone.org" S: A046 ENTRY "/addressbook/user/fred/A0537" "joe" "joe@stone.org"
NIL NIL
S: A046 ENTRY "/addressbook/group/Dinosaur Operators/A423" S: A046 ENTRY "/addressbook/group/Dinosaur Operators/A423"
"saurians" NIL "1" "saurians" NIL "1"
S: A046 MODTIME "19970728105252" S: A046 MODTIME "19970728105252"
S: A046 OK "SEARCH completed" S: A046 OK "SEARCH completed"
C: A047 SEARCH "/addressbook/user/fred/" RETURN ("*") EQUAL "entry" C: A047 SEARCH "/addressbook/user/fred/" RETURN ("*") EQUAL "entry"
"i;octet" "A0345" "i;octet" "A0345"
S: A047 ENTRY "A0345" ("modtime" "19970728102226" "addressbook.Alias" S: A047 ENTRY "A0345" (("modtime" "19970728102226") ("addressbook.Alias"
"fred" "addressbook.Email" "fred@stone.org" "fred") ("addressbook.Email" "fred@stone.org")
"addressbook.CommonName" "Fred Flintstone" ("addressbook.CommonName" "Fred Flintstone")
"addressbook.Surname" "Flintstone" "addressbook.GivenName" ("addressbook.Surname" "Flintstone") ("addressbook.GivenName"
"Fred") "Fred"))
S: A046 MODTIME "19970728105258" S: A047 MODTIME "19970728105258"
S: A047 OK "SEARCH completed" S: A047 OK "SEARCH completed"
C: A048 SEARCH "/options/~/vendor.example/" RETURN C: A048 SEARCH "/options/~/vendor.example/" RETURN
("option.value"("size" "value" "myrights")) ("option.value"("size" "value" "myrights"))
SORT ("entry" "i;octet") COMPARE "modtime" "i;octet" SORT ("entry" "i;octet") COMPARE "modtime" "i;octet"
"19970727123225" "19970727123225"
S: A048 ENTRY "blurdybloop" 5 "ghoti" "rwia" S: A048 ENTRY "blurdybloop" (5 "ghoti" "rwia")
S: A048 ENTRY "buckybits" 2 "10" "rwia" S: A048 ENTRY "buckybits" (2 "10" "rwia")
S: A048 ENTRY "windowSize" 7 "100x100" "rwia" S: A048 ENTRY "windowSize" (7 "100x100" "rwia")
S: A046 MODTIME "19970728105304" S: A048 MODTIME "19970728105304"
S: A048 OK "SEARCH completed" S: A048 OK "SEARCH completed"
C: A049 SEARCH "/addressbook/~/public" RETURN ("addressbook.Alias" C: A049 SEARCH "/addressbook/~/public" RETURN ("addressbook.Alias"
"addressbook.Email") MAKECONTEXT ENUMERATE "blob" LIMIT 100 1 "addressbook.Email") MAKECONTEXT ENUMERATE "blob" LIMIT 100 1
SORT ("addressbook.Alias" "i;octet") NOT EQUAL SORT ("addressbook.Alias" "i;octet") NOT EQUAL
"addressbook.Email" NIL "addressbook.Email" NIL
S: A049 ENTRY "A437" "aaguy" "aaguy@stone.org" S: A049 ENTRY "A437" "aaguy" "aaguy@stone.org"
S: A046 MODTIME "19970728105308"
Internet DRAFT ACAP August 1997
S: A049 MODTIME "19970728105308"
S: A049 OK (TOOMANY 347) "Context 'blob' created" S: A049 OK (TOOMANY 347) "Context 'blob' created"
C: A050 SEARCH "blob" RANGE 2 2 "19970728105308" ALL C: A050 SEARCH "blob" RANGE 2 2 "19970728105308" ALL
S: A050 ENTRY "A238" "abguy" "abguy@stone.org" S: A050 ENTRY "A238" "abguy" "abguy@stone.org"
S: A050 MODTIME "19970728105310"
S: A050 OK "SEARCH Completed" S: A050 OK "SEARCH Completed"
6.5. Contexts 6.5. Contexts
The following commands use contexts created by a SEARCH command with The following commands use contexts created by a SEARCH command with
a MAKECONTEXT modifier. a MAKECONTEXT modifier.
6.5.1. FREECONTEXT Command 6.5.1. FREECONTEXT Command
Arguments: context name Arguments: context name
skipping to change at page 40, line 44 skipping to change at page 39, line 51
Arguments: list of context names Arguments: list of context names
Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME
Result: OK - Updatecontext completed: all updates completed Result: OK - Updatecontext completed: all updates completed
NO - Updatecontext failed: no such context NO - Updatecontext failed: no such context
not a notify context not a notify context
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
The UPDATECONTEXT command causes the server to ensure that the The UPDATECONTEXT command causes the server to ensure that the
client is notified of all changes to the contexts listed as client is notified of all changes known to the server for the
arguments up to the current time. The contexts listed in the contexts listed as arguments up to the current time. The contexts
arguments must have been previously given to a successful SEARCH
command with a MAKECONTEXT NOTIFY modifier. A MODTIME untagged Internet DRAFT ACAP August 1997
response MUST be returned if any read-write metadata in the
context changed since the last MODTIME for that context. This listed in the arguments must have been previously given to a
includes metadata which is not listed in the RETURN modifier for successful SEARCH command with a MAKECONTEXT NOTIFY modifier. A
the context. 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 While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and
MODTIME at any time, the UPDATECONTEXT command is used to "prod" MODTIME at any time, the UPDATECONTEXT command is used to "prod"
the server to send any notifications it has not sent yet. the server to send any notifications it has not sent yet.
The UPDATECONTEXT command SHOULD NOT be used to poll for updates. 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" Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl"
S: Z4S9 OK "client has been notified of all changes" S: Z4S9 OK "client has been notified of all changes"
6.5.3. ADDTO Untagged Response 6.5.3. ADDTO Untagged Response
Data: context name Data: context name
entry name entry name
position position
metadata list metadata list
The untagged ADDTO response informs the client that an entry has The untagged ADDTO response informs the client that an entry has
been added to a context. The response includes the position been added to a context. The response includes the position
number of the added entry (the first entry in the context is number of the added entry (the first entry in the context is
numbered 1) and those metadata contained in the entry which match numbered 1) and those metadata contained in the entry which match
the RETURN statement when the context was created. the RETURN statement when the context was created.
For enumerated contexts, the ADDTO response implicitly adds one to For enumerated contexts, the ADDTO response implicitly adds one to
the position of all members of the context which had position the position of all members of the context which had position
numbers that were greater than or equal to the ADDTO position numbers that were greater than or equal to the ADDTO position
number. number. For non-enumerated contexts, the position field is always
0.
Example: S: * ADDTO "blurdybloop" "fred" 15 Example: S: * ADDTO "blurdybloop" "fred" 15
("addressbook.Email" "fred@rock.org") ("addressbook.Email" "fred@stone.org")
6.5.4. REMOVEFROM Untagged Response 6.5.4. REMOVEFROM Untagged Response
Data: context name Data: context name
entry name entry name
old position old position
The untagged REMOVEFROM response informs the client that an entry The untagged REMOVEFROM response informs the client that an entry
has been removed from a context. The response includes the has been removed from a context. The response includes the
Internet DRAFT ACAP August 1997
position number that the removed entry used to have (the first position number that the removed entry used to have (the first
entry in the context is numbered 1). entry in the context is numbered 1).
For enumerated contexts, the REMOVEFROM response implicitly For enumerated contexts, the REMOVEFROM response implicitly
subtracts one from the position numbers of all members of the subtracts one from the position numbers of all members of the
context which had position numbers greater than the REMOVEFROM context which had position numbers greater than the REMOVEFROM
position number. position number. For non-enumerated contexts, the position field
is always 0.
Example: S: * REMOVEFROM "blurdybloop" "fred" 15 Example: S: * REMOVEFROM "blurdybloop" "fred" 15
6.5.5. CHANGE Untagged Response 6.5.5. CHANGE Untagged Response
Data: context name Data: context name
entry name entry name
old position old position
new position new position
metadata list metadata list
skipping to change at page 43, line 5 skipping to change at page 42, line 5
position and new position are the same, then no implicit position position and new position are the same, then no implicit position
renumbering occurs. renumbering occurs.
CHANGE responses are not issued for entries which have changed CHANGE responses are not issued for entries which have changed
position implicitly due to another ADDTO, REMOVEFROM or CHANGE position implicitly due to another ADDTO, REMOVEFROM or CHANGE
response. response.
Example: S: * CHANGE "blurdybloop" "fred" 15 10 Example: S: * CHANGE "blurdybloop" "fred" 15 10
("addressbook.Email" "fred@stone.org") ("addressbook.Email" "fred@stone.org")
Internet DRAFT ACAP August 1997
6.5.6. MODTIME Untagged Response 6.5.6. MODTIME Untagged Response
Data: context name Data: context name
modtime value modtime value
The untagged MODTIME response informs the client that it has The untagged MODTIME response informs the client that it has
received all updates to entries in the context which have modtime received all updates to entries in the context which have modtime
values less than or equal to the modtime value in the argument. values less than or equal to the modtime value in the argument.
Example: S: * MODTIME mycontext "19970320162338" Example: S: * MODTIME mycontext "19970320162338"
skipping to change at page 43, line 33 skipping to change at page 42, line 35
Data: intermediate responses: ENTRY Data: intermediate responses: ENTRY
Result: OK - store completed Result: OK - store completed
NO - store failure: can't store that name NO - store failure: can't store that name
UNCHANGEDSINCE specified and entry changed UNCHANGEDSINCE specified and entry changed
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
invalid UTF-8 syntax in attribute name invalid UTF-8 syntax in attribute name
Creates, modifies, or deletes the named entries in the named Creates, modifies, or deletes the named entries in the named
datasets. The values of metadata not specified in the command are datasets. The values of metadata not specified in the command are
not changed. Setting the "value" metadata of an attribute to NIL not changed. Setting the "value" metadata of an attribute to NIL
removes that attribute from the entry. Setting the "value" of the removes that attribute from the entry. Setting the "value" of the
"entry" attribute to NIL removes that entry from the dataset and "entry" attribute to NIL removes that entry from the dataset and
cancels inheritance for the entire entry. Setting the "value" of cancels inheritance for the entire entry. Setting the "value" of
the "entry" attribute to DEFAULT removes that entry from the the "entry" attribute to DEFAULT removes that entry from the
inheriting dataset and reverts the entry and its attributes to inheriting dataset and reverts the entry and its attributes to
inherited values, if any. Changing the value of the "entry" inherited values, if any. Changing the value of the "entry"
attribute renames the entry. attribute renames the entry.
Storing DEFAULT to the "value" metadata of an attribute is Storing DEFAULT to the "value" metadata of an attribute is
equivalent to storing NIL, except that inheritance is enabled for equivalent to storing NIL, except that inheritance is enabled for
that attribute. If a non-NIL value is inherited then an ENTRY that attribute. If a non-NIL value is inherited then an ENTRY
intermediate response is generated to notify the client of the intermediate response is generated to notify the client of the
this change. The ENTRY response includes the entry-path and the this change. The ENTRY response includes the entry-path and the
attribute name and value metadata for each attribute which attribute name and value metadata for each attribute which
reverted to a non-NIL inherited setting. reverted to a non-NIL inherited setting.
Internet DRAFT ACAP August 1997
Storing NIL to the "value" metadata of an attribute MAY be treated Storing NIL to the "value" metadata of an attribute MAY be treated
equivalent to storing DEFAULT to that "value" if there is not a equivalent to storing DEFAULT to that "value" if there is a NIL
non-NIL value in the base dataset. value in the base dataset.
The STORE command is followed by one or more entry store lists. The STORE command is followed by one or more entry store lists.
Each entry store list begins with an entry path followed by STORE Each entry store list begins with an entry path followed by STORE
modifiers, followed by zero or more attribute store items. Each modifiers, followed by zero or more attribute store items. Each
attribute store item is made up of the attribute name followed by attribute store item is made up of the attribute name followed by
NIL (to remove the attribute's value), DEFAULT (to revert the item NIL (to remove the attribute's value), DEFAULT (to revert the item
to any inherited value), a single value (to set the attribute's to any inherited value), a single value (to set the attribute's
single value), or a list of metadata items to modify. The single value), or a list of metadata items to modify. The
following STORE modifiers may be specified: following STORE modifiers may be specified:
NOCREATE NOCREATE
By default, the server MUST create any datasets necessary to By default, the server MUST create any datasets necessary to
store the entry. If NOCREATE is specified, the STORE command store the entry, including multiple hierarchy levels. If
will fail with a NOEXIST error unless the containing dataset NOCREATE is specified, the STORE command will fail with a
already exists. NOEXIST error unless the parent dataset already exists.
UNCHANGEDSINCE UNCHANGEDSINCE
If the "modtime" of the entry is later than the If the "modtime" of the entry is later than the
unchangedsince time, then the store fails with a MODIFIED unchangedsince time, then the store fails with a MODIFIED
response code. Use of UNCHANGEDSINCE with a time of response code. Use of UNCHANGEDSINCE with a time of
"00000101000000" will always fail if the entry exists. "00000101000000" will always fail if the entry exists.
Clients writing to a shared dataset are encouraged to use Clients writing to a shared dataset are encouraged to use
UNCHANGEDSINCE when modifying an existing entry. UNCHANGEDSINCE when modifying an existing entry.
The server MUST either make all the changes specified or make none The server MUST either make all the changes specified in a single
of them. If successful, the server MUST update the "modtime" STORE command or make none of them. If successful, the server
attribute for every entry which was changed. MUST update the "modtime" attribute for every entry which was
changed.
It is illegal to list any metadata item within an attribute twice, It is illegal to list any metadata item within an attribute twice,
any attribute within an entry twice or any entry path twice. The any attribute within an entry twice or any entry path twice. The
server MUST return a BAD response if this happens. If the server MUST return a BAD response if this happens.
"modtime" attribute is included in the STORE command, then the
server MUST return a NO response with an ILLEGAL response code.
A STORE of a multi-value MAY re-order the strings in the multi- The server MAY re-order the strings in a multi-value on STORE and
value and MAY remove duplicate strings. However, SEARCH MUST MAY remove duplicate strings. However, SEARCH MUST return multi-
return multi-values and the associated size list metadata in a values and the associated size list metadata in a consistant
consistant order. order.
Example: C: A342 STORE ("/addressbook/user/fred/ABC547" Example: C: A342 STORE ("/addressbook/user/fred/ABC547"
"addressbook.TelephoneNumber" "555-1234" "addressbook.TelephoneNumber" "555-1234"
"addressbook.CommonName" "Barney Rubble" "addressbook.CommonName" "Barney Rubble"
"addressbook.AlternateNames" ("value" "addressbook.AlternateNames" ("value"
Internet DRAFT ACAP August 1997
("Barnacus Rubble" "Coco Puffs Thief")) ("Barnacus Rubble" "Coco Puffs Thief"))
"addressbook.Email" NIL) "addressbook.Email" NIL)
S: A342 OK "Store completed" S: A342 OK "Store completed"
C: A343 STORE ("/addressbook/user/joe/ABD42" C: A343 STORE ("/addressbook/user/joe/ABD42"
UNCHANGEDSINCE "19970320162338" UNCHANGEDSINCE "19970320162338"
"user.joe.hair-length" "10 inches") "user.joe.hair-length" "10 inches")
S: A343 NO (MODIFIED) "'ABD42' has been changed S: A343 NO (MODIFIED) "'ABD42' has been changed
by somebody else." by somebody else."
C: A344 STORE ("/addressbook/group/Developers/ACD54" C: A344 STORE ("/addressbook/group/Developers/ACD54"
"entry" NIL) "entry" NIL)
skipping to change at page 45, line 36 skipping to change at page 44, line 34
"/addressbook/group/Developers") "/addressbook/group/Developers")
S: A347 OK "Store completed" S: A347 OK "Store completed"
6.6.2. DELETEDSINCE Command 6.6.2. DELETEDSINCE Command
Arguments: dataset name Arguments: dataset name
time time
Data: intermediate response: DELETED Data: intermediate response: DELETED
Result: OK - DELETED completed Result: OK - DELETEDSINCE completed
NO - DELETED failure: can't read dataset NO - DELETEDSINCE failure: can't read dataset
date too far in the past date too far in the past
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
The DELETEDSINCE command returns in intermediate DELETED replies The DELETEDSINCE command returns in intermediate DELETED replies
the names of entries that have been deleted from the named dataset the names of entries that have been deleted from the named dataset
since the given time. since the given time.
Servers may impose a limit on the number or age of deleted entry 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 names they keep track of. If the server does not have information
going back to the specified time, the command fails, returning a going back to the specified time, the command fails, returning a
TOOOLD response code in the tagged NO response. TOOOLD response code in the tagged NO response.
Example: C: Z4S9 DELETEDSINCE "/folder/site/" 19951205103412 Example: C: Z4S9 DELETEDSINCE "/folder/site/" 19951205103412
S: Z4S9 DELETED "blurdybloop" S: Z4S9 DELETED "blurdybloop"
S: Z4S9 DELETED "anteaters" S: Z4S9 DELETED "anteaters"
S: Z4S9 OK "DELETEDSINCE completed" S: Z4S9 OK "DELETEDSINCE completed"
C: Z4U3 DELETEDSINCE "/folder/site/" 19951009040854 C: Z4U3 DELETEDSINCE "/folder/site/" 19951009040854
S: Z4U3 NO (TOOOLD) "Don't have that information" S: Z4U3 NO (TOOOLD) "Don't have that information"
Internet DRAFT ACAP August 1997
6.6.3. DELETED Intermediate Response 6.6.3. DELETED Intermediate Response
Data: entry name Data: entry name
The intermediate DELETED response occurs as a result of a The intermediate DELETED response occurs as a result of a
DELETEDSINCE command. It returns an entry that has been deleted DELETEDSINCE command. It returns an entry that has been deleted
from the dataset specified in the DELETEDSINCE command. from the dataset specified in the DELETEDSINCE command.
6.7. Access Control List Commands 6.7. Access Control List Commands
The commands in this section are used to manage access control lists. The commands in this section are used to manage access control lists.
6.7.1. SETACL Command 6.7.1. SETACL Command
Arguments: acl object Arguments: acl object
authentication identifier authentication identifier
access rights access rights
skipping to change at page 47, line 5 skipping to change at page 46, line 5
permissions enumerated in rights. If the object did not permissions enumerated in rights. If the object did not
previously have an access control list, one is created. previously have an access control list, one is created.
Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r" Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r"
S: A123 OK "Setacl complete" S: A123 OK "Setacl complete"
C: A124 SETACL ("/folder/site/") "B1FF" "rwa" C: A124 SETACL ("/folder/site/") "B1FF" "rwa"
S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not
permitted to modify access rights permitted to modify access rights
for '/folder/site/'" for '/folder/site/'"
Internet DRAFT ACAP August 1997
6.7.2. DELETEACL Command 6.7.2. DELETEACL Command
Arguments: acl object Arguments: acl object
optional authentication identifier optional authentication identifier
Data: no specific data for this command Data: no specific data for this command
Result: OK - deleteacl completed Result: OK - deleteacl completed
NO - deleteacl failure: can't delete acl NO - deleteacl failure: can't delete acl
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
skipping to change at page 48, line 6 skipping to change at page 47, line 5
NO - myrights failure: can't get rights NO - myrights failure: can't get rights
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
The MYRIGHTS command returns the set of rights that the client has The MYRIGHTS command returns the set of rights that the client has
to the given dataset or dataset attribute. to the given dataset or dataset attribute.
Example: C: A003 MYRIGHTS ("/folder/site") Example: C: A003 MYRIGHTS ("/folder/site")
S: A003 MYRIGHTS "r" S: A003 MYRIGHTS "r"
S: A003 OK "Myrights complete" S: A003 OK "Myrights complete"
Internet DRAFT ACAP August 1997
6.7.4. MYRIGHTS Intermediate Response 6.7.4. MYRIGHTS Intermediate Response
Data: rights Data: rights
The MYRIGHTS response occurs as a result of a MYRIGHTS command. The MYRIGHTS response occurs as a result of a MYRIGHTS command.
The argument is the set of rights that the client has for the The argument is the set of rights that the client has for the
object referred to in the MYRIGHTS command. object referred to in the MYRIGHTS command.
6.7.5. LISTRIGHTS Command 6.7.5. LISTRIGHTS Command
Arguments: acl object Arguments: acl object
authentication identifier authentication identifier
Data: untagged responses: LISTRIGHTS Data: untagged responses: LISTRIGHTS
Result: OK - listrights completed Result: OK - listrights completed
NO - listrights failure: can't get rights list NO - listrights failure: can't get rights list
BAD - command unknown or arguments invalid BAD - command unknown or arguments invalid
The LISTRIGHTS command takes an object and an identifier and The LISTRIGHTS command takes an object and an identifier and
returns information about what rights may be granted to the returns information about what rights the current user may revoke
identifier in the ACL for the object. or grant to that identifier in the ACL for that object.
Example: C: a001 LISTRIGHTS ("/folder/~/") "smith" Example: C: a001 LISTRIGHTS ("/folder/~/") "smith"
S: a001 LISTRIGHTS "ra" "w" S: a001 LISTRIGHTS "xra" "w" "i"
S: a001 OK Listrights completed S: a001 OK Listrights completed
C: a005 LISTRIGHTS ("/folder/site/archive/imap") "anyone" C: a005 LISTRIGHTS ("/folder/site/archive/imap") "anyone"
S: a005 LISTRIGHTS "" "r" "w" S: a005 LISTRIGHTS "" "x" "r" "w" "i"
S: a005 OK Listrights completed S: a005 OK Listrights completed
6.7.6. LISTRIGHTS Intermediate Response 6.7.6. LISTRIGHTS Intermediate Response
Data: required rights Data: required rights
list of optional rights list of optional rights
The LISTRIGHTS response occurs as a result of a LISTRIGHTS The LISTRIGHTS response occurs as a result of a LISTRIGHTS
command. The first argument is a string containing the (possibly command. The first argument is a string containing the (possibly
empty) set of rights the identifier will always be granted on the empty) set of rights the identifier will always be granted on the
dataset or attribute. dataset or attribute.
Following this are zero or more strings each containing a single Following this are zero or more strings each containing a single
right the identifier may be granted in the dataset or attribute. right which the current user may revoke or grant to the identifier
in the dataset or attribute.
The same right MUST NOT be listed more than once in the LISTRIGHTS The same right MUST NOT be listed more than once in the LISTRIGHTS
response. response.
Internet DRAFT ACAP August 1997
6.8. Quotas 6.8. Quotas
The section defines the commands and responses relating to quotas. The section defines the commands and responses relating to quotas.
6.8.1. GETQUOTA Command 6.8.1. GETQUOTA Command
Arguments: dataset Arguments: dataset
Data: untagged responses: QUOTA Data: untagged responses: QUOTA
skipping to change at page 49, line 44 skipping to change at page 48, line 42
Data: dataset Data: dataset
quota limit in bytes quota limit in bytes
amount of quota limit used amount of quota limit used
extension data extension data
The QUOTA untagged response is generated as a result of a GETQUOTA 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 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 or STORE command to warn about high usage of a quota. It includes
the name of the applicable dataset, the quota limit in bytes, the the name of the applicable dataset, the quota limit in bytes, the
quota usage and some optional extension data. Clients MUST ignore quota usage and some optional extension data. Clients MUST
the extension data as its use is reserved for a future extension. tolerate the extension data as its use is reserved for a future
extension.
6.9. Extensions 6.9. Extensions
In order to simplify the process of extending the protocol, clients In order to simplify the process of extending the protocol, clients
MUST ignore unknown server responses which meet the syntax of MUST tolerate unknown server responses which meet the syntax of
response-extend. In addition, clients MUST ignore unknown server response-extend. In addition, clients MUST tolerate unknown server
response codes which meet the syntax of resp-code-ext. Availability response codes which meet the syntax of resp-code-ext. Availability
of new commands MUST be announced via a capability on the initial of new commands MUST be announced via a capability on the initial
greeting line and such commands SHOULD meet the syntax of command-
extend. Internet DRAFT ACAP August 1997
greeting line and such commands SHOULD meet the syntax of
command-extend.
Servers MUST respond to unknown commands with a BAD command Servers MUST respond to unknown commands with a BAD command
completion result. Servers MUST skip over non-synchronizing literals completion result. Servers MUST skip over non-synchronizing literals
contained in an unknown command. This may be done by assuming the contained in an unknown command. This may be done by assuming the
unknown command matches the command-extend syntax, or by reading a unknown command matches the command-extend syntax, or by reading a
line at a time and checking for the non-synchronizing literal syntax line at a time and checking for the non-synchronizing literal syntax
at the end of the line. at the end of the line.
7. Registration Procedures 7. Registration Procedures
skipping to change at page 50, line 49 skipping to change at page 49, line 44
(3) Registration. Registration serves a two-fold purpose. First it (3) Registration. Registration serves a two-fold purpose. First it
prevents use of the same name for different purposes, and second it prevents use of the same name for different purposes, and second it
provides a one-stop list which can be used to locate existing provides a one-stop list which can be used to locate existing
extensions or dataset classes to prevent duplicate work. extensions or dataset classes to prevent duplicate work.
The following registration templates may be used to register ACAP The following registration templates may be used to register ACAP
protocol elements. protocol elements.
7.1. ACAP Capabilities 7.1. ACAP Capabilities
New ACAP capabilities MUST be standards track or IESG approved New ACAP capabilities MUST be specified in a standards track or IESG
experimental RFCs. Registration provides a simple way to locate all approved experimental RFCs. Registration provides a simple way to
extensions. Careful consideration should be made before extending locate all extensions. Careful consideration should be made before
the protocol, as it can lead to complexity or interoperability extending the protocol, as it can lead to complexity or
problems. interoperability problems.
To: iana@iana.org To: iana@iana.org
Subject: Registration of ACAP capability Subject: Registration of ACAP capability
Capability name: Capability name:
Internet DRAFT ACAP August 1997
Capability keyword: Capability keyword:
Capability arguments: Capability arguments:
Published Specification(s): Published Specification(s):
(Standards track or IESG approved experimental RFC) (Standards track or IESG approved experimental RFC)
Person and email address to contact for further information: Person and email address to contact for further information:
skipping to change at page 51, line 32 skipping to change at page 50, line 28
ACAP response codes are registered on a first come, first served ACAP response codes are registered on a first come, first served
basis. Proposals SHOULD be reviewed by the acap implementors mailing basis. Proposals SHOULD be reviewed by the acap implementors mailing
list mentioned above. list mentioned above.
To: iana@iana.org To: iana@iana.org
Subject: Registration of ACAP response code Subject: Registration of ACAP response code
Response Code: Response Code:
Arguments: Arguments (use ABNF to specify syntax):
Purpose: Purpose:
Published Specification(s): Published Specification(s):
(Optional, but encouraged) (Optional, but encouraged)
Person and email address to contact for further information: Person and email address to contact for further information:
7.3. Dataset Classes 7.3. Dataset Classes
skipping to change at page 52, line 4 skipping to change at page 50, line 47
7.3. Dataset Classes 7.3. Dataset Classes
A dataset class provides a core set of attributes for use in a A dataset class provides a core set of attributes for use in a
specified hierarchy. It may also define rules for the dataset specified hierarchy. It may also define rules for the dataset
hierarchy underneath that class. Dataset class specifications must hierarchy underneath that class. Dataset class specifications must
be standards track or IESG approved experimental RFCs. be standards track or IESG approved experimental RFCs.
To: iana@iana.org To: iana@iana.org
Subject: Registration of ACAP dataset class Subject: Registration of ACAP dataset class
Dataset class name/attribute prefix: Dataset class name/attribute prefix:
Purpose: Purpose:
Published Specification(s): Published Specification(s):
(Standards track or IESG approved experimental RFC) (Standards track or IESG approved experimental RFC)
Internet DRAFT ACAP August 1997
Person and email address to contact for further information: Person and email address to contact for further information:
7.4. Vendor Subtree 7.4. Vendor Subtree
Vendors may reserve a portion of the ACAP namespace for private use. Vendors may reserve a portion of the ACAP namespace for private use.
Dataset class names beginning with "vendor.<company/product name>." Dataset class names beginning with "vendor.<company/product name>."
are reserved for use by that company or product. In addition, all are reserved for use by that company or product. In addition, all
attribute names beginning with "vendor.<company/product name>." are attribute names beginning with "vendor.<company/product name>." are
reserved for use by that company or product. Registration is on a reserved for use by that company or product once registered.
first come, first served basis. Whenever possible, private Registration is on a first come, first served basis. Whenever
attributes and dataset classes should be avoided in favor of possible, private attributes and dataset classes should be avoided in
improving interoperable dataset class definitions. favor of improving interoperable dataset class definitions.
To: iana@iana.org To: iana@iana.org
Subject: Registration of ACAP vendor subtree Subject: Registration of ACAP vendor subtree
Private Prefix: vendor.<company/product name>. Private Prefix: vendor.<company/product name>.
Person and email address to contact for further information: Person and email address to contact for further information:
(company names and addresses should be included when appropriate) (company names and addresses should be included when appropriate)
8. Formal Syntax 8. Formal Syntax
The following syntax specification uses the augmented Backus-Naur The following syntax specification uses the augmented Backus-Naur
Form (BNF) notation as specified in [ABNF]. Form (BNF) notation as specified in [ABNF].
Except as noted otherwise, all alphabetic characters are Except as noted otherwise, all alphabetic characters are
case-insensitive. The use of upper or lower case characters to case-insensitive. The use of upper or lower case characters to
define token strings is for editorial clarity only. Implementations define token strings is for editorial clarity only. Implementations
MUST accept these strings in a case-insensitive fashion. MUST accept these strings in a case-insensitive fashion.
The "command" rule below defines the syntax for commands sent by the The "initial-greeting" rule below defines the initial ACAP greeting
client. The "response" rule below defines the syntax for responses from the server. The "command" rule below defines the syntax for
sent by the server. commands sent by the client. The "response" rule below defines the
syntax for responses sent by the server.
ALPHA = %x41-5A / %x61-7A ALPHA = %x41-5A / %x61-7A
;; alphabetic letters ;; alphabetic letters
ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E
;; Any CHAR except ATOM-SPECIALS ;; Any CHAR except ATOM-SPECIALS
ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS
BASE64-CHAR = ALPHA / DIGIT / "+" / "/"
;; case-sensitive
CHAR = %x01-7F CHAR = %x01-7F
CR = %x0C CR = %x0C
Internet DRAFT ACAP August 1997
CRLF = CR LF CRLF = CR LF
CTL = %x00-1F / %x7F CTL = %x00-1F / %x7F
DIGIT = "0" / DIGIT-NZ DIGIT = "0" / DIGIT-NZ
DIGIT-NZ = %x31-39 DIGIT-NZ = %x31-39
; non-zero digits ("1" - "9") ; non-zero digits ("1" - "9")
LF = %x0A LF = %x0A
skipping to change at page 54, line 4 skipping to change at page 52, line 42
TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E
;; Any ATOM-CHAR except "*" or "+" ;; Any ATOM-CHAR except "*" or "+"
TEXT-CHAR = %x01-09 / %x0B-0C / %x0E-7F TEXT-CHAR = %x01-09 / %x0B-0C / %x0E-7F
;; any CHAR except CR and LF ;; any CHAR except CR and LF
TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS
UTF8-1 = %x80-BF UTF8-1 = %x80-BF
UTF8-2 = %xC0-DF UTF8-1 UTF8-2 = %xC0-DF UTF8-1
UTF8-3 = %xE0-EF 2UTF8-1 UTF8-3 = %xE0-EF 2UTF8-1
UTF8-4 = %xF0-F7 3UTF8-1 UTF8-4 = %xF0-F7 3UTF8-1
UTF8-5 = %xF8-FB 4UTF8-1 UTF8-5 = %xF8-FB 4UTF8-1
UTF8-6 = %xFC-FD 5UTF8-1 UTF8-6 = %xFC-FD 5UTF8-1
UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF
Internet DRAFT ACAP August 1997
acl = "(" *acl-identrights ")" acl = "(" *acl-identrights ")"
acl-identifier = string-utf8 acl-identifier = string-utf8
;; MUST NOT contain TAB ;; MUST NOT contain TAB
acl-identrights = string-utf8 acl-identrights = string-utf8
;; The identifier followed by a TAB, followed by ;; The identifier followed by a TAB, followed by
;; the rights. ;; the rights.
acl-delobject = "(" dataset SPACE attribute [SPACE entry-name] ")" acl-delobject = "(" dataset SPACE attribute [SPACE entry-name] ")"
skipping to change at page 54, line 41 skipping to change at page 53, line 32
atom = ALPHA *1023ATOM-CHAR atom = ALPHA *1023ATOM-CHAR
attribute = string-utf8 attribute = string-utf8
;; dot-separated attribute name ;; dot-separated attribute name
;; MUST NOT contain "*" or "%" ;; MUST NOT contain "*" or "%"
attribute-store = attribute SPACE (value-nildef / attribute-store = attribute SPACE (value-nildef /
"(" 1*(metadata-write-q SPACE value-store) ")") "(" 1*(metadata-write-q SPACE value-store) ")")
;; MUST NOT include the same metadata twice ;; MUST NOT include the same metadata twice
auth-type = iana-token auth-type = <"> auth-type-name <">
;; as defined in SASL [SASL]
base64-token = *(4BASE64-CHAR) [base64-terminal]
base64-terminal = (2BASE64-CHAR "==") / (3BASE64-CHAR "=") auth-type-name = iana-token
;; as defined in SASL [SASL]
command = tag SPACE (command-any / command-auth / command = tag SPACE (command-any / command-auth /
command-nonauth) CRLF command-nonauth) CRLF
;; Modal based on state ;; Modal based on state
command-authent = "AUTHENTICATE" SPACE auth-type [SPACE base64-token] command-authent = "AUTHENTICATE" SPACE auth-type
*(CRLF base64-token) [SPACE string] *(CRLF string)
command-any = "NOOP" / command-lang / "LOGOUT" command-any = "NOOP" / command-lang / "LOGOUT" / command-extend
command-auth = command-delacl / command-dsince / command-auth = command-delacl / command-dsince /
command-freectx / command-getquota / command-freectx / command-getquota /
command-lrights / command-myrights / command-lrights / command-myrights /
command-search / command-setacl / command-search / command-setacl /
command-store command-store
;; only valid in authenticated state ;; only valid in authenticated state
command-delacl = "DELETEACL" SPACE acl-delobject [SPACE acl-identifier] command-delacl = "DELETEACL" SPACE acl-delobject [SPACE acl-identifier]
Internet DRAFT ACAP August 1997
command-dsince = "DELETEDSINCE" SPACE dataset SPACE time command-dsince = "DELETEDSINCE" SPACE dataset SPACE time
command-extend = extend-token [SPACE extension-data] command-extend = extend-token [SPACE extension-data]
command-freectx = "FREECONTEXT" SPACE context command-freectx = "FREECONTEXT" SPACE context
command-getquota = "GETQUOTA" SPACE dataset command-getquota = "GETQUOTA" SPACE dataset
command-lang = "LANG" *(SPACE lang-tag) command-lang = "LANG" *(SPACE lang-tag)
skipping to change at page 56, line 19 skipping to change at page 55, line 5
entry = entry-name / entry-path entry = entry-name / entry-path
entry-name = string-utf8 entry-name = string-utf8
;; entry name MUST NOT contain slash ;; entry name MUST NOT contain slash
;; MUST NOT begin with "." ;; MUST NOT begin with "."
entry-path = string-utf8 entry-path = string-utf8
;; slash-separated path to entry ;; slash-separated path to entry
;; begins with slash ;; begins with slash
Internet DRAFT ACAP August 1997
entry-relative = string-utf8 entry-relative = string-utf8
;; potentially relative path to entry ;; potentially relative path to entry
extend-token = atom extend-token = atom
;; MUST be defined by a standards track or ;; MUST be defined by a standards track or
;; IESG approved experimental protocol extension ;; IESG approved experimental protocol extension
extension-data = extension-item *(SPACE extension-item) extension-data = extension-item *(SPACE extension-item)
extension-item = extend-token / string / number / extension-item = extend-token / string / number /
skipping to change at page 57, line 19 skipping to change at page 56, line 5
metadata = attribute [ "(" metadata-type-list ")" ] metadata = attribute [ "(" metadata-type-list ")" ]
;; attribute MAY end in "*" as wildcard. ;; attribute MAY end in "*" as wildcard.
metadata-list = metadata *(SPACE metadata) metadata-list = metadata *(SPACE metadata)
metadata-type = "attribute" / "myrights" / "size" / metadata-type = "attribute" / "myrights" / "size" /
"count" / metadata-write "count" / metadata-write
metadata-type-q = <"> metadata-type <"> metadata-type-q = <"> metadata-type <">
Internet DRAFT ACAP August 1997
metadata-type-list = metadata-type-q *(SPACE metadata-type-q) metadata-type-list = metadata-type-q *(SPACE metadata-type-q)
metadata-write = "value" / "acl" metadata-write = "value" / "acl"
metadata-write-q = <"> metadata-write <"> metadata-write-q = <"> metadata-write <">
nil = "NIL" nil = "NIL"
number = *DIGIT number = *DIGIT
;; A 32-bit unsigned number. ;; A 32-bit unsigned number.
skipping to change at page 58, line 17 skipping to change at page 56, line 54
response-alert = "*" SPACE "ALERT" SPACE resp-body CRLF response-alert = "*" SPACE "ALERT" SPACE resp-body CRLF
;; Client MUST display alert text to user ;; Client MUST display alert text to user
response-bye = "*" SPACE "BYE" SPACE resp-body CRLF response-bye = "*" SPACE "BYE" SPACE resp-body CRLF
;; Server will disconnect condition ;; Server will disconnect condition
response-change = "*" SPACE "CHANGE" SPACE context SPACE entry-name response-change = "*" SPACE "CHANGE" SPACE context SPACE entry-name
SPACE position SPACE position SPACE return-data-list SPACE position SPACE position SPACE return-data-list
response-cont = "+" SPACE (quoted / base64-token) response-cont = "+" SPACE string
Internet DRAFT ACAP August 1997
response-deleted = tag SPACE "DELETED" SPACE entry-name response-deleted = tag SPACE "DELETED" SPACE entry-name
response-done = tag SPACE resp-cond-state CRLF response-done = tag SPACE resp-cond-state CRLF
response-entry = tag SPACE "ENTRY" SPACE entry SPACE return-data-list response-entry = tag SPACE "ENTRY" SPACE entry SPACE return-data-list
response-extend = (tag / "*") SPACE extend-token [SPACE extension-data] response-extend = (tag / "*") SPACE extend-token [SPACE extension-data]
response-lang = "*" SPACE "LANG" SPACE lang-tag 1*(SPACE comparator) response-lang = "*" SPACE "LANG" SPACE lang-tag 1*(SPACE comparator)
skipping to change at page 59, line 4 skipping to change at page 57, line 38
response-refer = tag SPACE "REFER" SPACE dataset 1*(SPACE response-refer = tag SPACE "REFER" SPACE dataset 1*(SPACE
<"> url-relative <">) <"> url-relative <">)
response-remove = "*" SPACE "REMOVEFROM" SPACE context SPACE response-remove = "*" SPACE "REMOVEFROM" SPACE context SPACE
entry-name SPACE position entry-name SPACE position
response-stat = "*" SPACE resp-cond-state CRLF response-stat = "*" SPACE resp-cond-state CRLF
resp-body = ["(" resp-code ")" SPACE] quoted resp-body = ["(" resp-code ")" SPACE] quoted
resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" /
resp-code-inval / resp-code-mod / resp-code-inval / resp-code-mod /
resp-code-noexist / resp-code-perm / "QUOTA" / resp-code-noexist / resp-code-perm / "QUOTA" /
resp-code-refer / resp-code-toomany / "TOOOLD" / resp-code-refer / resp-code-sasl /
resp-code-toomany / "TOOOLD" /
"TRANSITION-NEEDED" / "TRYFREECONTEXT" / "TRANSITION-NEEDED" / "TRYFREECONTEXT" /
"TRYLATER" / "WAYTOOMANY" / resp-code-ext "TRYLATER" / "WAYTOOMANY" / resp-code-ext
resp-code-ext = iana-token [SPACE extension-data] resp-code-ext = iana-token [SPACE extension-data]
;; unknown response codes are ignored by the client. ;; unknown response codes are tolerated by the client.
resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute) resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute)
resp-code-mod = "MODIFIED" SPACE entry-path resp-code-mod = "MODIFIED" SPACE entry-path
resp-code-noexist = "NOEXIST" SPACE dataset resp-code-noexist = "NOEXIST" SPACE dataset
Internet DRAFT ACAP August 1997
resp-code-perm = "PERMISSION" SPACE acl-object resp-code-perm = "PERMISSION" SPACE acl-object
resp-code-refer = "REFER" 1*(SPACE <"> url-relative <">) resp-code-refer = "REFER" 1*(SPACE <"> url-relative <">)
resp-code-sasl = "SASL" SPACE string
resp-code-toomany = "TOOMANY" SPACE nz-number resp-code-toomany = "TOOMANY" SPACE nz-number
resp-cond-state = ("OK" / "NO" / "BAD") SPACE resp-body resp-cond-state = ("OK" / "NO" / "BAD") SPACE resp-body
;; Status condition ;; Status condition
return-data = return-metadata / return-meta-list return-attr-list = "(" return-meta-list *(SPACE return-meta-list) ")"
;; return-meta-list format is used when "*" is ;; occurs when "*" is in the RETURN pattern on SEARCH
;; in the RETURN pattern on SEARCH
return-data = return-metadata / return-meta-list / return-attr-list
return-data-list = return-data *(SPACE return-data) return-data-list = return-data *(SPACE return-data)
return-meta-list = "(" return-metadata *(SPACE return-metadata) ")" return-meta-list = "(" return-metadata *(SPACE return-metadata) ")"
;; occurs when multiple metadata items requested
return-metadata = nil / string / value-list / acl return-metadata = nil / string / value-list / acl
searchkey-equal = "EQUAL" SPACE attribute SPACE comparator searchkey-equal = "EQUAL" SPACE attribute SPACE comparator
SPACE value-nil SPACE value-nil
searchkey-comp = "COMPARE" SPACE attribute SPACE comparator SPACE value searchkey-comp = "COMPARE" SPACE attribute SPACE comparator SPACE value
searchkey-prefix = "PREFIX" SPACE attribute SPACE comparator SPACE value searchkey-prefix = "PREFIX" SPACE attribute SPACE comparator SPACE value
skipping to change at page 60, line 17 skipping to change at page 59, line 5
searchmod-depth = "DEPTH" SPACE number searchmod-depth = "DEPTH" SPACE number
searchmod-hard = "HARDLIMIT" SPACE nz-number searchmod-hard = "HARDLIMIT" SPACE nz-number
searchmod-limit = "LIMIT" SPACE number SPACE number searchmod-limit = "LIMIT" SPACE number SPACE number
searchmod-make = "MAKECONTEXT" [SPACE "ENUMERATE"] searchmod-make = "MAKECONTEXT" [SPACE "ENUMERATE"]
[SPACE "NOTIFY"] SPACE context [SPACE "NOTIFY"] SPACE context
Internet DRAFT ACAP August 1997
searchmod-ninh = "NOINHERIT" searchmod-ninh = "NOINHERIT"
searchmod-return = "RETURN" SPACE "(" [metadata-list] ")" searchmod-return = "RETURN" SPACE "(" [metadata-list] ")"
searchmod-sort = "SORT" SPACE "(" sort-list ")" searchmod-sort = "SORT" SPACE "(" sort-list ")"
search-criteria = "ALL" / searchkey-equal / searchkey-comp / search-criteria = "ALL" / searchkey-equal / searchkey-comp /
searchkey-strict / searchkey-range / searchkey-strict / searchkey-range /
searchkey-prefix / searchkey-substr / searchkey-prefix / searchkey-substr /
"NOT" SPACE search-criteria / "NOT" SPACE search-criteria /
skipping to change at page 61, line 4 skipping to change at page 59, line 43
store-entry-list = store-entry *(SPACE store-entry) store-entry-list = store-entry *(SPACE store-entry)
;; MUST NOT include the same entry twice ;; MUST NOT include the same entry twice
store-modifier = store-mod-unchang / store-mod-nocreate store-modifier = store-mod-unchang / store-mod-nocreate
store-mod-nocreate = "NOCREATE" store-mod-nocreate = "NOCREATE"
store-mod-unchang = "UNCHANGEDSINCE" SPACE time store-mod-unchang = "UNCHANGEDSINCE" SPACE time
string = quoted / literal string = quoted / literal
string-list = string *(SPACE string) string-list = string *(SPACE string)
string-utf8 = quoted / literal-utf8 string-utf8 = quoted / literal-utf8
tag = 1*32TAG-CHAR tag = 1*32TAG-CHAR
time = <"> time-year time-month time-day time-hour time = <"> time-year time-month time-day time-hour
time-minute time-second time-subsecond <"> time-minute time-second time-subsecond <">
;; Timestamp in UTC ;; Timestamp in UTC
time-day = 2DIGIT ;; 01-31 time-day = 2DIGIT ;; 01-31
Internet DRAFT ACAP August 1997
time-hour = 2DIGIT ;; 00-23 time-hour = 2DIGIT ;; 00-23
time-minute = 2DIGIT ;; 00-59 time-minute = 2DIGIT ;; 00-59
time-month = 2DIGIT ;; 01-12 time-month = 2DIGIT ;; 01-12
time-second = 2DIGIT ;; 00-60 time-second = 2DIGIT ;; 00-60
time-subsecond = *DIGIT time-subsecond = *DIGIT
time-year = 4DIGIT time-year = 4DIGIT
value = string value = string
value-any = value-nil / value-list
value-list = "(" [value *(SPACE value)] ")" value-list = "(" [value *(SPACE value)] ")"
value-nil = value / nil value-nil = value / nil
value-nildef = value-nil / "DEFAULT" value-nildef = value-nil / "DEFAULT"
value-store = value-nildef / value-list / acl value-store = value-nildef / value-list / acl
url-acap = "acap://" url-server "/" url-enc-entry [url-filter] url-acap = "acap://" url-server "/" url-enc-entry [url-filter]
[url-extension] [url-extension]
skipping to change at page 62, line 12 skipping to change at page 60, line 47
url-achar = uchar / "&" / "=" / "~" url-achar = uchar / "&" / "=" / "~"
;; See RFC 1738 for definition of "uchar" ;; See RFC 1738 for definition of "uchar"
url-char = uchar / "=" / "~" / ":" / "@" / "/" url-char = uchar / "=" / "~" / ":" / "@" / "/"
;; See RFC 1738 for definition of "uchar" ;; See RFC 1738 for definition of "uchar"
url-enc-attr = 1*url-char url-enc-attr = 1*url-char
;; encoded version of attribute name ;; encoded version of attribute name
url-enc-auth = 1*url-achar url-enc-auth = 1*url-achar
;; encoded version of auth-type above ;; encoded version of auth-type-name above
url-enc-entry = 1*url-char url-enc-entry = 1*url-char
;; encoded version of entry-relative above ;; encoded version of entry-relative above
url-enc-user = *url-achar url-enc-user = *url-achar
;; encoded version of login userid ;; encoded version of login userid
Internet DRAFT ACAP August 1997
url-extension = *("?" 1*url-char) url-extension = *("?" 1*url-char)
url-filter = "?" url-attr-list url-filter = "?" url-attr-list
url-relative = url-acap / [url-enc-entry] [url-filter] url-relative = url-acap / [url-enc-entry] [url-filter]
;; url-enc-entry is relative to base URL ;; url-enc-entry is relative to base URL
url-server = [url-user [url-auth] "@"] hostport url-server = [url-enc-user [url-auth] "@"] hostport
;; See RFC 1738 for definition of "hostport" ;; See RFC 1738 for definition of "hostport"
9. Multi-lingual Considerations 9. Multi-lingual Considerations
The IAB charset workshop [IAB-CHARSET] came to a number of The IAB charset workshop [IAB-CHARSET] came to a number of
conclusions which influenced the design of ACAP. The decision to use conclusions which influenced the design of ACAP. The decision to use
UTF-8 as the character encoding scheme was based on that work. The UTF-8 as the character encoding scheme was based on that work. The
LANG command to negotiate a language for error messages is also LANG command to negotiate a language for error messages is also
included. included.
skipping to change at page 62, line 49 skipping to change at page 61, line 36
should be a way to identify the natural language for human readable should be a way to identify the natural language for human readable
strings. Several promising proposals have been made for use within strings. Several promising proposals have been made for use within
ACAP, but no clear consensus on a single method is apparent at this ACAP, but no clear consensus on a single method is apparent at this
stage. The following rules are likely to permit the addition of stage. The following rules are likely to permit the addition of
multi-lingual support in the future: multi-lingual support in the future:
(1) A work in progress called Multi-Lingual String Format (MLSF) (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 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 sequences to store language tags. In order to permit its addition to
a future version of this standard, client-side UTF-8 interpreters a future version of this standard, client-side UTF-8 interpreters
SHOULD silently ignore illegal multi-byte UTF-8 characters, and treat MUST be able to silently ignore illegal multi-byte UTF-8 characters,
illegal single-byte UTF-8 characters as end of string markers. and treat illegal single-byte UTF-8 characters as end of string
Servers, for the time being, MUST silently accept illegal UTF-8 markers. Servers, for the time being, MUST be able to silently
characters, except in attribute names and entry names. Clients MUST accept illegal UTF-8 characters, except in attribute names and entry
NOT send illegal UTF-8 characters to the server unless a future names. Clients MUST NOT send illegal UTF-8 characters to the server
standard changes this rule. unless a future standard changes this rule.
(2) There is a proposal to add language tags to Unicode. To support (2) There is a proposal to add language tags to Unicode. To support
this, servers MUST be able to store UTF-8 characters of up to 20 bits this, servers MUST be able to store UTF-8 characters of up to 20 bits
of data. of data.
(3) The metadata item "language" is reserved for future use. (3) The metadata item "language" is reserved for future use.
10. Security Considerations 10. Security Considerations
The AUTHENTICATE command uses SASL [SASL] to provide basic The AUTHENTICATE command uses SASL [SASL] to provide basic
authentication, authorization, integrity and privacy services. This authentication, authorization, integrity and privacy services. This
is described in section 6.3.1. The security considerations for the is described in section 6.3.1.
PLAIN SASL mechanism [SASL-PLAIN] also apply.
When the CRAM-MD5 mechanism is used, the security considerations for
the CRAM-MD5 SASL mechanism [CRAM-MD5] and the HMAC Keyed-Hashing
Internet DRAFT ACAP August 1997
algorithm [HMAC] apply. The CRAM-MD5 mechanism is also susceptible
to passive dictionary attacks. This means that if an authentication
session is recorded by a passive observer, that observer can try
common passwords through the CRAM-MD5 mechanism and see if the
results match. This attack is reduced by using hard to guess
passwords. Sites are encouraged to educate users and have the
password change service test candidate passwords against a
dictionary. ACAP implementations of CRAM-MD5 SHOULD permit passwords
of at least 64 characters in length.
ACAP protocol transactions are susceptible to passive observers or ACAP protocol transactions are susceptible to passive observers or
man in the middle attacks which alter the data, unless the optional man in the middle attacks which alter the data, unless the optional
encryption and integrity services of the AUTHENTICATE command are encryption and integrity services of the AUTHENTICATE command are
offered, or an external security mechanism is used for protection. enabled, or an external security mechanism is used for protection.
It may be useful to allow configuration of both clients and servers It may be useful to allow configuration of both clients and servers
to refuse to transfer sensitive information in the absence of strong to refuse to transfer sensitive information in the absence of strong
encryption. encryption.
ACAP access control lists provide fine grained authorization for ACAP access control lists provide fine grained authorization for
access to attributes. A number of related security issues are access to attributes. A number of related security issues are
described in section 3.5. described in section 3.5.
ACAP URLs have the same security considerations as IMAP URLs ACAP URLs have the same security considerations as IMAP URLs
[IMAP-URL]. [IMAP-URL].
skipping to change at page 63, line 47 skipping to change at page 62, line 46
be able to completely flush any non-public cached configuration data be able to completely flush any non-public cached configuration data
when a user leaves. when a user leaves.
As laptop computers can be easily stolen and a cache of configuration As laptop computers can be easily stolen and a cache of configuration
data may contain sensitive information, a disconnected mode ACAP data may contain sensitive information, a disconnected mode ACAP
client may wish to encrypt and password protect cached configuration client may wish to encrypt and password protect cached configuration
information. information.
11. Acknowledgments 11. Acknowledgments
Many thanks to the follow people who helped design ACAP over the past Many thanks to the follow people who have contributed to ACAP over
four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob Earhart, the past four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob
Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, Steve Hole, Earhart, Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield,
Steve Hubert, Dave Roberts, Bart Schaefer, Matt Wall and other Steve Dorner, Steve Hole, Steve Hubert, Dave Roberts, Bart Schaefer,
participants of the IETF ACAP working group. Matt Wall and other participants of the IETF ACAP working group.
Internet DRAFT ACAP August 1997
12. Authors' Addresses 12. Authors' Addresses
Chris Newman Chris Newman
Innosoft International, Inc. Innosoft International, Inc.
1050 Lakes Drive 1050 Lakes Drive
West Covina, CA 91790 USA West Covina, CA 91790 USA
Email: chris.newman@innosoft.com Email: chris.newman@innosoft.com
skipping to change at page 64, line 35 skipping to change at page 63, line 37
[ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF",
Work in progress: draft-ietf-drums-abnf-xx.txt Work in progress: draft-ietf-drums-abnf-xx.txt
[BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource
Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of
Minnesota, December 1994. Minnesota, December 1994.
<ftp://ds.internic.net/rfc/rfc1738.txt> <ftp://ds.internic.net/rfc/rfc1738.txt>
[CRAM-MD5] Klensin, Catoe, Krumviede, "IMAP/POP AUTHorize Extension
for Simple Challenge/Response", RFC 2095, MCI, January 1997.
<ftp://ds.internic.net/rfc/rfc2095.txt>
[HMAC] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for Message
Authentication", RFC 2104, IBM, UCSD, February 1997.
<ftp://ds.internic.net/rfc/rfc2104.txt>
[IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson, [IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson,
Crispin, Svanberg, "The Report of the IAB Character Set Workshop held Crispin, Svanberg, "The Report of the IAB Character Set Workshop held
29 February - 1 March, 1996", RFC 2130, April 1997. 29 February - 1 March, 1996", RFC 2130, April 1997.
<ftp://ds.internic.net/rfc/rfc2130.txt> <ftp://ds.internic.net/rfc/rfc2130.txt>
Internet DRAFT ACAP August 1997
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 2060, University of Washington, December 1996. 4rev1", RFC 2060, University of Washington, December 1996.
<ftp://ds.internic.net/rfc/rfc2060.txt> <ftp://ds.internic.net/rfc/rfc2060.txt>
[IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie
Mellon, January 1997. Mellon, January 1997.
<ftp://ds.internic.net/rfc/rfc2086.txt> <ftp://ds.internic.net/rfc/rfc2086.txt>
skipping to change at page 65, line 35 skipping to change at page 64, line 47
<ftp://ds.internic.net/rfc/rfc1766.txt> <ftp://ds.internic.net/rfc/rfc1766.txt>
[REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808,
UC Irvine, June 1995. UC Irvine, June 1995.
<ftp://ds.internic.net/rfc/rfc1808.txt> <ftp://ds.internic.net/rfc/rfc1808.txt>
[SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)",
Work in progress: draft-myers-auth-sasl-xx.txt Work in progress: draft-myers-auth-sasl-xx.txt
[SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress: [SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress.
draft-newman-sasl-anon-xx.txt.
[SASL-PLAIN] Newman, "Plaintext Password SASL Mechanism and
Transition Codes", Work in progress: draft-newman-sasl-plaintrans-
xx.txt.
[UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version [UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version
2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9. 2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9.
[US-ASCII] "USA Standard Code for Information Interchange," X3.4. [US-ASCII] "USA Standard Code for Information Interchange," X3.4.
American National Standards Institute: New York (1968). American National Standards Institute: New York (1968).
Internet DRAFT ACAP August 1997
[UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO
10646", RFC 2044, Alis Technologies, October 1996. 10646", RFC 2044, Alis Technologies, October 1996.
<ftp://ds.internic.net/rfc/rfc2044.txt> <ftp://ds.internic.net/rfc/rfc2044.txt>
Internet DRAFT ACAP August 1997
B. ACAP Keyword Index B. ACAP Keyword Index
ACAP (untagged response) ................................... 27 ACAP (untagged response) ................................... 26
ADDTO (untagged response) .................................. 41 ADDTO (untagged response) .................................. 40
ALERT (untagged response) .................................. 31 ALERT (untagged response) .................................. 30
ALL (search keyword) ....................................... 37 ALL (search keyword) ....................................... 36
AND (search keyword) ....................................... 37 AND (search keyword) ....................................... 36
AUTH-TOO-WEAK (response code) .............................. 19 AUTH-TOO-WEAK (response code) .............................. 18
AUTHENTICATE (command) ..................................... 32 AUTHENTICATE (command) ..................................... 31
BAD (response) ............................................. 30 BAD (response) ............................................. 29
BYE (untagged response) .................................... 31 BYE (untagged response) .................................... 30
CHANGE (untagged response) ................................. 42 CHANGE (untagged response) ................................. 41
COMPARE (search keyword) ................................... 37 COMPARE (search keyword) ................................... 36
COMPARESTRICT (search keyword) ............................. 37 COMPARESTRICT (search keyword) ............................. 36
CONTEXTLIMIT (ACAP capability) ............................. 27 CONTEXTLIMIT (ACAP capability) ............................. 26
DELETEACL (command) ........................................ 47 DELETEACL (command) ........................................ 45
DELETED (intermediate response) ............................ 46 DELETED (intermediate response) ............................ 45
DELETEDSINCE (command) ..................................... 45 DELETEDSINCE (command) ..................................... 44
DEPTH (search modifier) .................................... 34 DEPTH (search modifier) .................................... 33
ENCRYPT-NEEDED (response code) ............................. 19 ENCRYPT-NEEDED (response code) ............................. 18
ENTRY (intermediate response) .............................. 38 ENTRY (intermediate response) .............................. 37
EQUAL (search keyword) ..................................... 37 EQUAL (search keyword) ..................................... 36
FREECONTEXT (command) ...................................... 40 FREECONTEXT (command) ...................................... 39
GETQUOTA (command) ......................................... 49 GETQUOTA (command) ......................................... 48
HARDLIMIT (search modifier) ................................ 34 HARDLIMIT (search modifier) ................................ 33
IMPLEMENTATION (ACAP capability) ........................... 27 IMPLEMENTATION (ACAP capability) ........................... 26
INVALID (response code) .................................... 19 INVALID (response code) .................................... 18
LANG (command) ............................................. 28 LANG (command) ............................................. 27
LANG (intermediate response) ............................... 29 LANG (intermediate response) ............................... 28
LIMIT (search modifier) .................................... 34 LIMIT (search modifier) .................................... 33
LISTRIGHTS (command) ....................................... 48 LISTRIGHTS (command) ....................................... 47
LISTRIGHTS (intermediate response) ......................... 48 LISTRIGHTS (intermediate response) ......................... 47
LOGOUT (command) ........................................... 29 LOGOUT (command) ........................................... 28
MAKECONTEXT (search modifier) .............................. 35 MAKECONTEXT (search modifier) .............................. 34
MODIFIED (response code) ................................... 20 MODIFIED (response code) ................................... 19
MODTIME (intermediate response) ............................ 38 MODTIME (intermediate response) ............................ 37
MODTIME (untagged response) ................................ 43 MODTIME (untagged response) ................................ 42
MYRIGHTS (command) ......................................... 47 MYRIGHTS (command) ......................................... 46
MYRIGHTS (intermediate response) ........................... 48 MYRIGHTS (intermediate response) ........................... 47
NO (response) .............................................. 30 NO (response) .............................................. 29
NOCREATE (store modifier) .................................. 44 NOCREATE (store modifier) .................................. 43
NOEXIST (response code) .................................... 20 NOEXIST (response code) .................................... 19
NOINHERIT (search modifier) ................................ 36 NOINHERIT (search modifier) ................................ 35
NOOP (command) ............................................. 28 NOOP (command) ............................................. 27
NOT (search keyword) ....................................... 37 NOT (search keyword) ....................................... 36
OK (response) .............................................. 29 OK (response) .............................................. 29
OR (search keyword) ........................................ 37 OR (search keyword) ........................................ 36
PERMISSION (response code) ................................. 20 PERMISSION (response code) ................................. 19
PREFIX (search keyword) .................................... 37
QUOTA (response code) ...................................... 20 Internet DRAFT ACAP August 1997
QUOTA (untagged response) .................................. 49
RANGE (search keyword) ..................................... 37 PREFIX (search keyword) .................................... 36
REFER (intermediate response) .............................. 38 QUOTA (response code) ...................................... 19
REFER (response code) ...................................... 20 QUOTA (untagged response) .................................. 48
REMOVEFROM (untagged response) ............................. 41 RANGE (search keyword) ..................................... 36
RETURN (search modifier) ................................... 36 REFER (intermediate response) .............................. 37
REFER (response code) ...................................... 19
REMOVEFROM (untagged response) ............................. 40
RETURN (search modifier) ................................... 35
SASL (ACAP capability) ..................................... 27 SASL (ACAP capability) ..................................... 27
SASL (response code) ....................................... 19
SEARCH (command) ........................................... 33 SEARCH (command) ........................................... 33
SETACL (command) ........................................... 46 SETACL (command) ........................................... 45
SORT (search modifier) ..................................... 36 SORT (search modifier) ..................................... 35
STORE (command) ............................................ 43 STORE (command) ............................................ 42
SUBSTRING (search keyword) ................................. 38 SUBSTRING (search keyword) ................................. 37
TOOMANY (response code) .................................... 20 TOOMANY (response code) .................................... 19
TOOOLD (response code) ..................................... 20 TOOOLD (response code) ..................................... 19
TRANSITION-NEEDED (response code) .......................... 20 TRANSITION-NEEDED (response code) .......................... 19
TRYFREECONTEXT (response code) ............................. 21 TRYFREECONTEXT (response code) ............................. 20
TRYLATER (response code) ................................... 20 TRYLATER (response code) ................................... 20
UNCHANGEDSINCE (store modifier) ............................ 44 UNCHANGEDSINCE (store modifier) ............................ 43
UPDATECONTEXT (command) .................................... 40 UPDATECONTEXT (command) .................................... 39
WAYTOOMANY (response code) ................................. 21 WAYTOOMANY (response code) ................................. 20
acl (attribute metadata) ................................... 13 acl (attribute metadata) ................................... 12
anyone (ACL identifier) .................................... 18 anyone (ACL identifier) .................................... 16
attribute (attribute metadata) ............................. 13 attribute (attribute metadata) ............................. 12
dataset.acl (dataset attribute) ............................ 25 dataset.acl (dataset attribute) ............................ 24
dataset.acl.<attribute> (dataset attribute) ................ 25 dataset.acl.<attribute> (dataset attribute) ................ 24
dataset.inherit (dataset attribute) ........................ 25 dataset.inherit (dataset attribute) ........................ 24
en;nocase;octet (comparator) ............................... 17 entry (predefined attribute) ............................... 11
entry (predefined attribute) ............................... 12 i;ascii-casemap (comparator) ............................... 16
i;numeric (comparator) ..................................... 17 i;ascii-numeric (comparator) ............................... 16
i;octet (comparator) ....................................... 16 i;octet (comparator) ....................................... 15
modtime (predefined attribute) ............................. 12 modtime (predefined attribute) ............................. 11
myrights (attribute metadata) .............................. 13 myrights (attribute metadata) .............................. 12
size (attribute metadata) .................................. 13 size (attribute metadata) .................................. 12
subdataset (predefined attribute) .......................... 12 subdataset (predefined attribute) .......................... 11
value (attribute metadata) ................................. 14 value (attribute metadata) ................................. 13
 End of changes. 183 change blocks. 
454 lines changed or deleted 606 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/