idnits 2.17.1 draft-ietf-acap-spec-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-03-28) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 30 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 241: '... MUST be explicitly identified in th...' RFC 2119 keyword, line 242: '... which SHOULD include specific fixed...' RFC 2119 keyword, line 244: '...ication, clients MUST NOT depend on th...' RFC 2119 keyword, line 347: '... tag SHOULD be generated by the clie...' RFC 2119 keyword, line 418: '... A client MUST be prepared to accept...' (97 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1997) is 9722 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'KEYWORDS' on line 3282 looks like a reference -- Missing reference section? 'IMAP4' on line 3260 looks like a reference -- Missing reference section? 'US-ASCII' on line 3305 looks like a reference -- Missing reference section? 'SASL' on line 3297 looks like a reference -- Missing reference section? 'UTF8' on line 3310 looks like a reference -- Missing reference section? 'UNICODE-2' on line 3302 looks like a reference -- Missing reference section? 'ISO-10646' on line 3274 looks like a reference -- Missing reference section? 'BASIC-URL' on line 3236 looks like a reference -- Missing reference section? 'REL-URL' on line 3292 looks like a reference -- Missing reference section? 'SASL-ANON' on line 3300 looks like a reference -- Missing reference section? 'IMAP-URL' on line 3270 looks like a reference -- Missing reference section? 'ISO-C' on line 3278 looks like a reference -- Missing reference section? 'IMAP-ACL' on line 3265 looks like a reference -- Missing reference section? 'CRAM-MD5' on line 3242 looks like a reference -- Missing reference section? 'HMAC' on line 3247 looks like a reference -- Missing reference section? 'ENUMERATE' on line 1790 looks like a reference -- Missing reference section? 'NOTIFY' on line 1790 looks like a reference -- Missing reference section? 'ABNF' on line 3233 looks like a reference -- Missing reference section? 'LANG-TAGS' on line 3287 looks like a reference -- Missing reference section? 'IAB-CHARSET' on line 3252 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 1 warning (==), 22 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Newman 3 Internet Draft: ACAP Innosoft 4 Document: draft-ietf-acap-spec-06.txt J. G. Myers 5 Netscape 6 August 1997 7 Expires in six months 9 ACAP -- Application Configuration Access Protocol 11 Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 To view the entire list of current Internet-Drafts, please check the 24 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 25 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 26 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 27 ftp.isi.edu (US West Coast). 29 Abstract 31 The Application Configuration Access Protocol (ACAP) is designed to 32 support remote storage and access of program option, configuration 33 and preference information. The data store model is designed to 34 allow a client relatively simple access to interesting data, to allow 35 new information to be easily added without server re-configuration, 36 and to promote the use of both standardized data and custom or 37 proprietary data. Key features include 'inheritance' which can be 38 used to manage default values for configuration settings and access 39 control lists which allow interesting personal information to be 40 shared and group information to be restricted. 42 Internet DRAFT ACAP August 1997 44 Table of Contents 46 Status of this Memo ............................................... i 47 Abstract .......................................................... i 48 ACAP Protocol Specification ....................................... 1 49 1. Introduction ............................................. 1 50 1.1. Conventions Used in this Document ........................ 1 51 1.2. ACAP Data Model .......................................... 1 52 1.3. ACAP Design Goals ........................................ 1 53 1.4. Validation ............................................... 2 54 1.5. Definitions .............................................. 2 55 1.6. ACAP Command Overview .................................... 3 56 2. Protocol Framework ....................................... 4 57 2.1. Link Level ............................................... 4 58 2.2. Commands and Responses ................................... 4 59 2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 4 60 2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 5 61 2.3. Server States ............................................ 6 62 2.3.1. Non-Authenticated State .................................. 6 63 2.3.2. Authenticated State ...................................... 6 64 2.3.3. Logout State ............................................. 6 65 2.4. Operational Considerations ............................... 7 66 2.4.1. Untagged Status Updates .................................. 7 67 2.4.2. Response when No Command in Progress ..................... 7 68 2.4.3. Auto-logout Timer ........................................ 7 69 2.4.4. Multiple Commands in Progress ............................ 8 70 2.5. Server Command Continuation Request ...................... 8 71 2.6. Data Formats ............................................. 8 72 2.6.1. Atom ..................................................... 9 73 2.6.2. Number ................................................... 9 74 2.6.3. String ................................................... 9 75 2.6.3.1. 8-bit and Binary Strings ................................. 10 76 2.6.4. Parenthesized List ....................................... 10 77 2.6.5. NIL ...................................................... 10 78 3. Protocol Elements ........................................ 10 79 3.1. Entries and Attributes ................................... 10 80 3.1.1. Predefined Attributes .................................... 11 81 3.1.2. Attribute Metadata ....................................... 12 82 3.2. ACAP URL scheme .......................................... 13 83 3.2.1. ACAP URL User Name and Authentication Mechanism .......... 13 84 3.2.2. Relative ACAP URLs ....................................... 14 85 3.3. Contexts ................................................. 14 86 3.4. Comparators .............................................. 14 87 Internet DRAFT ACAP August 1997 89 3.5. Access Control Lists (ACLs) .............................. 16 90 3.6. Server Response Codes .................................... 18 91 4. Namespace Conventions .................................... 20 92 4.1. Dataset Namespace ........................................ 20 93 4.2. Attribute Namespace ...................................... 21 94 4.3. Formal Syntax for Dataset and Attribute Namespace ........ 22 95 5. Dataset Management ....................................... 23 96 5.1. Dataset Inheritance ...................................... 23 97 5.2. Dataset Attributes ....................................... 24 98 5.3. Dataset Creation ......................................... 24 99 5.4. Dataset Class Capabilities ............................... 25 100 5.5. Dataset Quotas ........................................... 25 101 6. Command and Response Specifications ...................... 25 102 6.1. Initial Connection ....................................... 26 103 6.1.1. ACAP Untagged Response ................................... 26 104 6.2. Any State ................................................ 27 105 6.2.1. NOOP Command ............................................. 27 106 6.2.2. LANG Command ............................................. 27 107 6.2.3. LANG Intermediate Response ............................... 28 108 6.2.4. LOGOUT Command ........................................... 28 109 6.2.5. OK Response .............................................. 29 110 6.2.6. NO Response .............................................. 29 111 6.2.7. BAD Response ............................................. 29 112 6.2.8. BYE Untagged Response .................................... 30 113 6.2.9. ALERT Untagged Response .................................. 30 114 6.3. Non-Authenticated State .................................. 31 115 6.3.1. AUTHENTICATE Command ..................................... 31 116 6.4. Searching ................................................ 32 117 6.4.1. SEARCH Command ........................................... 33 118 6.4.2. ENTRY Intermediate Response .............................. 37 119 6.4.3. MODTIME Intermediate Response ............................ 37 120 6.4.4. REFER Intermediate Response .............................. 37 121 6.4.5. Search Examples .......................................... 38 122 6.5. Contexts ................................................. 39 123 6.5.1. FREECONTEXT Command ...................................... 39 124 6.5.2. UPDATECONTEXT Command .................................... 39 125 6.5.3. ADDTO Untagged Response .................................. 40 126 6.5.4. REMOVEFROM Untagged Response ............................. 40 127 6.5.5. CHANGE Untagged Response ................................. 41 128 6.5.6. MODTIME Untagged Response ................................ 42 129 6.6. Dataset modification ..................................... 42 130 6.6.1. STORE Command ............................................ 42 131 6.6.2. DELETEDSINCE Command ..................................... 44 132 6.6.3. DELETED Intermediate Response ............................ 45 133 6.7. Access Control List Commands ............................. 45 134 6.7.1. SETACL Command ........................................... 45 135 6.7.2. DELETEACL Command ........................................ 45 136 6.7.3. MYRIGHTS Command ......................................... 46 137 Internet DRAFT ACAP August 1997 139 6.7.4. MYRIGHTS Intermediate Response ........................... 47 140 6.7.5. LISTRIGHTS Command ....................................... 47 141 6.7.6. LISTRIGHTS Intermediate Response ......................... 47 142 6.8. Quotas ................................................... 48 143 6.8.1. GETQUOTA Command ......................................... 48 144 6.8.3. QUOTA Untagged Response .................................. 48 145 6.9. Extensions ............................................... 48 146 7. Registration Procedures .................................. 49 147 7.1. ACAP Capabilities ........................................ 49 148 7.2. ACAP Response Codes ...................................... 50 149 7.3. Dataset Classes .......................................... 50 150 7.4. Vendor Subtree ........................................... 51 151 8. Formal Syntax ............................................ 51 152 9. Multi-lingual Considerations ............................. 61 153 10. Security Considerations .................................. 61 154 11. Acknowledgments .......................................... 62 155 12. Authors' Addresses ....................................... 63 156 Appendices ........................................................ 63 157 A. References ............................................... 63 158 B. ACAP Keyword Index ....................................... 66 159 Internet DRAFT ACAP August 1997 161 ACAP Protocol Specification 163 1. Introduction 165 1.1. Conventions Used in this Document 167 In examples, "C:" and "S:" indicate lines sent by the client and 168 server respectively. If such lines are wrapped without a new "C:" or 169 "S:" label, then the wrapping is for editorial clarity and is not 170 part of the command. 172 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", 173 and "MAY" in this document are to be interpreted as described in "Key 174 words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 176 1.2. ACAP Data Model 178 An ACAP server exports a hierarchical tree of entries. Each level of 179 the tree is called a dataset, and each dataset is made up of a list 180 of entries. Each entry has a unique name and may contain any number 181 of named attributes. Each attribute within an entry may be single 182 valued or multi-valued and may have associated metadata to assist 183 access and interpretation of the value. 185 The rules with which a client interprets the data within a portion of 186 ACAP's tree of entries are called a dataset class. 188 1.3. ACAP Design Goals 190 ACAP's primary purpose is to allow users access to their 191 configuration data from multiple network-connected computers. Users 192 can then sit down in front of any network-connected computer, run any 193 ACAP-enabled application and have access to their own configuration 194 data. Because it is hoped that many applications will become ACAP- 195 enabled, client simplicity was preferred to server or protocol 196 simplicity whenever reasonable. 198 ACAP is designed to be easily manageable. For this reason, it 199 includes "inheritance" which allows one dataset to inherit default 200 attributes from another dataset. In addition, access control lists 201 are included to permit delegation of management and quotas are 202 included to control storage. Finally, an ACAP server which is 203 conformant to this base specification should be able to support most 204 dataset classes defined in the future without requiring a server 205 reconfiguration or upgrade. 207 ACAP is designed to operate well with a client that only has 208 intermittent access to an ACAP server. For this reason, each entry 210 Internet DRAFT ACAP August 1997 212 has a server maintained modification time so that the client may 213 detect changes. In addition, the client may ask the server for a 214 list of entries which have been removed since it last accessed the 215 server. 217 ACAP presumes that a dataset may be potentially large and/or the 218 client's network connection may be slow, and thus offers server 219 sorting, selective fetching and change notification for entries 220 within a dataset. 222 As required for most Internet protocols, security, scalability and 223 internationalization were important design goals. 225 Given these design goals, an attempt was made to keep ACAP as simple 226 as possible. It is a traditional Internet text based protocol which 227 massively simplifies protocol debugging. It was designed based on 228 the successful IMAP [IMAP4] protocol framework, with a few 229 refinements. 231 1.4. Validation 233 By default, any value may be stored in any attribute for which the 234 user has appropriate permission and quota. This rule is necessary to 235 allow the addition of new simple dataset classes without 236 reconfiguring or upgrading the server. 238 In some cases, such as when the value has special meaning to the 239 server, it is useful to have the server enforce validation by 240 returning the INVALID response code to a STORE command. These cases 241 MUST be explicitly identified in the dataset class specification 242 which SHOULD include specific fixed rules for validation. Since a 243 given ACAP server may be unaware of any particular dataset class 244 specification, clients MUST NOT depend on the presence of enforced 245 validation on the server. 247 1.5. Definitions 249 access control list (ACL) 250 A set of identifier, rights pairs associated with an object. An 251 ACL is used to determine which operations a user is permitted to 252 perform on that object. See section 3.5. 254 attribute 255 A named value within an entry. See section 3.1. 257 comparator 258 A named function which can be used to perform one or more of 260 Internet DRAFT ACAP August 1997 262 three comparison operations: ordering, equality and substring 263 matching. See section 3.4. 265 context 266 An ordered subset of entries in a dataset, created by a SEARCH 267 command with a MAKECONTEXT modifier. See section 3.3. 269 dataset 270 One level of hierarchy in ACAP's tree of entries. 272 dataset class specification 273 The rules which allow a client to interpret the data within a 274 portion of ACAP's tree of entries. 276 entry 277 A set of attributes with a unique entry name. See section 3.1. 279 metadata 280 Information describing an attribute, its value and any access 281 controls associated with that attribute. See section 3.1.2. 283 NIL This represents the non-existence of a particular data item. 285 NUL A control character encoded as 0 in US-ASCII [US-ASCII]. 287 octet 288 An 8-bit value. On most modern computer systems, an octet is 289 one byte. 291 SASL Simple Authentication and Security Layer [SASL]. 293 UTC Universal Coordinated Time as maintained by the Bureau 294 International des Poids et Mesures (BIPM). 296 UTF-8 297 An 8-bit transformation format of the Universal Character Set 298 [UTF8]. Note that an incompatible change was made to the coded 299 character set referenced by [UTF8], so for the purpose of this 300 document, UTF-8 refers to the UTF-8 encoding as defined by 301 version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646] 302 including amendments one through seven. 304 1.6. ACAP Command Overview 306 The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic 307 protocol services. The SEARCH command is used to select, sort, fetch 308 and monitor changes to attribute values and metadata. The 310 Internet DRAFT ACAP August 1997 312 UPDATECONTEXT and FREECONTEXT commands are also used to assist in 313 monitoring changes in attribute values and metadata. The STORE 314 command is used to add, modify and delete entries and attributes. 315 The DELETEDSINCE command is used to assist a client in 316 re-synchronizing a cache with the server. The GETQUOTA, SETACL, 317 DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine 318 storage quotas and examine or modify access permissions. 320 2. Protocol Framework 322 2.1. Link Level 324 The ACAP protocol assumes a reliable data stream such as provided by 325 TCP. When TCP is used, an ACAP server listens on port 674. 327 2.2. Commands and Responses 329 An ACAP session consists of the establishment of a client/server 330 connection, an initial greeting from the server, and client/server 331 interactions. These client/server interactions consist of a client 332 command, server data, and a server completion result. 334 ACAP is a text-based line-oriented protocol. In general, 335 interactions transmitted by clients and servers are in the form of 336 lines; that is, sequences of characters that end with a CRLF. The 337 protocol receiver of an ACAP client or server is either reading a 338 line, or is reading a sequence of octets with a known count (a 339 literal) followed by a line. Both clients and servers must be 340 capable of handling lines of arbitrary length. 342 2.2.1. Client Protocol Sender and Server Protocol Receiver 344 The client command begins an operation. Each client command is 345 prefixed with a identifier (an alphanumeric string of no more than 32 346 characters, e.g., A0001, A0002, etc.) called a "tag". A different 347 tag SHOULD be generated by the client for each command. 349 There are two cases in which a line from the client does not 350 represent a complete command. In one case, a command argument is 351 quoted with an octet count (see the description of literal in section 352 2.6.3); in the other case, the command arguments require server 353 feedback (see the AUTHENTICATE command). In some of these cases, the 354 server sends a command continuation request if it is ready for the 355 next part of the command. This response is prefixed with the token 356 "+". 358 Note: If, instead, the server detected an error in a 359 command, it sends a BAD completion response with tag 361 Internet DRAFT ACAP August 1997 363 matching the command (as described below) to reject the 364 command and prevent the client from sending any more of the 365 command. 367 It is also possible for the server to send a completion or 368 intermediate response for some other command (if multiple 369 commands are in progress), or untagged data. In either 370 case, the command continuation request is still pending; 371 the client takes the appropriate action for the response, 372 and reads another response from the server. 374 The ACAP server reads a command line from the client, parses the 375 command and its arguments, and transmits server data and a server 376 command completion result. 378 2.2.2. Server Protocol Sender and Client Protocol Receiver 380 Data transmitted by the server to the client come in four forms: 381 command continuation requests, command completion results, 382 intermediate responses, and untagged responses. 384 A command continuation request is prefixed with the token "+". 386 A command completion result indicates the success or failure of the 387 operation. It is tagged with the same tag as the client command 388 which began the operation. Thus, if more than one command is in 389 progress, the tag in a server completion response identifies the 390 command to which the response applies. There are three possible 391 server completion responses: OK (indicating success), NO (indicating 392 failure), or BAD (indicating protocol error such as unrecognized 393 command or command syntax error). 395 An intermediate response returns data which can only be interpreted 396 within the context of a command in progress. It is tagged with the 397 same tag as the client command which began the operation. Thus, if 398 more than one command is in progress, the tag in an intermediate 399 response identifies the command to which the response applies. A 400 tagged response other than "OK", "NO", or "BAD" is an intermediate 401 response. 403 An untagged response returns data or status messages which may be 404 interpreted outside the context of a command in progress. It is 405 prefixed with the token "*". Untagged data may be sent as a result 406 of a client command, or may be sent unilaterally by the server. 407 There is no syntactic difference between untagged data that resulted 408 from a specific command and untagged data that were sent 409 unilaterally. 411 Internet DRAFT ACAP August 1997 413 The protocol receiver of an ACAP client reads a response line from 414 the server. It then takes action on the response based upon the 415 first token of the response, which may be a tag, a "*", or a "+" as 416 described above. 418 A client MUST be prepared to accept any server response at all times. 419 This includes untagged data that it may not have requested. 421 This topic is discussed in greater detail in the Server Responses 422 section. 424 2.3. Server States 426 An ACAP server is in one of three states. Most commands are valid in 427 only certain states. It is a protocol error for the client to 428 attempt a command while the server is in an inappropriate state for 429 that command. In this case, a server will respond with a BAD command 430 completion result. 432 2.3.1. Non-Authenticated State 434 In non-authenticated state, the user must supply authentication 435 credentials before most commands will be permitted. This state is 436 entered when a connection starts. 438 2.3.2. Authenticated State 440 In authenticated state, the user is authenticated and most commands 441 will be permitted. This state is entered when acceptable 442 authentication credentials have been provided. 444 2.3.3. Logout State 446 In logout state, the session is being terminated, and the server will 447 close the connection. This state can be entered as a result of a 448 client request or by unilateral server decision. 450 Internet DRAFT ACAP August 1997 452 +--------------------------------------+ 453 |initial connection and server greeting| 454 +--------------------------------------+ 455 || (1) || (2) 456 VV || 457 +-----------------+ || 458 |non-authenticated| || 459 +-----------------+ || 460 || (4) || (3) || 461 || VV || 462 || +----------------+ || 463 || | authenticated | || 464 || +----------------+ || 465 || || (4) || 466 VV VV VV 467 +--------------------------------------+ 468 | logout and close connection | 469 +--------------------------------------+ 471 (1) connection (ACAP greeting) 472 (2) rejected connection (BYE greeting) 473 (3) successful AUTHENTICATE command 474 (4) LOGOUT command, server shutdown, or connection closed 476 2.4. Operational Considerations 478 2.4.1. Untagged Status Updates 480 At any time, a server can send data that the client did not request. 482 2.4.2. Response when No Command in Progress 484 Server implementations are permitted to send an untagged response 485 while there is no command in progress. Server implementations that 486 send such responses MUST deal with flow control considerations. 487 Specifically, they must either (1) verify that the size of the data 488 does not exceed the underlying transport's available window size, or 489 (2) use non-blocking writes. 491 2.4.3. Auto-logout Timer 493 If a server has an inactivity auto-logout timer, that timer MUST be 494 of at least 30 minutes duration. The receipt of ANY command from the 495 client during that interval MUST suffice to reset the auto-logout 496 timer. 498 Internet DRAFT ACAP August 1997 500 2.4.4. Multiple Commands in Progress 502 The client is not required to wait for the completion result of a 503 command before sending another command, subject to flow control 504 constraints on the underlying data stream. Similarly, a server is 505 not required to process a command to completion before beginning 506 processing of the next command, unless an ambiguity would result 507 because of a command that would affect the results of other commands. 508 If there is such an ambiguity, the server executes commands to 509 completion in the order given by the client. 511 2.5. Server Command Continuation Request 513 The command continuation request is indicated by a "+" token instead 514 of a tag. This indicates that the server is ready to accept the 515 continuation of a command from the client. 517 This response is used in the AUTHENTICATE command to transmit server 518 data to the client, and request additional client data. This 519 response is also used if an argument to any command is a 520 synchronizing literal (see section 2.6.3). 522 The client is not permitted to send the octets of a synchronizing 523 literal unless the server indicates that it expects it. This permits 524 the server to process commands and reject errors on a line-by-line 525 basis, assuming it checks for non-synchronizing literals at the end 526 of each line. The remainder of the command, including the CRLF that 527 terminates a command, follows the octets of the literal. If there 528 are any additional command arguments the literal octets are followed 529 by a space and those arguments. 531 Example: C: A099 FREECONTEXT {10} 532 S: + "Ready for additional command text" 533 C: FRED 534 C: FOOB 535 S: A099 OK "FREECONTEXT completed" 536 C: A044 BLURDYBLOOP {102856} 537 S: A044 BAD "No such command as 'BLURDYBLOOP'" 539 2.6. Data Formats 541 ACAP uses textual commands and responses. Data in ACAP can be in one 542 of five forms: atom, number, string, parenthesized list or NIL. 544 Internet DRAFT ACAP August 1997 546 2.6.1. Atom 548 An atom consists of one to 1024 non-special characters. It must 549 begin with a letter. Atoms are used for protocol keywords. 551 2.6.2. Number 553 A number consists of one or more digit characters, and represents a 554 numeric value. Numbers are restricted to the range of an unsigned 555 32-bit integer: 0 < number < 4,294,967,296. 557 2.6.3. String 559 A string is in one of two forms: literal and quoted string. The 560 literal form is the general form of string. The quoted string form 561 is an alternative that avoids the overhead of processing a literal at 562 the cost of restrictions of what may be in a quoted string. 564 A literal is a sequence of zero or more octets (including CR and LF), 565 prefix-quoted with an octet count in the form of an open brace ("{"), 566 the number of octets, close brace ("}"), and CRLF. In the case of 567 literals transmitted from server to client, the CRLF is immediately 568 followed by the octet data. 570 There are two forms of literals transmitted from client to server. 571 The form where the open brace ("{") and number of octets is 572 immediately followed by a close brace ("}") and CRLF is called a 573 synchronizing literal. When sending a synchronizing literal, the 574 client must wait to receive a command continuation request before 575 sending the octet data (and the remainder of the command). The other 576 form of literal, the non-synchronizing literal, is used to transmit a 577 string from client to server without waiting for a command 578 continuation request. The non-synchronizing literal differs from the 579 synchronizing literal by having a plus ("+") between the number of 580 octets and the close brace ("}") and by having the octet data 581 immediately following the CRLF. 583 A quoted string is a sequence of zero to 1024 octets excluding NUL, 584 CR and LF, with double quote (<">) characters at each end. 586 The empty string is represented as "" (a quoted string with zero 587 characters between double quotes), as {0} followed by CRLF (a 588 synchronizing literal with an octet count of 0), or as {0+} followed 589 by a CRLF (a non-synchronizing literal with an octet count of 0). 591 Note: Even if the octet count is 0, a client transmitting a 592 synchronizing literal must wait to receive a command 593 continuation request. 595 Internet DRAFT ACAP August 1997 597 2.6.3.1. 8-bit and Binary Strings 599 Most strings in ACAP are restricted to UTF-8 characters and may not 600 contain NUL octets. Attribute values MAY contain any octets 601 including NUL. 603 2.6.4. Parenthesized List 605 Data structures are represented as a "parenthesized list"; a sequence 606 of data items, delimited by space, and bounded at each end by 607 parentheses. A parenthesized list can contain other parenthesized 608 lists, using multiple levels of parentheses to indicate nesting. 610 The empty list is represented as () -- a parenthesized list with no 611 members. 613 2.6.5. NIL 615 The special atom "NIL" represents the non-existence of a particular 616 data item that is represented as a string or parenthesized list, as 617 distinct from the empty string "" or the empty parenthesized list (). 619 3. Protocol Elements 621 This section defines data formats and other protocol elements used 622 throughout the ACAP protocol. 624 3.1. Entries and Attributes 626 Within a dataset, each entry name is made up of zero or more UTF-8 627 characters other than slash ("/"). A slash separated list of 628 entries, one at each level of the hierarchy, forms the full path to 629 an entry. 631 Each entry is made up of a set of attributes. Each attribute has a 632 hierarchical name in UTF-8, with each component of the name separated 633 by a period ("."). 635 The value of an attribute is either single or multi-valued. A single 636 value is NIL (has no value), or a string of zero or more octets. A 637 multi-value is a list of zero or more strings, each of zero or more 638 octets. 640 Attribute names are not permitted to contain asterisk ("*") or 641 percent ("%") and MUST be valid UTF-8 strings which do not contain 642 NUL. Invalid attribute names result in a BAD response. Entry names 643 are not permitted to begin with "." or contain slash ("/") and MUST 644 be valid UTF-8 strings which do not contain NUL. Invalid entry names 646 Internet DRAFT ACAP August 1997 648 in the entry field of a command result in a BAD response. 650 Use of non-visible UTF-8 characters in attribute and entry names is 651 discouraged. 653 3.1.1. Predefined Attributes 655 Attribute names which do not contain a dot (".") are reserved for 656 standardized attributes which have meaning in any dataset. The 657 following attributes are defined by the ACAP protocol. 659 entry 660 Contains the name of the entry. MUST be single valued. 661 Attempts to use illegal or multi-valued values for the entry 662 attribute are protocol errors and MUST result in a BAD 663 completion response. This is a special case. 665 modtime 666 Contains the date and time any read-write metadata in the entry 667 was last modified. This value MUST be in UTC, MUST be 668 automatically updated by the server. 670 The value consists of 14 or more US-ASCII digits. The first 671 four indicate the year, the next two indicate the month, the 672 next two indicate the day of month, the next two indicate the 673 hour (0 - 23), the next two indicate the minute, and the next 674 two indicate the second. Any further digits indicate fractions 675 of a second. 677 The time, particularly fractions of a second, need not be 678 accurate. It is REQUIRED, however, that any two entries in a 679 dataset changed by successive modifications have strictly 680 ascending modtime values. In addition, each STORE command 681 within a dataset (including simultaneous stores from different 682 connections) MUST use different modtime values. 684 This attribute has enforced validation, so any attempt to STORE 685 a value in this attribute MAY result in a NO response with an 686 INVALID response code. 688 subdataset 689 If this attribute is set, it indicates the existence of a sub- 690 dataset of this entry. 692 The value consists of a list of relative ACAP URLs (see section 693 3.2) which may be used to locate the sub-dataset. The base URL 694 is the full path to the entry followed by a slash ("/"). The 695 value "." indicates a subdataset is located directly under this 697 Internet DRAFT ACAP August 1997 699 one. Multiple values indicate replicated copies of the 700 subdataset. 702 For example, if the dataset "/folder/site/" has an entry 703 "public-folder" with a subdataset attribute of ".", then there 704 exists a dataset "/folder/site/public-folder/". If the value of 705 the subdataset attribute was instead 706 "//other.acap.domain//folder/site/public-folder/", that would 707 indicate the dataset is actually located on a different ACAP 708 server. 710 A dataset can be created by storing a "subdataset" attribute 711 including ".", and a sub-hierarchy of datasets is deleted by 712 storing a NIL value to the "subdataset" attribute on the entry 713 in the parent dataset. 715 This attribute has enforced syntax validation. Specifically, if 716 an attempt is made to STORE a non-list value (other than NIL), 717 an empty list, or one of the values does not follow the URL 718 syntax rules [BASIC-URL, REL-URL], then this will result in a NO 719 response with an INVALID response code. 721 3.1.2. Attribute Metadata 723 Each attribute is made up of metadata items which describe that 724 attribute, its value and any associated access controls. Metadata 725 items may be either read-only, in which case the client is never 726 permitted to modify the item, or read-write, in which case the client 727 may modify the item if the access control list (ACL) permits. 729 The following metadata items are defined in this specification: 731 acl The access control list for the attribute, if one exists. If 732 the attribute does not have an ACL, NIL is returned. 733 Read-write. See section 3.5 for the contents of an ACL. 735 attribute 736 The attribute name. Read-only. 738 myrights 739 The set of rights that the client has to the attribute. 740 Read-only. See section 3.5 for the possible rights. 742 size This is the length of the value. In the case of a 743 multi-value, this is a list of lengths for each of the values. 744 Read-only. 746 Internet DRAFT ACAP August 1997 748 value The value. For a multi-value, this is a list of single 749 values. Read-write. 751 Additional items of metadata may be defined in extensions to this 752 protocol. Servers MUST respond to unrecognized metadata by returning 753 a BAD command completion result. 755 3.2. ACAP URL scheme 757 ACAP URLs are used within the ACAP protocol for the "subdataset" 758 attribute, referrals and inheritance. They provide a convenient 759 syntax for referring to other ACAP datasets. The ACAP URL follows 760 the common Internet scheme syntax as defined in [BASIC-URL] except 761 that plaintext passwords are not permitted. If : is omitted, 762 the port defaults to 674. 764 An ACAP URL has the following general form: 766 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 767 [url-extension] 769 The element includes the hostname, and optional user 770 name, authentication mechanism and port number. The 771 element contains the name of an entry path encoded according to the 772 rules in [BASIC-URL]. 774 The element is an optional list of interesting attribute 775 names. If omitted, the URL refers to all attributes of the named 776 entry. The element is reserved for extensions to 777 this URL scheme. 779 Note that unsafe or reserved characters such as " " or "?" MUST be 780 hex encoded as described in the URL specification [BASIC-URL]. Hex 781 encoded octets are interpreted according to UTF-8 [UTF8]. 783 3.2.1. ACAP URL User Name and Authentication Mechanism 785 A user name and/or authentication mechanism may be supplied. They 786 are used in the "AUTHENTICATE" command after making the connection to 787 the ACAP server. If no user name or authentication mechanism is 788 supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by 789 default. If an authentication mechanism is supplied without a user 790 name, then one SHOULD be obtained from the specified mechanism or 791 requested from the user as appropriate. If a user name is supplied 792 without an authentication mechanism then ";AUTH=*" is assumed. 794 The ";AUTH=" authentication parameter is interpreted as described in 795 the IMAP URL Scheme [IMAP-URL]. 797 Internet DRAFT ACAP August 1997 799 Note that if unsafe or reserved characters such as " " or ";" are 800 present in the user name or authentication mechanism, they MUST be 801 encoded as described in the URL specification [BASIC-URL]. 803 3.2.2. Relative ACAP URLs 805 Because ACAP uses "/" as the hierarchy separator for dataset paths, 806 it works well with the relative URL rules defined in the relative URL 807 specification [REL-URL]. 809 The grammar element is considered part of the user name for 810 purposes of resolving relative ACAP URLs. 812 The base URL for a relative URL stored in an attribute's value is 813 formed by taking the path to the dataset containing that attribute, 814 appending a "/" followed by the entry name of the entry containing 815 that attribute followed by "/". 817 3.3. Contexts 819 A context is subset of entries in a dataset or datasets, created by a 820 SEARCH command with a MAKECONTEXT modifier. Context names are 821 client-generated strings and must not start with the slash ('/') 822 character. 824 When a client creates a context, it may request automatic 825 notification of changes. A client may also request enumeration of 826 entries within a context. Enumeration simplifies the implementation 827 of a "virtual scrollbar" by the client. 829 A context exists only within the ACAP session in which it was 830 created. When the connection is closed, all contexts associated with 831 that connection are automatically discarded. A server is required to 832 support at least 100 active contexts within a session. If the server 833 supports a larger limit it must advertise it in a CONTEXTLIMIT 834 capability. 836 3.4. Comparators 838 A comparator is a named function which takes two input values and can 839 be used to perform one or more of four comparison operations: 840 ordering, equality, prefix and substring matching. 842 The ordering operation is used both for the SORT search modifier and 843 the COMPARE and COMPARESTRICT search keys. Ordering comparators can 844 determine the ordinal precedence of any two values. When used for 845 ordering, a comparator's name can be prefixed with "+" or "-" to 846 indicate that the ordering should be normal order or reversed order 848 Internet DRAFT ACAP August 1997 850 respectively. If no prefix is included, "+" is assumed. 852 For the purpose of ordering, a comparator may designate certain 853 values as having an undefined ordinal precedence. Such values always 854 collate with equal value after all other values regardless of whether 855 normal or reversed ordering is used. Unless the comparator 856 definition specifies otherwise, multi-values and NIL values have an 857 undefined ordinal precedence. 859 The equality operation is used for the EQUAL search modifier, and 860 simply determines if the two values are considered equal under the 861 comparator function. When comparing a single value to a multi-value, 862 the two are considered equal if any one of the multiple values is 863 equal to the single value. 865 The prefix match operation is used for the PREFIX search modifier, 866 and simply determines if the search value is a prefix of the item 867 being searched. In the case of prefix search on a multi-value, the 868 match is successful if the value is a prefix of any one of the 869 multiple values. 871 The substring match operation is used for the SUBSTRING search 872 modifier, and simply determines if search value is a substring of the 873 item being searched. In the case of substring search on a multi- 874 value, the match is successful if the value is a substring of any one 875 of the multiple values. 877 Rules for naming and registering comparators will be defined in a 878 future specification. Servers MUST respond to unknown or improperly 879 used comparators with a BAD command completion result. 881 The following comparators are defined by this standard and MUST be 882 implemented: 884 i;octet 885 Operations: Ordering, Equality, Prefix match, Substring match 887 For collation, the i;octet comparator interprets the value of 888 an attribute as a series of unsigned octets with ordinal 889 values from 0 to 255. When ordering two strings, each octet 890 pair is compared in sequence until the octets are unequal or 891 the end of the string is reached. When collating two strings 892 where the shorter is a prefix of the longer, the shorter 893 string is interpreted as having a smaller ordinal value. The 894 "i;octet" or "+i;octet" forms collate smaller ordinal values 895 earlier, and the "-i;octet" form collates larger ordinal 896 values earlier. 898 Internet DRAFT ACAP August 1997 900 For the equality function, two strings are equal if they are 901 the same length and contain the same octets in the same 902 order. NIL is equal only to itself. 904 For non-binary, non-nil single values, i;octet ordering is 905 equivalent to the ANSI C [ISO-C] strcmp() function applied to 906 C string representations of the values. For non-binary, 907 non-nil single values, i;octet substring match is equivalent 908 to the ANSI C strstr() function applied to the C string 909 representations of the values. 911 i;ascii-casemap 912 Operations: Ordering, Equality, Prefix match, Substring match 914 The i;ascii-casemap comparator first applies a mapping to the 915 attribute values which translates all US-ASCII letters to 916 uppercase (octet values 0x61 to 0x7A are translated to octet 917 values 0x41 to 0x5A respectively), then applies the i;octet 918 comparator as described above. With this function the values 919 "hello" and "HELLO" have the same ordinal value and are 920 considered equal. 922 i;ascii-numeric 923 Operations: Ordering, Equality 925 The i;ascii-numeric comparator interprets strings as decimal 926 positive integers represented as US-ASCII digits. All values 927 which do not begin with a US-ASCII digit are considered equal 928 with an ordinal value higher than all non-NIL single-valued 929 attributes. Otherwise, all US-ASCII digits (octet values 930 0x30 to 0x39) are interpreted starting from the beginning of 931 the string to the first non-digit or the end of the string. 933 3.5. Access Control Lists (ACLs) 935 An access control list is a set of identifier, rights pairs used to 936 restrict access to a given dataset, attribute or attribute within an 937 entry. An ACL is represented by a multi-value with each value 938 containing an identifier followed by a tab character followed by the 939 rights. The syntax is defined by the "acl" rule in the formal syntax 940 in section 8. 942 Identifier is a UTF-8 string. The identifier "anyone" is reserved to 943 refer to the universal identity (all authentications, including 944 anonymous). All user name strings accepted by the AUTHENTICATE 945 command to authenticate to the ACAP server are reserved as 946 identifiers for the corresponding user. Identifiers starting with a 948 Internet DRAFT ACAP August 1997 950 slash ("/") character are reserved for authorization groups which 951 will be defined in a future specification. Identifiers MAY be 952 prefixed with a dash ("-") to indicate a revocation of rights. All 953 other identifiers have implementation-defined meanings. 955 Rights is a string listing a (possibly empty) set of alphanumeric 956 characters, each character listing a set of operations which is being 957 controlled. Letters are reserved for "standard" rights, listed 958 below. The set of standard rights may only be extended by a 959 standards-track or IESG approved experimental RFC. Digits are 960 reserved for implementation or site defined rights. The currently 961 defined standard rights are: 963 x - search (use EQUAL search key with i;octet comparator) 964 r - read (access with SEARCH command) 965 w - write (modify with STORE command) 966 i - insert (perform STORE on a previously NIL value) 967 a - administer (perform SETACL or STORE on ACL attribute/metadata) 969 An implementation may force rights to always or never be granted. In 970 particular, implementations are expected to grant implicit read and 971 administer rights to a user's personal dataset storage in order to 972 avoid denial of service problems. Rights are never tied, unlike the 973 IMAP ACL extension [IMAP-ACL]. 975 It is possible for multiple identifiers in an access control list to 976 apply to a given user (or other authentication identity). For 977 example, an ACL may include rights to be granted to the identifier 978 matching the user, one or more implementation-defined identifiers 979 matching groups which include the user, and/or the identifier 980 "anyone". These rights are combined by taking the union of all 981 positive rights which apply to a given user and subtracting the union 982 of all negative rights which apply to that user. A client MAY avoid 983 this calculation by using the MYRIGHTS command and metadata items. 985 Each attribute of each entry of a dataset may potentially have an 986 ACL. If an attribute in an entry does not have an ACL, then access 987 is controlled by a default ACL for that attribute in the dataset, if 988 it exists. If there is no default ACL for that attribute in the 989 dataset, access is controlled by a default ACL for that dataset. The 990 default ACL for a dataset must exist. 992 In order to perform any access or manipulation on an entry in a 993 dataset, the client must have 'r' rights on the "entry" attribute of 994 the entry. Implementations should take care not to reveal via error 995 messages the existence of an entry for which the client does not have 996 'r' rights. A client does not need access to the "subdataset" 997 attribute of the parent dataset in order to access the contents of a 999 Internet DRAFT ACAP August 1997 1001 dataset. 1003 Many of the ACL commands and responses include an "acl object" 1004 parameter, for specifying what the ACL applies to. This is a 1005 parenthesized list. The list contains just the dataset name when 1006 referring to the default ACL for a dataset. The list contains a 1007 dataset name and an attribute name when referring to the default ACL 1008 for an attribute in a dataset. The list contains a dataset name, an 1009 attribute name, and an entry name when referring to the ACL for an 1010 attribute of an entry of a dataset. 1012 3.6. Server Response Codes 1014 An OK, NO, BAD, ALERT or BYE response from the server MAY contain a 1015 response code to describe the event in a more detailed machine 1016 parsable fashion. A response code consists of data inside 1017 parentheses in the form of an atom, possibly followed by a space and 1018 arguments. Response codes are defined when there is a specific 1019 action that a client can take based upon the additional information. 1020 In order to support future extension, the response code is 1021 represented as a slash-separated hierarchy with each level of 1022 hierarchy representing increasing detail about the error. Clients 1023 MUST tolerate additional hierarchical response code detail which they 1024 don't understand. 1026 The currently defined response codes are: 1028 AUTH-TOO-WEAK 1029 This response code is returned on a tagged NO result from an 1030 AUTHENTICATE command. It indicates that site security policy 1031 forbids the use of the requested mechanism for the specified 1032 authentication identity. 1034 ENCRYPT-NEEDED 1035 This response code is returned on a tagged NO result from an 1036 AUTHENTICATE command. It indicates that site security policy 1037 requires the use of a strong encryption mechanism for the 1038 specified authentication identity and mechanism. 1040 INVALID 1041 This response code indicates that a STORE command included 1042 data which the server implementation does not permit. It 1043 MUST NOT be used unless the dataset class specification for 1044 the attribute in question explicitly permits enforced server 1046 Internet DRAFT ACAP August 1997 1048 validation. The argument is the attribute which was invalid. 1050 MODIFIED 1051 This response code indicates that a conditional store failed 1052 because the modtime on the entry is later than the modtime 1053 specified with the STORE command UNCHANGEDSINCE modifier. 1054 The argument is the entry which had been modified. 1056 NOEXIST 1057 This response code indicates that a search or NOCREATE store 1058 failed because a specified dataset did not exist. The 1059 argument is the dataset which does not exist. 1061 PERMISSION 1062 A command failed due to insufficient permission based on the 1063 access control list or implicit rights. The argument is the 1064 acl-object which caused the permission failure. 1066 QUOTA 1067 A STORE or SETACL command which would have increased the size 1068 of the dataset failed due to insufficient quota. 1070 REFER 1071 This response code may be returned in a tagged NO response to 1072 any command that takes a dataset name as a parameter. It has 1073 one or more arguments with the syntax of relative URLs. It 1074 is a referral, indicating that the command should be retried 1075 using one of the relative URLs. 1077 SASL This response code can occur in the tagged OK response to a 1078 successful AUTHENTICATE command and includes the optional 1079 final server response data from the server as specified by 1080 SASL [SASL]. 1082 TOOMANY 1083 This response code may be returned in a tagged OK response to 1084 a SEARCH command which includes the LIMIT modifier. The 1085 argument returns the total number of matching entries. 1087 TOOOLD 1088 The modtime specified in the DELETEDSINCE command is too old, 1089 so deletedsince information is no longer available. 1091 TRANSITION-NEEDED 1092 This response code occurs on a NO response to an AUTHENTICATE 1093 command. It indicates that the user name is valid, but the 1094 entry in the authentication database needs to be updated in 1095 order to permit authentication with the specified mechanism. 1097 Internet DRAFT ACAP August 1997 1099 This can happen if a user has an entry in a system 1100 authentication database such as Unix /etc/passwd, but does 1101 not have credentials suitable for use by the specified 1102 mechanism. 1104 TRYLATER 1105 A command failed due to a temporary server failure. The 1106 client MAY continue using local information and try the 1107 command later. 1109 TRYFREECONTEXT 1110 This response code may be returned in a tagged NO response to 1111 a SEARCH command which includes the MAKECONTEXT modifier. It 1112 indicates that a new context may not be created due to the 1113 server's limit on the number of existing contexts. 1115 WAYTOOMANY 1116 This response code may be returned in a tagged NO response to 1117 a SEARCH command which includes a HARDLIMIT search modifier. 1118 It indicates that the SEARCH would have returned more entries 1119 than the HARDLIMIT permitted. 1121 Additional response codes MUST be registered with IANA according 1122 to the proceedures in section 7.2. Client implementations MUST 1123 tolerate response codes that they do not recognize. 1125 4. Namespace Conventions 1127 4.1. Dataset Namespace 1129 The dataset namespace is a slash-separated hierarchy. The first 1130 component of the dataset namespace is a dataset class. Dataset 1131 classes MUST have a vendor prefix (vendor.) or be 1132 specified in a standards track or IESG approved experimental RFC. 1133 See section 7.3 for the registration template. 1135 The second component of the dataset name is "site", "group", "host", 1136 or "user" referring to server-wide data, administrative group data, 1137 per-host data and per-user data respectively. 1139 For "group", "host", and "user" areas, the third component of the 1140 path is the group name, the fully qualified host domain name, or the 1141 user name. A path of the form "//~/" is a convenient 1142 abbreviation for "//user//". 1144 Dataset names which begin with "/byowner/" are reserved as an 1145 alternate view of the namespace. This provides a way to see all the 1146 dataset classes which a particular owner uses. For example, 1148 Internet DRAFT ACAP August 1997 1150 "/byowner/~//" is an alternate name for 1151 "//~/". Byowner provides a way to view a list of 1152 dataset classes owned by a given user; this is done using the dataset 1153 "/byowner/user//" with the NOINHERIT SEARCH modifier. 1155 The dataset "/" may be used to find all dataset classes visible to 1156 the current user. A dataset of the form "//user/" may 1157 be used to find all users which have made a dataset or entry of that 1158 class visible to the current user. 1160 The formal syntax for a dataset name is defined by the "dataset-name" 1161 rule in section 4.3. 1163 4.2. Attribute Namespace 1165 Attribute names which do not contain a dot (".") are reserved for 1166 standardized attributes which have meaning in any dataset. In order 1167 to simplify client implementations, the attribute namespace is 1168 intended to be unique across all datasets. To achieve this, 1169 attribute names are prefixed with the dataset class name followed by 1170 a dot ("."). Attributes which affect management of the dataset are 1171 prefixed with "dataset.". In addition, a subtree of the "vendor." 1172 attribute namespace may be registered with IANA according to the 1173 rules in section 7.4. ACAP implementors are encouraged to help 1174 define interoperable dataset classes specifications rather than using 1175 the private attribute namespace. 1177 Some users or sites may wish to add their own private attributes to 1178 certain dataset classes. In order to enable this, the "user.." and "site." subtrees of the attribute namespace are reserved 1180 for user-specific and site-specific attributes respectively and will 1181 not be standardized. Such attributes are not interoperable so are 1182 discouraged in favor of defining standard attributes. A future 1183 extension is expected to permit discovery of syntax for user or 1184 site-specific attributes. Clients wishing to support display of user 1185 or site-specific attributes should display the value of any non-NIL 1186 single-valued "user.." or "site." attribute which has 1187 valid UTF-8 syntax. 1189 The formal syntax for an attribute name is defined by the 1190 "attribute-name" rule in the next section. 1192 Internet DRAFT ACAP August 1997 1194 4.3. Formal Syntax for Dataset and Attribute Namespace 1196 The naming conventions for datasets and attributes are defined by the 1197 following ABNF. Note that this grammar is not part of the ACAP 1198 protocol syntax in section 8, as dataset names and attribute names 1199 are encoded as strings within the ACAP protocol. 1201 attribute-dacl = "dataset.acl" *("." name-component) 1203 attribute-dset = dataset-std 1*("." name-component) 1204 ;; MUST be defined in a dataset class specification 1206 attribute-name = attribute-std / attr-site / attr-user / vendor-name 1208 attribute-std = "entry" / "subdataset" / "modtime" / "dataset.inherit" 1209 / attribute-dacl / attribute-dset 1211 attr-site = "site" 1*("." name-component) 1213 attr-user = "user." name-component 1*("." name-component) 1215 byowner = "/byowner/" owner "/" [dataset-class "/" dataset-sub] 1217 dataset-class = dataset-std / vendor-name 1219 dataset-normal = "/" [dataset-class "/" (owner-prefix / dataset-tail)] 1221 dataset-name = byowner / dataset-normal 1223 dataset-std = name-component 1224 ;; MUST be registered with IANA and the spec MUST 1225 ;; be published as a standards track or 1226 ;; IESG-approved experimental RFC 1228 dataset-sub = *(dname-component "/") 1229 ;; The rules for this portion of the namespace may 1230 ;; be further restricted by the dataset class 1231 ;; specification. 1233 dataset-tail = owner "/" dataset-sub 1235 dname-component = 1*UTF8-CHAR 1236 ;; MUST NOT begin with "." or contain "/" 1238 name-component = 1*UTF8-CHAR 1239 ;; MUST NOT contain ".", "/", "%", or "*" 1241 owner = "site" / owner-host / owner-group / owner-user / "~" 1243 Internet DRAFT ACAP August 1997 1245 owner-group = "group/" dname-component 1247 owner-host = "host/" dname-component 1249 owner-prefix = "group/" / "host/" / "user/" 1251 owner-user = "user/" dname-component 1253 vendor-name = vendor-token *("." name-component) 1255 vendor-token = "vendor." name-component 1256 ;; MUST be registered with IANA 1258 5. Dataset Management 1260 The entry with an empty name ("") in the dataset is used to hold 1261 management information for the dataset as a whole. 1263 5.1. Dataset Inheritance 1265 It is possible for one dataset to inherit data from another. The 1266 dataset from which the data is inherited is called the base dataset. 1267 Data in the base dataset appears in the inheriting dataset, except 1268 when overridden by a STORE to the inheriting dataset. 1270 The base dataset is usually a system-wide or group-wide set of 1271 defaults. A system-wide dataset usually has one inheriting dataset 1272 per user, allowing each user to add to or modify the defaults as 1273 appropriate. 1275 An entry which exists in both the inheriting and base dataset 1276 inherits a modtime equal to the greater of the two modtimes. An 1277 attribute in such an entry is inherited from the base dataset if it 1278 was never modified by a STORE command in the inheriting dataset or if 1279 DEFAULT was stored to that attribute. This permits default entries 1280 to be amended rather than replaced in the inheriting dataset. 1282 The "subdataset" attribute is not directly inherited. If the base 1283 dataset includes a "subdataset" attribute and the inheriting dataset 1284 does not, then the "subdataset" attribute will inherit a virtual 1285 value of a list containing a ".". The subdataset at that node is 1286 said to be a "virtual" dataset as it is simply a virtual copy of the 1287 appropriate base dataset with all "subdataset" attributes changed to 1288 a list containing a ".". A virtual dataset is not visible if 1289 NOINHERIT is specified on the SEARCH command. 1291 Servers MUST support at least two levels of inheritance. This 1292 permits a user's dataset such as "/options/user/fred/common" to 1294 Internet DRAFT ACAP August 1997 1296 inherit from a group dataset such as "/options/group/dinosaur 1297 operators/common" which in turn inherits from a server-wide dataset 1298 such as "/options/site/common". 1300 5.2. Dataset Attributes 1302 The following attributes apply to management of the dataset when 1303 stored in the "" entry of a dataset. These attributes are not 1304 inherited. 1306 dataset.acl 1307 This holds the default access control list for the dataset. 1308 This attribute is validated, so an invalid access control list 1309 in a STORE command will result in a NO response with an INVALID 1310 response code. 1312 dataset.acl. 1313 This holds the default access control list for an attribute 1314 within the dataset. This attribute is validated, so an invalid 1315 access control list in a STORE command will result in a NO 1316 response with an INVALID response code. 1318 dataset.inherit 1319 This holds the name of a dataset from which to inherit according 1320 to the rules in the previous section. This attribute MAY refer 1321 to a non-existent dataset, in which case nothing is inherited. 1322 This attribute is validated, so illegal dataset syntax or an 1323 attempt to store a multi-value will result in a NO response with 1324 an INVALID response code. 1326 5.3. Dataset Creation 1328 When a dataset is first created (by storing a "." in the subdataset 1329 attribute or storing an entry in a previously non-existent dataset), 1330 the dataset attributes are initialized with the values from the 1331 parent dataset in the "/byowner/" hierarchy. In the case of the 1332 "dataset.inherit" attribute, the appropriate hierarchy component is 1333 added. For example, given the following entry (note that \t refers 1334 to the US-ASCII horizontal tab character): 1336 entry path "/byowner/user/joe/" 1337 dataset.acl ("joe\txrwia" "fred\txr") 1338 dataset.inherit "/byowner/site" 1340 If a new dataset class "/byowner/user/joe/new" is created, it will 1341 have the following dataset attributes: 1343 entry path "/byowner/user/joe/new/" 1345 Internet DRAFT ACAP August 1997 1347 dataset.acl ("joe\txrwia" "fred\txr") 1348 dataset.inherit "/byowner/site/new" 1350 Note that the dataset "/byowner/user/joe/new/" is equivalent to 1351 "/new/user/joe/". 1353 5.4. Dataset Class Capabilities 1355 Certain dataset classes or dataset class features may only be useful 1356 if there is an active updating client or integrated server support 1357 for the feature. The dataset class "capability" is reserved to allow 1358 clients or servers to advertise such features. The "entry" attribute 1359 within this dataset class is the name of the dataset class whose 1360 features are being described. The attributes are prefixed with 1361 "capability.." and are defined by the appropriate 1362 dataset class specification. 1364 Since it is possible for an unprivileged user to run an active client 1365 for himself, a per-user capability dataset is useful. The dataset 1366 "/capability/~/" holds information about all features available to 1367 the user (via inheritance), and the dataset "/capability/site/" holds 1368 information about all features supported by the site. 1370 5.5. Dataset Quotas 1372 Management and scope of quotas is implementation dependent. Clients 1373 can check the applicable quota limit and usage (in bytes) with the 1374 GETQUOTA command. Servers can notify the client of a low quota 1375 situation with the QUOTA untagged response. 1377 6. Command and Response Specifications 1379 ACAP commands and responses are described in this section. Commands 1380 are organized first by the state in which the command is permitted, 1381 then by a general category of command type. 1383 Command arguments, identified by "Arguments:" in the command 1384 descriptions below, are described by function, not by syntax. The 1385 precise syntax of command arguments is described in the Formal Syntax 1386 section. 1388 Some commands cause specific server data to be returned; these are 1389 identified by "Data:" in the command descriptions below. See the 1390 response descriptions in the Responses section for information on 1391 these responses, and the Formal Syntax section for the precise syntax 1392 of these responses. It is possible for server data to be transmitted 1393 as a result of any command; thus, commands that do not specifically 1394 require server data specify "no specific data for this command" 1396 Internet DRAFT ACAP August 1997 1398 instead of "none". 1400 The "Result:" in the command description refers to the possible 1401 tagged status responses to a command, and any special interpretation 1402 of these status responses. 1404 6.1. Initial Connection 1406 Upon session startup, the server sends one of two untagged responses: 1407 ACAP or BYE. The untagged BYE response is described in section 1408 6.2.8. 1410 6.1.1. ACAP Untagged Response 1412 Data: capability list 1414 The untagged ACAP response indicates the session is ready to 1415 accept commands and contains a space-separated listing of 1416 capabilities that the server supports. Each capability is 1417 represented by a list containing the capability name optionally 1418 followed by capability specific string arguments. 1420 ACAP capability names MUST be defined in a standards track or IESG 1421 approved experimental RFC and registered with IANA according to 1422 the rules in section 7.1. 1424 Client implementations SHOULD NOT require any capability name 1425 beyond those defined in this specification, and MUST tolerate any 1426 unknown capability names. A client implementation MAY be 1427 configurable to require SASL mechanisms other than CRAM-MD5 1428 [CRAM-MD5] for site security policy reasons. 1430 The following initial capabilities are defined: 1432 CONTEXTLIMIT 1433 The CONTEXTLIMIT capability has one argument which is a 1434 number describing the maximum number of contexts the server 1435 supports per connection. The number 0 indicates the server 1436 has no limit, otherwise this number MUST be greater than 1437 100. 1439 IMPLEMENTATION 1440 The IMPLEMENTATION capability has one argument which is a 1441 string describing the server implementation. ACAP clients 1442 MUST NOT alter their behavior based on this value. It is 1444 Internet DRAFT ACAP August 1997 1446 intended primarily for debugging purposes. 1448 SASL The SASL capability includes a list of the authentication 1449 mechanisms supported by the server. See section 6.3.1. 1451 Example: S: * ACAP (IMPLEMENTATION "ACME v3.5") 1452 (SASL "CRAM-MD5") (CONTEXTLIMIT "200") 1454 6.2. Any State 1456 The following commands and responses are valid in any state. 1458 6.2.1. NOOP Command 1460 Arguments: none 1462 Data: no specific data for this command (but see below) 1464 Result: OK - noop completed 1465 BAD - command unknown or arguments invalid 1467 The NOOP command always succeeds. It does nothing. It can be 1468 used to reset any inactivity auto-logout timer on the server. 1470 Example: C: a002 NOOP 1471 S: a002 OK "NOOP completed" 1473 6.2.2. LANG Command 1475 Arguments: list of language preferences 1477 Data: intermediate response: LANG 1479 Result: OK - lang completed 1480 NO - no matching language available 1481 BAD - command unknown or arguments invalid 1483 One or more arguments are supplied to indicate the client's 1484 preferred languages for error messages. The server will match 1485 each client preference in order against its internal table of 1486 available error string languages. For a client preference to 1487 match a server language, the client's language tag MUST be a 1488 prefix of the server's tag and match up to a "-" or the end of 1489 string. If a match is found, the server returns an intermediate 1490 LANG response and an OK response. The LANG response indicates the 1491 actual language selected and appropriate comparators for use with 1493 Internet DRAFT ACAP August 1997 1495 the languages listed in the LANG command. 1497 If no LANG command is issued, all error text strings MUST be in 1498 English intended for an international audience. This rule is 1499 necessary because the default error text has to be in a language 1500 which is most likely to be useful to any pair of client and server 1501 vendors (since both have to diagnose problems). In addition, the 1502 default language for errors has to use the US-ASCII subset of 1503 UTF-8, since it can be displayed on the largest number of 1504 computers. Explicitly negotiating "en" is the same as the default 1505 language, but MAY be different from explicitly negotiating "en-US" 1506 or "en-UK". 1508 Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" 1509 C: A003 LANG "fr-ca" "i;octet" "i;ascii-numeric" 1510 "i;ascii-casemap" "en;primary" "fr;primary" 1511 S: A003 OK "Bonjour" 1513 6.2.3. LANG Intermediate Response 1515 Data: language for error responses 1516 appropriate comparators 1518 The LANG response indicates the language which will be used for 1519 error responses and the comparators which are appropriate for the 1520 languages listed in the LANG command. The comparators SHOULD be 1521 in approximate order from most efficient (usually "i;octet") to 1522 most appropriate for human text in the preferred language. 1524 6.2.4. LOGOUT Command 1526 Arguments: none 1528 Data: mandatory untagged response: BYE 1530 Result: OK - logout completed 1531 BAD - command unknown or arguments invalid 1533 The LOGOUT command informs the server that the client is done with 1534 the session. The server must send a BYE untagged response before 1535 the (tagged) OK response, and then close the network connection. 1537 Example: C: A023 LOGOUT 1538 S: * BYE "ACAP Server logging out" 1539 S: A023 OK "LOGOUT completed" 1540 (Server and client then close the connection) 1542 Internet DRAFT ACAP August 1997 1544 6.2.5. OK Response 1546 Data: optional response code 1547 human-readable text 1549 The OK response indicates an information message from the server. 1550 When tagged, it indicates successful completion of the associated 1551 command. The human-readable text may be presented to the user as 1552 an information message. The untagged form indicates an 1553 information-only message; the nature of the information MAY be 1554 indicated by a response code. 1556 Example: S: * OK "Master ACAP server is back up" 1558 6.2.6. NO Response 1560 Data: optional response code 1561 human-readable text 1563 The NO response indicates an operational error message from the 1564 server. When tagged, it indicates unsuccessful completion of the 1565 associated command. The untagged form indicates a warning; the 1566 command may still complete successfully. The human-readable text 1567 describes the condition. 1569 Example: C: A010 SEARCH "/addressbook/" DEPTH 3 RETURN ("*") 1570 EQUAL "entry" "+i;octet" "bozo" 1571 S: * NO "Master ACAP server is down, your data may 1572 be out of date." 1573 S: A010 OK "search done" 1574 ... 1575 C: A222 STORE ("/folder/site/comp.mail.misc" 1576 "folder.creation-time" "19951206103412") 1577 S: A222 NO (PERMISSION ("/folder/site/")) "Permission 1578 denied" 1580 6.2.7. BAD Response 1582 Data: optional response code 1583 human-readable text 1585 The BAD response indicates an error message from the server. When 1586 tagged, it reports a protocol-level error in the client's command; 1587 the tag indicates the command that caused the error. The untagged 1588 form indicates a protocol-level error for which the associated 1589 command can not be determined; it may also indicate an internal 1591 Internet DRAFT ACAP August 1997 1593 server failure. The human-readable text describes the condition. 1595 Example: C: ...empty line... 1596 S: * BAD "Empty command line" 1597 C: A443 BLURDYBLOOP 1598 S: A443 BAD "Unknown command" 1599 C: A444 NOOP Hello 1600 S: A444 BAD "invalid arguments" 1602 6.2.8. BYE Untagged Response 1604 Data: optional response code 1605 human-readable text 1607 The untagged BYE response indicates that the server is about to 1608 close the connection. The human-readable text may be displayed to 1609 the user in a status report by the client. The BYE response may 1610 be sent as part of a normal logout sequence, or as a panic 1611 shutdown announcement by the server. It is also used by some 1612 server implementations as an announcement of an inactivity auto- 1613 logout. 1615 This response is also used as one of two possible greetings at 1616 session startup. It indicates that the server is not willing to 1617 accept a session from this client. 1619 Example: S: * BYE "Auto-logout; idle for too long" 1621 6.2.9. ALERT Untagged Response 1623 Data: optional response code 1624 human-readable text 1626 The human-readable text contains a special human generated alert 1627 message that MUST be presented to the user in a fashion that calls 1628 the user's attention to the message. This is intended to be used 1629 for vital messages from the server administrator to the user, such 1630 as a warning that the server will soon be shut down for 1631 maintenance. 1633 Example: S: * ALERT "This ACAP server will be shut down in 1634 10 minutes for system maintenance." 1636 Internet DRAFT ACAP August 1997 1638 6.3. Non-Authenticated State 1640 In non-authenticated state, the AUTHENTICATE command establishes 1641 authentication and enters authenticated state. The AUTHENTICATE 1642 command provides a general mechanism for a variety of authentication 1643 techniques. 1645 Server implementations may allow non-authenticated access to certain 1646 information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism. 1648 Once authenticated (including as anonymous), it is not possible to 1649 re-enter non-authenticated state. 1651 Only the any-state commands (NOOP, LANG and LOGOUT) and the 1652 AUTHENTICATE command are valid in non-authenticated state. 1654 6.3.1. AUTHENTICATE Command 1656 Arguments: SASL mechanism name 1657 optional initial response 1659 Data: continuation data may be requested 1661 Result: OK - authenticate completed, now in authenticated state 1662 NO - authenticate failure: unsupported authentication 1663 mechanism, credentials rejected 1664 BAD - command unknown or arguments invalid, 1665 authentication exchange cancelled 1667 The AUTHENTICATE command indicates a SASL [SASL] authentication 1668 mechanism to the server. If the server supports the requested 1669 authentication mechanism, it performs an authentication protocol 1670 exchange to authenticate and identify the user. Optionally, it 1671 also negotiates a security layer for subsequent protocol 1672 interactions. If the requested authentication mechanism is not 1673 supported, the server rejects the AUTHENTICATE command by sending 1674 a tagged NO response. 1676 The authentication protocol exchange consists of a series of 1677 server challenges and client answers that are specific to the 1678 authentication mechanism. A server challenge consists of a 1679 command continuation request with the "+" token followed by a 1680 string. The client answer consists of a line consisting of a 1681 string. If the client wishes to cancel an authentication 1682 exchange, it should issue a line with a single unquoted "*". If 1683 the server receives such an answer, it must reject the 1684 AUTHENTICATE command by sending a tagged BAD response. 1686 Internet DRAFT ACAP August 1997 1688 The optional initial-response argument to the AUTHENTICATE command 1689 is used to save a round trip when using authentication mechanisms 1690 that are defined to send no data in the initial challenge. When 1691 the initial-response argument is used with such a mechanism, the 1692 initial empty challenge is not sent to the client and the server 1693 uses the data in the initial-response argument as if it were sent 1694 in response to the empty challenge. If the initial-response 1695 argument to the AUTHENTICATE command is used with a mechanism that 1696 sends data in the initial challenge, the server rejects the 1697 AUTHENTICATE command by sending a tagged NO response. 1699 The service name specified by this protocol's profile of SASL is 1700 "acap". 1702 If a security layer is negotiated through the SASL authentication 1703 exchange, it takes effect immediately following the CRLF that 1704 concludes the authentication exchange for the client, and the CRLF 1705 of the tagged OK response for the server. 1707 All ACAP implementations MUST implement the CRAM-MD5 SASL 1708 mechanism [CRAM-MD5], although they MAY offer a configuration 1709 option to disable it if site security policy dictates. CRAM-MD5 1710 uses the HMAC-MD5 [HMAC] Keyed-Hashing construction. The example 1711 below is the same example described in the CRAM-MD5 specification. 1713 If an AUTHENTICATE command fails with a NO response, the client 1714 may try another authentication mechanism by issuing another 1715 AUTHENTICATE command. In other words, the client may request 1716 authentication types in decreasing order of preference. 1718 Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5") 1719 (SASL "CRAM-MD5" "KERBEROS_V4") 1720 C: A001 AUTHENTICATE "CRAM-MD5" 1721 S: + "<1896.697170952@postoffice.reston.mci.net>" 1722 C: "tim b913a602c7eda7a495b4e6e7334d3890" 1723 S: A001 OK "CRAM-MD5 authentication successful" 1725 6.4. Searching 1727 This section describes the SEARCH command, for retrieving data from 1728 datasets. 1730 Internet DRAFT ACAP August 1997 1732 6.4.1. SEARCH Command 1734 Arguments: dataset or context name 1735 optional list of modifiers 1736 search criteria 1738 Data: intermediate responses: ENTRY, MODTIME, REFER 1739 untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME 1741 Result: OK - search completed 1742 NO - search failure: can't perform search 1743 BAD - command unknown or arguments invalid 1745 The SEARCH command identifies a subset of entries in a dataset and 1746 returns information on that subset to the client. Inherited 1747 entries and attributes are included in the search unless the 1748 NOINHERIT search modifier is included or the user does not have 1749 permission to read the attributes in the base dataset. 1751 The first argument to SEARCH identifies what is to be searched. 1752 If the string begins with a slash ("/"), it is the name of a 1753 dataset to be searched, otherwise it is a name of a context that 1754 was created by a SEARCH command given previously in the session. 1756 A successful SEARCH command MAY result in intermediate ENTRY 1757 responses and MUST result in a MODTIME intermediate response. 1759 Following that are zero or more modifiers to the search. Each 1760 modifier may be specified at most once. The defined modifiers 1761 are: 1763 DEPTH number 1764 The SEARCH command will traverse the dataset tree up to the 1765 specified depth. ENTRY responses will include the full path 1766 to the entry. A value of "0" indicates that the search 1767 should traverse the entire tree. A value of "1" is the 1768 default and indicates only the specified dataset should be 1769 searched. If a dataset is traversed which is not located on 1770 the current server, then a REFER intermediate response is 1771 returned for that subtree and the search continues. 1773 HARDLIMIT number 1774 If the SEARCH command would result in more than number 1775 entries, the SEARCH fails with a NO completion result with a 1776 WAYTOOMANY response code. 1778 LIMIT number number 1779 Limits the number of intermediate ENTRY responses that the 1781 Internet DRAFT ACAP August 1997 1783 search may generate. The first numeric argument specifies 1784 the limit, the second number specifies the number of entries 1785 to return if the number of matches exceeds the limit. If the 1786 limit is exceeded, the SEARCH command still succeeds, 1787 returning the total number of matches in a TOOMANY response 1788 code in the tagged OK response. 1790 MAKECONTEXT [ENUMERATE] [NOTIFY] context 1791 Causes the SEARCH command to create a context with the name 1792 given in the argument to refer to the matching entries. If 1793 the SEARCH is successful, the context name may then be given 1794 as an argument to subsequent SEARCH commands to search the 1795 set of matching entries. If a context with the specified 1796 name already exists, it is first freed. If a new context may 1797 not be created due to the server's limit on the number of 1798 existing contexts, the command fails, returning a 1799 TRYFREECONTEXT response code in the NO completion response. 1801 The optional "ENUMERATE" and "NOTIFY" arguments may be 1802 included to request enumeration of the context (for virtual 1803 scroll bars) or change notifications for the context. If 1804 "NOTIFY" is not requested, the context represents a snapshot 1805 of the entries at the time the SEARCH was issued. 1807 ENUMERATE requests that the contents of the context be 1808 ordered according to the SORT modifier and that sequential 1809 numbers, starting with one, be assigned to the entries in the 1810 context. This permits the RANGE modifier to be used to fetch 1811 portions of the ordered context. 1813 NOTIFY requests that the server send untagged ADDTO, 1814 REMOVEFROM, CHANGE, and MODTIME responses while the context 1815 created by this SEARCH command exists. The server MAY issue 1816 untagged ADDTO, REMOVEFROM, CHANGE and MODTIME notifications 1817 for a context at any time between the issuing of the SEARCH 1818 command with MAKECONTEXT NOTIFY and the completion of a 1819 FREECONTEXT command for the context. Notifications are only 1820 issued for changes which occur after the server receives the 1821 SEARCH command which created the context. After issuing a 1822 sequence of ADDTO, REMOVEFROM or CHANGE notifications, the 1823 server MUST issue an untagged MODTIME notification indicating 1824 that the client has all updates to the entries in the context 1825 up to and including the given modtime value. Servers are 1826 permitted a reasonable delay to batch change notifications 1827 before sending them to the client. 1829 The position arguments of the ADDTO, REMOVEFROM and CHANGE 1831 Internet DRAFT ACAP August 1997 1833 notifications are 0 if ENUMERATE is not requested. 1835 NOINHERIT 1836 This causes the SEARCH command to operate without 1837 inheritance. It can be used to tell which values are 1838 explicit overrides. If MAKECONTEXT is also specified, the 1839 created context is also not affected by inheritance. 1841 RETURN (metadata...) 1842 Specifies what is to be returned in intermediate ENTRY 1843 responses. If this modifier is not specified, no 1844 intermediate ENTRY responses are returned. 1846 Inside the parentheses is an optional list of attributes, 1847 each optionally followed by a parenthesized list of metadata. 1848 If the parenthesized list of metadata is not specified, it 1849 defaults to "(value)". 1851 An attribute name with a trailing "*" requests all attributes 1852 with that prefix. A "*" by itself requests all attributes. 1853 If the parenthesized list of metadata is not specified for an 1854 attribute with a trailing "*", it defaults to "(attribute 1855 value)". Results matching such an attribute pattern are 1856 grouped in parentheses. 1858 Following the last intermediate ENTRY response, the server 1859 returns a single intermediate MODTIME response. 1861 SORT (attribute comparator ...) 1862 Specifies the order in which any resulting ENTRY replies are 1863 to be returned to the client. The SORT modifier takes as an 1864 argument a parenthesized list of one or more 1865 attribute/comparator pairs. Attribute lists the attribute to 1866 sort on, comparator specifies the name of the collation rule 1867 to apply to the values of the attribute. Successive 1868 attribute/comparator pairs are used to order two entries only 1869 when all preceding pairs indicate the two entries collate the 1870 same. 1872 If the SORT modifier is used in conjunction with the 1873 MAKECONTEXT modifier, the SORT modifier specifies the 1874 ordering of entries in the created context. 1876 If no SORT modifier is specified, or none of the 1877 attribute/comparator pairs indicates an order for the two 1878 entries, the server uses the order of the entries that exists 1879 in the context or dataset being searched. 1881 Internet DRAFT ACAP August 1997 1883 Following the modifiers is the search criteria. Searching 1884 criteria consist of one or more search keys. Search keys may be 1885 combined using the AND, and OR search keys. For example, the 1886 criteria (the newline is for readability and not part of the 1887 criteria): 1888 AND COMPARE "modtime" "+i;octet" "19951206103400" 1889 COMPARE "modtime" "-i;octet" "19960112000000" 1890 refers to all entries modified between 10:34 December 6 1995 and 1891 midnight January 12, 1996 UTC. 1893 The currently defined search keys are as follows. 1895 ALL This matches all entries. 1897 AND search-key1 search-key2 1898 Entries that match both search keys. 1900 COMPARE attribute comparator value 1901 Entries for which the value of the specified attribute 1902 collates using the specified comparator the same or later 1903 than the specified value. 1905 COMPARESTRICT attribute comparator value 1906 Entries for which the specified attribute collates using the 1907 specified comparator later than the specified value. 1909 EQUAL attribute comparator value 1910 Entries for which the value of the attribute is equal to the 1911 specified value using the specified comparator. 1913 NOT search-key 1914 Entries that do not match the specified search key. 1916 OR search-key1 search-key2 1917 Entries that match either search key. 1919 PREFIX attribute comparator value 1920 Entries which begin with the specified value using the 1921 specified comparator. If the specified comparator doesn't 1922 support substring matching, a BAD response is returned. 1924 RANGE start end time 1925 Entries which are within the specified range of the 1926 enumerated context's ordering. The lowest-ordered entry in 1927 the context is assigned number one, the next lowest entry is 1928 assigned number two, and so on. The numeric arguments 1929 specify the lowest and highest numbers to match. The time 1930 specifies that the client has processed notifications for the 1932 Internet DRAFT ACAP August 1997 1934 context up to the specified time. If the context has been 1935 modified since then, the server MUST either return a NO with 1936 a MODIFIED response code, or return the results that the 1937 SEARCH would have returned if none of the changes since that 1938 time had been made. 1940 RANGE is only permitted on enumerated contexts. If RANGE is 1941 used with a dataset or non-enumerated context, the server 1942 MUST return a BAD response. 1944 SUBSTRING attribute comparator value 1945 Entries which contain the specified value, using the 1946 specified comparator. If the specified comparator doesn't 1947 support substring matching, a BAD response is returned. 1949 6.4.2. ENTRY Intermediate Response 1951 Data: entry name 1952 entry data 1954 The ENTRY intermediate response occurs as a result of a SEARCH or 1955 STORE command. This is the means by which dataset entries are 1956 returned to the client. 1958 The ENTRY response begins with the entry name, if a SEARCH command 1959 without the DEPTH modifier was issued, or the entry path in other 1960 cases. This is followed by a set of zero or more items, one for 1961 each metadata item in the RETURN search modifier. Results 1962 matching an attribute pattern or returning multiple metadata items 1963 are grouped in parentheses. 1965 6.4.3. MODTIME Intermediate Response 1967 Data: modtime value 1969 The MODTIME intermediate response occurs as a result of a SEARCH 1970 command. It indicates that the just created context or the 1971 previously returned ENTRY responses include all updates to the 1972 returned entries up to and including the modtime value in the 1973 argument. 1975 6.4.4. REFER Intermediate Response 1977 Data: dataset path 1978 relative ACAP URLs 1980 Internet DRAFT ACAP August 1997 1982 The REFER intermediate response occurs as a result of a 1983 multi-level SEARCH where one of the levels is located on a 1984 different server. The response indicates the dataset which is not 1985 located on the current server and one or more relative ACAP URLs 1986 for where that dataset may be found. 1988 6.4.5. Search Examples 1990 Here are some SEARCH command exchanges between the client and server: 1992 C: A046 SEARCH "/addressbook/" DEPTH 3 RETURN ("addressbook.Alias" 1993 "addressbook.Email" "addressbook.List") OR NOT EQUAL 1994 "addressbook.Email" "i;octet" NIL NOT EQUAL "addressbook.List" 1995 "i;octet" NIL 1996 S: A046 ENTRY "/addressbook/user/joe/A0345" "fred" 1997 "fred@stone.org" NIL 1998 S: A046 ENTRY "/addressbook/user/fred/A0537" "joe" "joe@stone.org" 1999 NIL 2000 S: A046 ENTRY "/addressbook/group/Dinosaur Operators/A423" 2001 "saurians" NIL "1" 2002 S: A046 MODTIME "19970728105252" 2003 S: A046 OK "SEARCH completed" 2005 C: A047 SEARCH "/addressbook/user/fred/" RETURN ("*") EQUAL "entry" 2006 "i;octet" "A0345" 2007 S: A047 ENTRY "A0345" (("modtime" "19970728102226") ("addressbook.Alias" 2008 "fred") ("addressbook.Email" "fred@stone.org") 2009 ("addressbook.CommonName" "Fred Flintstone") 2010 ("addressbook.Surname" "Flintstone") ("addressbook.GivenName" 2011 "Fred")) 2012 S: A047 MODTIME "19970728105258" 2013 S: A047 OK "SEARCH completed" 2015 C: A048 SEARCH "/options/~/vendor.example/" RETURN 2016 ("option.value"("size" "value" "myrights")) 2017 SORT ("entry" "i;octet") COMPARE "modtime" "i;octet" 2018 "19970727123225" 2019 S: A048 ENTRY "blurdybloop" (5 "ghoti" "rwia") 2020 S: A048 ENTRY "buckybits" (2 "10" "rwia") 2021 S: A048 ENTRY "windowSize" (7 "100x100" "rwia") 2022 S: A048 MODTIME "19970728105304" 2023 S: A048 OK "SEARCH completed" 2025 C: A049 SEARCH "/addressbook/~/public" RETURN ("addressbook.Alias" 2026 "addressbook.Email") MAKECONTEXT ENUMERATE "blob" LIMIT 100 1 2027 SORT ("addressbook.Alias" "i;octet") NOT EQUAL 2028 "addressbook.Email" NIL 2029 S: A049 ENTRY "A437" "aaguy" "aaguy@stone.org" 2031 Internet DRAFT ACAP August 1997 2033 S: A049 MODTIME "19970728105308" 2034 S: A049 OK (TOOMANY 347) "Context 'blob' created" 2036 C: A050 SEARCH "blob" RANGE 2 2 "19970728105308" ALL 2037 S: A050 ENTRY "A238" "abguy" "abguy@stone.org" 2038 S: A050 MODTIME "19970728105310" 2039 S: A050 OK "SEARCH Completed" 2041 6.5. Contexts 2043 The following commands use contexts created by a SEARCH command with 2044 a MAKECONTEXT modifier. 2046 6.5.1. FREECONTEXT Command 2048 Arguments: context name 2050 Data: no specific data for this command 2052 Result: OK - freecontext completed 2053 NO - freecontext failure: no such context 2054 BAD - command unknown or arguments invalid 2056 The FREECONTEXT command causes the server to free all state 2057 associated with the named context. The context may no longer be 2058 searched and the server will no longer issue any untagged 2059 responses for the context. The context is no longer counted 2060 against the server's limit on the number of contexts. 2062 Example: C: A683 FREECONTEXT "blurdybloop" 2063 S: A683 OK "Freecontext completed" 2065 6.5.2. UPDATECONTEXT Command 2067 Arguments: list of context names 2069 Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME 2071 Result: OK - Updatecontext completed: all updates completed 2072 NO - Updatecontext failed: no such context 2073 not a notify context 2074 BAD - command unknown or arguments invalid 2076 The UPDATECONTEXT command causes the server to ensure that the 2077 client is notified of all changes known to the server for the 2078 contexts listed as arguments up to the current time. The contexts 2080 Internet DRAFT ACAP August 1997 2082 listed in the arguments must have been previously given to a 2083 successful SEARCH command with a MAKECONTEXT NOTIFY modifier. A 2084 MODTIME untagged response MUST be returned if any read-write 2085 metadata in the context changed since the last MODTIME for that 2086 context. This includes metadata which is not listed in the RETURN 2087 modifier for the context. 2089 While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and 2090 MODTIME at any time, the UPDATECONTEXT command is used to "prod" 2091 the server to send any notifications it has not sent yet. 2093 The UPDATECONTEXT command SHOULD NOT be used to poll for updates. 2095 Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl" 2096 S: Z4S9 OK "client has been notified of all changes" 2098 6.5.3. ADDTO Untagged Response 2100 Data: context name 2101 entry name 2102 position 2103 metadata list 2105 The untagged ADDTO response informs the client that an entry has 2106 been added to a context. The response includes the position 2107 number of the added entry (the first entry in the context is 2108 numbered 1) and those metadata contained in the entry which match 2109 the RETURN statement when the context was created. 2111 For enumerated contexts, the ADDTO response implicitly adds one to 2112 the position of all members of the context which had position 2113 numbers that were greater than or equal to the ADDTO position 2114 number. For non-enumerated contexts, the position field is always 2115 0. 2117 Example: S: * ADDTO "blurdybloop" "fred" 15 2118 ("addressbook.Email" "fred@stone.org") 2120 6.5.4. REMOVEFROM Untagged Response 2122 Data: context name 2123 entry name 2124 old position 2126 The untagged REMOVEFROM response informs the client that an entry 2127 has been removed from a context. The response includes the 2129 Internet DRAFT ACAP August 1997 2131 position number that the removed entry used to have (the first 2132 entry in the context is numbered 1). 2134 For enumerated contexts, the REMOVEFROM response implicitly 2135 subtracts one from the position numbers of all members of the 2136 context which had position numbers greater than the REMOVEFROM 2137 position number. For non-enumerated contexts, the position field 2138 is always 0. 2140 Example: S: * REMOVEFROM "blurdybloop" "fred" 15 2142 6.5.5. CHANGE Untagged Response 2144 Data: context name 2145 entry name 2146 old position 2147 new position 2148 metadata list 2150 The untagged CHANGE response informs the client that an entry in a 2151 context has either changed position in the context or has changed 2152 the values of one or more of the attributes specified in the 2153 RETURN modifier when the context was created. 2155 The response includes the previous and current position numbers of 2156 the entry (which are 0 if ENUMERATE was not specified on the 2157 context) and the attribute metadata requested in the RETURN 2158 modifier when the context was created. 2160 For enumerated contexts, the CHANGE response implicitly changes 2161 the position numbers of all entries which had position numbers 2162 between the old and new position. If old position is less than 2163 new position, than one is subtracted from all entries which had 2164 position numbers in that range. Otherwise one is added to all 2165 entries which had position numbers in that range. If the old 2166 position and new position are the same, then no implicit position 2167 renumbering occurs. 2169 CHANGE responses are not issued for entries which have changed 2170 position implicitly due to another ADDTO, REMOVEFROM or CHANGE 2171 response. 2173 Example: S: * CHANGE "blurdybloop" "fred" 15 10 2174 ("addressbook.Email" "fred@stone.org") 2176 Internet DRAFT ACAP August 1997 2178 6.5.6. MODTIME Untagged Response 2180 Data: context name 2181 modtime value 2183 The untagged MODTIME response informs the client that it has 2184 received all updates to entries in the context which have modtime 2185 values less than or equal to the modtime value in the argument. 2187 Example: S: * MODTIME mycontext "19970320162338" 2189 6.6. Dataset modification 2191 The following commands and responses handle modification of datasets. 2193 6.6.1. STORE Command 2195 Arguments: entry store list 2197 Data: intermediate responses: ENTRY 2199 Result: OK - store completed 2200 NO - store failure: can't store that name 2201 UNCHANGEDSINCE specified and entry changed 2202 BAD - command unknown or arguments invalid 2203 invalid UTF-8 syntax in attribute name 2205 Creates, modifies, or deletes the named entries in the named 2206 datasets. The values of metadata not specified in the command are 2207 not changed. Setting the "value" metadata of an attribute to NIL 2208 removes that attribute from the entry. Setting the "value" of the 2209 "entry" attribute to NIL removes that entry from the dataset and 2210 cancels inheritance for the entire entry. Setting the "value" of 2211 the "entry" attribute to DEFAULT removes that entry from the 2212 inheriting dataset and reverts the entry and its attributes to 2213 inherited values, if any. Changing the value of the "entry" 2214 attribute renames the entry. 2216 Storing DEFAULT to the "value" metadata of an attribute is 2217 equivalent to storing NIL, except that inheritance is enabled for 2218 that attribute. If a non-NIL value is inherited then an ENTRY 2219 intermediate response is generated to notify the client of the 2220 this change. The ENTRY response includes the entry-path and the 2221 attribute name and value metadata for each attribute which 2222 reverted to a non-NIL inherited setting. 2224 Internet DRAFT ACAP August 1997 2226 Storing NIL to the "value" metadata of an attribute MAY be treated 2227 equivalent to storing DEFAULT to that "value" if there is a NIL 2228 value in the base dataset. 2230 The STORE command is followed by one or more entry store lists. 2231 Each entry store list begins with an entry path followed by STORE 2232 modifiers, followed by zero or more attribute store items. Each 2233 attribute store item is made up of the attribute name followed by 2234 NIL (to remove the attribute's value), DEFAULT (to revert the item 2235 to any inherited value), a single value (to set the attribute's 2236 single value), or a list of metadata items to modify. The 2237 following STORE modifiers may be specified: 2239 NOCREATE 2240 By default, the server MUST create any datasets necessary to 2241 store the entry, including multiple hierarchy levels. If 2242 NOCREATE is specified, the STORE command will fail with a 2243 NOEXIST error unless the parent dataset already exists. 2245 UNCHANGEDSINCE 2246 If the "modtime" of the entry is later than the 2247 unchangedsince time, then the store fails with a MODIFIED 2248 response code. Use of UNCHANGEDSINCE with a time of 2249 "00000101000000" will always fail if the entry exists. 2250 Clients writing to a shared dataset are encouraged to use 2251 UNCHANGEDSINCE when modifying an existing entry. 2253 The server MUST either make all the changes specified in a single 2254 STORE command or make none of them. If successful, the server 2255 MUST update the "modtime" attribute for every entry which was 2256 changed. 2258 It is illegal to list any metadata item within an attribute twice, 2259 any attribute within an entry twice or any entry path twice. The 2260 server MUST return a BAD response if this happens. 2262 The server MAY re-order the strings in a multi-value on STORE and 2263 MAY remove duplicate strings. However, SEARCH MUST return multi- 2264 values and the associated size list metadata in a consistant 2265 order. 2267 Example: C: A342 STORE ("/addressbook/user/fred/ABC547" 2268 "addressbook.TelephoneNumber" "555-1234" 2269 "addressbook.CommonName" "Barney Rubble" 2270 "addressbook.AlternateNames" ("value" 2272 Internet DRAFT ACAP August 1997 2274 ("Barnacus Rubble" "Coco Puffs Thief")) 2275 "addressbook.Email" NIL) 2276 S: A342 OK "Store completed" 2277 C: A343 STORE ("/addressbook/user/joe/ABD42" 2278 UNCHANGEDSINCE "19970320162338" 2279 "user.joe.hair-length" "10 inches") 2280 S: A343 NO (MODIFIED) "'ABD42' has been changed 2281 by somebody else." 2282 C: A344 STORE ("/addressbook/group/Developers/ACD54" 2283 "entry" NIL) 2284 S: A344 OK "Store completed" 2285 C: A345 STORE ("/option/~/common/SMTPserver" 2286 "option.value" DEFAULT) 2287 S: A345 ENTRY "/option/~/common/SMTPserver" 2288 "option.value" "smtp.server.do.main" 2289 S: A345 OK "Store completed" 2290 C: A347 STORE ("/addressbook/~/" "dataset.inherit" 2291 "/addressbook/group/Developers") 2292 S: A347 OK "Store completed" 2294 6.6.2. DELETEDSINCE Command 2296 Arguments: dataset name 2297 time 2299 Data: intermediate response: DELETED 2301 Result: OK - DELETEDSINCE completed 2302 NO - DELETEDSINCE failure: can't read dataset 2303 date too far in the past 2304 BAD - command unknown or arguments invalid 2306 The DELETEDSINCE command returns in intermediate DELETED replies 2307 the names of entries that have been deleted from the named dataset 2308 since the given time. 2310 Servers may impose a limit on the number or age of deleted entry 2311 names they keep track of. If the server does not have information 2312 going back to the specified time, the command fails, returning a 2313 TOOOLD response code in the tagged NO response. 2315 Example: C: Z4S9 DELETEDSINCE "/folder/site/" 19951205103412 2316 S: Z4S9 DELETED "blurdybloop" 2317 S: Z4S9 DELETED "anteaters" 2318 S: Z4S9 OK "DELETEDSINCE completed" 2319 C: Z4U3 DELETEDSINCE "/folder/site/" 19951009040854 2320 S: Z4U3 NO (TOOOLD) "Don't have that information" 2322 Internet DRAFT ACAP August 1997 2324 6.6.3. DELETED Intermediate Response 2326 Data: entry name 2328 The intermediate DELETED response occurs as a result of a 2329 DELETEDSINCE command. It returns an entry that has been deleted 2330 from the dataset specified in the DELETEDSINCE command. 2332 6.7. Access Control List Commands 2334 The commands in this section are used to manage access control lists. 2336 6.7.1. SETACL Command 2338 Arguments: acl object 2339 authentication identifier 2340 access rights 2342 Data: no specific data for this command 2344 Result: OK - setacl completed 2345 NO - setacl failure: can't set acl 2346 BAD - command unknown or arguments invalid 2348 The SETACL command changes the access control list on the 2349 specified object so that the specified identifier is granted the 2350 permissions enumerated in rights. If the object did not 2351 previously have an access control list, one is created. 2353 Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r" 2354 S: A123 OK "Setacl complete" 2355 C: A124 SETACL ("/folder/site/") "B1FF" "rwa" 2356 S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not 2357 permitted to modify access rights 2358 for '/folder/site/'" 2360 Internet DRAFT ACAP August 1997 2362 6.7.2. DELETEACL Command 2364 Arguments: acl object 2365 optional authentication identifier 2367 Data: no specific data for this command 2369 Result: OK - deleteacl completed 2370 NO - deleteacl failure: can't delete acl 2371 BAD - command unknown or arguments invalid 2373 If given the optional identifier argument, the DELETEACL command 2374 removes any portion of the access control list on the specified 2375 object for the specified identifier. 2377 If not given the optional identifier argument, the DELETEACL 2378 command removes the ACL from the object entirely, causing access 2379 to be controlled by a higher-level default ACL. This form of the 2380 DELETEACL command is not permitted on the default ACL for a 2381 dataset and servers MUST return a BAD. 2383 Example: C: A223 DELETEACL ("/addressbook/~/public") "anyone" 2384 S: A223 OK "Deleteacl complete" 2385 C: A224 DELETEACL ("/folder/site") 2386 S: A224 BAD "Can't delete ACL from dataset" 2387 C: A225 DELETEACL ("/addressbook/user/fred" 2388 "addressbook.Email" "barney") 2389 S: A225 OK "Deleteacl complete" 2391 6.7.3. MYRIGHTS Command 2393 Arguments: acl object 2395 Data: intermediate responses: MYRIGHTS 2397 Result: OK - myrights completed 2398 NO - myrights failure: can't get rights 2399 BAD - command unknown or arguments invalid 2401 The MYRIGHTS command returns the set of rights that the client has 2402 to the given dataset or dataset attribute. 2404 Example: C: A003 MYRIGHTS ("/folder/site") 2405 S: A003 MYRIGHTS "r" 2406 S: A003 OK "Myrights complete" 2408 Internet DRAFT ACAP August 1997 2410 6.7.4. MYRIGHTS Intermediate Response 2412 Data: rights 2414 The MYRIGHTS response occurs as a result of a MYRIGHTS command. 2415 The argument is the set of rights that the client has for the 2416 object referred to in the MYRIGHTS command. 2418 6.7.5. LISTRIGHTS Command 2420 Arguments: acl object 2421 authentication identifier 2423 Data: untagged responses: LISTRIGHTS 2425 Result: OK - listrights completed 2426 NO - listrights failure: can't get rights list 2427 BAD - command unknown or arguments invalid 2429 The LISTRIGHTS command takes an object and an identifier and 2430 returns information about what rights the current user may revoke 2431 or grant to that identifier in the ACL for that object. 2433 Example: C: a001 LISTRIGHTS ("/folder/~/") "smith" 2434 S: a001 LISTRIGHTS "xra" "w" "i" 2435 S: a001 OK Listrights completed 2436 C: a005 LISTRIGHTS ("/folder/site/archive/imap") "anyone" 2437 S: a005 LISTRIGHTS "" "x" "r" "w" "i" 2438 S: a005 OK Listrights completed 2440 6.7.6. LISTRIGHTS Intermediate Response 2442 Data: required rights 2443 list of optional rights 2445 The LISTRIGHTS response occurs as a result of a LISTRIGHTS 2446 command. The first argument is a string containing the (possibly 2447 empty) set of rights the identifier will always be granted on the 2448 dataset or attribute. 2450 Following this are zero or more strings each containing a single 2451 right which the current user may revoke or grant to the identifier 2452 in the dataset or attribute. 2454 The same right MUST NOT be listed more than once in the LISTRIGHTS 2455 response. 2457 Internet DRAFT ACAP August 1997 2459 6.8. Quotas 2461 The section defines the commands and responses relating to quotas. 2463 6.8.1. GETQUOTA Command 2465 Arguments: dataset 2467 Data: untagged responses: QUOTA 2469 Result: OK - Quota information returned 2470 NO - Quota failure: can't access resource limit 2471 no resource limit 2472 BAD - command unknown or arguments invalid 2474 The GETQUOTA command takes the name of a dataset, and returns in 2475 an untagged QUOTA response the name of the dataset, quota limit in 2476 bytes that applies to that dataset and the quota usage within that 2477 limit. The scope of a quota limit is implementation dependent. 2479 Example: C: A043 GETQUOTA "/option/user/fred/common" 2480 S: * QUOTA "/option/user/fred/common" 1048576 2475 2481 S: A043 OK "Getquota completed" 2483 6.8.3. QUOTA Untagged Response 2485 Data: dataset 2486 quota limit in bytes 2487 amount of quota limit used 2488 extension data 2490 The QUOTA untagged response is generated as a result of a GETQUOTA 2491 command or MAY be generated by the server in response to a SEARCH 2492 or STORE command to warn about high usage of a quota. It includes 2493 the name of the applicable dataset, the quota limit in bytes, the 2494 quota usage and some optional extension data. Clients MUST 2495 tolerate the extension data as its use is reserved for a future 2496 extension. 2498 6.9. Extensions 2500 In order to simplify the process of extending the protocol, clients 2501 MUST tolerate unknown server responses which meet the syntax of 2502 response-extend. In addition, clients MUST tolerate unknown server 2503 response codes which meet the syntax of resp-code-ext. Availability 2504 of new commands MUST be announced via a capability on the initial 2506 Internet DRAFT ACAP August 1997 2508 greeting line and such commands SHOULD meet the syntax of 2509 command-extend. 2511 Servers MUST respond to unknown commands with a BAD command 2512 completion result. Servers MUST skip over non-synchronizing literals 2513 contained in an unknown command. This may be done by assuming the 2514 unknown command matches the command-extend syntax, or by reading a 2515 line at a time and checking for the non-synchronizing literal syntax 2516 at the end of the line. 2518 7. Registration Procedures 2520 ACAP's usefulness comes from providing a structured storage model for 2521 all sorts of configuration data. However, for its potential to be 2522 achieved, it is important that the Internet community strives for the 2523 following goals: 2525 (1) Standardization. It is very important to standardize dataset 2526 classes. The authors hope that ACAP achieves the success that SNMP 2527 has seen with the definition of numerous standards track MIBs. 2529 (2) Community Review. In the absence of standardization, it is 2530 important to get community review on a proposal to improve its 2531 engineering quality. Community review is strongly recommended prior 2532 to registration. The ACAP implementors mailing list 2533 should be used for this purpose. 2535 (3) Registration. Registration serves a two-fold purpose. First it 2536 prevents use of the same name for different purposes, and second it 2537 provides a one-stop list which can be used to locate existing 2538 extensions or dataset classes to prevent duplicate work. 2540 The following registration templates may be used to register ACAP 2541 protocol elements. 2543 7.1. ACAP Capabilities 2545 New ACAP capabilities MUST be specified in a standards track or IESG 2546 approved experimental RFCs. Registration provides a simple way to 2547 locate all extensions. Careful consideration should be made before 2548 extending the protocol, as it can lead to complexity or 2549 interoperability problems. 2551 To: iana@iana.org 2552 Subject: Registration of ACAP capability 2554 Capability name: 2556 Internet DRAFT ACAP August 1997 2558 Capability keyword: 2560 Capability arguments: 2562 Published Specification(s): 2564 (Standards track or IESG approved experimental RFC) 2566 Person and email address to contact for further information: 2568 7.2. ACAP Response Codes 2570 ACAP response codes are registered on a first come, first served 2571 basis. Proposals SHOULD be reviewed by the acap implementors mailing 2572 list mentioned above. 2574 To: iana@iana.org 2575 Subject: Registration of ACAP response code 2577 Response Code: 2579 Arguments (use ABNF to specify syntax): 2581 Purpose: 2583 Published Specification(s): 2585 (Optional, but encouraged) 2587 Person and email address to contact for further information: 2589 7.3. Dataset Classes 2591 A dataset class provides a core set of attributes for use in a 2592 specified hierarchy. It may also define rules for the dataset 2593 hierarchy underneath that class. Dataset class specifications must 2594 be standards track or IESG approved experimental RFCs. 2596 To: iana@iana.org 2597 Subject: Registration of ACAP dataset class 2599 Dataset class name/attribute prefix: 2601 Purpose: 2603 Published Specification(s): 2605 (Standards track or IESG approved experimental RFC) 2607 Internet DRAFT ACAP August 1997 2609 Person and email address to contact for further information: 2611 7.4. Vendor Subtree 2613 Vendors may reserve a portion of the ACAP namespace for private use. 2614 Dataset class names beginning with "vendor.." 2615 are reserved for use by that company or product. In addition, all 2616 attribute names beginning with "vendor.." are 2617 reserved for use by that company or product once registered. 2618 Registration is on a first come, first served basis. Whenever 2619 possible, private attributes and dataset classes should be avoided in 2620 favor of improving interoperable dataset class definitions. 2622 To: iana@iana.org 2623 Subject: Registration of ACAP vendor subtree 2625 Private Prefix: vendor.. 2627 Person and email address to contact for further information: 2629 (company names and addresses should be included when appropriate) 2631 8. Formal Syntax 2633 The following syntax specification uses the augmented Backus-Naur 2634 Form (BNF) notation as specified in [ABNF]. 2636 Except as noted otherwise, all alphabetic characters are 2637 case-insensitive. The use of upper or lower case characters to 2638 define token strings is for editorial clarity only. Implementations 2639 MUST accept these strings in a case-insensitive fashion. 2641 The "initial-greeting" rule below defines the initial ACAP greeting 2642 from the server. The "command" rule below defines the syntax for 2643 commands sent by the client. The "response" rule below defines the 2644 syntax for responses sent by the server. 2646 ALPHA = %x41-5A / %x61-7A 2647 ;; alphabetic letters 2649 ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E 2650 ;; Any CHAR except ATOM-SPECIALS 2652 ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS 2654 CHAR = %x01-7F 2656 CR = %x0C 2658 Internet DRAFT ACAP August 1997 2660 CRLF = CR LF 2662 CTL = %x00-1F / %x7F 2664 DIGIT = "0" / DIGIT-NZ 2666 DIGIT-NZ = %x31-39 2667 ; non-zero digits ("1" - "9") 2669 LF = %x0A 2671 OCTET = %x00-FF 2673 QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS 2675 QUOTED-SPECIALS = <"> / "\" 2677 SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / 2678 %x23-5B / %x5D-7F 2679 ;; any TEXT-CHAR except QUOTED-SPECIALS 2681 SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / 2682 UTF8-5 / UTF8-6 2684 SPACE = %x20 2686 TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E 2687 ;; Any ATOM-CHAR except "*" or "+" 2689 TEXT-CHAR = %x01-09 / %x0B-0C / %x0E-7F 2690 ;; any CHAR except CR and LF 2692 TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS 2694 UTF8-1 = %x80-BF 2696 UTF8-2 = %xC0-DF UTF8-1 2698 UTF8-3 = %xE0-EF 2UTF8-1 2700 UTF8-4 = %xF0-F7 3UTF8-1 2702 UTF8-5 = %xF8-FB 4UTF8-1 2704 UTF8-6 = %xFC-FD 5UTF8-1 2706 UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF 2708 Internet DRAFT ACAP August 1997 2710 acl = "(" *acl-identrights ")" 2712 acl-identifier = string-utf8 2713 ;; MUST NOT contain TAB 2715 acl-identrights = string-utf8 2716 ;; The identifier followed by a TAB, followed by 2717 ;; the rights. 2719 acl-delobject = "(" dataset SPACE attribute [SPACE entry-name] ")" 2721 acl-object = "(" dataset [SPACE attribute [SPACE entry-name]] ")" 2723 acl-rights = quoted 2725 atom = ALPHA *1023ATOM-CHAR 2727 attribute = string-utf8 2728 ;; dot-separated attribute name 2729 ;; MUST NOT contain "*" or "%" 2731 attribute-store = attribute SPACE (value-nildef / 2732 "(" 1*(metadata-write-q SPACE value-store) ")") 2733 ;; MUST NOT include the same metadata twice 2735 auth-type = <"> auth-type-name <"> 2737 auth-type-name = iana-token 2738 ;; as defined in SASL [SASL] 2740 command = tag SPACE (command-any / command-auth / 2741 command-nonauth) CRLF 2742 ;; Modal based on state 2744 command-authent = "AUTHENTICATE" SPACE auth-type 2745 [SPACE string] *(CRLF string) 2747 command-any = "NOOP" / command-lang / "LOGOUT" / command-extend 2749 command-auth = command-delacl / command-dsince / 2750 command-freectx / command-getquota / 2751 command-lrights / command-myrights / 2752 command-search / command-setacl / 2753 command-store 2754 ;; only valid in authenticated state 2756 command-delacl = "DELETEACL" SPACE acl-delobject [SPACE acl-identifier] 2758 Internet DRAFT ACAP August 1997 2760 command-dsince = "DELETEDSINCE" SPACE dataset SPACE time 2762 command-extend = extend-token [SPACE extension-data] 2764 command-freectx = "FREECONTEXT" SPACE context 2766 command-getquota = "GETQUOTA" SPACE dataset 2768 command-lang = "LANG" *(SPACE lang-tag) 2770 command-lrights = "LISTRIGHTS" SPACE acl-object 2772 command-myrights = "MYRIGHTS" SPACE acl-object 2774 command-nonauth = command-authent 2775 ;; only valid in non-authenticated state 2777 command-search = "SEARCH" SPACE (dataset / context) 2778 *(SPACE search-modifier) 2779 SPACE search-criteria 2780 ;; MUST NOT include same search-modifier twice 2782 command-setacl = "SETACL" SPACE acl-object SPACE acl-identifier 2783 SPACE acl-rights 2785 command-store = "STORE" SPACE store-entry-list 2787 comparator = <"> comparator-name <"> 2789 comparator-name = ["+" / "-"] iana-token 2791 context = string-utf8 2792 ;; MUST NOT begin with slash ("/") 2794 dataset = string-utf8 2795 ;; slash-separated dataset name 2796 ;; begins with slash 2798 entry = entry-name / entry-path 2800 entry-name = string-utf8 2801 ;; entry name MUST NOT contain slash 2802 ;; MUST NOT begin with "." 2804 entry-path = string-utf8 2805 ;; slash-separated path to entry 2806 ;; begins with slash 2808 Internet DRAFT ACAP August 1997 2810 entry-relative = string-utf8 2811 ;; potentially relative path to entry 2813 extend-token = atom 2814 ;; MUST be defined by a standards track or 2815 ;; IESG approved experimental protocol extension 2817 extension-data = extension-item *(SPACE extension-item) 2819 extension-item = extend-token / string / number / 2820 "(" [extension-data] ")" 2822 iana-token = atom 2823 ;; MUST be registered with IANA 2825 initial-greeting = "*" SPACE "ACAP" *(SPACE "(" init-capability ")") CRLF 2827 init-capability = init-cap-context / init-cap-extend / 2828 init-cap-implem / init-cap-sasl 2830 init-cap-context = "CONTEXTLIMIT" SPACE string 2832 init-cap-extend = iana-token [SPACE string-list] 2834 init-cap-implem = "IMPLEMENTATION" SPACE string 2836 init-cap-sasl = "SASL" SPACE string-list 2838 lang-tag = <"> Language-Tag <"> 2839 ;; Language-Tag rule is defined in [LANG-TAGS] 2841 literal = "{" number [ "+" ] "}" CRLF *OCTET 2842 ;; The number represents the number of octets 2843 ;; MUST be literal-utf8 except for values 2845 literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR 2846 ;; The number represents the number of octets 2847 ;; not the number of characters 2849 metadata = attribute [ "(" metadata-type-list ")" ] 2850 ;; attribute MAY end in "*" as wildcard. 2852 metadata-list = metadata *(SPACE metadata) 2854 metadata-type = "attribute" / "myrights" / "size" / 2855 "count" / metadata-write 2857 metadata-type-q = <"> metadata-type <"> 2859 Internet DRAFT ACAP August 1997 2861 metadata-type-list = metadata-type-q *(SPACE metadata-type-q) 2863 metadata-write = "value" / "acl" 2865 metadata-write-q = <"> metadata-write <"> 2867 nil = "NIL" 2869 number = *DIGIT 2870 ;; A 32-bit unsigned number. 2871 ;; (0 <= n < 4,294,967,296) 2873 nz-number = DIGIT-NZ *DIGIT 2874 ;; A 32-bit unsigned non-zero number. 2875 ;; (0 < n < 4,294,967,296) 2877 position = number 2878 ;; "0" if context is not enumerated 2879 ;; otherwise this is non-zero 2881 quota-limit = number 2883 quota-usage = number 2885 quoted = <"> *QUOTED-CHAR <"> 2886 ;; limited to 1024 octets between the <">s 2888 response = response-addto / response-alert / response-bye / 2889 response-change / response-cont / 2890 response-deleted / response-done / response-entry / 2891 response-extend / response-listr / 2892 response-lang / response-mtimei / response-mtimeu / 2893 response-myright / response-quota / 2894 response-refer / response-remove / response-stat 2896 response-addto = "*" SPACE "ADDTO" SPACE context SPACE entry-name 2897 SPACE position SPACE return-data-list 2899 response-alert = "*" SPACE "ALERT" SPACE resp-body CRLF 2900 ;; Client MUST display alert text to user 2902 response-bye = "*" SPACE "BYE" SPACE resp-body CRLF 2903 ;; Server will disconnect condition 2905 response-change = "*" SPACE "CHANGE" SPACE context SPACE entry-name 2906 SPACE position SPACE position SPACE return-data-list 2908 response-cont = "+" SPACE string 2910 Internet DRAFT ACAP August 1997 2912 response-deleted = tag SPACE "DELETED" SPACE entry-name 2914 response-done = tag SPACE resp-cond-state CRLF 2916 response-entry = tag SPACE "ENTRY" SPACE entry SPACE return-data-list 2918 response-extend = (tag / "*") SPACE extend-token [SPACE extension-data] 2920 response-lang = "*" SPACE "LANG" SPACE lang-tag 1*(SPACE comparator) 2922 response-listr = tag SPACE "LISTRIGHTS" SPACE acl-rights 2923 *(SPACE acl-rights) 2925 response-mtimei = tag SPACE "MODTIME" SPACE time 2927 response-mtimeu = "*" SPACE "MODTIME" SPACE context SPACE time 2929 response-myright = tag SPACE "MYRIGHTS" SPACE acl-rights 2931 response-quota = "*" SPACE "QUOTA" SPACE dataset SPACE quota-limit 2932 SPACE quota-usage [SPACE extension-data] 2934 response-refer = tag SPACE "REFER" SPACE dataset 1*(SPACE 2935 <"> url-relative <">) 2937 response-remove = "*" SPACE "REMOVEFROM" SPACE context SPACE 2938 entry-name SPACE position 2940 response-stat = "*" SPACE resp-cond-state CRLF 2942 resp-body = ["(" resp-code ")" SPACE] quoted 2944 resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / 2945 resp-code-inval / resp-code-mod / 2946 resp-code-noexist / resp-code-perm / "QUOTA" / 2947 resp-code-refer / resp-code-sasl / 2948 resp-code-toomany / "TOOOLD" / 2949 "TRANSITION-NEEDED" / "TRYFREECONTEXT" / 2950 "TRYLATER" / "WAYTOOMANY" / resp-code-ext 2952 resp-code-ext = iana-token [SPACE extension-data] 2953 ;; unknown response codes are tolerated by the client. 2955 resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute) 2957 resp-code-mod = "MODIFIED" SPACE entry-path 2959 resp-code-noexist = "NOEXIST" SPACE dataset 2961 Internet DRAFT ACAP August 1997 2963 resp-code-perm = "PERMISSION" SPACE acl-object 2965 resp-code-refer = "REFER" 1*(SPACE <"> url-relative <">) 2967 resp-code-sasl = "SASL" SPACE string 2969 resp-code-toomany = "TOOMANY" SPACE nz-number 2971 resp-cond-state = ("OK" / "NO" / "BAD") SPACE resp-body 2972 ;; Status condition 2974 return-attr-list = "(" return-meta-list *(SPACE return-meta-list) ")" 2975 ;; occurs when "*" is in the RETURN pattern on SEARCH 2977 return-data = return-metadata / return-meta-list / return-attr-list 2979 return-data-list = return-data *(SPACE return-data) 2981 return-meta-list = "(" return-metadata *(SPACE return-metadata) ")" 2982 ;; occurs when multiple metadata items requested 2984 return-metadata = nil / string / value-list / acl 2986 searchkey-equal = "EQUAL" SPACE attribute SPACE comparator 2987 SPACE value-nil 2989 searchkey-comp = "COMPARE" SPACE attribute SPACE comparator SPACE value 2991 searchkey-prefix = "PREFIX" SPACE attribute SPACE comparator SPACE value 2993 searchkey-range = "RANGE" SPACE nz-number SPACE nz-number 2994 SPACE time 2996 searchkey-strict = "COMPARESTRICT" SPACE attribute SPACE comparator 2997 SPACE value 2999 searchkey-substr = "SUBSTRING" SPACE attribute SPACE comparator 3000 SPACE value 3002 searchmod-depth = "DEPTH" SPACE number 3004 searchmod-hard = "HARDLIMIT" SPACE nz-number 3006 searchmod-limit = "LIMIT" SPACE number SPACE number 3008 searchmod-make = "MAKECONTEXT" [SPACE "ENUMERATE"] 3009 [SPACE "NOTIFY"] SPACE context 3011 Internet DRAFT ACAP August 1997 3013 searchmod-ninh = "NOINHERIT" 3015 searchmod-return = "RETURN" SPACE "(" [metadata-list] ")" 3017 searchmod-sort = "SORT" SPACE "(" sort-list ")" 3019 search-criteria = "ALL" / searchkey-equal / searchkey-comp / 3020 searchkey-strict / searchkey-range / 3021 searchkey-prefix / searchkey-substr / 3022 "NOT" SPACE search-criteria / 3023 "OR" SPACE search-criteria SPACE search-criteria / 3024 "AND" SPACE search-criteria SPACE search-criteria 3026 search-modifier = searchmod-depth / searchmod-hard / 3027 searchmod-limit / searchmod-make / searchmod-ninh / 3028 searchmod-return / searchmod-sort 3030 sort-list = sort-item *(SPACE sort-item) 3032 sort-item = attribute SPACE comparator 3034 store-entry = "(" entry-path *(SPACE store-modifier) 3035 *(SPACE attribute-store) ")" 3036 ;; MUST NOT include the same store-modifier twice 3037 ;; MUST NOT include the same attribute twice 3039 store-entry-list = store-entry *(SPACE store-entry) 3040 ;; MUST NOT include the same entry twice 3042 store-modifier = store-mod-unchang / store-mod-nocreate 3044 store-mod-nocreate = "NOCREATE" 3046 store-mod-unchang = "UNCHANGEDSINCE" SPACE time 3048 string = quoted / literal 3050 string-list = string *(SPACE string) 3052 string-utf8 = quoted / literal-utf8 3054 tag = 1*32TAG-CHAR 3056 time = <"> time-year time-month time-day time-hour 3057 time-minute time-second time-subsecond <"> 3058 ;; Timestamp in UTC 3060 time-day = 2DIGIT ;; 01-31 3062 Internet DRAFT ACAP August 1997 3064 time-hour = 2DIGIT ;; 00-23 3066 time-minute = 2DIGIT ;; 00-59 3068 time-month = 2DIGIT ;; 01-12 3070 time-second = 2DIGIT ;; 00-60 3072 time-subsecond = *DIGIT 3074 time-year = 4DIGIT 3076 value = string 3078 value-list = "(" [value *(SPACE value)] ")" 3080 value-nil = value / nil 3082 value-nildef = value-nil / "DEFAULT" 3084 value-store = value-nildef / value-list / acl 3086 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 3087 [url-extension] 3088 ;; url-enc-entry interpreted relative to "/" 3090 url-attr-list = url-enc-attr *("&" url-enc-attr) 3092 url-auth = ";AUTH=" ("*" / url-enc-auth) 3094 url-achar = uchar / "&" / "=" / "~" 3095 ;; See RFC 1738 for definition of "uchar" 3097 url-char = uchar / "=" / "~" / ":" / "@" / "/" 3098 ;; See RFC 1738 for definition of "uchar" 3100 url-enc-attr = 1*url-char 3101 ;; encoded version of attribute name 3103 url-enc-auth = 1*url-achar 3104 ;; encoded version of auth-type-name above 3106 url-enc-entry = 1*url-char 3107 ;; encoded version of entry-relative above 3109 url-enc-user = *url-achar 3110 ;; encoded version of login userid 3112 Internet DRAFT ACAP August 1997 3114 url-extension = *("?" 1*url-char) 3116 url-filter = "?" url-attr-list 3118 url-relative = url-acap / [url-enc-entry] [url-filter] 3119 ;; url-enc-entry is relative to base URL 3121 url-server = [url-enc-user [url-auth] "@"] hostport 3122 ;; See RFC 1738 for definition of "hostport" 3124 9. Multi-lingual Considerations 3126 The IAB charset workshop [IAB-CHARSET] came to a number of 3127 conclusions which influenced the design of ACAP. The decision to use 3128 UTF-8 as the character encoding scheme was based on that work. The 3129 LANG command to negotiate a language for error messages is also 3130 included. 3132 Section 3.4.5 of the IAB charset workshop report states that there 3133 should be a way to identify the natural language for human readable 3134 strings. Several promising proposals have been made for use within 3135 ACAP, but no clear consensus on a single method is apparent at this 3136 stage. The following rules are likely to permit the addition of 3137 multi-lingual support in the future: 3139 (1) A work in progress called Multi-Lingual String Format (MLSF) 3140 proposes a layer on top of UTF-8 which uses otherwise illegal UTF-8 3141 sequences to store language tags. In order to permit its addition to 3142 a future version of this standard, client-side UTF-8 interpreters 3143 MUST be able to silently ignore illegal multi-byte UTF-8 characters, 3144 and treat illegal single-byte UTF-8 characters as end of string 3145 markers. Servers, for the time being, MUST be able to silently 3146 accept illegal UTF-8 characters, except in attribute names and entry 3147 names. Clients MUST NOT send illegal UTF-8 characters to the server 3148 unless a future standard changes this rule. 3149 (2) There is a proposal to add language tags to Unicode. To support 3150 this, servers MUST be able to store UTF-8 characters of up to 20 bits 3151 of data. 3152 (3) The metadata item "language" is reserved for future use. 3154 10. Security Considerations 3156 The AUTHENTICATE command uses SASL [SASL] to provide basic 3157 authentication, authorization, integrity and privacy services. This 3158 is described in section 6.3.1. 3160 When the CRAM-MD5 mechanism is used, the security considerations for 3161 the CRAM-MD5 SASL mechanism [CRAM-MD5] and the HMAC Keyed-Hashing 3163 Internet DRAFT ACAP August 1997 3165 algorithm [HMAC] apply. The CRAM-MD5 mechanism is also susceptible 3166 to passive dictionary attacks. This means that if an authentication 3167 session is recorded by a passive observer, that observer can try 3168 common passwords through the CRAM-MD5 mechanism and see if the 3169 results match. This attack is reduced by using hard to guess 3170 passwords. Sites are encouraged to educate users and have the 3171 password change service test candidate passwords against a 3172 dictionary. ACAP implementations of CRAM-MD5 SHOULD permit passwords 3173 of at least 64 characters in length. 3175 ACAP protocol transactions are susceptible to passive observers or 3176 man in the middle attacks which alter the data, unless the optional 3177 encryption and integrity services of the AUTHENTICATE command are 3178 enabled, or an external security mechanism is used for protection. 3179 It may be useful to allow configuration of both clients and servers 3180 to refuse to transfer sensitive information in the absence of strong 3181 encryption. 3183 ACAP access control lists provide fine grained authorization for 3184 access to attributes. A number of related security issues are 3185 described in section 3.5. 3187 ACAP URLs have the same security considerations as IMAP URLs 3188 [IMAP-URL]. 3190 ACAP clients are encouraged to consider the security problems 3191 involved with a lab computer situation. Specifically, a client cache 3192 of ACAP configuration information MUST NOT allow access by an 3193 unauthorized user. One way to assure this is for an ACAP client to 3194 be able to completely flush any non-public cached configuration data 3195 when a user leaves. 3197 As laptop computers can be easily stolen and a cache of configuration 3198 data may contain sensitive information, a disconnected mode ACAP 3199 client may wish to encrypt and password protect cached configuration 3200 information. 3202 11. Acknowledgments 3204 Many thanks to the follow people who have contributed to ACAP over 3205 the past four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob 3206 Earhart, Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, 3207 Steve Dorner, Steve Hole, Steve Hubert, Dave Roberts, Bart Schaefer, 3208 Matt Wall and other participants of the IETF ACAP working group. 3210 Internet DRAFT ACAP August 1997 3212 12. Authors' Addresses 3214 Chris Newman 3215 Innosoft International, Inc. 3216 1050 Lakes Drive 3217 West Covina, CA 91790 USA 3219 Email: chris.newman@innosoft.com 3221 John Gardiner Myers 3222 Netscape Communications 3223 501 East Middlefield Road 3224 Mail Stop MV-029 3225 Mountain View, CA 94043 3227 Email: jgmyers@netscape.com 3229 Appendices 3231 A. References 3233 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", 3234 Work in progress: draft-ietf-drums-abnf-xx.txt 3236 [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource 3237 Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of 3238 Minnesota, December 1994. 3240 3242 [CRAM-MD5] Klensin, Catoe, Krumviede, "IMAP/POP AUTHorize Extension 3243 for Simple Challenge/Response", RFC 2095, MCI, January 1997. 3245 3247 [HMAC] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for Message 3248 Authentication", RFC 2104, IBM, UCSD, February 1997. 3250 3252 [IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson, 3253 Crispin, Svanberg, "The Report of the IAB Character Set Workshop held 3254 29 February - 1 March, 1996", RFC 2130, April 1997. 3256 3258 Internet DRAFT ACAP August 1997 3260 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 3261 4rev1", RFC 2060, University of Washington, December 1996. 3263 3265 [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie 3266 Mellon, January 1997. 3268 3270 [IMAP-URL] Newman, "IMAP URL Scheme", RFC XXXX, Innosoft, July 1997. 3272 3274 [ISO-10646] ISO/IEC 10646-1:1993(E) "Information Technology-- 3275 Universal Multiple-octet Coded Character Set (UCS)." See also 3276 amendments 1 through 7, plus editorial corrections. 3278 [ISO-C] "Programming languages -- C", ISO/IEC 9899:1990, 3279 International Organization for Standardization. This is effectively 3280 the same as ANSI C standard X3.159-1989. 3282 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 3283 Requirement Levels", RFC 2119, Harvard University, March 1997. 3285 3287 [LANG-TAGS] Alvestrand, H., "Tags for the Identification of 3288 Languages", RFC 1766. 3290 3292 [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, 3293 UC Irvine, June 1995. 3295 3297 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 3298 Work in progress: draft-myers-auth-sasl-xx.txt 3300 [SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress. 3302 [UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version 3303 2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9. 3305 [US-ASCII] "USA Standard Code for Information Interchange," X3.4. 3306 American National Standards Institute: New York (1968). 3308 Internet DRAFT ACAP August 1997 3310 [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO 3311 10646", RFC 2044, Alis Technologies, October 1996. 3313 3315 Internet DRAFT ACAP August 1997 3317 B. ACAP Keyword Index 3319 ACAP (untagged response) ................................... 26 3320 ADDTO (untagged response) .................................. 40 3321 ALERT (untagged response) .................................. 30 3322 ALL (search keyword) ....................................... 36 3323 AND (search keyword) ....................................... 36 3324 AUTH-TOO-WEAK (response code) .............................. 18 3325 AUTHENTICATE (command) ..................................... 31 3326 BAD (response) ............................................. 29 3327 BYE (untagged response) .................................... 30 3328 CHANGE (untagged response) ................................. 41 3329 COMPARE (search keyword) ................................... 36 3330 COMPARESTRICT (search keyword) ............................. 36 3331 CONTEXTLIMIT (ACAP capability) ............................. 26 3332 DELETEACL (command) ........................................ 45 3333 DELETED (intermediate response) ............................ 45 3334 DELETEDSINCE (command) ..................................... 44 3335 DEPTH (search modifier) .................................... 33 3336 ENCRYPT-NEEDED (response code) ............................. 18 3337 ENTRY (intermediate response) .............................. 37 3338 EQUAL (search keyword) ..................................... 36 3339 FREECONTEXT (command) ...................................... 39 3340 GETQUOTA (command) ......................................... 48 3341 HARDLIMIT (search modifier) ................................ 33 3342 IMPLEMENTATION (ACAP capability) ........................... 26 3343 INVALID (response code) .................................... 18 3344 LANG (command) ............................................. 27 3345 LANG (intermediate response) ............................... 28 3346 LIMIT (search modifier) .................................... 33 3347 LISTRIGHTS (command) ....................................... 47 3348 LISTRIGHTS (intermediate response) ......................... 47 3349 LOGOUT (command) ........................................... 28 3350 MAKECONTEXT (search modifier) .............................. 34 3351 MODIFIED (response code) ................................... 19 3352 MODTIME (intermediate response) ............................ 37 3353 MODTIME (untagged response) ................................ 42 3354 MYRIGHTS (command) ......................................... 46 3355 MYRIGHTS (intermediate response) ........................... 47 3356 NO (response) .............................................. 29 3357 NOCREATE (store modifier) .................................. 43 3358 NOEXIST (response code) .................................... 19 3359 NOINHERIT (search modifier) ................................ 35 3360 NOOP (command) ............................................. 27 3361 NOT (search keyword) ....................................... 36 3362 OK (response) .............................................. 29 3363 OR (search keyword) ........................................ 36 3364 PERMISSION (response code) ................................. 19 3366 Internet DRAFT ACAP August 1997 3368 PREFIX (search keyword) .................................... 36 3369 QUOTA (response code) ...................................... 19 3370 QUOTA (untagged response) .................................. 48 3371 RANGE (search keyword) ..................................... 36 3372 REFER (intermediate response) .............................. 37 3373 REFER (response code) ...................................... 19 3374 REMOVEFROM (untagged response) ............................. 40 3375 RETURN (search modifier) ................................... 35 3376 SASL (ACAP capability) ..................................... 27 3377 SASL (response code) ....................................... 19 3378 SEARCH (command) ........................................... 33 3379 SETACL (command) ........................................... 45 3380 SORT (search modifier) ..................................... 35 3381 STORE (command) ............................................ 42 3382 SUBSTRING (search keyword) ................................. 37 3383 TOOMANY (response code) .................................... 19 3384 TOOOLD (response code) ..................................... 19 3385 TRANSITION-NEEDED (response code) .......................... 19 3386 TRYFREECONTEXT (response code) ............................. 20 3387 TRYLATER (response code) ................................... 20 3388 UNCHANGEDSINCE (store modifier) ............................ 43 3389 UPDATECONTEXT (command) .................................... 39 3390 WAYTOOMANY (response code) ................................. 20 3391 acl (attribute metadata) ................................... 12 3392 anyone (ACL identifier) .................................... 16 3393 attribute (attribute metadata) ............................. 12 3394 dataset.acl (dataset attribute) ............................ 24 3395 dataset.acl. (dataset attribute) ................ 24 3396 dataset.inherit (dataset attribute) ........................ 24 3397 entry (predefined attribute) ............................... 11 3398 i;ascii-casemap (comparator) ............................... 16 3399 i;ascii-numeric (comparator) ............................... 16 3400 i;octet (comparator) ....................................... 15 3401 modtime (predefined attribute) ............................. 11 3402 myrights (attribute metadata) .............................. 12 3403 size (attribute metadata) .................................. 12 3404 subdataset (predefined attribute) .......................... 11 3405 value (attribute metadata) ................................. 13