idnits 2.17.1 draft-ietf-acap-spec-04.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-04-26) 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 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 25 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 203: '... mechanism and SHOULD support an enc...' RFC 2119 keyword, line 349: '... MUST be explicitly identified in th...' RFC 2119 keyword, line 350: '... which SHOULD include specific fixed...' RFC 2119 keyword, line 352: '...ication, clients MUST NOT depend on th...' RFC 2119 keyword, line 526: '... A client MUST be prepared to accept...' (103 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 (June 1997) is 9812 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. 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? 'ENUMERATE' on line 1933 looks like a reference -- Missing reference section? 'NOTIFY' on line 1933 looks like a reference -- Missing reference section? 'KEYWORDS' on line 3346 looks like a reference -- Missing reference section? 'IMAP4' on line 3326 looks like a reference -- Missing reference section? 'US-ASCII' on line 3374 looks like a reference -- Missing reference section? 'SASL' on line 3361 looks like a reference -- Missing reference section? 'UTF8' on line 3377 looks like a reference -- Missing reference section? 'UNICODE-2' on line 3371 looks like a reference -- Missing reference section? 'ISO-10646' on line 3336 looks like a reference -- Missing reference section? 'BASIC-URL' on line 3314 looks like a reference -- Missing reference section? 'SASL-ANON' on line 3364 looks like a reference -- Missing reference section? 'REL-URL' on line 3356 looks like a reference -- Missing reference section? 'ISO-C' on line 3340 looks like a reference -- Missing reference section? 'IMAP-ACL' on line 3331 looks like a reference -- Missing reference section? 'SASL-PLAIN' on line 3367 looks like a reference -- Missing reference section? 'ABNF' on line 3311 looks like a reference -- Missing reference section? 'LANG-TAGS' on line 3351 looks like a reference -- Missing reference section? 'IAB-CHARSET' on line 3320 looks like a reference Summary: 8 errors (**), 0 flaws (~~), 1 warning (==), 21 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-04.txt J. G. Myers 5 Netscape 6 June 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 June 19, 1997 44 Table of Contents 46 Status of this Memo ............................................... i 47 Abstract .......................................................... i 48 ACAP Protocol Specification ....................................... 1 49 0. Changes from version -03 to version -04 .................. 1 50 0.1. Open Issues .............................................. 3 51 1. Introduction ............................................. 3 52 1.1. Conventions Used in this Document ........................ 3 53 1.2. ACAP Data Model .......................................... 3 54 1.3. ACAP Design Goals ........................................ 3 55 1.4. Validation ............................................... 4 56 1.5. Definitions .............................................. 4 57 1.6. ACAP Command Overview .................................... 6 58 2. Protocol Framework ....................................... 6 59 2.1. Link Level ............................................... 6 60 2.2. Commands and Responses ................................... 6 61 2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 6 62 2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 7 63 2.3. Server States ............................................ 8 64 2.3.1. Non-Authenticated State .................................. 8 65 2.3.2. Authenticated State ...................................... 8 66 2.3.3. Logout State ............................................. 8 67 2.4. Operational Considerations ............................... 9 68 2.4.1. Untagged Status Updates .................................. 9 69 2.4.2. Response when No Command in Progress ..................... 9 70 2.4.3. Auto-logout Timer ........................................ 9 71 2.4.4. Multiple Commands in Progress ............................ 10 72 2.5. Server Command Continuation Request ...................... 10 73 2.6. Data Formats ............................................. 10 74 2.6.1. Atom ..................................................... 11 75 2.6.2. Number ................................................... 11 76 2.6.3. String ................................................... 11 77 2.6.3.1. 8-bit and Binary Strings ................................. 12 78 2.6.4. Parenthesized List ....................................... 12 79 2.6.5. NIL ...................................................... 12 80 3. Protocol Elements ........................................ 12 81 3.1. Entries and Attributes ................................... 12 82 3.1.1. Predefined Attributes .................................... 13 83 3.1.2. Attribute metadata ....................................... 14 84 3.2. ACAP URL scheme .......................................... 15 85 3.2.1. ACAP URL User Name and Authentication Mechanism .......... 15 86 3.2.2. Relative ACAP URLs ....................................... 16 87 Internet DRAFT ACAP June 19, 1997 89 3.3. Contexts ................................................. 16 90 3.4. Comparators .............................................. 17 91 3.5. Access Control Lists (ACLs) .............................. 18 92 3.6. Server Response Codes .................................... 20 93 4. Namespace Conventions .................................... 22 94 4.1. Dataset Namespace ........................................ 22 95 4.2. Attribute Namespace ...................................... 23 96 4.3. Formal Syntax for Dataset and Attribute Namespace ........ 23 97 5. Dataset Management ....................................... 25 98 5.1. Dataset Inheritance ...................................... 25 99 5.2. Dataset Attributes ....................................... 25 100 5.3. Dataset Creation ......................................... 26 101 5.4. Dataset Class Capabilities ............................... 26 102 5.5. Dataset Quotas ........................................... 27 103 6. Command and Response Specifications ...................... 28 104 6.1. Initial Connection ....................................... 29 105 6.1.1. ACAP Untagged Response ................................... 29 106 6.2. Any State ................................................ 30 107 6.2.1. NOOP Command ............................................. 30 108 6.2.2. LANG Command ............................................. 30 109 6.2.3. LANG Untagged Response ................................... 31 110 6.2.4. LOGOUT Command ........................................... 31 111 6.2.5. OK Response .............................................. 31 112 6.2.6. NO Response .............................................. 32 113 6.2.7. BAD Response ............................................. 32 114 6.2.8. BYE Untagged Response .................................... 33 115 6.2.9. ALERT Untagged Response .................................. 33 116 6.3. Non-Authenticated State .................................. 33 117 6.3.1. AUTHENTICATE Command ..................................... 34 118 6.4. Searching ................................................ 35 119 6.4.1. SEARCH Command ........................................... 35 120 6.4.2. ENTRY Intermediate Response .............................. 40 121 6.4.3. MODTIME Intermediate Response ............................ 40 122 6.4.4. REFER Intermediate Response .............................. 40 123 6.5. Contexts ................................................. 41 124 6.5.1. FREECONTEXT Command ...................................... 41 125 6.5.2. UPDATECONTEXT Command .................................... 41 126 6.5.3. ADDTO Untagged Response .................................. 42 127 6.5.4. REMOVEFROM Untagged Response ............................. 42 128 6.5.5. CHANGE Untagged Response ................................. 43 129 6.5.6. MODTIME Untagged Response ................................ 43 130 6.6. Dataset modification ..................................... 44 131 6.6.1. STORE Command ............................................ 44 132 6.6.2. DELETEDSINCE Command ..................................... 45 133 6.6.3. DELETED Intermediate Response ............................ 46 134 6.7. Access Control List Commands ............................. 46 135 6.7.1. SETACL Command ........................................... 46 136 6.7.2. DELETEACL Command ........................................ 47 137 Internet DRAFT ACAP June 19, 1997 139 6.7.3. MYRIGHTS Command ......................................... 47 140 6.7.4. MYRIGHTS Intermediate Response ........................... 48 141 6.7.5. LISTRIGHTS Command ....................................... 48 142 6.7.6. LISTRIGHTS Intermediate Response ......................... 49 143 6.8. Quotas ................................................... 49 144 6.8.1. GETQUOTA Command ......................................... 49 145 6.8.3. QUOTA Untagged Response .................................. 50 146 6.9. Extensions ............................................... 50 147 7. Registration Procedures .................................. 50 148 7.1. Comparators .............................................. 51 149 7.2. ACAP Capabilities ........................................ 51 150 7.3. ACAP Response Codes ...................................... 52 151 7.4. Dataset Classes .......................................... 52 152 7.5. Vendor Subtree ........................................... 53 153 8. Formal Syntax ............................................ 53 154 9. Multi-lingual Considerations ............................. 63 155 10. Security Considerations .................................. 64 156 11. Acknowledgments .......................................... 64 157 12. Authors' Addresses ....................................... 64 158 Appendices ........................................................ 65 159 A. References ............................................... 65 160 B. ACAP Keyword Index ....................................... 67 161 Internet DRAFT ACAP June 19, 1997 163 ACAP Protocol Specification 165 0. Changes from version -03 to version -04 167 1) Changed ABNF reference to use new ABNF spec, added UTF-8 syntax 168 and got rid of all stuff in grammar. 170 2) Added length limit of 32 on tags. 172 3) Renamed "ordering function" to "comparator" 174 4) Put "" around comparator, made "+" / "-" optional. 176 5) Added SUBSTRING and PREFIX search keys. 178 6) Added multi-valued attributes. 180 7) Restricted numbers to 32-bit values. 182 8) Added description of data model and design goals. 184 9) Permit multiple referrals. 186 10) Simplified ACAP URL. 188 11) Noted that UNCHANGEDSINCE with a time of "00000101000000" will 189 always fail if the entry exists. 191 12) Used "base dataset" rather than "inherited dataset" 193 13) Fixed ABNF to group results for each RETURN item. 195 14) Forbid use of "*" or "%" in attribute name. 197 15) Added TRYCACHE response code. 199 16) Clarified that any two STORE operations must result in different 200 modtimes, even if simultaneous. 202 17) Added recommendation that all servers support the PLAIN SASL 203 mechanism and SHOULD support an encryption layer or stronger 204 standards track SASL mechanism. 206 18) Added a bunch of text to security considerations section after 207 being warned that the IESG is becoming much more stringent about 208 security considerations. Comments would be appreciated. 210 Internet DRAFT ACAP June 19, 1997 212 19) Noted that change responses are not issued for implicit 213 renumbering. 215 20) Removed ".bin" attribute naming convention. 217 21) Removed partial fetch attribute. 219 22) Removed "o" ACL bit. 221 23) Added acl-object argument to PERMISSION error. 223 24) Atoms must begin with a letter to distinguish them from numbers. 224 Added that atoms are used for protocol keywords. 226 25) Make ALERT a separate untagged response 228 26) Change NOTIFYCONTEXT to MAKECONTEXT [ENUMERATE] [NOTIFY] 230 27) Added Multi-lingual considerations section 232 28) Updated STORE grammar to deal with multiple writable metadata 233 items and multi-valued attributes. 235 29) make metadata item names be quoted strings 237 30) Fixed LISTRIGHTS, SETACL examples. 239 31) Added dataset creation section, dataset capabilities section. 241 32) Added NOINHERIT SEARCH modifier. 243 33) Added NOEXIST response code and NOCREATE store modifier. 245 34) Added LANG command. 247 35) Added user specific and site specific attribute namespaces. 249 36) Removed SETQUOTA command, added description of /quota dataset 250 class. SETQUOTA was broken because it didn't fall under the auspices 251 of ACAP's ACL system. 253 37) Allow servers to implement schemes to defeat client polling with 254 UPDATECONTEXT. 256 38) Forbid duplicate search modifiers, store modifiers, store 257 entries, store entry attributes, store attribute metadata. 259 Internet DRAFT ACAP June 19, 1997 261 0.1. Open Issues 263 1) Consider making ACL model more precise. Would like to pick AFS 264 semantics over POSIX semantics since AFS semantics are more 265 intuitive. Currently both ACL semantics are permitted. 267 2) Need more examples. 269 3) Descriptive comparator naming, including vendor naming. 271 1. Introduction 273 1.1. Conventions Used in this Document 275 In examples, "C:" and "S:" indicate lines sent by the client and 276 server respectively. If such lines are wrapped without a new "C:" or 277 "S:" label, then the wrapping is for editorial clarity and is not 278 part of the command. 280 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", 281 and "MAY" in this document are to be interpreted as described in "Key 282 words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 284 1.2. ACAP Data Model 286 An ACAP server exports a hierarchical tree of entries. Each level of 287 the tree is called a dataset, and each dataset is made up of a list 288 of entries. Each entry has a unique name and may contain any number 289 of named attributes. Each attribute within an entry may be single 290 valued or multi-valued and may have associated metadata to assist 291 access and interpretation of the value. 293 The rules with which a client interprets the data within a portion of 294 ACAP's tree of entries are called a dataset class. 296 1.3. ACAP Design Goals 298 ACAP's primary purpose is to allow users access to their 299 configuration data from multiple network-connected computers. Users 300 can then sit down in front of any network-connected computer, run any 301 ACAP-enabled application and have access to their own configuration 302 data. Because it is hoped that many applications will become ACAP- 303 enabled, client simplicity was preferred to server or protocol 304 simplicity whenever reasonable. 306 ACAP is designed to be easily manageable. For this reason, it 307 includes "inheritance" which allows one dataset to inherit default 308 attributes from another dataset. In addition, access control lists 310 Internet DRAFT ACAP June 19, 1997 312 are included to permit delegation of management and quotas are 313 included to prevent storage abuse. Finally, an ACAP server which is 314 conformant to this base specification should be able to support most 315 dataset classes defined in the future without requiring a server 316 reconfiguration or upgrade. 318 ACAP is designed to operate well with a client that only has 319 intermittent access to an ACAP server. For this reason, each entry 320 has a server maintained modification time so that the client may 321 detect changes. In addition, the client may ask the server for a 322 list of entries which have been removed since it last accessed the 323 server. 325 ACAP presumes that a dataset may be potentially large and/or the 326 client's network connection may be slow, and thus offers server 327 sorting, selective fetching and change notification for entries 328 within a dataset. 330 As required for most Internet protocols, security, scalability and 331 internationalization were important design goals. 333 Given these design goals, an attempt was made to keep ACAP as simple 334 as possible. It is a traditional Internet text based protocol which 335 massively simplifies protocol debugging. It was designed based on 336 the successful IMAP [IMAP4] protocol framework, with a few minor 337 simplifications. 339 1.4. Validation 341 By default, any value may be stored in any attribute for which the 342 user has appropriate permission and quota. This rule is necessary to 343 allow the addition of new simple dataset classes without 344 reconfiguring or upgrading the server. 346 In some cases, such as when the value has special meaning to the 347 server, it is useful to have the server enforce validation by 348 returning the INVALID response code to a STORE command. These cases 349 MUST be explicitly identified in the dataset class specification 350 which SHOULD include specific fixed rules for validation. Since a 351 given ACAP server may be unaware of any particular dataset class 352 specification, clients MUST NOT depend on the presence of enforced 353 validation on the server. 355 1.5. Definitions 357 access control list (ACL) 358 A set of identifier, rights pairs associated with an object. An 360 Internet DRAFT ACAP June 19, 1997 362 ACL is used to determine which operations a user is permitted to 363 perform on that object. See section ###. 365 attribute 366 A named value within an entry. See section ###. 368 comparator 369 A named function which can be used to perform one or more of 370 three comparison operations: ordering, equality and substring 371 matching. See section ###. 373 context 374 An ordered subset of entries in a dataset, created by a SEARCH 375 command with a MAKECONTEXT modifier. See section ###. 377 dataset 378 One level of hierarchy in ACAP's tree of entries. See section 379 ###. 381 dataset class specification 382 The rules which allow a client to interpret the data within a 383 portion of ACAP's tree of entries. 385 entry 386 A set of attributes with a unique entry name. See section ###. 388 metadata 389 Information describing an attribute, its value and any access 390 controls associated with that attribute. See section ###. 392 NIL This represents the non-existence of a particular data item. 394 NUL A control character encoded as 0 in US-ASCII [US-ASCII]. 396 octet 397 An 8-bit value. On most modern computer systems, an octet is 398 one byte. 400 SASL Simple Authentication and Security Layer [SASL]. 402 UTC Universal Coordinated Time as maintained by the Bureau 403 International des Poids et Mesures (BIPM). 405 UTF-8 406 An 8-bit transformation format of the Universal Character Set 407 [UTF8]. Note that an incompatible change was made to the coded 408 character set referenced by [UTF8], so for the purpose of this 409 document, UTF-8 refers to the UTF-8 encoding as defined by 411 Internet DRAFT ACAP June 19, 1997 413 version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646] 414 including amendments one through seven. 416 1.6. ACAP Command Overview 418 The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic 419 protocol services. The SEARCH command is used to select, sort, fetch 420 and monitor changes to attribute values and metadata. The 421 UPDATECONTEXT and FREECONTEXT commands are also used to assist in 422 monitoring changes in attribute values and metadata. The STORE 423 command is used to add, modify and delete entries and attributes. 424 The DELETEDSINCE command is used to assist a client in 425 re-synchronizing a cache with the server. The GETQUOTA, SETACL, 426 DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine 427 storage quotas and examine or modify access permissions. 429 2. Protocol Framework 431 2.1. Link Level 433 The ACAP protocol assumes a reliable data stream such as provided by 434 TCP. When TCP is used, an ACAP server listens on port 674. 436 2.2. Commands and Responses 438 An ACAP session consists of the establishment of a client/server 439 connection, an initial greeting from the server, and client/server 440 interactions. These client/server interactions consist of a client 441 command, server data, and a server completion result. 443 All interactions transmitted by client and server are in the form of 444 lines; that is, strings that end with a CRLF. The protocol receiver 445 of an ACAP client or server is either reading a line, or is reading a 446 sequence of octets with a known count followed by a line. Both 447 clients and servers must be capable of handling lines of arbitrary 448 length. 450 2.2.1. Client Protocol Sender and Server Protocol Receiver 452 The client command begins an operation. Each client command is 453 prefixed with a identifier (an alphanumeric string of no more than 32 454 characters, e.g., A0001, A0002, etc.) called a "tag". A different 455 tag is generated by the client for each command. 457 There are two cases in which a line from the client does not 458 represent a complete command. In one case, a command argument is 459 quoted with an octet count (see the description of literal in section 461 Internet DRAFT ACAP June 19, 1997 463 ###); in the other case, the command arguments require server 464 feedback (see the AUTHENTICATE command). In some of these cases, the 465 server sends a command continuation request if it is ready for the 466 next part of the command. This response is prefixed with the token 467 "+". 469 Note: If, instead, the server detected an error in the 470 command, it sends a BAD completion response with tag 471 matching the command (as described below) to reject the 472 command and prevent the client from sending any more of the 473 command. 475 It is also possible for the server to send a completion or 476 intermediate response for some other command (if multiple 477 commands are in progress), or untagged data. In either 478 case, the command continuation request is still pending; 479 the client takes the appropriate action for the response, 480 and reads another response from the server. 482 The ACAP server reads a command line from the client, parses the 483 command and its arguments, and transmits server data and a server 484 command completion result. 486 2.2.2. Server Protocol Sender and Client Protocol Receiver 488 Data transmitted by the server to the client come in four forms: 489 command continuation requests, command completion results, 490 intermediate responses, and untagged responses. 492 A command continuation request is prefixed with the token "+". 494 A command completion result indicates the success or failure of the 495 operation. It is tagged with the same tag as the client command 496 which began the operation. Thus, if more than one command is in 497 progress, the tag in a server completion response identifies the 498 command to which the response applies. There are three possible 499 server completion responses: OK (indicating success), NO (indicating 500 failure), or BAD (indicating protocol error such as unrecognized 501 command or command syntax error). 503 An intermediate response returns data which can only be interpreted 504 within the context of a command in progress. It is tagged with the 505 same tag as the client command which began the operation. Thus, if 506 more than one command is in progress, the tag in an intermediate 507 response identifies the command to which the response applies. A 508 tagged response other than "OK", "NO", or "BAD" is an intermediate 509 response. 511 Internet DRAFT ACAP June 19, 1997 513 An untagged response returns data or status messages which may be 514 interpreted outside the context of a command in progress. It is 515 prefixed with the token "*". Untagged data may be sent as a result 516 of a client command, or may be sent unilaterally by the server. 517 There is no syntactic difference between untagged data that resulted 518 from a specific command and untagged data that were sent 519 unilaterally. 521 The protocol receiver of an ACAP client reads a response line from 522 the server. It then takes action on the response based upon the 523 first token of the response, which may be a tag, a "*", or a "+" as 524 described above. 526 A client MUST be prepared to accept any server response at all times. 527 This includes untagged data that it may not have requested. 529 This topic is discussed in greater detail in the Server Responses 530 section. 532 2.3. Server States 534 An ACAP server is in one of three states. Most commands are valid in 535 only certain states. It is a protocol error for the client to 536 attempt a command while the server is in an inappropriate state for 537 that command. In this case, a server will respond with a BAD command 538 completion result. 540 2.3.1. Non-Authenticated State 542 In non-authenticated state, the user must supply authentication 543 credentials before most commands will be permitted. This state is 544 entered when a connection starts. 546 2.3.2. Authenticated State 548 In authenticated state, the user is authenticated and most commands 549 will be permitted. This state is entered when acceptable 550 authentication credentials have been provided. 552 2.3.3. Logout State 554 In logout state, the session is being terminated, and the server will 555 close the connection. This state can be entered as a result of a 556 client request or by unilateral server decision. 558 Internet DRAFT ACAP June 19, 1997 560 +--------------------------------------+ 561 |initial connection and server greeting| 562 +--------------------------------------+ 563 || (1) || (2) 564 VV || 565 +-----------------+ || 566 |non-authenticated| || 567 +-----------------+ || 568 || (4) || (3) || 569 || VV || 570 || +----------------+ || 571 || | authenticated | || 572 || +----------------+ || 573 || || (4) || 574 VV VV VV 575 +--------------------------------------+ 576 | logout and close connection | 577 +--------------------------------------+ 579 (1) connection (ACAP greeting) 580 (2) rejected connection (BYE greeting) 581 (3) successful AUTHENTICATE command 582 (4) LOGOUT command, server shutdown, or connection closed 584 2.4. Operational Considerations 586 2.4.1. Untagged Status Updates 588 At any time, a server can send data that the client did not request. 590 2.4.2. Response when No Command in Progress 592 Server implementations are permitted to send an untagged response 593 while there is no command in progress. Server implementations that 594 send such responses MUST deal with flow control considerations. 595 Specifically, they must either (1) verify that the size of the data 596 does not exceed the underlying transport's available window size, or 597 (2) use non-blocking writes. 599 2.4.3. Auto-logout Timer 601 If a server has an inactivity auto-logout timer, that timer MUST be 602 of at least 30 minutes duration. The receipt of ANY command from the 603 client during that interval MUST suffice to reset the auto-logout 604 timer. 606 Internet DRAFT ACAP June 19, 1997 608 2.4.4. Multiple Commands in Progress 610 The client is not required to wait for the completion result of a 611 command before sending another command, subject to flow control 612 constraints on the underlying data stream. Similarly, a server is 613 not required to process a command to completion before beginning 614 processing of the next command, unless an ambiguity would result 615 because of a command that would affect the results of other commands. 616 If there is such an ambiguity, the server executes commands to 617 completion in the order given by the client. 619 2.5. Server Command Continuation Request 621 The command continuation request is indicated by a "+" token instead 622 of a tag. This indicates that the server is ready to accept the 623 continuation of a command from the client. 625 This response is used in the AUTHENTICATE command to transmit server 626 data to the client, and request additional client data. This 627 response is also used if an argument to any command is a 628 synchronizing literal. 630 The client is not permitted to send the octets of a synchronizing 631 literal unless the server indicates that it expects it. This permits 632 the server to process commands and reject errors on a line-by-line 633 basis, assuming it checks for non-synchronizing literals at the end 634 of each line. The remainder of the command, including the CRLF that 635 terminates a command, follows the octets of the literal. If there 636 are any additional command arguments the literal octets are followed 637 by a space and those arguments. 639 Example: C: A099 FREECONTEXT {10} 640 S: + "Ready for additional command text" 641 C: FRED 642 C: FOOB 643 S: A099 OK "FREECONTEXT completed" 644 C: A044 BLURDYBLOOP {102856} 645 S: A044 BAD "No such command as 'BLURDYBLOOP'" 647 2.6. Data Formats 649 ACAP uses textual commands and responses. Data in ACAP can be in one 650 of five forms: atom, number, string, parenthesized list or NIL. 652 Internet DRAFT ACAP June 19, 1997 654 2.6.1. Atom 656 An atom consists of one to 1024 non-special characters. It must 657 begin with a letter. Atoms are used for protocol keywords. 659 2.6.2. Number 661 A number consists of one or more digit characters, and represents a 662 numeric value. Numbers are restricted to the range of an unsigned 663 32-bit integer: 0 < number < 4,294,967,296. 665 2.6.3. String 667 A string is in one of two forms: literal and quoted string. The 668 literal form is the general form of string. The quoted string form 669 is an alternative that avoids the overhead of processing a literal at 670 the cost of restrictions of what may be in a quoted string. 672 A literal is a sequence of zero or more octets (including CR and LF), 673 prefix-quoted with an octet count in the form of an open brace ("{"), 674 the number of octets, close brace ("}"), and CRLF. In the case of 675 literals transmitted from server to client, the CRLF is immediately 676 followed by the octet data. 678 There are two forms of literals transmitted from client to server. 679 The form where the open brace ("{") and number of octets is 680 immediately followed by a close brace ("}") and CRLF is called a 681 synchronizing literal. When sending a synchronizing literal, the 682 client must wait to receive a command continuation request (described 683 later in this document) before sending the octet data (and the 684 remainder of the command). The other form of literal, the 685 non-synchronizing literal, is used to transmit a string from client 686 to server without waiting for a command continuation request. The 687 non-synchronizing literal differs from the synchronizing literal by 688 having a plus ("+") between the number of octets and the close brace 689 ("}") and by having the octet data immediately following the CRLF. 691 A quoted string is a sequence of zero to 1024 octets excluding NUL, 692 CR and LF, with double quote (<">) characters at each end. 694 The empty string is represented as "" (a quoted string with zero 695 characters between double quotes), as {0} followed by CRLF (a 696 synchronizing literal with an octet count of 0), or as {0+} followed 697 by a CRLF (a non-synchronizing literal with an octet count of 0). 699 Note: Even if the octet count is 0, a client transmitting a 700 synchronizing literal must wait to receive a command 701 continuation request. 703 Internet DRAFT ACAP June 19, 1997 705 2.6.3.1. 8-bit and Binary Strings 707 Most strings in ACAP are restricted to UTF-8 characters and may not 708 contain NUL octets. Attribute values MAY contain any octets 709 including NUL. 711 2.6.4. Parenthesized List 713 Data structures are represented as a "parenthesized list"; a sequence 714 of data items, delimited by space, and bounded at each end by 715 parentheses. A parenthesized list can contain other parenthesized 716 lists, using multiple levels of parentheses to indicate nesting. 718 The empty list is represented as () -- a parenthesized list with no 719 members. 721 2.6.5. NIL 723 The special atom "NIL" represents the non-existence of a particular 724 data item that is represented as a string or parenthesized list, as 725 distinct from the empty string "" or the empty parenthesized list (). 727 3. Protocol Elements 729 This section defines data formats and other protocol elements used 730 throughout the ACAP protocol. 732 3.1. Entries and Attributes 734 Within a dataset, each entry name is made up of zero or more UTF-8 735 characters other than slash ("/"). A slash separated list of 736 entries, one at each level of the hierarchy, forms the full path to 737 an entry. 739 Each entry is made up of a set of attributes. Each attribute has a 740 hierarchical name in UTF-8, with each component of the name separated 741 by a period ("."). 743 The value of an attribute is either single or multi-valued. A single 744 value is NIL (has no value), or a string of zero or more octets. A 745 multi-value is a list of zero or more strings, each of zero or more 746 octets. 748 Attribute names are not permitted to contain asterisk ("*") or 749 percent ("%") and MUST be valid UTF-8 strings which do not contain 750 NUL. Invalid attribute names result in a BAD response. Entry names 751 are not permitted to begin with "." or contain slash ("/") and MUST 752 be valid UTF-8 strings which do not contain NUL. Invalid entry names 754 Internet DRAFT ACAP June 19, 1997 756 in the entry field of a command result in a BAD response. 758 Use of non-visible UTF-8 characters in attribute and entry names is 759 discouraged. 761 3.1.1. Predefined Attributes 763 Attribute names which do not contain a dot (".") are reserved for 764 standardized attributes which have meaning in any dataset. The 765 following attributes are defined by the ACAP protocol. 767 entry 768 Contains the name of the entry. MUST be single valued. 769 Attempts to use illegal or multi-valued values for the entry 770 attribute are protocol errors and MUST result in a BAD 771 completion response. This is a special case. 773 modtime 774 Contains the date and time any read-write metadata in the entry 775 was last modified. This value MUST be in UTC, MUST be 776 automatically updated by the server. 778 The value consists of 14 or more US-ASCII digits. The first 779 four indicate the year, the next two indicate the month, the 780 next two indicate the day of month, the next two indicate the 781 hour (0 - 23), the next two indicate the minute, and the next 782 two indicate the second. Any further digits indicate fractions 783 of a second. 785 The time, particularly fractions of a second, need not be 786 accurate. It is REQUIRED, however, that any two entries in a 787 dataset changed by successive modifications have strictly 788 ascending modtime values. In addition, each STORE command 789 within a dataset (including simultaneous stores from different 790 connections) MUST use different modtime values. 792 This attribute has enforced validation, so any attempt to STORE 793 a value in this attribute MUST result in a NO response with an 794 INVALID response code. 796 subdataset 797 If this attribute is set, it indicates the existence of a sub- 798 dataset of this entry. 800 The value consists of a list of relative ACAP URLs (see section 801 ###) which may be used to locate the sub-dataset. The base URL 802 is the full path to the entry followed by a slash ("/"). The 803 value "." indicates a subdataset is located directly under this 805 Internet DRAFT ACAP June 19, 1997 807 one. Multiple values indicate replicated copies of the 808 subdataset. 810 For example, if the dataset "/folder/site/" has an entry 811 "public-folder" with a subdataset attribute of ".", then there 812 exists a dataset "/folder/site/public-folder/". If the value of 813 the subdataset attribute was instead 814 "//other.acap.domain//folder/site/public-folder/" that would 815 indicate the dataset is actually located on a different ACAP 816 server. 818 A dataset can be created by storing a "subdataset" attribute 819 including ".", and a sub-hierarchy of datasets is deleted by 820 storing a NIL value to the "subdataset" attribute on the entry 821 in the parent dataset. 823 This attribute has enforced syntax validation. Specifically, if 824 an attempt is made to STORE a single-value (other than NIL), an 825 empty list, or one of the values does not follow the URL syntax 826 rules [BASIC-URL], then this will result in a NO response with 827 an INVALID response code. 829 3.1.2. Attribute metadata 831 Each attribute is made up of metadata items which describe that 832 attribute, its value and any associated access controls. Metadata 833 items may be either read-only in which case the client is never 834 permitted to modify the item, or read-write, in which case the client 835 may modify the item if the access control list (ACL) permits. 837 The following metadata items are defined in this specification: 839 acl The access control list for the attribute, if one exists. If 840 the attribute does not have an ACL, NIL is returned. 841 Read-write. See section ### for the contents of an ACL. 843 attribute 844 The attribute name. Read-only. 846 myrights 847 The set of rights that the client has to the attribute. 848 Read-only. See section ### for the possible rights. 850 size This is the length of the value. In the case of a 852 Internet DRAFT ACAP June 19, 1997 854 multi-value, this is a list of lengths for each of the values. 856 value The value. For a multi-value, this is a list of single 857 values. 859 Additional items of metadata may be defined in extensions to this 860 protocol. Servers MUST respond to queries of unrecognized metadata 861 by returning a BAD command completion result. 863 3.2. ACAP URL scheme 865 ACAP URLs are used within the ACAP protocol for the "subdataset" 866 attribute, referrals and inheritance. They provide a convenient 867 syntax for referring to other ACAP datasets. The ACAP URL follows 868 the common Internet scheme syntax as defined in [BASIC-URL]. If 869 : is omitted, the port defaults to 674. 871 An ACAP URL has the following general form: 873 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 875 The element includes the hostname, and optional user 876 name, authentication mechanism and port number. The 877 element contains the name of an entry path encoded according to the 878 rules in [BASIC-URL]. 880 The element is an optional list of interesting attribute 881 names. If omitted, the URL refers to all attributes of the named 882 entry. 884 Note that unsafe or reserved characters such as " " or "?" MUST be 885 hex encoded as described in the URL specification [BASIC-URL]. Hex 886 encoded octets are interpreted according to UTF-8 [UTF8]. 888 3.2.1. ACAP URL User Name and Authentication Mechanism 890 A user name and/or authentication mechanism may be supplied. They 891 are used in the "AUTHENTICATE" command after making the connection to 892 the ACAP server. If no user name or authentication mechanism is 893 supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by 894 default. If the URL supplies just a user name, the program 895 interpreting the ACAP URL SHOULD request a password from the user if 896 necessary. 898 An authentication mechanism can be expressed by adding 899 ";AUTH=" to the end of the user name. When such an 900 is indicated, the client SHOULD request appropriate 901 credentials from that mechanism and use the "AUTHENTICATE" command. 903 Internet DRAFT ACAP June 19, 1997 905 If no user name is specified, one SHOULD be obtained from the 906 mechanism or requested from the user as appropriate. 908 The string ";AUTH=*" indicates that the client SHOULD select an 909 appropriate authentication mechanism. It MAY use any mechanism 910 listed in the initial ACAP response. If no user name is specified 911 and no appropriate authentication mechanisms are available, the 912 client SHOULD fall back to anonymous login as described above. This 913 allows a URL which grants read-write access to authorized users, and 914 read-only anonymous access to other users. 916 Note that if unsafe or reserved characters such as " " or ";" are 917 present in the user name or authentication mechanism, they MUST be 918 encoded as described in the URL specification [BASIC-URL]. 920 3.2.2. Relative ACAP URLs 922 Because ACAP uses "/" as the hierarchy separator for dataset paths, 923 it works well with the relative URL rules defined in the relative URL 924 specification [REL-URL]. 926 The grammar element is considered part of the user name for 927 purposes of resolving relative ACAP URLs. 929 The base URL for a relative URL stored in an attribute's value is 930 formed by taking the path to the dataset containing that attribute, 931 appending a "/" followed by the entry name of the entry containing 932 that attribute followed by "/". 934 3.3. Contexts 936 A context is subset of entries in a dataset or datasets, created by a 937 SEARCH command with a MAKECONTEXT modifier. Context names are 938 client-generated strings and must not start with the slash ('/') 939 character. 941 When a client creates a context, it may request automatic 942 notification of changes. A client may also request enumeration of 943 entries within a context. Enumeration simplifies the implementation 944 of a "virtual scrollbar" by the client. 946 A context exists only within the ACAP session it was created. When 947 the connection is closed, all contexts associated with that 948 connection are automatically discarded. A server is required to 949 support at least 100 active contexts within a session. If the server 950 supports a larger limit it must advertise it in a CONTEXTLIMIT 951 capability. 953 Internet DRAFT ACAP June 19, 1997 955 3.4. Comparators 957 A comparator is a named function which takes two input values and can 958 be used to perform one or more of three comparison operations: 959 ordering, equality and substring matching. 961 The ordering operation is used both for the SORT search modifier and 962 the COMPARE and COMPARESTRICT search keys. Ordering comparators can 963 determine the ordinal precedence of any two values. When used for 964 ordering, a comparator's name can be prefixed with "+" or "-" to 965 indicate that the ordering should be normal order or reversed order 966 respectively. If no prefix is included, "+" is assumed. 968 For the purpose of ordering, a comparator may designate certain 969 values as having an undefined ordinal precedence. Such values always 970 collate with equal value after all other values regardless of whether 971 normal or reversed ordering is used. Unless the comparator 972 definition specifies otherwise, multi-values and NIL values have an 973 undefined ordinal precedence. 975 The equality operation is used for the EQUAL search modifier, and 976 simply determines if the two values are considered equal under the 977 comparator function. When comparing a single value to a multi-value, 978 the two are considered equal if any one of the multiple values is 979 equal to the single value. 981 The substring match operation is used for the PREFIX and SUBSTRING 982 search modifiers, and simply determines if search value is a prefix 983 or a substring of the item being searched. In the case of substring 984 search on a multi-valued attribute, the match is successful if the 985 value is a prefix or substring of any one of the multiple values. 987 Additional comparators may be registered with the Internet Assigned 988 Number Authority (IANA) according to the rules in section ###. 989 Servers MUST respond to unknown or improperly used comparators with a 990 BAD command completion result. 992 The following comparators are defined by this standard: 994 octet 995 Operations: Ordering, Equality, Substring match 997 For collation, the octet comparator interprets the value of 998 an attribute as a series of unsigned octets with ordinal 999 values from 0 to 255. When ordering two strings, each octet 1000 pair is compared in sequence until the octets are unequal or 1001 the end of the string is reached. When collating two strings 1002 where the shorter is a prefix of the longer, the shorter 1004 Internet DRAFT ACAP June 19, 1997 1006 string is interpreted as having a smaller ordinal value. The 1007 "octet" or "+octet" forms collate smaller ordinal values 1008 earlier, and the "-octet" form collates larger ordinal values 1009 earlier. 1011 For the equality function, two strings are equal if they are 1012 the same length and contain the same octets in the same 1013 order. NIL is equal only to itself. 1015 For non-binary, non-nil single values, octet ordering is 1016 equivalent to the ANSI C [ISO-C] strcmp() function applied to 1017 C string representations of the values. For non-binary, 1018 non-nil single values, octet substring match is equivalent to 1019 the ANSI C strstr() function applied to the C string 1020 representations of the values. 1022 en-nocase 1023 Operations: Ordering, Equality, Substring match 1025 The en-nocase comparator first applies a mapping to the 1026 attribute values which translates all US-ASCII letters to 1027 uppercase (octet values 0x61 to 0x7A are translated to octet 1028 values 0x41 to 0x5A respectively), then applies the octet 1029 comparator as described above. With this function the values 1030 "hello" and "HELLO" have the same ordinal value and are 1031 considered equal. 1033 numeric 1034 Operations: Ordering, Equality 1036 The numeric comparator interprets strings as decimal positive 1037 integers represented as US-ASCII digits. All values which do 1038 not begin with a US-ASCII digit are considered equal with an 1039 ordinal value higher than all non-NIL single-valued 1040 attributes. Otherwise, all US-ASCII digits (octet values 1041 0x30 to 0x39) are interpreted starting from the beginning of 1042 the string to the first non-digit or the end of the string. 1044 3.5. Access Control Lists (ACLs) 1046 An access control list is a set of identifier,rights pairs used to 1047 restrict access to a given dataset, attribute or attribute within an 1048 entry. An ACL is represented by a multi-value with each value 1049 containing the identifier followed by a tab character followed by the 1050 rights. The syntax is defined by the "acl" rule in the formal syntax 1051 in section ###. 1053 Internet DRAFT ACAP June 19, 1997 1055 Identifier is a UTF-8 string. The identifier "anyone" is reserved to 1056 refer to the universal identity (all authentications, including 1057 anonymous). All user name strings accepted by the AUTHENTICATE 1058 command to authenticate to the ACAP server are reserved as 1059 identifiers for the corresponding user. Identifiers starting with a 1060 dash ("-") are reserved for "negative rights", described below. All 1061 other identifier strings have implementation-defined meanings. 1063 Rights is a string listing a (possibly empty) set of alphanumeric 1064 characters, each character listing a set of operations which is being 1065 controlled. Letters are reserved for "standard" rights, listed 1066 below. The set of standard rights may only be extended by a 1067 standards-track or IESG approved experimental RFC. Digits are 1068 reserved for implementation or site defined rights. The currently 1069 defined standard rights are: 1071 r - read 1072 w - write 1073 i - insert (perform store on a previously NIL value) 1074 a - administer (perform store on ACL attribute/metadata) 1076 An implementation may force rights to always or never be granted. In 1077 particular, implementations are expected to grant implicit read and 1078 administer rights to a user's personal dataset storage in order to 1079 avoid denial of service problems. Rights are never tied, unlike the 1080 IMAP ACL extension [IMAP-ACL]. 1082 It is possible for multiple identifiers in an access control list to 1083 apply to a given user (or other authentication identity). For 1084 example, an ACL may include rights to be granted to the identifier 1085 matching the user, one or more implementation-defined identifiers 1086 matching groups which include the user, and/or the identifier 1087 "anyone". How these rights are combined to determine the user's 1088 access is implementation-defined. An implementation may choose, for 1089 example, to use the union of the rights granted to the applicable 1090 identifiers. An implementation may instead choose, for example, to 1091 only use those rights granted to the most specific identifier present 1092 in the ACL. A client may determine the set of rights granted to the 1093 logged-in user for a given mailbox by using the MYRIGHTS command. 1095 When an identifier in an ACL starts with a dash ("-"), that indicates 1096 that associated rights are to be removed from the identifier that is 1097 prefixed by the dash. For example, if the identifier "-fred" is 1098 granted the "w" right, that indicates that the "w" right is to be 1099 removed from users matching the identifier "fred". Implementations 1100 need not support having identifiers which start with a dash in ACLs. 1102 Each attribute of each entry of a dataset may potentially have an 1104 Internet DRAFT ACAP June 19, 1997 1106 ACL. If an attribute in an entry does not have an ACL, then access 1107 is controlled by a default ACL for that attribute in the dataset, if 1108 it exists. If there is no default ACL for that attribute in the 1109 dataset, access is controlled by a default ACL for that dataset. The 1110 default ACL for a dataset must exist. 1112 In order to perform any access or manipulation on an entry in a 1113 dataset, the client must have 'r' rights on the "entry" attribute of 1114 the entry. Implementations should take care not to reveal via error 1115 messages the existence of an entry for which the client does not have 1116 attribute of the parent dataset in order to access the contents of a 1117 dataset. 1119 Many of the ACL commands and responses include an "acl object" 1120 parameter, for specifying what the ACL applies to. This is a 1121 parenthesized list. The list contains just the dataset name when 1122 referring to the default ACL for a dataset. The list contains a 1123 dataset name and an attribute name when referring to the default ACL 1124 for an attribute in a dataset. The list contains a dataset name, an 1125 attribute name, and an entry name when referring to the ACL for an 1126 attribute of an entry of a dataset. 1128 3.6. Server Response Codes 1130 An OK, NO, BAD, ALERT or BYE response from the server MAY contain a 1131 response code to describe the event in a more detailed machine 1132 parsable fashion. A response code consists of data inside 1133 parentheses in the form of an atom, possibly followed by a space and 1134 arguments. Response codes are defined when there is a specific 1135 action that a client can take based upon the additional information. 1137 The currently defined response codes are: 1139 ENCRYPT-NEEDED 1140 This response code is returned on a tagged NO result from an 1141 AUTHENTICATE command. It indicates that site security policy 1142 requires the use of a strong encryption mechanism for the 1143 specified authentication identity. 1145 INVALID 1146 This response code indicates that a STORE command included 1147 data which the server implementation does not permit. It 1148 MUST NOT be used unless the dataset class specification for 1149 the attribute in question explicitly permits enforced server 1151 Internet DRAFT ACAP June 19, 1997 1153 validation. The argument is the attribute which was invalid. 1155 MODIFIED 1156 This response code indicates that a conditional store failed 1157 because the modtime on the entry is later than the modtime 1158 specified with the STORE command UNCHANGEDSINCE modifier. 1159 The argument is the entry which had been modified. 1161 NOEXIST 1162 This response code indicates that a search or NOCREATE store 1163 failed because a specified dataset did not exist. The 1164 argument is the dataset which does not exist. 1166 PERMISSION 1167 A command failed due to insufficient permission based on the 1168 access control list or implicit rights. The argument is the 1169 acl-object which caused the permission failure. 1171 PLAINTEXT-DENIED 1172 This response code is returned on a tagged NO result from an 1173 AUTHENTICATE PLAIN command. It indicates that site security 1174 policy forbids the use of plain text passwords for the 1175 specified authentication identity. 1177 QUOTA 1178 A STORE command which would have increased the size of the 1179 dataset failed due to insufficient quota. 1181 REFER 1182 This response code may be returned in a tagged NO response to 1183 any command that takes a dataset name as a parameter. It has 1184 one or more arguments with the syntax of relative URLs. It 1185 is a referral, indicating that the command should be retried 1186 using one of the relative URLs. 1188 TOOMANY 1189 This response code may be returned in a tagged OK response to 1190 a SEARCH command which includes the LIMIT modifier. The 1191 argument returns the total number of matching entries. 1193 TRANSITION-NEEDED 1194 This response code occurs on a NO response to an AUTHENTICATE 1195 command with a mechanism other than PLAIN or ANONYMOUS. It 1196 indicates that the PLAIN SASL [SASL-PLAIN] mechanism is 1197 needed prior to using the stronger mechanism requested. 1199 TRYCACHE 1200 A STORE or SETACL command failed due to a temporary server 1202 Internet DRAFT ACAP June 19, 1997 1204 failure. If the client caches the command, it may succeed 1205 during a later cache replay. 1207 TRYFREECONTEXT 1208 This response code may be returned in a tagged NO response to 1209 a SEARCH command which includes the MAKECONTEXT modifier. It 1210 indicates that a new context may not be created due to the 1211 server's limit on the number of existing contexts. 1213 WAYTOOMANY 1214 This response code may be returned in a tagged NO response to 1215 a SEARCH command which includes a HARDLIMIT search modifier. 1216 It indicates that the SEARCH would have returned more entries 1217 than the HARDLIMIT permitted. 1219 Additional response codes MUST be registered with IANA according 1220 to the proceedures in section ###. Client implementations MUST 1221 ignore response codes that they do not recognize. 1223 4. Namespace Conventions 1225 4.1. Dataset Namespace 1227 The dataset namespace is a slash-separated hierarchy. The first 1228 component of the dataset namespace is a dataset class. Dataset 1229 classes MUST have a vendor prefix (vendor.) or be 1230 standards track or IESG approved experimental RFCs. See section ### 1231 for the registration template. 1233 The second component of the dataset name is "site", "group", "host", 1234 or "user" referring to server-wide data, administrative group data, 1235 per-host data and per-user data respectively. 1237 For "group", "host", and "user" areas, the third component of the 1238 path is the group name, the fully qualified host domain name, or the 1239 user name. A path of the form "//~/" is a convenient 1240 abbreviation for "//user//". 1242 Dataset names which begin with "/byowner/" are reserved as an 1243 alternate view of the namespace. This provides a way to see all the 1244 dataset classes which a particular owner uses. For example, 1245 "/byowner/~//" is an alternate name for "//~/". Byowner provides a way to view a list of dataset classes 1247 owned by a given user; this is done using the dataset 1248 "/byowner/user//" with the NOINHERIT SEARCH modifier. 1250 The dataset "/" may be used to find all dataset classes visible to 1251 the current user. A dataset of the form "//user/" may 1253 Internet DRAFT ACAP June 19, 1997 1255 be used to find all users which have made a dataset or entry of that 1256 class visible to the current user. 1258 The formal syntax for a dataset name is defined by the "dataset-name" 1259 terminal in section ###. 1261 4.2. Attribute Namespace 1263 Attribute names which do not contain a dot (".") are reserved for 1264 standardized attributes which have meaning in any dataset. In order 1265 to simplify implementations, the attribute namespace is intended to 1266 be unique across all datasets. To achieve this, attribute names are 1267 prefixed with the dataset class name followed by a dot ("."). 1268 Attributes which effect management of the dataset are prefixed with 1269 "dataset.". In addition, a subtree of the "vendor." attribute 1270 namespace may be registered with IANA according to the rules in 1271 section ###. ACAP implementors are encouraged to help define 1272 interoperable dataset classes specifications rather than using the 1273 private attribute namespace. 1275 Finally, the "user.." and "site." subtrees of the 1276 attribute namespace are reserved for user-specific and site-specific 1277 attributes respectively. Such attributes are not interoperable so 1278 are discouraged in favor of defining standard attributes. A future 1279 extension is expected to permit discovery of syntax for user or 1280 site-specific attributes. Clients wishing to support display of user 1281 or site-specific attributes should display the value of any non-NIL 1282 single-valued "user.." or "site." attribute which has 1283 valid UTF-8 syntax. 1285 The formal syntax for an attribute name is defined by the 1286 "attribute-name" terminal in the next section. 1288 4.3. Formal Syntax for Dataset and Attribute Namespace 1290 The naming conventions for datasets and attributes are defined by the 1291 following ABNF. Note that this grammar is not part of the ACAP 1292 protocol syntax in section ###, as dataset names and attribute names 1293 are encoded as strings within the ACAP protocol. 1295 attribute-dacl = "dataset.acl" *("." name-component) 1297 attribute-dset = dataset-std 1*("." name-component) 1298 ;; MUST be defined in a dataset class specification 1300 attribute-name = attribute-std / attr-site / attr-user / vendor-name 1302 Internet DRAFT ACAP June 19, 1997 1304 attribute-std = "entry" / "subdataset" / "modtime" / "dataset.inherit" 1305 / attribute-dacl / attribute-dset 1307 attr-site = "site" 1*("." name-component) 1309 attr-user = "user." name-component 1*("." name-component) 1311 byowner = "/byowner/" owner "/" [dataset-class "/" dataset-sub] 1313 dataset-class = dataset-std / vendor-name 1315 dataset-normal = "/" [dataset-class "/" (owner-prefix / dataset-tail)] 1317 dataset-name = byowner / dataset-normal 1319 dataset-std = name-component 1320 ;; MUST be registered with IANA and the spec MUST 1321 ;; be published as a standards track or 1322 ;; IESG-approved experimental RFC 1324 dataset-sub = *(dname-component "/") 1325 ;; The rules for this portion of the namespace may 1326 ;; be further restricted by the dataset class 1327 ;; specification. 1329 dataset-tail = owner "/" dataset-sub 1331 dname-component = 1*UTF8-CHAR 1332 ;; MUST NOT begin with "." or contain "/" 1334 name-component = 1*UTF8-CHAR 1335 ;; MUST NOT contain ".", "/", "%", or "*" 1337 owner = "site" / owner-host / owner-group / owner-user / "~" 1339 owner-group = "group/" dname-component 1341 owner-host = "host/" dname-component 1343 owner-prefix = "group/" / "host/" / "user/" 1345 owner-user = "user/" dname-component 1347 vendor-name = vendor-token *("." name-component) 1349 vendor-token = "vendor." name-component 1350 ;; MUST be registered with IANA 1352 Internet DRAFT ACAP June 19, 1997 1354 5. Dataset Management 1356 The entry with an empty name ("") in the dataset is used to hold 1357 management information for the dataset as a whole. 1359 5.1. Dataset Inheritance 1361 It is possible for one dataset to inherit data from another. The 1362 dataset from which the data is inherited is called the base dataset. 1363 Data in the base dataset appears in the inheriting dataset, except 1364 where overridden by data in the inheriting dataset. 1366 The base dataset is usually a system-wide or group-wide set of 1367 defaults. A system-wide dataset usually has one inheriting dataset 1368 per user, allowing each user to add to or modify the defaults as 1369 appropriate. 1371 An entry which exists in both the inheriting and inherited dataset 1372 has a modtime equal to the greater of the modtimes for the purposes 1373 of a SEARCH command and context notification. Inheritance has no 1374 effect on the STORE command, except that if NIL is stored to an 1375 attribute and there is a default value in a base dataset, then an 1376 ENTRY response is returned to notify the client of the change. 1378 The "subdataset" attribute is not directly inherited. If the base 1379 dataset includes a "subdataset" attribute and the inheriting dataset 1380 does not, then the "subdataset" attribute will inherit a virtual 1381 value of a list containing a ".". The subdataset at that node is 1382 said to be a "virtual" dataset as it is simply a virtual copy of the 1383 appropriate base dataset with all "subdataset" attributes changed to 1384 a list containing a ".". A virtual dataset is not visible if 1385 NOINHERIT is specified on the SEARCH command. 1387 Servers MUST support at least two levels of inheritance. This 1388 permits a user's dataset such as "/options/user/fred/common" to 1389 inherit from a group dataset such as "/options/group/dinosaur 1390 operators/common" which in turn inherits from a server-wide dataset 1391 such as "/options/site/common". 1393 5.2. Dataset Attributes 1395 The following attributes apply to management of the dataset when 1396 stored in the "" entry of a dataset. These attributes are not 1397 inherited. 1399 Internet DRAFT ACAP June 19, 1997 1401 dataset.acl 1402 This holds the default access control list for the dataset. It 1403 can not be modified by the STORE command, only by the SETACL and 1404 DELETEACL commands. 1406 dataset.acl. 1407 This holds the default access control list for an attribute 1408 within the dataset. It can not be modified by the STORE command, 1409 only by the SETACL and DELETEACL commands. 1411 dataset.inherit 1412 This holds the name of a dataset to inherit according to the 1413 rules in section ###. This attribute may refer to a non- 1414 existent dataset, in which case nothing is inherited. 1416 5.3. Dataset Creation 1418 When a dataset is first created (by storing a "." in the subdataset 1419 attribute or storing an entry in a previously non-existent dataset), 1420 the dataset attributes are initialized with the values from the 1421 parent dataset in the "/byowner/" hierarchy. In the case of the 1422 "dataset.inherit" attribute, the appropriate hierarchy component is 1423 added. For example, given the following entry: 1425 entry path "/byowner/user/joe/" 1426 dataset.acl ("joe" "rwia") 1427 dataset.inherit "/byowner/site" 1429 If a new dataset class "/byowner/~/new" is created, it will have the 1430 following dataset attributes: 1432 entry path "/byowner/user/joe/new/" 1433 dataset.acl ("joe" "rwia") 1434 dataset.inherit "/byowner/site/new" 1436 Note that the dataset "/byowner/user/joe/new/" is equivalent to 1437 "/new/user/joe/". 1439 5.4. Dataset Class Capabilities 1441 Certain dataset classes or dataset class features may only be useful 1442 if there is an active updating client or integrated server support 1443 for the feature. The dataset class "capability" is reserved to allow 1444 clients or servers to advertise such features. The "entry" attribute 1445 within this dataset class is the name of the dataset class whose 1446 features are being described. The attributes are prefixed with 1447 "capability.." and are defined by the appropriate 1449 Internet DRAFT ACAP June 19, 1997 1451 dataset class specification. 1453 Since it is possible for an unprivileged user to run an active client 1454 for himself, a per-user capability dataset is useful. The dataset 1455 "/capability/~/" holds information about all features available to 1456 the user (via inheritance), and the dataset "/capability/site/" holds 1457 information about all features supported by the site. 1459 5.5. Dataset Quotas 1461 The dataset class "quota" is reserved for quota management. Each 1462 node of the "/byowner" view of the ACAP namespace MAY have an 1463 associated entry in the quota dataset class. A quota root is a quota 1464 limit and usage listed in the "quota" dataset class which applies to 1465 a sub-tree of the ACAP "/byowner" name-space exempting all parts of 1466 that sub-tree with their own quota root. 1468 A quota limit specifies the total number of bytes a sub-tree of the 1469 ACAP name-space may consume exempting all parts of that sub-tree with 1470 their own quota roots. The actual number of bytes which a dataset or 1471 entry consumes is implementation dependent. However two rules are 1472 necessary to promote interoperability: 1474 1) Removing an entry or dataset MUST reduce the quota usage. 1476 2) A STORE command MUST NOT fail with a quota error if for all entry 1477 modifications under a given quota root the sum of the lengths of the 1478 attribute names and values is less then the quota limit minus the 1479 quota usage. For some implementations, it MAY be necessary to allow 1480 the quota usage to exceed the quota limit in order to satisfy this 1481 rule. Note that a STORE command MAY succeed even if there does not 1482 appear to be enough space. 1484 The algorithm for locating a quota root for a dataset is as follows. 1485 First, if the dataset name does not begin with "/byowner", then the 1486 name is mapped appropriately. Second, the "/byowner" is replaced 1487 with "/quota". Third, any trailing "/" is removed. If the resulting 1488 entry-path contains a "quota.limit" attribute, that is the quota 1489 root. Otherwise, the last component of the entry path is removed, 1490 and the previous step is repeated. The GETQUOTA command implements 1491 this algorithm in order to simplify ACAP clients. 1493 The quota dataset class itself is exempt from quota management. ACAP 1494 implementations SHOULD apply a very restrictive default ACL to quota 1495 datasets. 1497 The creation of a new quota root SHOULD NOT be automatically linked 1498 to the creation of a dataset. Quota roots MAY be completely 1500 Internet DRAFT ACAP June 19, 1997 1502 independent, or MAY reduce the limit of their parent quota root on 1503 creation. Quota roots SHOULD NOT be nested -- modifying data should 1504 only effect the usage within one quota root. When a quota limit is 1505 removed (by storing NIL in quota.limit), its usage is added to the 1506 parent quota root, and its limit MAY be added to the parent quota 1507 root. 1509 The following attributes are defined within the quota dataset class: 1511 quota.limit 1512 This is single-valued. The syntax for this value follows the 1513 "number" rule defined below. This represents the quota limit, 1514 in bytes, as defined in section ###. 1516 quota.usage 1517 This is single-valued. The syntax for this value follows the 1518 "number" rule defined below. This is the quota usage in bytes. 1519 It MAY be greater than the quota limit. 1521 Because it can require excessive computation for some 1522 implementations, ACAP servers MAY respond with NO to a SEARCH command 1523 requesting context notification for the quota.usage attribute. 1525 6. Command and Response Specifications 1527 ACAP commands and responses are described in this section. Commands 1528 are organized first by the state in which the command is permitted, 1529 then by a general category of command type. 1531 Command arguments, identified by "Arguments:" in the command 1532 descriptions below, are described by function, not by syntax. The 1533 precise syntax of command arguments is described in the Formal Syntax 1534 section. 1536 Some commands cause specific server data to be returned; these are 1537 identified by "Data:" in the command descriptions below. See the 1538 response descriptions in the Responses section for information on 1539 these responses, and the Formal Syntax section for the precise syntax 1540 of these responses. It is possible for server data to be transmitted 1541 as a result of any command; thus, commands that do not specifically 1542 require server data specify "no specific data for this command" 1543 instead of "none". 1545 The "Result:" in the command description refers to the possible 1546 tagged status responses to a command, and any special interpretation 1547 of these status responses. 1549 Internet DRAFT ACAP June 19, 1997 1551 6.1. Initial Connection 1553 Upon session startup, the server sends one of two untagged responses: 1554 ACAP or BYE. The untagged BYE response is described in section ###. 1556 6.1.1. ACAP Untagged Response 1558 Data: capability list 1560 The untagged ACAP response indicates the session is ready to 1561 accept commands and contains a space-separated listing of 1562 capabilities that the server supports. Each capability is 1563 represented by a list containing the capability name optionally 1564 followed by capability specific string arguments. 1566 ACAP capability names MUST be defined in a standards track or IESG 1567 approved experimental RFC and registered with IANA according to 1568 the rules in section ###. 1570 Client implementations SHOULD NOT require any capability name, and 1571 MUST ignore any unknown capability names. 1573 The following initial capabilities are defined: 1575 COMPARATORS 1576 The COMPARATORS capability includes a list of the comparator 1577 functions which the server supports. See section ### for a 1578 description of comparators. 1580 CONTEXTLIMIT 1581 The CONTEXTLIMIT capability has one argument which is a 1582 number describing the maximum number of contexts the server 1583 supports per connection. The number 0 indicates the server 1584 has no limit, otherwise this number MUST be greater than 1585 100. 1587 IMPLEMENTATION 1588 The IMPLEMENTATION capability has one argument which is a 1589 string describing the server implementation. ACAP clients 1590 MUST NOT alter their behavior based on this value. It is 1591 intended primarily for debugging purposes. 1593 SASL The SASL capability includes a list of the authentication 1594 mechanisms supported by the server. See section ###. 1596 Example: S: * ACAP (IMPLEMENTATION "ACME v3.5") 1597 (SASL "CRAM-MD5" "PLAIN") (CONTEXTLIMIT "200") 1599 Internet DRAFT ACAP June 19, 1997 1601 6.2. Any State 1603 The following commands and responses are valid in any state. 1605 6.2.1. NOOP Command 1607 Arguments: none 1609 Data: no specific data for this command (but see below) 1611 Result: OK - noop completed 1612 BAD - command unknown or arguments invalid 1614 The NOOP command always succeeds. It does nothing. It can be 1615 used to reset any inactivity auto-logout timer on the server. 1617 Example: C: a002 NOOP 1618 S: a002 OK "NOOP completed" 1620 6.2.2. LANG Command 1622 Arguments: optional list of language preferences 1624 Data: untagged response: LANG 1626 Result: OK - lang completed 1627 NO - no matching language available 1628 BAD - command unknown or arguments invalid 1630 The LANG command with no arguments generates an untagged LANG 1631 response including a list of languages which the server supports 1632 for localized error text strings. If one or more arguments are 1633 supplied they indicate the client's preferred languages for error 1634 messages. The server will match each client preference in order 1635 against its internal table of available error strings languages. 1636 For a client preference to match a server language table, the 1637 client's language tag MUST be a prefix of the server's tag and 1638 match up to a "-" or the end of string. If a match is found, the 1639 server returns an OK response. If no match is found, the server 1640 returns an untagged LANG response followed by a NO response. 1642 If no LANG command is issued, all error text strings MUST be in 1643 English. This rule is necessary because the default error text 1644 has to be in a language which is understandable by any pair of 1645 client and server vendors (since both have to diagnose problems). 1646 In addition, the default language for errors has to use the 1648 Internet DRAFT ACAP June 19, 1997 1650 US-ASCII subset of UTF-8, since it can be displayed on the largest 1651 number of computers. 1653 Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" 1654 S: A003 OK "Bonjour" 1656 6.2.3. LANG Untagged Response 1658 Data: list of supported language tags 1660 The LANG response indicates the languages supported for server 1661 error messages. 1663 Example: C: N004 LANG 1664 S: * LANG "fr-ca" "en-ca" 1665 S: N004 OK "LANG completed" 1667 6.2.4. LOGOUT Command 1669 Arguments: none 1671 Data: mandatory untagged response: BYE 1673 Result: OK - logout completed 1674 BAD - command unknown or arguments invalid 1676 The LOGOUT command informs the server that the client is done with 1677 the session. The server must send a BYE untagged response before 1678 the (tagged) OK response, and then close the network connection. 1680 Example: C: A023 LOGOUT 1681 S: * BYE "ACAP Server logging out" 1682 S: A023 OK "LOGOUT completed" 1683 (Server and client then close the connection) 1685 6.2.5. OK Response 1687 Data: optional response code 1688 human-readable text 1690 The OK response indicates an information message from the server. 1691 When tagged, it indicates successful completion of the associated 1692 command. The human-readable text may be presented to the user as 1693 an information message. The untagged form indicates an 1694 information-only message; the nature of the information may be 1696 Internet DRAFT ACAP June 19, 1997 1698 indicated by a response code. 1700 Example: S: * OK "XXX - need good example" 1702 6.2.6. NO Response 1704 Data: optional response code 1705 human-readable text 1707 The NO response indicates an operational error message from the 1708 server. When tagged, it indicates unsuccessful completion of the 1709 associated command. The untagged form indicates a warning; the 1710 command may still complete successfully. The human-readable text 1711 describes the condition. 1713 Example: C: A010 SEARCH ... 1714 S: * NO "Master ACAP server is down, your data may 1715 be out of date." 1716 S: A010 OK "search done" 1717 ... 1718 C: A222 STORE ("/folder/comp.mail.misc" 1719 "folder.creation-time" "19951206103412") 1720 S: A222 NO (PERMISSION ("/folder/")) "Permission denied" 1722 6.2.7. BAD Response 1724 Data: optional response code 1725 human-readable text 1727 The BAD response indicates an error message from the server. When 1728 tagged, it reports a protocol-level error in the client's command; 1729 the tag indicates the command that caused the error. The untagged 1730 form indicates a protocol-level error for which the associated 1731 command can not be determined; it may also indicate an internal 1732 server failure. The human-readable text describes the condition. 1734 Example: C: ...empty line... 1735 S: * BAD "Empty command line" 1736 C: A443 BLURDYBLOOP 1737 S: A443 BAD "Unknown command" 1738 C: A444 NOOP Hello 1739 S: A444 BAD "invalid arguments" 1741 Internet DRAFT ACAP June 19, 1997 1743 6.2.8. BYE Untagged Response 1745 Data: optional response code 1746 human-readable text 1748 The untagged BYE response indicates that the server is about to 1749 close the connection. The human-readable text may be displayed to 1750 the user in a status report by the client. The BYE response may 1751 be sent as part of a normal logout sequence, or as a panic 1752 shutdown announcement by the server. It is also used by some 1753 server implementations as an announcement of an inactivity auto- 1754 logout. 1756 This response is also used as one of two possible greetings at 1757 session startup. It indicates that the server is not willing to 1758 accept a session from this client. 1760 Example: S: * BYE "Auto-logout; idle for too long" 1762 6.2.9. ALERT Untagged Response 1764 Data: optional response code 1765 human-readable text 1767 The human-readable text contains a special human generated alert 1768 message that MUST be presented to the user in a fashion that calls 1769 the user's attention to the message. This is intended to be used 1770 for vital messages from the server administrator to the user, such 1771 as a warning that the server will soon be shut down for 1772 maintenance. 1774 Example: S: * ALERT "This ACAP server will be shut down in 1775 10 minutes for system maintenance." 1777 6.3. Non-Authenticated State 1779 In non-authenticated state, the AUTHENTICATE command establishes 1780 authentication and enters authenticated state. The AUTHENTICATE 1781 command provides a general mechanism for a variety of authentication 1782 techniques. 1784 Server implementations may allow non-authenticated access to certain 1785 information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism. 1787 Once authenticated (including as anonymous), it is not possible to 1788 re-enter non-authenticated state. 1790 Internet DRAFT ACAP June 19, 1997 1792 Only the any-state commands (NOOP, LANG and LOGOUT) and the 1793 AUTHENTICATE command are valid in non-authenticated state. 1795 6.3.1. AUTHENTICATE Command 1797 Arguments: SASL mechanism name 1798 optional initial response 1800 Data: continuation data may be requested 1802 Result: OK - authenticate completed, now in authenticated state 1803 NO - authenticate failure: unsupported authentication 1804 mechanism, credentials rejected 1805 BAD - command unknown or arguments invalid, 1806 authentication exchange cancelled 1808 The AUTHENTICATE command indicates an authentication mechanism to 1809 the server. If the server supports the requested authentication 1810 mechanism, it performs an authentication protocol exchange to 1811 authenticate and identify the user. Optionally, it also 1812 negotiates a security layer for subsequent protocol interactions. 1813 If the requested authentication mechanism is not supported, the 1814 server rejects the AUTHENTICATE command by sending a tagged NO 1815 response. 1817 The authentication protocol exchange consists of a series of 1818 server challenges and client answers that are specific to the 1819 authentication mechanism. A server challenge consists of a 1820 command continuation request with the "+" token followed by a 1821 BASE64 encoded string. The client answer consists of a line 1822 consisting of a BASE64 encoded string. If the client wishes to 1823 cancel an authentication exchange, it should issue a line with a 1824 single "*". If the server receives such an answer, it must reject 1825 the AUTHENTICATE command by sending a tagged BAD response. 1827 The optional initial-response argument to the AUTHENTICATE command 1828 is used to save a round trip when using authentication mechanisms 1829 that are defined to send no data in the initial challenge. When 1830 the initial-response argument is used with such a mechanism, the 1831 initial empty challenge is not sent to the client and the server 1832 uses the data in the initial-response argument as if it were sent 1833 in response to the empty challenge. If the initial-response 1834 argument to the AUTHENTICATE command is used with a mechanism 1835 that sends data in the initial challenge, the server rejects the 1836 AUTHENTICATE command by sending a tagged NO response. 1838 The service name specified by this protocol's profile of SASL is 1840 Internet DRAFT ACAP June 19, 1997 1842 "acap". 1844 If a security layer is negotiated through the SASL authentication 1845 exchange, it takes effect immediately following the CRLF that 1846 concludes the authentication exchange for the client, and the CRLF 1847 of the tagged OK response for the server. 1849 All ACAP implementations MUST support the PLAIN SASL mechanism 1850 [SASL-PLAIN], although they MAY offer a configuration option to 1851 disable plaintext passwords if site security policy dictates. 1852 ACAP implementations SHOULD support an external encryption service 1853 or a stronger standards track SASL mechanism. 1855 If an AUTHENTICATE command fails with a NO response, the client 1856 may try another authentication mechanism by issuing another 1857 AUTHENTICATE command. In other words, the client may request 1858 authentication types in decreasing order of preference. 1860 Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5") 1861 (SASL "PLAIN" "KERBEROS_V4") 1862 C: A001 AUTHENTICATE KERBEROS_V4 1863 S: + AmFYig== 1864 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1865 +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd 1866 WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh 1867 S: + or//EoAADZI= 1868 C: DiAF5A4gA+oOIALuBkAAmw== 1869 S: A001 OK "Kerberos V4 authentication successful" 1871 6.4. Searching 1873 This section describes the SEARCH command, for retrieving data from 1874 datasets. 1876 Internet DRAFT ACAP June 19, 1997 1878 6.4.1. SEARCH Command 1880 Arguments: dataset or context name 1881 optional list of modifiers 1882 search criteria 1884 Data: intermediate responses: ENTRY, MODTIME, REFER 1885 untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME 1887 Result: OK - search completed 1888 NO - search failure: can't perform search 1889 BAD - command unknown or arguments invalid 1891 The SEARCH command identifies a subset of entries in a dataset and 1892 returns information on that subset to the client. 1894 The first argument to SEARCH identifies what is to be searched. 1895 If the string begins with a slash ("/"), it is the name of a 1896 dataset to be searched, otherwise it is a name of a context that 1897 was created by a SEARCH command given previously in the session. 1899 A successful SEARCH command MUST result in a MODTIME intermediate 1900 response. 1902 Following that are zero or more modifiers to the search. Each 1903 modifier may be specified at most once. The defined modifiers 1904 are: 1906 DEPTH number 1907 The SEARCH command will traverse the dataset tree up to the 1908 specified depth. ENTRY responses will include the full path 1909 to the entry. A value of "0" indicates that the search 1910 should traverse the entire tree. A value of "1" is the 1911 default and indicates only the specified dataset should be 1912 searched. If a dataset is traversed which is not located on 1913 the current server, then a REFER intermediate response is 1914 returned for that subtree and the search continues. 1916 HARDLIMIT number 1917 If the SEARCH command would result in more than number 1918 entries, the SEARCH fails with a NO completion result with a 1919 WAYTOOMANY response code. 1921 LIMIT number number 1922 Limits the number of intermediate ENTRY responses that the 1923 search may generate. The first numeric argument specifies 1924 the limit, the second number specifies the number of entries 1925 to return if the number of matches exceeds the limit. If the 1927 Internet DRAFT ACAP June 19, 1997 1929 limit is exceeded, the SEARCH command still succeeds, 1930 returning the total number of matches in a TOOMANY response 1931 code in the tagged OK response. 1933 MAKECONTEXT [ENUMERATE] [NOTIFY] context 1934 The SEARCH command creates a context with the name given in 1935 the argument to refer to the matching entries. If the SEARCH 1936 is successful, the context name may then be given as an 1937 argument to subsequent SEARCH commands to search the set of 1938 matching entries. If a context with the specified name 1939 already exists, it is first freed. If a new context may not 1940 be created due to the server's limit on the number of 1941 existing contexts, the command fails, returning a 1942 TRYFREECONTEXT response code in the NO completion response. 1944 The optional "ENUMERATE" and "NOTIFY" arguments may be 1945 included to request enumeration of the context (for virtual 1946 scroll bars) or change notifications for the context. 1948 ENUMERATE requests that the contents of the context be 1949 ordered according to the SORT modifier and that sequential 1950 numbers, starting with one, be assigned to the entries in the 1951 context. This permits the RANGE modifier to be used to fetch 1952 portions of the ordered context. 1954 NOTIFY requests that the server send untagged ADDTO, 1955 REMOVEFROM, CHANGE, and MODTIME responses while the context 1956 created by this SEARCH command exists. The server MAY issue 1957 untagged ADDTO, REMOVEFROM, CHANGE and MODTIME notifications 1958 for a context at any time between the issuing of the SEARCH 1959 command with MAKECONTEXT NOTIFY and the completion of a 1960 FREECONTEXT command for the context. Notifications are only 1961 issued for changes which occur after the server receives the 1962 SEARCH command which created the context. After issuing a 1963 sequence of ADDTO, REMOVEFROM or CHANGE notifications, the 1964 server MUST issue an untagged MODTIME notification indicating 1965 that the client has all updates to the entries in the context 1966 up to and including the given modtime value. Servers are 1967 permitted a reasonable delay to batch change notifications 1968 before sending them to the client. 1970 The position arguments of the ADDTO, REMOVEFROM and CHANGE 1971 notifications are 0 if ENUMERATE is not requested. 1973 NOINHERIT 1974 This causes the SEARCH command to operate without 1975 inheritance. It can be used to tell which values are 1976 explicit overrides. If MAKECONTEXT is also specified, the 1978 Internet DRAFT ACAP June 19, 1997 1980 created context is also not effected by inheritance. 1982 RETURN (metadata...) 1983 Specifies what is to be returned in intermediate ENTRY 1984 responses. If this modifier is not specified, no 1985 intermediate ENTRY responses are returned. 1987 Inside the parentheses is a list of attributes, each 1988 optionally followed by a parenthesized list of metadata. If 1989 the parenthesized list of metadata is not specified, it 1990 defaults to "(value)". 1992 An attribute name with a trailing "*" requests all attributes 1993 with that prefix. A "*" by itself requests all attributes. 1994 If the parenthesized list of metadata is not specified for an 1995 attribute with a trailing "*", it defaults to "(attribute 1996 value)". 1998 Following the last intermediate ENTRY response, the server 1999 returns a single intermediate MODTIME response. 2001 SORT (attribute comparator ...) 2002 Specifies the order in which any resulting ENTRY replies are 2003 to be returned to the client. The SORT modifier takes as an 2004 argument a parenthesized list of one or more 2005 attribute/comparator pairs. Attribute lists the attribute to 2006 sort on, comparator specifies the name of the collation rule 2007 to apply to the values of the attribute. Successive 2008 attribute/comparator pairs are used to order two entries only 2009 when all preceding pairs indicate the two entries collate the 2010 same. 2012 If the SORT modifier is used in conjunction with the 2013 MAKECONTEXT modifier, the SORT modifier specifies the 2014 ordering of entries in the created context. 2016 If no SORT modifier is specified, or none of the 2017 attribute/comparator pairs indicates an order for the two 2018 entries, the server uses the order of the entries that exists 2019 in the context or dataset being searched. 2021 Following the modifiers is the search criteria. Searching 2022 criteria consist of one or more search keys. Search keys may be 2023 combined using the AND, and OR search keys. For example, the 2024 criteria (the newline is for readability and not part of the 2025 criteria): 2027 Internet DRAFT ACAP June 19, 1997 2029 AND COMPARE "modtime" "+octet" "19951206103400" 2030 COMPARE "modtime" "-octet" "19960112000000" 2031 refers to all entries modified between 10:34 December 6 1995 and 2032 midnight January 12, 1996 UTC. 2034 The currently defined search keys are as follows. 2036 ALL This matches all entries. 2038 AND search-key1 search-key2 2039 Entries that match both search keys. 2041 COMPARE attribute comparator value 2042 Entries for which the value of the specified attribute 2043 collates using the specified comparator the same or later 2044 than the specified value. 2046 COMPARESTRICT attribute comparator value 2047 Entries for which the specified attribute collates using the 2048 specified comparator later than the specified value. 2050 EQUAL attribute comparator value 2051 Entries for which the value of the attribute is equal to the 2052 specified value using the specified comparator. 2054 NOT search-key 2055 Entries that do not match the specified search key. 2057 OR search-key1 search-key2 2058 Entries that match either search key. 2060 PREFIX attribute comparator value 2061 Entries which begin with the specified value using the 2062 specified comparator. If the specified comparator doesn't 2063 support substring matching, a BAD response is returned. 2065 RANGE start end time 2066 Entries which are within the specified range of the 2067 enumerated context's ordering. The lowest-ordered entry in 2068 the context is assigned number one, the next lowest entry is 2069 assigned number two, and so on. The numeric arguments 2070 specify the lowest and highest numbers to match. The time 2071 specifies that the client has processed notifications for the 2072 context up to the specified time. If the context has been 2073 modified since then, the server MUST either return a NO with 2074 a MODIFIED response code, or return the results that the 2075 SEARCH would have returned if none of the changes since that 2076 time had been made. 2078 Internet DRAFT ACAP June 19, 1997 2080 RANGE is only permitted on contexts. If RANGE is used with a 2081 dataset, the server MUST return a BAD response. 2083 SUBSTRING attribute comparator value 2084 Entries which contain the specified value, using the 2085 specified comparator. If the specified comparator doesn't 2086 support substring matching, a BAD response is returned. 2088 Example: C: [TODO - write examples] 2090 6.4.2. ENTRY Intermediate Response 2092 Data: entry name 2093 entry data 2095 The ENTRY intermediate response occurs as a result of a SEARCH 2096 command. This is the means by which dataset entries are returned 2097 to the client. The entry with the given name matches the search. 2098 Following the entry name is a set of zero or more lists, one for 2099 each item in the RETURN search modifier, each containing the 2100 requested metadata for the requested attribute(s) within the 2101 entry. 2103 6.4.3. MODTIME Intermediate Response 2105 Data: modtime value 2107 The MODTIME intermediate response occurs as a result of a SEARCH 2108 command. It indicates that the just created context or the 2109 previously returned ENTRY responses include all updates to the 2110 returned entries up to and including the modtime value in the 2111 argument. 2113 6.4.4. REFER Intermediate Response 2115 Data: dataset path 2116 ACAP URL 2118 The REFER intermediate response occurs as a result of a 2119 multi-level SEARCH where one of the levels is located on a 2120 different server. The response indicates the dataset which is not 2121 located on the current server and an ACAP URL for where that 2122 dataset may be found. 2124 Internet DRAFT ACAP June 19, 1997 2126 6.5. Contexts 2128 The following commands use contexts created by a SEARCH command with 2129 a MAKECONTEXT modifier. 2131 6.5.1. FREECONTEXT Command 2133 Arguments: context name 2135 Data: no specific data for this command 2137 Result: OK - freecontext completed 2138 NO - freecontext failure: no such context 2139 BAD - command unknown or arguments invalid 2141 The FREECONTEXT command causes the server to free all state 2142 associated with the named context. The context may no longer be 2143 searched and the server will no longer issue any untagged 2144 responses for the context. The context is no longer counted 2145 against the server's limit on the number of contexts. 2147 Example: C: A683 FREECONTEXT "blurdybloop" 2148 S: A683 OK "Freecontext completed" 2150 6.5.2. UPDATECONTEXT Command 2152 Arguments: list of context names 2154 Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME 2156 Result: OK - Updatecontext completed: all updates completed 2157 NO - Updatecontext failed: no such context 2158 not a notify context 2159 BAD - command unknown or arguments invalid 2161 The UPDATECONTEXT command causes the server to ensure that the 2162 client is notified of all changes to the contexts listed as 2163 arguments up to the current time. The contexts listed in the 2164 arguments must have been previously given to a successful SEARCH 2165 command with a MAKECONTEXT NOTIFY modifier. A MODTIME untagged 2166 response MUST be returned if any read-write metadata in the 2167 context changed since the last MODTIME for that context. This 2168 includes metadata which is not listed in the RETURN modifier for 2169 the context. 2171 While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and 2173 Internet DRAFT ACAP June 19, 1997 2175 MODTIME at any time, the UPDATECONTEXT command is used to "prod" 2176 the server to send any notifications it has not sent yet. 2178 The UPDATECONTEXT command SHOULD NOT be used to poll for updates. 2179 If two or more UPDATECONTEXT commands occur between the delay 2180 period the server uses to generate unsolicited change 2181 notifications, then the server MAY treat all UPDATECONTEXT 2182 commands after the first as NOOP commands to discourage client 2183 polling. 2185 Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl" 2186 S: Z4S9 OK "client has been notified of all changes" 2188 6.5.3. ADDTO Untagged Response 2190 Data: context name 2191 entry name 2192 position 2193 metadata list 2195 The untagged ADDTO response informs the client that an entry has 2196 been added to a context. The response includes the position 2197 number of the added entry (the first entry in the context is 2198 numbered 1) and those metadata contained in the entry which match 2199 the RETURN statement when the context was created. 2201 The ADDTO response implicitly adds one to the position of all 2202 members of the context which had position numbers that were 2203 greater than or equal to the ADDTO position number. 2205 Example: S: * ADDTO "blurdybloop" "fred" 15 2206 ("addressbook.email" "fred@rock.org") 2208 6.5.4. REMOVEFROM Untagged Response 2210 Data: context name 2211 entry name 2212 old position 2214 The untagged REMOVEFROM response informs the client that an entry 2215 has been removed from a context. The response includes the 2216 position number that the removed entry used to have (the first 2217 entry in the context is numbered 1). 2219 The REMOVEFROM response implicitly subtracts one from the position 2220 numbers of all members of the context which had position numbers 2222 Internet DRAFT ACAP June 19, 1997 2224 greater than the REMOVEFROM position number. 2226 Example: S: * REMOVEFROM "blurdybloop" "fred" 15 2228 6.5.5. CHANGE Untagged Response 2230 Data: context name 2231 entry name 2232 old position 2233 new position 2234 metadata list 2236 The untagged CHANGE response informs the client that an entry in a 2237 context has either changed position in the context or has changed 2238 the values of one or more of the attributes specified in the 2239 RETURN modifier when the context was created. 2241 The response includes the previous and current position numbers of 2242 the entry (if ENUMERATE was specified on the context) and the 2243 attribute metadata requested in the RETURN modifier when the 2244 context was created. 2246 The CHANGE response implicitly changes the position numbers of all 2247 entries which had position numbers between the old and new 2248 position. If old position is less than new position, than one is 2249 subtracted from all entries which had position numbers in that 2250 range. Otherwise one is added to all entries which had position 2251 numbers in that range. If the old position and new position are 2252 the same, then no implicit position renumbering occurs. 2254 CHANGE responses are not issued for entries which have changed 2255 position implicitly due to another ADDTO, REMOVEFROM or CHANGE 2256 response. 2258 Example: S: * CHANGE "blurdybloop" "fred" 15 10 2259 ("addressbook.email" "fred@stone.org") 2261 6.5.6. MODTIME Untagged Response 2263 Data: context name 2264 modtime value 2266 The untagged MODTIME response informs the client that it has 2267 received all updates to entries in the context which have modtime 2268 values less than or equal to the modtime value in the argument. 2270 Internet DRAFT ACAP June 19, 1997 2272 Example: S: * MODTIME mycontext "19970320162338" 2274 6.6. Dataset modification 2276 The following commands and responses handle modification of datasets. 2278 6.6.1. STORE Command 2280 Arguments: entry store list 2282 Data: intermediate responses: ENTRY 2284 Result: OK - store completed 2285 NO - store failure: can't store that name 2286 UNCHANGEDSINCE specified and entry changed 2287 BAD - command unknown or arguments invalid 2288 invalid UTF-8 syntax in attribute name 2290 Creates, modifies or deletes the named entries in the named 2291 datasets. The values of metadata not specified in the command are 2292 not changed. Setting the "value" metadata of an attribute to NIL 2293 removes that attribute from the entry. Setting the "value" of the 2294 "entry" attribute to NIL removes that entry from the dataset. 2295 Changing the value of the "entry" attribute renames the entry. 2297 The STORE command is followed by one or more entry store lists. 2298 Each entry store list begins with an entry path followed by STORE 2299 modifiers, followed by zero or more attribute store items. Each 2300 attribute store item is made up of the attribute name followed by 2301 a NIL (to remove the attribute's value), a single value (to set 2302 the attribute's single value), or a list of metadata items to 2303 modify. The following STORE modifiers may be specified: 2305 NOCREATE 2306 By default, the server MUST create any datasets necessary to 2307 store the entry. If NOCREATE is specified, the STORE command 2308 will fail with a NOEXIST error unless the containing dataset 2309 already exists. 2311 UNCHANGEDSINCE 2312 If the "modtime" of the entry is later than the 2313 unchangedsince time, then the store fails with a MODIFIED 2314 response code. Use of UNCHANGEDSINCE with a time of 2315 "00000101000000" will always fail if the entry exists. 2316 Clients writing to a shared dataset are encouraged to use 2317 UNCHANGEDSINCE when modifying an existing entry. 2319 Internet DRAFT ACAP June 19, 1997 2321 The server MUST either make all the changes specified or make none 2322 of them. If successful, the server MUST update the "modtime" 2323 attribute for every entry which was changed. 2325 It is illegal to list any metadata item within an attribute twice, 2326 any attribute within an entry twice or to any entry path twice. 2327 The server MUST return a BAD response if this happens. If the 2328 "modtime" attribute is included in the STORE command, then the 2329 server MUST return a NO response with an ILLEGAL response code. 2331 When NIL is stored to an attribute, and there is an inherited 2332 default value, then an ENTRY intermediate response is generated to 2333 notify the client of this change, this response includes the 2334 attribute name and value metadata for each attribute which 2335 reverted to a non-NIL inherited setting. 2337 Example: C: A342 STORE ("/addressbook/user/fred/ABC547" 2338 "addressbook.phone" "555-1234" 2339 "addressbook.CommonName" "Barney Rubble" 2340 "addressbook.email" NIL) 2341 S: A342 OK "Store completed" 2342 C: A343 STORE ("/addressbook/user/joe/ABD42" 2343 UNCHANGEDSINCE "19970320162338" 2344 "user.joe.hair-length" "10 inches") 2345 S: A343 NO (MODIFIED) "'ABD42' has been changed 2346 by somebody else." 2347 C: A344 STORE ("/addressbook/group/Tech/ACD54" 2348 "entry" NIL) 2349 S: A344 OK "Store completed" 2350 C: A345 STORE ("/option/~/mail/SMTPserver" "value" NIL) 2351 S: A345 ENTRY "SMTPserver" "value" "smtp.server.do.main" 2352 S: A345 OK "Store completed" 2354 6.6.2. DELETEDSINCE Command 2356 Arguments: dataset name 2357 time 2359 Data: intermediate response: DELETED 2361 Result: OK - DELETED completed 2362 NO - DELETED failure: can't read dataset 2363 date too far in the past 2364 BAD - command unknown or arguments invalid 2366 The DELETEDSINCE command returns in intermediate DELETED replies 2368 Internet DRAFT ACAP June 19, 1997 2370 the names of entries that have been deleted from the named dataset 2371 since the given time. 2373 Servers may impose a limit on the number or age of deleted entry 2374 names they keep track of. If the server does not have information 2375 going back to the specified time, the command fails, returning a 2376 TOOOLD response code in the tagged NO response. 2378 Example: C: Z4S9 DELETEDSINCE "/folder/site" 19951205103412 2379 S: Z4S9 DELETED "blurdybloop" 2380 S: Z4S9 DELETED "anteaters" 2381 S: Z4S9 OK "DELETEDSINCE completed" 2382 C: Z4U3 DELETEDSINCE "/folder/site" 19951009040854 2383 S: Z4U3 NO (TOOOLD) "Don't have that information" 2385 6.6.3. DELETED Intermediate Response 2387 Data: entry name 2389 The intermediate DELETED response occurs as a result of a 2390 DELETEDSINCE command. It returns an entry that has been deleted 2391 from the dataset specified in the DELETEDSINCE command. 2393 Example: S: Z4S9 DELETED "blurdybloop" 2395 6.7. Access Control List Commands 2397 The commands in this section are used to manage access control lists. 2399 6.7.1. SETACL Command 2401 Arguments: acl object 2402 authentication identifier 2403 access rights 2405 Data: no specific data for this command 2407 Result: OK - setacl completed 2408 NO - setacl failure: can't set acl 2409 BAD - command unknown or arguments invalid 2411 The SETACL command changes the access control list on the 2412 specified object so that the specified identifier is granted the 2413 permissions enumerated in rights. If the object did not 2414 previously have an access control list, one is created. 2416 Internet DRAFT ACAP June 19, 1997 2418 Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r" 2419 S: A123 OK "Setacl complete" 2420 C: A124 SETACL ("/folder/site/") "B1FF" "rwa" 2421 S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not 2422 permitted to modify access rights 2423 for '/folder/site/'" 2425 6.7.2. DELETEACL Command 2427 Arguments: acl object 2428 optional authentication identifier 2430 Data: no specific data for this command 2432 Result: OK - deleteacl completed 2433 NO - deleteacl failure: can't delete acl 2434 BAD - command unknown or arguments invalid 2436 If given the optional identifier argument, the DELETEACL command 2437 removes any portion of the access control list on the specified 2438 object for the specified identifier. 2440 If not given the optional identifier argument, the DELETEACL 2441 command removes the ACL from the object entirely, causing access 2442 to be controlled by a higher-level default ACL. This form of the 2443 DELETEACL command is not permitted on the default ACL for a 2444 dataset and servers MUST return a BAD. 2446 Example: C: A223 DELETEACL ("/addressbook/~/public") "anyone" 2447 S: A223 OK "Deleteacl complete" 2448 C: A224 DELETEACL ("/folder/site") 2449 S: A224 BAD "Can't delete ACL from dataset" 2450 C: A225 DELETEACL ("/addressbook/user/fred" 2451 "addressbook.email" "barney") 2452 S: A225 OK "Deleteacl complete" 2454 Internet DRAFT ACAP June 19, 1997 2456 6.7.3. MYRIGHTS Command 2458 Arguments: acl object 2460 Data: intermediate responses: MYRIGHTS 2462 Result: OK - myrights completed 2463 NO - myrights failure: can't get rights 2464 BAD - command unknown or arguments invalid 2466 The MYRIGHTS command returns the set of rights that the client has 2467 to the given dataset or dataset attribute. 2469 Example: C: A003 MYRIGHTS ("/folder/site") 2470 S: A003 MYRIGHTS "r" 2471 S: A003 OK "Myrights complete" 2473 6.7.4. MYRIGHTS Intermediate Response 2475 Data: rights 2477 The MYRIGHTS response occurs as a result of a MYRIGHTS command. 2478 The argument is the set of rights that the client has for the 2479 object referred to in the MYRIGHTS command. 2481 6.7.5. LISTRIGHTS Command 2483 Arguments: acl object 2484 authentication identifier 2486 Data: untagged responses: LISTRIGHTS 2488 Result: OK - listrights completed 2489 NO - listrights failure: can't get rights list 2490 BAD - command unknown or arguments invalid 2492 The LISTRIGHTS command takes an object and an identifier and 2493 returns information about what rights may be granted to the 2494 identifier in the ACL for the object. 2496 Example: C: a001 LISTRIGHTS ("/folder") "smith" 2497 S: a001 LISTRIGHTS "r" "w" 2498 S: a001 OK Listrights completed 2499 C: a005 LISTRIGHTS ("/folder/archive.imap") "anyone" 2501 Internet DRAFT ACAP June 19, 1997 2503 S: a005 LISTRIGHTS "" "r" "w" 2504 S: a005 OK Listrights completed 2506 6.7.6. LISTRIGHTS Intermediate Response 2508 Data: required rights 2509 list of optional rights 2511 The LISTRIGHTS response occurs as a result of a LISTRIGHTS 2512 command. The first argument is a string containing the (possibly 2513 empty) set of rights the identifier will always be granted on the 2514 dataset or attribute. 2516 Following this are zero or more strings each containing a single 2517 right the identifier may be granted in the dataset or attribute. 2519 The same right MUST NOT be listed more than once in the LISTRIGHTS 2520 response. 2522 6.8. Quotas 2524 The section defines the commands and responses relating to quotas. 2526 6.8.1. GETQUOTA Command 2528 Arguments: dataset 2530 Data: untagged responses: QUOTA 2532 Result: OK - Quota information returned 2533 NO - Quota failure: can't access resource limit 2534 no resource limit 2535 BAD - command unknown or arguments invalid 2537 The GETQUOTA command takes the name of a dataset, and returns in 2538 an untagged QUOTA response the name of the dataset, its quota 2539 root, the quota limit on that root and the quota usage within that 2540 root. 2542 Example: C: A043 GETQUOTA "/option/user/fred/common" 2543 S: * QUOTA "/option/user/fred/common" "/quota/user/fred" 2544 1048576 2475 2545 S: A043 OK "Getquota completed" 2547 Internet DRAFT ACAP June 19, 1997 2549 6.8.3. QUOTA Untagged Response 2551 Data: dataset 2552 quota root 2553 quota limit in bytes 2554 amount of quota limit used 2556 The QUOTA untagged response is generated as a result of a GETQUOTA 2557 command or MAY be generated by the server in response to a SEARCH 2558 or STORE command to warn about high usage of a quota. It includes 2559 the name of the applicable dataset, the quota root, the quota 2560 limit in bytes and the quota usage. 2562 6.9. Extensions 2564 In order to simplify the process of extending the protocol, clients 2565 MUST ignore unknown server responses which meet the syntax of 2566 response-extend. In addition, clients MUST ignore server response 2567 codes which meet the syntax of resp-code-ext. Availability of new 2568 commands MUST be announced via a capability on the initial greeting 2569 line and such commands SHOULD meet the syntax of command-extend. 2571 Servers MUST respond to unknown commands with a BAD command 2572 completion result. Servers MUST skip over non-synchronizing literals 2573 contained in an unknown command. This may be done by assuming the 2574 unknown command matches the command-extend syntax, or by reading a 2575 line at a time and checking for the non-synchronizing literal syntax 2576 at the end of the line. 2578 7. Registration Procedures 2580 ACAP's usefulness comes from providing a structured storage model for 2581 all sorts of configuration data. However, for its potential to be 2582 achieved, it is important that the Internet community strives for the 2583 following goals: 2585 (1) Standardization. It is very important to standardize dataset 2586 classes. The authors hope that ACAP achieves the success that SNMP 2587 has seen with the definition of numerous standards track MIBs. 2589 (2) Community Review. In the absence of standardization, it is 2590 important to get community review on a proposal to improve its 2591 engineering quality. Community review is strongly recommended prior 2592 to registration. The ACAP implementors mailing list 2593 should be used for this purpose. 2595 (3) Registration. Registration serves a two-fold purpose. First it 2596 prevents use of the same name for different purposes, and second it 2598 Internet DRAFT ACAP June 19, 1997 2600 provides a one-stop list which can be used to locate existing 2601 extensions or dataset classes to prevent duplicate work. 2603 The following registration templates may be used to register ACAP 2604 protocol elements. 2606 7.1. Comparators 2608 Additional comparators may be registered with IANA on a first-come, 2609 first-served basis. Comparators intended for interoperable use MUST 2610 be defined as a standards-track or IESG-approved-experimental RFC. 2612 To: XXX@XXX.XXX 2613 Subject: Registration of new comparator 2615 Comparator name: 2617 Scope: 2619 (Describe any limitations on intended use in terms of standards scope, 2620 dataset classes, and specific locales.) 2622 Operations: Ordering, Equality, Substring match 2624 Published Specification(s): 2626 (If the published specification is not standards track, or no 2627 published specification is referenced then the comparator is 2628 assumed to be for limited use.) 2630 Person and email address to contact for further information: 2632 7.2. ACAP Capabilities 2634 New ACAP capabilities MUST be standards track or IESG approved 2635 experimental RFCs. Registration provides a simple way to locate all 2636 extensions. Careful consideration should be made before extending 2637 the protocol, as it can lead to complexity or interoperability 2638 problems. 2640 To: XXX@XXX.XXX 2641 Subject: Registration of ACAP capability 2643 Capability name: 2645 Capability keyword: 2647 Capability arguments: 2649 Internet DRAFT ACAP June 19, 1997 2651 Published Specification(s): 2653 (Standards track or IESG approved experimental RFC) 2655 Person and email address to contact for further information: 2657 7.3. ACAP Response Codes 2659 ACAP response codes are registered on a first come, first served 2660 basis. Proposals SHOULD be reviewed by the acap implementors mailing 2661 list mentioned above. 2663 To: XXX@XXX.XXX 2664 Subject: Registration of ACAP response code 2666 Response Code: 2668 Arguments: 2670 Purpose: 2672 Published Specification(s): 2674 (Optional, but encouraged) 2676 Person and email address to contact for further information: 2678 7.4. Dataset Classes 2680 A dataset class provides a core set of attributes for use in a 2681 specified hierarchy. It may also define rules for the dataset 2682 hierarchy underneath that class. Dataset class specifications must 2683 be standards track or IESG approved experimental RFCs. 2685 To: XXX@XXX.XXX 2686 Subject: Registration of ACAP dataset class 2688 Dataset class name/attribute prefix: 2690 Purpose: 2692 Published Specification(s): 2694 (Standards track or IESG approved experimental RFC) 2696 Person and email address to contact for further information: 2698 Internet DRAFT ACAP June 19, 1997 2700 7.5. Vendor Subtree 2702 Vendors may reserve a portion of the ACAP namespace for private use. 2703 Dataset class names beginning with "vendor.." 2704 are reserved for use by that company or product. In addition, all 2705 attribute names beginning with "vendor.." are 2706 reserved for use by that company or product. Registration is on a 2707 first come, first served basis. Whenever possible, private 2708 attributes and dataset classes should be avoided in favor of 2709 improving interoperable dataset class definitions. 2711 To: XXX@XXX.XXX 2712 Subject: Registration of ACAP vendor subtree 2714 Private Prefix: vendor.. 2716 Person and email address to contact for further information: 2718 (company names and addresses should be included when appropriate) 2720 8. Formal Syntax 2722 The following syntax specification uses the augmented Backus-Naur 2723 Form (BNF) notation as specified in [ABNF]. 2725 Except as noted otherwise, all alphabetic characters are 2726 case-insensitive. The use of upper or lower case characters to 2727 define token strings is for editorial clarity only. Implementations 2728 MUST accept these strings in a case-insensitive fashion. 2730 The "command" rule below defines the syntax for commands sent by the 2731 client. The "response" rule below defines the syntax for responses 2732 sent by the server. 2734 ALPHA = %x41..5A / %x61..7A 2735 ;; alphabetic letters 2737 ATOM-CHAR = "!" / %x23..27 / %x2A..5B / %x5D..7A / %x7C..7E 2738 ;; Any CHAR except ATOM-SPECIALS 2740 ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS 2742 BASE64-CHAR = ALPHA / DIGIT / "+" / "/" 2743 ;; case-sensitive 2745 CHAR = %x01..7F 2747 CR = %x0C 2749 Internet DRAFT ACAP June 19, 1997 2751 CRLF = CR LF 2753 CTL = %x00..1F / %x7F 2755 DIGIT = "0" / DIGIT-NZ 2757 DIGIT-NZ = %x31..39 2758 ; non-zero digits ("1" - "9") 2760 LF = %x0A 2762 OCTET = %x00..FF 2764 QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS 2766 QUOTED-SPECIALS = <"> / "\" 2768 SAFE-CHAR = %x01..09 / %x0B..0C / %x0E..21 / 2769 %x23..5B / %x5D..7F 2770 ;; any TEXT-CHAR except QUOTED-SPECIALS 2772 SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / 2773 UTF8-5 / UTF8-6 2775 SPACE = %x20 2777 TAG-CHAR = %x21 / %x23..27 / %x2C..5B / %x5D..7A / %x7C..7E 2778 ;; Any ATOM-CHAR except "*" or "+" 2780 TEXT-CHAR = %x01..09 / %x0B..0C / %x0E..7F 2781 ;; any CHAR except CR and LF 2783 TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS 2785 UTF8-1 = %x80..BF 2787 UTF8-2 = %xC0..DF UTF8-1 2789 UTF8-3 = %xE0..EF 2UTF8-1 2791 UTF8-4 = %xF0..F7 3UTF8-1 2793 UTF8-5 = %xF8..FB 4UTF8-1 2795 UTF8-6 = %xFC..FD 5UTF8-1 2797 UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF 2799 Internet DRAFT ACAP June 19, 1997 2801 acl = "(" *acl-identrights ")" 2803 acl-identifier = string-utf8 2804 ;; MUST NOT contain TAB 2806 acl-identrights = string-utf8 2807 ;; The identifier followed by a TAB, followed by 2808 ;; the rights. 2810 acl-object = "(" dataset [SPACE attribute [SPACE entry-name]] ")" 2812 acl-rights = quoted 2814 atom = ALPHA *1023ATOM-CHAR 2816 attribute = string-utf8 2817 ;; dot-separated attribute name 2818 ;; MUST NOT contain "*" or "%" 2820 attribute-store = attribute SPACE (value-nil / 2821 "(" 1*(metadata-write-q SPACE value-store) ")") 2822 ;; MUST NOT include the same metadata twice 2824 auth-type = iana-token 2825 ;; as defined in SASL [SASL] 2827 base64-token = *(4BASE64-CHAR) [base64-terminal] 2829 base64-terminal = (2BASE64-CHAR "==") / (3BASE64-CHAR "=") 2831 command = tag SPACE (command-any / command-auth / 2832 command-nonauth) CRLF 2833 ;; Modal based on state 2835 command-authent = "AUTHENTICATE" SPACE auth-type [SPACE base64-token] 2836 *(CRLF base64-token) 2838 command-any = "NOOP" / command-lang / "LOGOUT" 2840 command-auth = command-delacl / command-dsince / 2841 command-freectx / command-getquota / 2842 command-lrights / command-myrights / 2843 command-search / command-setacl / 2844 command-store 2845 ;; only valid in authenticated state 2847 command-delacl = "DELETEACL" SPACE acl-object [SPACE acl-identifier] 2849 Internet DRAFT ACAP June 19, 1997 2851 command-dsince = "DELETEDSINCE" SPACE dataset SPACE time 2853 command-extend = extend-token [SPACE extension-data] 2855 command-freectx = "FREECONTEXT" SPACE context 2857 command-getquota = "GETQUOTA" SPACE dataset 2859 command-lang = "LANG" *(SPACE lang-tag) 2861 command-lrights = "LISTRIGHTS" SPACE acl-object 2863 command-myrights = "MYRIGHTS" SPACE acl-object 2865 command-nonauth = command-authent 2866 ;; only valid in non-authenticated state 2868 command-search = "SEARCH" SPACE (dataset / context) 2869 *(SPACE search-modifier) 2870 SPACE search-criteria 2871 ;; MUST NOT include same search-modifier twice 2873 command-setacl = "SETACL" SPACE acl-object SPACE acl-identifier 2874 SPACE acl-rights 2876 command-store = "STORE" SPACE store-entry-list 2878 comparator = <"> comparator-name <"> 2880 comparator-name = ["+" / "-"] iana-token 2882 context = string-utf8 2883 ;; MUST NOT begin with slash ("/") 2885 dataset = string-utf8 2886 ;; slash-separated dataset name 2887 ;; begins with slash 2889 entry = entry-name / entry-path 2891 entry-name = string-utf8 2892 ;; entry name MUST NOT contain slash 2893 ;; MUST NOT begin with "." 2895 entry-path = string-utf8 2896 ;; slash-separated path to entry 2897 ;; begins with slash 2899 Internet DRAFT ACAP June 19, 1997 2901 entry-relative = string-utf8 2902 ;; potentially relative path to entry 2904 extend-token = atom 2905 ;; MUST be defined by a standards track or 2906 ;; IESG approved experimental protocol extension 2908 extension-data = extension-item *(SPACE extension-item) 2910 extension-item = extend-token / string / number / 2911 "(" [extension-data] ")" 2913 iana-token = atom 2914 ;; MUST be registered with IANA 2916 initial-greeting = "*" SPACE "ACAP" *(SPACE "(" init-capability ")") CRLF 2918 init-capability = init-cap-compare / init-cap-context / 2919 init-cap-extend / init-cap-implem / init-cap-sasl 2921 init-cap-compare = "COMPARATORS" SPACE string-list 2923 init-cap-context = "CONTEXTLIMIT" SPACE string 2925 init-cap-extend = iana-token [SPACE string-list] 2927 init-cap-implem = "IMPLEMENTATION" SPACE string 2929 init-cap-sasl = "SASL" SPACE string-list 2931 lang-tag = <"> Language-Tag <"> 2932 ;; Language-Tag rule is defined in [LANG-TAGS] 2934 literal = "{" number [ "+" ] "}" CRLF *OCTET 2935 ;; The number represents the number of octets 2936 ;; MUST be literal-utf8 except for values 2938 literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR 2939 ;; The number represents the number of octets 2940 ;; not the number of characters 2942 metadata = attribute [ "(" metadata-type-list ")" ] 2943 ;; attribute MAY end in "*" as wildcard. 2945 metadata-list = metadata *(SPACE metadata) 2947 metadata-type = "attribute" / "myrights" / "size" / 2948 "count" / metadata-write 2950 Internet DRAFT ACAP June 19, 1997 2952 metadata-type-q = <"> metadata-type <"> 2954 metadata-type-list = metadata-type-q *(SPACE metadata-type-q) 2956 metadata-write = "value" / "acl" 2958 metadata-write-q = <"> metadata-write <"> 2960 nil = "NIL" 2962 nstring = nil / string 2964 number = *DIGIT 2965 ;; A 32-bit unsigned number. 2966 ;; (0 <= n < 4,294,967,296) 2968 nz-number = DIGIT-NZ *DIGIT 2969 ;; A 32-bit unsigned non-zero number. 2970 ;; (0 < n < 4,294,967,296) 2972 position = number 2973 ;; "0" if context is not enumerated 2974 ;; otherwise this is non-zero 2976 quota-limit = number 2978 quota-root = entry-path 2980 quota-usage = number 2982 quoted = <"> *QUOTED-CHAR <"> 2983 ;; limited to 1024 octets between the <">s 2985 response = response-addto / response-alert / response-bye / 2986 response-change / response-cont / 2987 response-deleted / response-done / response-entry / 2988 response-extend / response-listr / 2989 response-lang / response-mtimei / response-mtimeu / 2990 response-myright / response-quota / 2991 response-refer / response-remove / response-stat 2993 response-addto = "*" SPACE "ADDTO" SPACE context SPACE entry-name 2994 SPACE position SPACE return-data-list 2996 response-alert = "*" SPACE "ALERT" SPACE resp-body CRLF 2997 ;; Client MUST display alert text to user 2999 Internet DRAFT ACAP June 19, 1997 3001 response-bye = "*" SPACE "BYE" SPACE resp-body CRLF 3002 ;; Server will disconnect condition 3004 response-change = "*" SPACE "CHANGE" SPACE context SPACE entry-name 3005 SPACE position SPACE position SPACE return-data-list 3007 response-cont = "+" SPACE (quoted / base64-token) 3009 response-deleted = tag SPACE "DELETED" SPACE entry-name 3011 response-done = tag SPACE resp-cond-state CRLF 3013 response-entry = tag SPACE "ENTRY" SPACE entry SPACE return-data-list 3015 response-extend = (tag / "*") SPACE extend-token [SPACE extension-data] 3017 response-lang = "*" SPACE "LANG" SPACE lang-tag *(SPACE lang-tag) 3019 response-listr = tag SPACE "LISTRIGHTS" SPACE acl-rights 3020 *(SPACE acl-rights) 3022 response-mtimei = tag SPACE "MODTIME" SPACE time 3024 response-mtimeu = "*" SPACE "MODTIME" SPACE context SPACE time 3026 response-myright = tag SPACE "MYRIGHTS" SPACE acl-rights 3028 response-quota = "*" SPACE "QUOTA" SPACE dataset SPACE quota-root 3029 SPACE quota-limit SPACE quota-usage 3031 response-refer = tag SPACE "REFER" SPACE dataset 1*(SPACE 3032 <"> url-relative <">) 3034 response-remove = "*" SPACE "REMOVEFROM" SPACE context SPACE 3035 entry-name SPACE position 3037 response-stat = "*" SPACE resp-cond-state CRLF 3039 resp-body = ["(" resp-code ")" SPACE] quoted 3041 resp-code = "ENCRYPT-NEEDED" / resp-code-inval / 3042 resp-code-many / resp-code-mod / 3043 resp-code-noexist / resp-code-perm / 3044 "PLAINTEXT-DENIED" / "QUOTA" / resp-code-refer / 3045 "TRANSITION-NEEDED" / "TRYCACHE" / 3046 "TRYFREECONTEXT" / resp-code-way / resp-code-ext 3048 Internet DRAFT ACAP June 19, 1997 3050 resp-code-ext = iana-token [SPACE extension-data] 3051 ;; unknown response codes are ignored by the client. 3053 resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute) 3055 resp-code-many = "TOOMANY" SPACE nz-number 3057 resp-code-mod = "MODIFIED" SPACE entry-path 3059 resp-code-noexist = "NOEXIST" SPACE dataset 3061 resp-code-perm = "PERMISSION" SPACE acl-object 3063 resp-code-refer = "REFER" 1*(SPACE <"> url-relative <">) 3065 resp-code-way = "WAYTOOMANY" 3067 resp-cond-state = ("OK" / "NO" / "BAD") SPACE resp-body 3068 ;; Status condition 3070 return-data = "(" return-metadata *(SPACE return-metadata) ")" 3071 ;; one return-data list is included per item in 3072 ;; the RETURN statement 3074 return-data-list = return-data *(SPACE return-data) 3076 return-metadata = nil / string / value-list / acl 3078 searchkey-equal = "EQUAL" SPACE attribute SPACE comparator 3079 SPACE value-nil 3081 searchkey-comp = "COMPARE" SPACE attribute SPACE comparator SPACE value 3083 searchkey-prefix = "PREFIX" SPACE attribute SPACE comparator SPACE value 3085 searchkey-range = "RANGE" SPACE nz-number SPACE nz-number 3086 SPACE time 3088 searchkey-strict = "COMPARESTRICT" SPACE attribute SPACE comparator 3089 SPACE value 3091 searchkey-substr = "SUBSTRING" SPACE attribute SPACE comparator 3092 SPACE value 3094 searchmod-depth = "DEPTH" SPACE number 3096 searchmod-hard = "HARDLIMIT" SPACE nz-number 3098 Internet DRAFT ACAP June 19, 1997 3100 searchmod-limit = "LIMIT" SPACE number SPACE number 3102 searchmod-make = "MAKECONTEXT" [SPACE "ENUMERATE"] 3103 [SPACE "NOTIFY"] SPACE context 3105 searchmod-ninh = "NOINHERIT" 3107 searchmod-return = "RETURN" SPACE "(" [metadata-list] ")" 3109 searchmod-sort = "SORT" SPACE "(" sort-list ")" 3111 search-criteria = "ALL" / searchkey-equal / searchkey-comp / 3112 searchkey-strict / searchkey-range / 3113 searchkey-prefix / searchkey-substr / 3114 "NOT" SPACE search-criteria / 3115 "OR" SPACE search-criteria SPACE search-criteria / 3116 "AND" SPACE search-criteria SPACE search-criteria 3118 search-modifier = searchmod-depth / searchmod-hard / 3119 searchmod-limit / searchmod-make / searchmod-ninh / 3120 searchmod-return / searchmod-sort 3122 sort-list = sort-item *(SPACE sort-item) 3124 sort-item = attribute SPACE comparator 3126 store-entry = "(" entry-path *(SPACE store-modifier) 3127 *(SPACE attribute-store) ")" 3128 ;; MUST NOT include the same store-modifier twice 3129 ;; MUST NOT include the same attribute twice 3131 store-entry-list = store-entry *(SPACE store-entry) 3132 ;; MUST NOT include the same entry twice 3134 store-modifier = store-mod-unchang / store-mod-nocreate 3136 store-mod-nocreate = "NOCREATE" 3138 store-mod-unchang = "UNCHANGEDSINCE" SPACE time 3140 string = quoted / literal 3142 string-list = string *(SPACE string) 3144 string-utf8 = quoted / literal-utf8 3146 tag = 1*32TAG-CHAR 3148 Internet DRAFT ACAP June 19, 1997 3150 time = <"> time-year time-month time-day time-hour 3151 time-minute time-second time-subsecond <"> 3152 ;; Timestamp in UTC 3154 time-day = 2DIGIT ;; 01-31 3156 time-hour = 2DIGIT ;; 00-23 3158 time-minute = 2DIGIT ;; 00-59 3160 time-month = 2DIGIT ;; 01-12 3162 time-second = 2DIGIT ;; 00-60 3164 time-subsecond = *DIGIT 3166 time-year = 4DIGIT 3168 value = string 3170 value-any = value-nil / value-list 3172 value-list = "(" [value *(SPACE value)] ")" 3174 value-nil = value / nil 3176 value-store = value-any / acl 3178 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 3179 ;; url-enc-entry interpreted relative to "/" 3181 url-attr-list = url-enc-attr *("&" url-enc-attr) 3183 url-auth = ";AUTH=" ("*" / url-enc-auth) 3185 url-achar = uchar / "&" / "=" / "~" 3186 ;; See RFC 1738 for definition of "uchar" 3188 url-char = uchar / "=" / "~" / ":" / "@" / "/" 3189 ;; See RFC 1738 for definition of "uchar" 3191 url-enc-attr = 1*url-char 3192 ;; encoded version of attribute name 3194 url-enc-auth = 1*url-achar 3195 ;; encoded version of auth-type above 3197 Internet DRAFT ACAP June 19, 1997 3199 url-enc-entry = 1*url-char 3200 ;; encoded version of entry-relative above 3202 url-enc-user = *url-achar 3203 ;; encoded version of login userid 3205 url-filter = "?" url-attr-list 3207 url-relative = url-acap / [url-enc-entry] [url-filter] 3208 ;; url-enc-entry is relative to base URL 3210 url-server = [url-user [url-auth] "@"] hostport 3211 ;; See RFC 1738 for definition of "hostport" 3213 9. Multi-lingual Considerations 3215 The IAB charset workshop [IAB-CHARSET] came to a number of 3216 conclusions which influenced the design of ACAP. The decision to use 3217 UTF-8 as the character encoding scheme was based on that work. The 3218 LANG command to negotiate a language for error messages is also 3219 included. 3221 Section 3.4.5 of the IAB charset workshop report states that there 3222 should be a way to identify the natural language for human readable 3223 strings. Several promising proposals have been made for use within 3224 ACAP, but no clear consensus on a single method is apparent at this 3225 stage. The following rules are likely to permit the addition of 3226 multi-lingual support in the future: 3228 (1) A work in progress called Multi-Lingual String Format (MLSF) 3229 proposes a layer on top of UTF-8 which uses otherwise illegal UTF-8 3230 sequences to store language tags. In order to permit its addition to 3231 a future version of this standard, client-side UTF-8 interpreters 3232 SHOULD silently ignore illegal multi-byte UTF-8 characters, and treat 3233 illegal single-byte UTF-8 characters as end of string markers. 3234 Servers, for the time being, MUST silently accept illegal UTF-8 3235 characters, except in attribute names and entry names. Clients MUST 3236 NOT send illegal UTF-8 characters to the server unless a future 3237 standard changes this rule. 3239 (2) There is a proposal to add language tags to Unicode. To support 3240 this, servers MUST be able to store UTF-8 characters of up to 20 bits 3241 of data. 3243 (3) The metadata item "language" is reserved for future use. 3245 (4) The ";" character in attribute names is reserved for future use. 3247 Internet DRAFT ACAP June 19, 1997 3249 10. Security Considerations 3251 The AUTHENTICATE command uses SASL [SASL] to provide basic 3252 authentication, authorization, integrity and privacy services. This 3253 is described in section ###. The security considerations for the 3254 PLAIN SASL mechanism [SASL-PLAIN] also apply. 3256 ACAP protocol transactions are susceptible to passive observers or 3257 man in the middle attacks which alter the data, unless the optional 3258 encryption and integrity services of the AUTHENTICATE command are 3259 offered, or an external security mechanism is used for protection. 3260 It may be useful to allow configuration of both clients and servers 3261 to refuse to transfer sensitive information in the absence of strong 3262 encryption. 3264 ACAP access control lists provide fine grained authorization for 3265 access to attributes. A number of related security issues are 3266 described in section ###. 3268 ACAP clients are encouraged to consider the security problems 3269 involved with a lab computer situation. Specifically, a client cache 3270 of ACAP configuration information MUST NOT allow access by an 3271 unauthorized user. One way to assure this is for an ACAP client to 3272 be able to completely flush any non-public cached configuration data 3273 when a user leaves. 3275 As laptop computers can be easily stolen and a cache of configuration 3276 data may contain sensitive information, a disconnected mode ACAP 3277 client may wish to encrypt and password protect cached configuration 3278 information. 3280 11. Acknowledgments 3282 Many thanks to the follow people who helped design ACAP over the past 3283 four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob Earhart, 3284 Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, Steve Hole, 3285 Steve Hubert, Dave Roberts, Bart Schaefer, Matt Wall and other 3286 participants of the IETF ACAP working group. 3288 12. Authors' Addresses 3290 Chris Newman 3291 Innosoft International, Inc. 3292 1050 Lakes Drive 3293 West Covina, CA 91790 USA 3295 Email: chris.newman@innosoft.com 3297 Internet DRAFT ACAP June 19, 1997 3299 John Gardiner Myers 3300 Netscape Communications 3301 501 East Middlefield Road 3302 Mail Stop MV-029 3303 Mountain View, CA 94043 3305 Email: jgmyers@netscape.com 3307 Appendices 3309 A. References 3311 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", 3312 Work in progress: draft-ietf-drums-abnf-xx.txt 3314 [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource 3315 Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of 3316 Minnesota, December 1994. 3318 3320 [IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson, 3321 Crispin, Svanberg, "The Report of the IAB Character Set Workshop held 3322 29 February - 1 March, 1996", RFC 2130, April 1997. 3324 3326 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 3327 4rev1", RFC 2060, University of Washington, December 1996. 3329 3331 [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie 3332 Mellon, January 1997. 3334 3336 [ISO-10646] ISO/IEC 10646-1:1993(E) "Information Technology-- 3337 Universal Multiple-octet Coded Character Set (UCS)." See also 3338 amendments 1 through 7, plus editorial corrections. 3340 [ISO-C] "Programming languages -- C", ISO/IEC 9899:1990, 3341 International Organization for Standardization. This is effectively 3342 the same as ANSI C standard X3.159-1989. 3344 Internet DRAFT ACAP June 19, 1997 3346 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 3347 Requirement Levels", RFC 2119, Harvard University, March 1997. 3349 3351 [LANG-TAGS] Alvestrand, H., "Tags for the Identification of 3352 Languages", RFC 1766. 3354 3356 [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, 3357 UC Irvine, June 1995. 3359 3361 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 3362 Work in progress: draft-myers-auth-sasl-xx.txt 3364 [SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress: 3365 draft-newman-sasl-anon-xx.txt. 3367 [SASL-PLAIN] Newman, "Plaintext Password SASL Mechanism and 3368 Transition Codes", Work in progress: draft-newman-sasl-plaintrans- 3369 xx.txt. 3371 [UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version 3372 2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9. 3374 [US-ASCII] "USA Standard Code for Information Interchange," X3.4. 3375 American National Standards Institute: New York (1968). 3377 [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO 3378 10646", RFC 2044, Alis Technologies, October 1996. 3380 3382 Internet DRAFT ACAP June 19, 1997 3384 B. ACAP Keyword Index 3386 ACAP (untagged response) ................................... 29 3387 ADDTO (untagged response) .................................. 42 3388 ALERT (untagged response) .................................. 33 3389 ALL (search keyword) ....................................... 39 3390 AND (search keyword) ....................................... 39 3391 AUTHENTICATE (command) ..................................... 34 3392 BAD (response) ............................................. 32 3393 BYE (untagged response) .................................... 33 3394 CHANGE (untagged response) ................................. 43 3395 COMPARATORS (ACAP capability) .............................. 29 3396 COMPARE (search keyword) ................................... 39 3397 COMPARESTRICT (search keyword) ............................. 39 3398 CONTEXTLIMIT (ACAP capability) ............................. 29 3399 DELETEACL (command) ........................................ 47 3400 DELETED (intermediate response) ............................ 46 3401 DELETEDSINCE (command) ..................................... 45 3402 DEPTH (search modifier) .................................... 36 3403 ENCRYPT-NEEDED (response code) ............................. 20 3404 ENTRY (intermediate response) .............................. 40 3405 EQUAL (search keyword) ..................................... 39 3406 FREECONTEXT (command) ...................................... 41 3407 GETQUOTA (command) ......................................... 49 3408 HARDLIMIT (search modifier) ................................ 36 3409 IMPLEMENTATION (ACAP capability) ........................... 29 3410 INVALID (response code) .................................... 20 3411 LANG (command) ............................................. 30 3412 LANG (untagged response) ................................... 31 3413 LIMIT (search modifier) .................................... 36 3414 LISTRIGHTS (command) ....................................... 48 3415 LISTRIGHTS (intermediate response) ......................... 49 3416 LOGOUT (command) ........................................... 31 3417 MAKECONTEXT (search modifier) .............................. 37 3418 MODIFIED (response code) ................................... 21 3419 MODTIME (intermediate response) ............................ 40 3420 MODTIME (untagged response) ................................ 43 3421 MYRIGHTS (command) ......................................... 47 3422 MYRIGHTS (intermediate response) ........................... 48 3423 NO (response) .............................................. 32 3424 NOCREATE (store modifier) .................................. 44 3425 NOEXIST (response code) .................................... 21 3426 NOINHERIT (search modifier) ................................ 37 3427 NOOP (command) ............................................. 30 3428 NOT (search keyword) ....................................... 39 3429 OK (response) .............................................. 31 3430 OR (search keyword) ........................................ 39 3431 PERMISSION (response code) ................................. 21 3433 Internet DRAFT ACAP June 19, 1997 3435 PLAINTEXT-DENIED (response code) ........................... 21 3436 PREFIX (search keyword) .................................... 39 3437 QUOTA (response code) ...................................... 21 3438 QUOTA (untagged response) .................................. 50 3439 RANGE (search keyword) ..................................... 39 3440 REFER (intermediate response) .............................. 40 3441 REFER (response code) ...................................... 21 3442 REMOVEFROM (untagged response) ............................. 42 3443 RETURN (search modifier) ................................... 38 3444 SASL (ACAP capability) ..................................... 29 3445 SEARCH (command) ........................................... 35 3446 SETACL (command) ........................................... 46 3447 SORT (search modifier) ..................................... 38 3448 STORE (command) ............................................ 44 3449 SUBSTRING (search keyword) ................................. 40 3450 TOOMANY (response code) .................................... 21 3451 TRANSITION-NEEDED (response code) .......................... 21 3452 TRYCACHE (response code) ................................... 21 3453 TRYFREECONTEXT (response code) ............................. 22 3454 UNCHANGEDSINCE (store modifier) ............................ 44 3455 UPDATECONTEXT (command) .................................... 41 3456 WAYTOOMANY (response code) ................................. 22 3457 acl (attribute metadata) ................................... 14 3458 anyone (ACL identifier) .................................... 19 3459 attribute (attribute metadata) ............................. 14 3460 dataset.acl (dataset attribute) ............................ 26 3461 dataset.acl. (dataset attribute) ................ 26 3462 dataset.inherit (dataset attribute) ........................ 26 3463 en-nocase (comparator) ..................................... 18 3464 entry (predefined attribute) ............................... 13 3465 modtime (predefined attribute) ............................. 13 3466 myrights (attribute metadata) .............................. 14 3467 numeric (comparator) ....................................... 18 3468 octet (comparator) ......................................... 17 3469 quota.limit (predefined attribute) ......................... 28 3470 quota.usage (predefined attribute) ......................... 28 3471 size (attribute metadata) .................................. 14 3472 subdataset (predefined attribute) .......................... 13 3473 value (attribute metadata) ................................. 15