idnits 2.17.1 draft-ietf-acap-spec-03.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-19) 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 6 months document validity. ** 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 a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 17 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 -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 153: '...e to definitions of MUST, SHOULD, etc....' RFC 2119 keyword, line 313: '...we can make it a SHOULD rather than a ...' RFC 2119 keyword, line 454: '... A client MUST be prepared to accept...' RFC 2119 keyword, line 522: '...d such responses MUST deal with flow c...' RFC 2119 keyword, line 529: '...utologout timer, that timer MUST be of...' (53 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 279 has weird spacing: '...d. and prs....' == Line 2263 has weird spacing: '.... or prs....' -- 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 (March 1997) is 9897 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'IMAIL' on line 2672 looks like a reference -- Missing reference section? 'UTF-8' on line 745 looks like a reference -- Missing reference section? 'BASIC-URL' on line 2685 looks like a reference -- Missing reference section? 'UTF8' on line 2677 looks like a reference -- Missing reference section? 'BASE-URL' on line 825 looks like a reference -- Missing reference section? 'REL-URL' on line 2691 looks like a reference -- Missing reference section? 'SASL' on line 2669 looks like a reference -- Missing reference section? 'IMAP-ACL' on line 2664 looks like a reference -- Missing reference section? 'IMAP4' on line 2659 looks like a reference -- Missing reference section? 'US-ASCII' on line 2682 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 3 warnings (==), 12 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-03.txt J. G. Myers 5 Expire in six months March 1997 7 ACAP -- Application Configuration Access Protocol 9 Status of this Memo 11 This document is an Internet Draft. Internet Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its Areas, 13 and its Working Groups. Note that other groups may also distribute 14 working documents as Internet Drafts. 16 Internet Drafts are draft documents valid for a maximum of six 17 months. Internet Drafts may be updated, replaced, or obsoleted by 18 other documents at any time. It is not appropriate to use Internet 19 Drafts as reference material or to cite them other than as a 20 ``working draft'' or ``work in progress``. 22 To learn the current status of any Internet-Draft, please check the 23 1id-abstracts.txt listing contained in the Internet-Drafts Shadow 24 Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or 25 munnari.oz.au. 27 This document suggests a proposed protocol for the Internet 28 community, and requests discussion and suggestions for improvements. 29 Distribution of this draft is unlimited. 31 The protocol discussed in this document is experimental and subject 32 to change. Persons planning on either implementing or using this 33 protocol are STRONGLY URGED to get in touch with the author before 34 embarking on such a project. 36 Abstract 38 The Application Configuration Access Protocol (ACAP) is designed to 39 support remote storage and access of program option, configuration 40 and preference information. 42 Internet DRAFT ACAP March 26, 1997 44 Table of Contents 46 Status of this Memo ............................................... i 47 Abstract .......................................................... i 48 ACAP Protocol Specification ....................................... 1 49 0. Changes from version -01 to version -02 .................. 1 50 0.1. Changes from draft -02 to draft -03 ...................... 2 51 0.2. Open Issues .............................................. 4 52 1. Conventions Used in this Document ........................ 4 53 2. Protocol Overview ........................................ 5 54 2.1. Link Level ............................................... 5 55 2.2. Commands and Responses ................................... 5 56 2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 5 57 2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 6 58 2.3. State and Flow Diagram ................................... 7 59 2.3.1. Non-Authenticated State .................................. 7 60 2.3.2. Authenticated State ...................................... 7 61 2.3.3. Logout State ............................................. 7 62 2.4. Operational Considerations ............................... 8 63 2.4.1. Untagged Status Updates .................................. 8 64 2.4.2. Response when No Command in Progress ..................... 8 65 2.4.3. Autologout Timer ......................................... 8 66 2.4.4. Multiple Commands in Progress ............................ 9 67 2.5. Datasets and Entries ..................................... 9 68 2.6. Predefined Attributes .................................... 9 69 2.7. Attribute metadata ....................................... 10 70 2.8. Operational Command Overview ............................. 11 71 3. Protocol Elements ........................................ 11 72 3.1. Data Formats ............................................. 12 73 3.1.1. Atom ..................................................... 12 74 3.1.2. Number ................................................... 12 75 3.1.3. String ................................................... 12 76 3.1.3.1. 8-bit and Binary Strings ................................. 13 77 3.1.4. Parenthesized List ....................................... 13 78 3.1.5 NIL ...................................................... 13 79 3.2. ACAP URL scheme .......................................... 13 80 3.2.1. ACAP URL User Name and Authentication Mechanism .......... 14 81 3.2.2. Relative ACAP URLs ....................................... 15 82 3.3. Contexts ................................................. 15 83 3.4. Orderings ................................................ 15 84 3.5. Server Status Responses .................................. 16 85 3.6. Server Command Continuation Request ...................... 17 86 4. Protocol Specification ................................... 19 87 Internet DRAFT ACAP March 26, 1997 89 4.1. Initial Connection ....................................... 19 90 4.1.1. ACAP Untagged Response ................................... 19 91 4.2. Any State ................................................ 20 92 4.2.1. NOOP Command ............................................. 20 93 4.2.2. LOGOUT Command ........................................... 21 94 4.2.3. OK Response .............................................. 21 95 4.2.4. NO Response .............................................. 21 96 4.2.5. BAD Response ............................................. 22 97 4.2.6. BYE Untagged Response .................................... 22 98 4.3. Non-Authenticated State .................................. 23 99 4.3.1. AUTHENTICATE Command ..................................... 23 100 4.4. Searching ................................................ 25 101 4.4.1. SEARCH Command ........................................... 25 102 4.4.2. ENTRY Intermediate Response .............................. 29 103 4.4.3. MODTIME Intermediate Response ............................ 29 104 4.4.4. REFER Intermediate Response .............................. 29 105 4.5. Contexts ................................................. 30 106 4.5.1. FREECONTEXT Command ...................................... 30 107 4.5.2. UPDATECONTEXT Command .................................... 30 108 4.5.3. ADDTO Untagged Response .................................. 31 109 4.5.4. REMOVEFROM Untagged Response ............................. 31 110 4.5.5. CHANGE Untagged Response ................................. 32 111 4.5.6. MODTIME Untagged Response ................................ 32 112 4.6. Dataset modification ..................................... 32 113 4.6.1. STORE Command ............................................ 33 114 4.6.2. DELETEDSINCE Command ..................................... 34 115 4.6.3. DELETED Intermediate Response ............................ 34 116 4.7. Access Control Lists ..................................... 34 117 4.7.1. SETACL Command ........................................... 36 118 4.7.2. DELETEACL Command ........................................ 37 119 4.7.3. MYRIGHTS Command ......................................... 37 120 4.7.4. MYRIGHTS Intermediate Response ........................... 38 121 4.7.5. LISTRIGHTS Command ....................................... 38 122 4.7.6. LISTRIGHTS Intermediate Response ......................... 38 123 4.8. Quotas ................................................... 39 124 4.8.1. SETQUOTA Command ......................................... 39 125 4.8.2. GETQUOTA Command ......................................... 40 126 4.8.3. QUOTA Intermediate Response .............................. 40 127 4.9. Extensions ............................................... 40 128 5. Dataset Management ....................................... 41 129 5.1. Dataset Inheritance ...................................... 41 130 5.2. Dataset attributes ....................................... 41 131 6. Namespace conventions .................................... 42 132 6.1. Dataset Namespace ........................................ 42 133 6.2. Attribute Namespace ...................................... 42 134 7. Registration procedures .................................. 42 135 7.1. Ordering Functions ....................................... 43 136 7.2. ACAP Capabilities ........................................ 43 137 Internet DRAFT ACAP March 26, 1997 139 7.3. Dataset Classes .......................................... 44 140 7.4. Private Attribute Subtree ................................ 44 141 8. Formal Syntax ............................................ 45 142 9. Security Considerations .................................. 53 143 10. Authors' Addresses ....................................... 53 144 Appendices ........................................................ 54 145 A. References ............................................... 54 146 B. ACAP Keyword Index ....................................... 55 147 Internet DRAFT ACAP March 26, 1997 149 ACAP Protocol Specification 151 0. Changes from version -01 to version -02 153 1) Added reference to definitions of MUST, SHOULD, etc. 155 2) Removed last mention of "NIL". 157 3) Renamed "name" to "entry". 159 4) Datasets are ordered in a server-determined manner. 161 5) "acl" metadata is read-only. 163 6) return error on fetch of undefined metadata. 165 7) Added "subdataset" attribute and discussion of dataset hierarchy. 167 8) Changed "request response" to "request", and "result response" to 168 "result" to simplify the text. 170 9) Removed "Child Dataset Attributes" and added "Operational Command 171 Overview" 173 10) Restructured document a bit, adding a "protocol elements" section 175 11) Added "*" rule to the RETURN search modifier. 177 12) Added the DEPTH search modifier. 179 13) Added predefined orderings. 181 14) Added ACAP URL scheme 183 15) Removed NOTIFYCONTEXT command, added NOTIFYCONTEXT search 184 modifier. 186 16) DELETEDFROM -> intermediate DELETED response 188 17) Added second argument to LIMIT search modifier. 190 18) Added "[" and "]" to atom_specials to deal with special 191 information tokens cleanly; removed "*" and "%" 193 19) made resp_text into quoted string to simplify parsing. 195 Internet DRAFT ACAP March 26, 1997 197 20) Added SASL list to Capability greeting. 199 21) Removed ACL, LISTRIGHTS, GETACL, NOACL in favor of dataset 200 management attributes 202 22) Added AND to SEARCH keys and removed parentheses around SEARCH 203 keys. 205 23) simplified MYRIGHTS command and result 207 24) Simplified STORE and DELETE using entry-path 209 25) Remove locking of entire dataset. Add MODTIME intermediate 210 result to LOCK command. 212 26) Added GETQUOTA and SETQUOTA. 214 27) Astring is removed from the grammar, except for LOGIN. 216 28) Changed term "shadow" to "inherit" 218 29) Added dataset management section 220 30) Added sort-hint 222 31) Added QUOTA and PERMISSION response codes 224 32) Added registration procedures 226 33) Added dataset namespace conventions 228 34) TOOMANYCONTEXTS -> TRYFREECONTEXT 230 0.1. Changes from draft -02 to draft -03 232 1) Removed sort-hint, LOGIN, createtime, DELETE, LOCK, UNLOCK. DUMB 233 SASL mechanism will be defined in a separate document. 235 2) Put NIL back in. 237 3) Changed STORE command to allow NIL, include conditional store, and 238 store multiple entries atomically. 240 4) Fleshed out "extensions" section a bit. 242 5) Used parenthesis instead of brackets for special information 243 tokens. Simplifies parsing. Took "[" and "]" back out of atom 244 specials. 246 Internet DRAFT ACAP March 26, 1997 248 6) *Changed quoted string to allow UTF-8 characters. 250 7) kilobytes -> octets 252 8) Added "time" field to the RANGE search modifier to remove 253 ambiguity problems with unsolicited notifications. 255 9) Clarified that a BAD completion result must be returned for a 256 number of cases (bad metadata, invalid search modifier combinations, 257 etc). 259 10) Updated example in ACAP URL section and added rest of description 260 for the element. 262 11) Clarified octet collation. 264 12) Clarified REFER response code. Added REFER intermediate response 265 to SEARCH. 267 13) Clarified DEPTH search modifier. 269 14) Forbid use of "*" in attribute name. Forbid entry name from 270 beginning with ".". 272 15) Finished changing "NOTIFYCONTEXT command" to "NOTIFYCONTEXT 273 search modifier". 275 16) Changed ACL identifier to permit UTF-8. 277 17) Added reference to US-ASCII. 279 18) private. -> vnd. and prs. 281 19) permit multiple arguments to a capability. 283 20) Put back LISTRIGHTS command and response. 285 21) Added "ALL" search key, "HARDLIMIT" search modifier and 286 "WAYTOOMANY" response code. 288 22) Allow STORE with no attributes added; SHOULD/MUST rules as 289 appropriate. 291 23) Clarify inheritance rules with respect to modtime attribute and 292 ACL attributes. 294 24) Added rule about UPDATECONTEXT returning MODTIME if changes. 296 Internet DRAFT ACAP March 26, 1997 298 25) Clarify that ADDTO/REMOVEFROM/CHANGE renumber other entries in 299 the context. 301 26) Added editorial clarity note to section 1. 303 27) Require MODTIME response to successful SEARCH. 305 28) Allow size to be 0 in value. 307 0.2. Open Issues 309 1) Document structure: do you like it? 311 2) Need to define precise Unicode-based ordering function, if one 312 exists that isn't a nightmare to implement. If it is a nightmare to 313 implement, we can make it a SHOULD rather than a MUST. 315 3) Consider making ACL model more precise. Would like to pick AFS 316 semantics over POSIX semantics since AFS semantics are more 317 intuitive. Need to confer with security area director. Currently 318 both ACL semantics are permitted. 320 4) Current namespace conventions make certion useful operations 321 difficult. Other simple conventions appear worse. Need a way to 322 permit both "list all shared addressbooks" and "list all datasets 323 owned by this user". Ideas include multiple namespaces (e.g., 324 "/addressbooks/user/chris" and "/user/chris/addressbook" are the 325 same), out of band dataset class typing, and permitting "*" wild card 326 in place of a dataset path element. 328 5) Some people have indicated a desire for multi-valued attributes. 330 6) Do we need some sort of a "touch" operation? 332 7) Need to think more about the "subdataset" attribute and 333 inheritance. 335 8) Need to think more about the "o" ACL right and inheritance. 337 9) Need more examples. 339 1. Conventions Used in this Document 341 In examples, "C:" and "S:" indicate lines sent by the client and 342 server respectively. If such lines are wrapped without a new "C:" or 343 "S:" label, then the wrapping is for editorial clarity and is not 344 part of the command. 346 Internet DRAFT ACAP March 26, 1997 348 The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 349 in this document are to be interpreted as described in RFC xxxx. 351 The protocol syntax specification uses the Augmented Backus-Naur Form 352 (ABNF) notation as specified in [IMAIL] with one exception; the 353 delimiter used with the "#" construct is a single space (SPACE) and 354 not one or more commas. 356 2. Protocol Overview 358 2.1. Link Level 360 The ACAP protocol assumes a reliable data stream such as provided by 361 TCP. When TCP is used, an ACAP server listens on port 674. 363 2.2. Commands and Responses 365 An ACAP session consists of the establishment of a client/server 366 connection, an initial greeting from the server, and client/server 367 interactions. These client/server interactions consist of a client 368 command, server data, and a server completion result. 370 All interactions transmitted by client and server are in the form of 371 lines; that is, strings that end with a CRLF. The protocol receiver 372 of an ACAP client or server is either reading a line, or is reading a 373 sequence of octets with a known count followed by a line. Both 374 clients and servers must be capable of handling lines of arbitrary 375 length. 377 2.2.1. Client Protocol Sender and Server Protocol Receiver 379 The client command begins an operation. Each client command is 380 prefixed with a identifier (typically a short alphanumeric string, 381 e.g., A0001, A0002, etc.) called a "tag". A different tag is 382 generated by the client for each command. 384 There are two cases in which a line from the client does not 385 represent a complete command. In one case, a command argument is 386 quoted with an octet count (see the description of literal in section 387
); in the other case, the command arguments require server 388 feedback (see the AUTHENTICATE command). In some of these cases, the 389 server sends a command continuation request if it is ready for the 390 next part of the command. This response is prefixed with the token 391 "+". 393 Note: If, instead, the server detected an error in the 395 Internet DRAFT ACAP March 26, 1997 397 command, it sends a BAD completion response with tag 398 matching the command (as described below) to reject the 399 command and prevent the client from sending any more of the 400 command. 402 It is also possible for the server to send a completion or 403 intermediate response for some other command (if multiple 404 commands are in progress), or untagged data. In either 405 case, the command continuation request is still pending; 406 the client takes the appropriate action for the response, 407 and reads another response from the server. 409 The ACAP server reads a command line from the client, parses the 410 command and its arguments, and transmits server data and a server 411 command completion result. 413 2.2.2. Server Protocol Sender and Client Protocol Receiver 415 Data transmitted by the server to the client come in four forms: 416 command continuation requests, command completion results, 417 intermediate responses, and untagged responses. 419 A command continuation request is prefixed with the token "+". 421 A command completion result indicates the success or failure of the 422 operation. It is tagged with the same tag as the client command 423 which began the operation. Thus, if more than one command is in 424 progress, the tag in a server completion response identifies the 425 command to which the response applies. There are three possible 426 server completion responses: OK (indicating success), NO (indicating 427 failure), or BAD (indicating protocol error such as unrecognized 428 command or command syntax error). 430 An intermediate response returns data which can only be interpreted 431 within the context of a command in progress. It is tagged with the 432 same tag as the client command which began the operation. Thus, if 433 more than one command is in progress, the tag in an intermediate 434 response identifies the command to which the response applies. A 435 tagged response other than "OK", "NO", or "BAD" is an intermediate 436 response. 438 An untagged response returns data or status messages which may be 439 interpreted outside the context of a command in progress. It is 440 prefixed with the token "*". Untagged data may be sent as a result 441 of a client command, or may be sent unilaterally by the server. 442 There is no syntactic difference between untagged data that resulted 443 from a specific command and untagged data that were sent 445 Internet DRAFT ACAP March 26, 1997 447 unilaterally. 449 The protocol receiver of an ACAP client reads a response line from 450 the server. It then takes action on the response based upon the 451 first token of the response, which may be a tag, a "*", or a "+" as 452 described above. 454 A client MUST be prepared to accept any server response at all times. 455 This includes untagged data that it may not have requested. 457 This topic is discussed in greater detail in the Server Responses 458 section. 460 2.3. State and Flow Diagram 462 An ACAP server is in one of three states. Most commands are valid in 463 only certain states. It is a protocol error for the client to 464 attempt a command while the server is in an inappropriate state for 465 that command. In this case, a server will respond with a BAD command 466 completion result. 468 2.3.1. Non-Authenticated State 470 In non-authenticated state, the user must supply authentication 471 credentials before most commands will be permitted. This state is 472 entered when a connection starts. 474 2.3.2. Authenticated State 476 In authenticated state, the user is authenticated and most commands 477 will be permitted. This state is entered when acceptable 478 authentication credentials have been provided. 480 2.3.3. Logout State 482 In logout state, the session is being terminated, and the server will 483 close the connection. This state can be entered as a result of a 484 client request or by unilateral server decision. 486 Internet DRAFT ACAP March 26, 1997 488 +--------------------------------------+ 489 |initial connection and server greeting| 490 +--------------------------------------+ 491 || (1) || (2) 492 VV || 493 +-----------------+ || 494 |non-authenticated| || 495 +-----------------+ || 496 || (4) || (3) || 497 || VV || 498 || +----------------+ || 499 || | authenticated | || 500 || +----------------+ || 501 || || (4) || 502 VV VV VV 503 +--------------------------------------+ 504 | logout and close connection | 505 +--------------------------------------+ 507 (1) connection (ACAP greeting) 508 (2) rejected connection (BYE greeting) 509 (3) successful AUTHENTICATE command 510 (4) LOGOUT command, server shutdown, or connection closed 512 2.4. Operational Considerations 514 2.4.1. Untagged Status Updates 516 At any time, a server can send data that the client did not request. 518 2.4.2. Response when No Command in Progress 520 Server implementations are permitted to send an untagged response 521 while there is no command in progress. Server implementations that 522 send such responses MUST deal with flow control considerations. 523 Specifically, they must either (1) verify that the size of the data 524 does not exceed the underlying transport's available window size, or 525 (2) use non-blocking writes. 527 2.4.3. Autologout Timer 529 If a server has an inactivity autologout timer, that timer MUST be of 530 at least 30 minutes' duration. The receipt of ANY command from the 531 client during that interval MUST suffice to reset the autologout 532 timer. 534 Internet DRAFT ACAP March 26, 1997 536 2.4.4. Multiple Commands in Progress 538 The client is not required to wait for the completion result of a 539 command before sending another command, subject to flow control 540 constraints on the underlying data stream. Similarly, a server is 541 not required to process a command to completion before beginning 542 processing of the next command, unless an ambiguity would result 543 because of a command that would affect the results of other commands. 544 If there is such an ambiguity, the server executes commands to 545 completion in the order given by the client. 547 2.5. Datasets and Entries 549 The primary data structure in ACAP is the "dataset", which is a named 550 set of entries. Datasets are named hierarchically, with each 551 component of the name preceded by a slash ("/") and containing one or 552 more UTF-8 characters (other than slash). 554 Each entry in a dataset is a set of attribute/value pairs. Each 555 attribute is a hierarchical name in UTF-8, with each component of the 556 name being separated with a period ("."). Each attribute/value pair 557 may have additional metadata; this is described in section
. 558 There must be exactly one "entry" attribute, whose value is unique 559 amongst all entries in the dataset and contains zero or more UTF-8 560 characters other than slash ("/") or dot ("."). 562 Entries in a dataset are ordered in a server-determined manner. 564 The value of an attribute is a string containing one or more octets. 565 The semantics of a value are defined by the specification of its 566 attribute. Values of attributes ending in ".bin" contain arbitrary 567 data. Values of other attributes are textual and are restricted to 568 non-zero UTF-8 characters. 570 Attribute names are not permitted to contain "*", and entry names are 571 not permitted to begin with ".". Servers MUST return a BAD 572 completion result to clients which violate this. 574 2.6. Predefined Attributes 576 Attribute names which do not contain a dot (".") are reserved for 577 standardized attributes which have meaning in any dataset. The 578 following attributes are defined by the ACAP protocol. 580 entry Contains the name of the entry. 582 modtime 583 Contains the date and time, in UTC, any value or acl in the 585 Internet DRAFT ACAP March 26, 1997 587 entry was last modified. This value is automatically updated 588 by the server and may not be directly modified by the client. 590 The value consists of 14 or more US-ASCII digits. The first 591 four indicate the year, the next two indicate the month, the 592 next two indicate the day of month, the next two indicate the 593 hour (0 - 23), the next two indicate the minute, and the next 594 two indicate the second. Any further digits indicate 595 fractions of a second. 597 The time, particularly fractions of a second, need not be 598 accurate. It is required, however, that any two entries in a 599 dataset changed by successive modifications have strictly 600 ascending modtime values. 602 subdataset 603 If this attribute is set, it indicates the existence of a 604 sub-dataset of this entry. 606 The value consists of a list of CRLF separated relative ACAP 607 URLs (see section
for ACAP URL specification) which 608 may be used to locate where the sub-dataset is actually 609 stored. The base URL for the subdataset attribute is formed 610 by appending the entry name followed by a "/" to the end of 611 the parent dataset name. 613 For example, if the dataset "/mailboxes/common" has an entry 614 "public-folder" with a subdataset attribute of ".", then there 615 exists a dataset "/mailboxes/common/public-folder". If the 616 value of the subdataset attribute was instead 617 "//other.acap.domain//mailboxes/common/public-folder" that 618 would indicate the dataset is actually located on a different 619 ACAP server. 621 A dataset is created by storing a "subdataset" attribute 622 including ".", and a sub-hierarchy of datasets is deleted by 623 clearing the value of the "subdataset" attribute on the entry 624 in the upper dataset. 626 2.7. Attribute metadata 628 Each attribute/value pair may have additional metadata associated 629 with it. For completeness, the attribute and value themselves are 630 defined as metadata. The defined items of metadata associated with 632 Internet DRAFT ACAP March 26, 1997 634 an attribute/value pair are: 636 attribute 637 The attribute name. Read-only. 639 value The value. 641 value 642 A substring of the value. ORIGIN is specified as a non- 643 negative decimal number indicating the octet position of the 644 first desired octet. An ORIGIN of 0 specifies the first octet 645 of the value. SIZE is specified as a positive, decimal 646 number, specifying the maximum number of octets desired. A 647 SIZE of 0 fetches all octets after the ORiGIN. Read-only. 649 size The length of the value, in octets. Read-only. 651 acl The access control list for the attribute/value pair, if one 652 exists. If the attribute/value pair does not have an ACL, NIL 653 is returned. Read-write. See section
for the 654 contents of an ACL. 656 myrights 657 The set of rights that the client has to the attribute/value 658 pair. Read-only. See section
for the possible 659 rights. 661 Additional items of metadata may be defined in extensions to this 662 protocol. Servers must respond to queries of unrecognized metadata 663 by returning a BAD command completion result. 665 2.8. Operational Command Overview 667 The AUTHENTICATE, NOOP, and LOGOUT commands provide basic protocol 668 services. The SEARCH command is used to select, sort, fetch and 669 monitor changes to attribute values and metadata. The UPDATECONTEXT 670 and FREECONTEXT commands are also used to assist in monitoring 671 changes in attribute values and metadata. The STORE command is used 672 to add, modify and delete entries and attributes. The DELETEDSINCE 673 command is used to assist a client in resynchronizing a cache with 674 the server. The SETQUOTA, GETQUOTA, SETACL, DELETEACL and MYRIGHTS 675 commands are used to examine or modifty quota usages and access 676 permissions. 678 3. Protocol Elements 680 This section defines data formats and other protocol elements used 681 throughout the ACAP protocol. 683 Internet DRAFT ACAP March 26, 1997 685 3.1. Data Formats 687 ACAP uses textual commands and responses. Data in ACAP can be in one 688 of four forms: atom, number, string, parenthesized list, or NIL. 690 3.1.1. Atom 692 An atom consists of one to 1024 non-special characters. 694 3.1.2. Number 696 A number consists of one or more digit characters, and represents a 697 numeric value. 699 3.1.3. String 701 A string is in one of two forms: literal and quoted string. The 702 literal form is the general form of string. The quoted string form 703 is an alternative that avoids the overhead of processing a literal at 704 the cost of restrictions of what may be in a quoted string. 706 A literal is a sequence of zero or more octets (including CR and LF), 707 prefix-quoted with an octet count in the form of an open brace ("{"), 708 the number of octets, close brace ("}"), and CRLF. In the case of 709 literals transmitted from server to client, the CRLF is immediately 710 followed by the octet data. 712 There are two forms of literals transmitted from client to server. 713 The form where the open brace ("{") and number of octets is 714 immediately followed by a close brace ("}") and CRLF is called a 715 synchronizing literal. When sending a synchronizing literal, the 716 client must wait to receive a command continuation request (described 717 later in this document) before sending the octet data (and the 718 remainder of the command). The other form of literal, the non- 719 synchronizing literal, is used to transmit a string from client to 720 server without waiting for a command continuation request. The non- 721 synchronizing literal differs from the synchronizing literal by 722 having a plus ("+") between the number of octets and the close brace 723 ("}") and by having the octet data immediately following the CRLF. 725 A quoted string is a sequence of zero to 1024 octets excluding CR, 726 LF, double quote (<">), or backslash ("\") with double quote (<">) 727 characters at each end. 729 The empty string is respresented as "" (a quoted string with zero 731 Internet DRAFT ACAP March 26, 1997 733 characters between double quotes), as {0} followed by CRLF (a 734 synchronizing literal with an octet count of 0), or as {0+} followed 735 by a CRLF (a non-synchronizing literal with an octet count of 0). 737 Note: Even if the octet count is 0, a client transmitting a 738 synchronizing literal must wait to receive a command 739 continuation request. 741 3.1.3.1. 8-bit and Binary Strings 743 ACAP implementations MAY transmit 8-bit octets in literals. Except 744 in the values of attributes whose names end with ".bin", these octets 745 are interpreted as UTF-8 character sequences [UTF-8]. NUL octets are 746 only permitted in the values of attributes whose names end with 747 ".bin". Servers SHOULD verify that any non-binary string sent by the 748 client has valid UTF-8 syntax before storing it. 750 3.1.4. Parenthesized List 752 Data structures are represented as a "parenthesized list"; a sequence 753 of data items, delimited by space, and bounded at each end by 754 parentheses. A parenthesized list can contain other parenthesized 755 lists, using multiple levels of parentheses to indicate nesting. 757 The empty list is represented as () -- a parenthesized list with no 758 members. 760 3.1.5 NIL 762 The special atom "NIL" represents the non-existence of a particular 763 data item that is represented as a string or parenthesized list, as 764 distinct from the empty string "" or the empty parenthesized list (). 766 3.2. ACAP URL scheme 768 ACAP URLs are used within the ACAP protocol for the "subdataset" 769 attribute, referrals and inheritance. They provide a convenient 770 syntax for referring to other ACAP datasets. The ACAP URL follows 771 the common Internet scheme syntax as defined in [BASIC-URL]. If 772 : is omitted, the port defaults to 674. 774 An ACAP URL has the following general form: 776 url-acap ::= "acap://" url-server "/" url-enc-entry [url-filter] 778 Internet DRAFT ACAP March 26, 1997 780 The element (defined below) includes the hostname, and 781 optional user name, authentication mechanism and port number. The 782 element contains the name of an entry path encoded 783 according to the rules in [BASIC-URL]. 785 The element is made up of up to three components. The 786 first is a which specifies a list of interesting 787 attributes. The second is which specifies the DEPTH of 788 the search. The final element is which is an 789 encoded version of search-criteria. The default values for these 790 fields are "*", "DEPTH=1", and "ALL" respectively. 792 Note that unsafe or reserved characters such as " " or "?" must be 793 encoded according to the rules defined in [BASIC-URL]. Note that 794 octets encoded in the %A0 format with the high bit set are 795 interpreted according to UTF-8 [UTF8]. 797 3.2.1. ACAP URL User Name and Authentication Mechanism 799 A user name and/or authentication mechanism may be supplied. They 800 are used in the "AUTHENTICATE" command after making the connection to 801 the ACAP server. If no user name or authentication mechanism is 802 supplied, then the user name "anonymous" is used with the SASL XXX 803 mechanism and the password is supplied as the Internet e-mail address 804 of the end user accessing the resource. If the URL supplies just a 805 user name, the program interpreting the ACAP URL SHOULD request a 806 password from the user if necessary. 808 An authentication mechanism can be expressed by adding 809 ";AUTH=" to the end of the user name. When such an 810 is indicated, the client SHOULD request appropriate 811 credentials from that mechanism and use the "AUTHENTICATE" command. 812 If no user name is specified, one SHOULD be obtained from the 813 mechanism or requested from the user as appropriate. 815 The string ";AUTH=*" indicates that the client SHOULD select an 816 appropriate authentication mechanism. It MAY use any mechanism 817 listed in the initial ACAP response. If no user name is specified 818 and no appropriate authentication mechanisms are available, the 819 client SHOULD fall back to anonymous login as described above. This 820 allows a URL which grants read-write access to authorized users, and 821 read-only anonymous access to other users. 823 Note that if unsafe or reserved characters such as " " or ";" are 824 present in the user name or authentication mechanism, they MUST be 825 encoded as described in BASE-URL [BASE-URL]. 827 Internet DRAFT ACAP March 26, 1997 829 3.2.2. Relative ACAP URLs 831 Because ACAP uses "/" as the hierarchy separator for dataset paths, 832 it works well with the relative URL rules defined in REL-URL [REL- 833 URL]. 835 The grammar element is considered part of the user name for 836 purposes of resolving relative ACAP URLs. 838 The base URL for a relative URL stored in an attribute's value is 839 formed by taking the path to the dataset containing that attribute, 840 appending a "/" followed by the entry name of the entry containing 841 that attribute followed by "/". 843 3.3. Contexts 845 A context is an ordered subset of entries in a dataset, created by a 846 SEARCH command with a MAKECONTEXT modifier. Context names are 847 client-generated strings and must not start with the slash ('/') 848 character. 850 Contexts only have scope within the ACAP session in which they were 851 created. There is a server-imposed limit on the number of contexts 852 that may exist at one time within a session. The minimum value for 853 this limit is 100, if the server supports a larger limit it must 854 advertise it in a CONTEXTLIMIT capability. 856 3.4. Orderings 858 An ordering is a named collation function which takes two input 859 strings and determines whether they are greater than, less than, or 860 equal to each other. Orderings are used both for simple equality 861 searching, for ordinal comparision searching and for sorting of 862 attributes. An ordering is prefixed by either "+" or "-". If 863 prefixed by "-", then the order is reversed. In all collation 864 functions, NIL is always less than any other value and is equal only 865 to itself. 867 Additional ordering functions may be registered with IANA according 868 to the rules in section
. 870 The following ordering functions are defined by this standard: 872 octet The octet ordering function interprets the value of an 873 attribute as a series of unsigned octets with ordinal values 874 from 0 to 255. Each octet pair is compared in sequence 875 until the octets are unequal or the end of the string is 876 reached. When collating two strings where the shorter is a 878 Internet DRAFT ACAP March 26, 1997 880 prefix of the longer, the shorter string is interpreted as 881 having a smaller ordinal value. The +octet form collates 882 smaller ordinal values earlier, and the -octet form collates 883 larger ordinal values earlier. For non-binary values, the 884 +octet ordering is equivalent to the ANSI C strcmp() 885 function applied to C string representations of the values. 887 en-nocase 888 The en-nocase ordering function first applies a mapping to 889 the attribute values which translates all US-ASCII letters 890 to uppercase (octet values 0x61 to 0x7A are translated to 891 octet values 0x41 to 0x5A respectively), then applies the 892 octet ordering function as described above. With this 893 function the values "hello" and "HELLO" have the same 894 ordinal value and are considered equal. 896 numeric 897 The numeric ordering function assigns ordinal values based 898 on a US-ASCII encoded decimal positive integer 899 interpretation. With the numeric function, all values which 900 do not begin with a digit are considered equal with an 901 ordinal value of -1. Otherwise, all US-ASCII digits (octet 902 values 0x30 to 0x39) are interpreted starting from the 903 beginning of the string to the first non-digit or the end of 904 the string. 906 3.5. Server Status Responses 908 An OK, NO or BAD response from the server, whether tagged or 909 untagged, is considered a status response. Status responses may 910 include an optional response code. A response code consists of data 911 inside parentheses in the form of an atom, possibly followed by a 912 space and arguments. The response code contains additional 913 information or status codes for client software beyond the OK/NO/BAD 914 condition, and are defined when there is a specific action that a 915 client can take based upon the additional information. 917 The currently defined response codes are: 919 ALERT The human-readable text contains a special alert 920 that MUST be presented to the user in a fashion 921 that calls the user's attention to the message. 923 MODIFIED This response code indicates that a conditional 924 store failed because the MODTIME on the entry is 925 later than the modtime specified with the STORE 927 Internet DRAFT ACAP March 26, 1997 929 command. 931 PERMISSION A STORE, SETQUOTA, or SETACL command failed due to 932 insufficient permission. 934 QUOTA A STORE command which would have increased the size 935 of the dataset failed due to insufficient quota. 937 REFER This response code may be returned in a tagged NO 938 response to any command that takes a dataset name 939 as a parameter. It has one argument with the 940 syntax of a relative URL. It is a referral, 941 indicating that the command should be retried using 942 the dataset named in the relative URL. 944 TOOMANY This response code may be returned in a tagged OK 945 response to a SEARCH command which includes the 946 LIMIT modifier. The argument returns the number of 947 matching entries. 949 TRYFREECONTEXT This response code may be returned in a tagged NO 950 respose to a SEARCH command which includes the 951 MAKECONTEXT modifier. It indicates that a new 952 context may not be created due to the server's 953 limit on the number of existing contexts. 955 WAYTOOMANY This response code may be returned in a tagged OK 956 response to a SEARCH command which includes a 957 HARDLIMIT search modifier. It indicates that the 958 SEARCH would have returned more entries than the 959 hardlimit permitted. 961 Additional response codes defined by particular client or server 962 implementations should be prefixed with an "X" until they are 963 added to a revision of this protocol. Client implementations MUST 964 ignore response codes that they do not recognize. 966 3.6. Server Command Continuation Request 968 The command continuation request is indicated by a "+" token instead 969 of a tag. This indicates that the server is ready to accept the 970 continuation of a command from the client. The remainder of this 971 response is a line of text. 973 This response is used in the AUTHENTICATE command to transmit server 974 data to the client, and request additional client data. This 975 response is also used if an argument to any command is a 976 synchronizing literal. 978 Internet DRAFT ACAP March 26, 1997 980 The client is not permitted to send the octets of a synchronizing 981 literal unless the server indicates that it expects it. This permits 982 the server to process commands and reject errors on a line-by-line 983 basis, assuming it checks for non-synchronizing literals at the end 984 of each line. The remainder of the command, including the CRLF that 985 terminates a command, follows the octets of the literal. If there 986 are any additional command arguments the literal octets are followed 987 by a space and those arguments. 989 Example: C: A099 FREECONTEXT {10} 990 S: + "Ready for additional command text" 991 C: FRED 992 C: FOOB 993 S: A099 OK "FREECONTEXT completed" 994 C: A044 BLURDYBLOOP {102856} 995 S: A044 BAD "No such command as 'BLURDYBLOOP'" 997 Internet DRAFT ACAP March 26, 1997 999 4. Protocol Specification 1001 ACAP commands and responses are described in this section. Commands 1002 are organized first by the state in which the command is permitted, 1003 then by a general category of command type. 1005 Command arguments, identified by "Arguments:" in the command 1006 descriptions below, are described by function, not by syntax. The 1007 precise syntax of command arguments is described in the Formal Syntax 1008 section. 1010 Some commands cause specific server data to be returned; these are 1011 identified by "Data:" in the command descriptions below. See the 1012 response descriptions in the Responses section for information on 1013 these responses, and the Formal Syntax section for the precise syntax 1014 of these responses. It is possible for server data to be transmitted 1015 as a result of any command; thus, commands that do not specifically 1016 require server data specify "no specific data for this command" 1017 instead of "none". 1019 The "Result:" in the command description refers to the possible 1020 tagged status responses to a command, and any special interpretation 1021 of these status responses. 1023 4.1. Initial Connection 1025 Upon session startup, the server sends one of two untagged responses: 1026 ACAP or BYE. The untagged BYE response is described in section 1027
. 1029 4.1.1. ACAP Untagged Response 1031 Data: capability list 1033 The untagged ACAP response indicates the session is ready to 1034 accept commands and contains a space-separated listing of 1035 capabilities that the server supports. Each capability is an atom 1036 name, possibly followed by a string argument in parenthesis. 1038 ACAP capability names MUST be defined in a standards track or IESG 1039 approved experimental RFC and registered with IANA according to 1040 the rules in section
. 1042 Client implementations SHOULD NOT require any capability name, and 1043 MUST ignore any unknown capability names. 1045 Internet DRAFT ACAP March 26, 1997 1047 The following initial capabilities are defined: 1049 CONTEXTLIMIT 1050 The CONTEXTLIMIT capability has one argument which is a 1051 number describing the maximum number of contexts the server 1052 supports per connection. The number 0 indicates the server 1053 has no limit, otherwise this number MUST be greater than 1054 100. 1056 IMPLEMENTATION 1057 The IMPLEMENTATION capability has one argument which is a 1058 string describing the server implementation. ACAP clients 1059 MUST NOT alter their behavior based on this value. It is 1060 intended primarily for debugging purposes. 1062 ORDERINGS 1063 The ORDERINGS capability includes a list of the 1064 ordering/comparison functions which the server supports. 1065 See section
for a description of 1066 ordering/comparison functions. 1068 SASL The SASL capability includes a list of the authentication 1069 mechanisms supported by the server. See [SASL] for more 1070 information. 1072 Example: S: * OK IMPLEMENTATION("ACME v3.5") SASL("CRAM-MD5" 1073 "GSSAPI") 1075 4.2. Any State 1077 The following commands and responses are valid in any state. 1079 4.2.1. NOOP Command 1081 Arguments: none 1083 Data: no specific data for this command (but see below) 1085 Result: OK - noop completed 1086 BAD - command unknown or arguments invalid 1088 The NOOP command always succeeds. It does nothing. It can be 1090 Internet DRAFT ACAP March 26, 1997 1092 used to reset any inactivity autologout timer on the server. 1094 Example: C: a002 NOOP 1095 S: a002 OK "NOOP completed" 1097 4.2.2. LOGOUT Command 1099 Arguments: none 1101 Data: mandatory untagged response: BYE 1103 Result: OK - logout completed 1104 BAD - command unknown or arguments invalid 1106 The LOGOUT command informs the server that the client is done with 1107 the session. The server must send a BYE untagged response before 1108 the (tagged) OK response, and then close the network connection. 1110 Example: C: A023 LOGOUT 1111 S: * BYE "ACAP Server logging out" 1112 S: A023 OK "LOGOUT completed" 1113 (Server and client then close the connection) 1115 4.2.3. OK Response 1117 Data: optional response code 1118 human-readable text 1120 The OK response indicates an information message from the server. 1121 When tagged, it indicates successful completion of the associated 1122 command. The human-readable text may be presented to the user as 1123 an information message. The untagged form indicates an 1124 information-only message; the nature of the information may be 1125 indicated by a response code. 1127 Example: S: * OK (ALERT) "System shutdown in 10 minutes" 1129 4.2.4. NO Response 1131 Data: optional response code 1132 human-readable text 1134 The NO response indicates an operational error message from the 1135 server. When tagged, it indicates unsuccessful completion of the 1136 associated command. The untagged form indicates a warning; the 1138 Internet DRAFT ACAP March 26, 1997 1140 command may still complete successfully. The human-readable text 1141 describes the condition. 1143 Example: C: A001 NOOP 1144 S: * NO (ALERT) "Dataset '/addressbook/user/fred' is at 1145 98% of quota" 1146 S: A001 OK "NOOP" 1147 ... 1148 C: A222 STORE ("/mailboxes/comp.mail.misc" 1149 "mailbox.creation-time" 1150 "19951206103412") 1151 S: A222 NO (PERMISSION) "Permission denied" 1153 4.2.5. BAD Response 1155 Data: optional response code 1156 human-readable text 1158 The BAD response indicates an error message from the server. When 1159 tagged, it reports a protocol-level error in the client's command; 1160 the tag indicates the command that caused the error. The untagged 1161 form indicates a protocol-level error for which the associated 1162 command can not be determined; it may also indicate an internal 1163 server failure. The human-readable text describes the condition. 1165 Example: C: ...empty line... 1166 S: * BAD "Empty command line" 1167 C: A443 BLURDYBLOOP 1168 S: A443 BAD "Unknown command" 1169 C: A444 NOOP Hello 1170 S: A444 BAD "invalid arguments" 1172 4.2.6. BYE Untagged Response 1174 Data: optional response code 1175 human-readable text 1177 The untagged BYE response indicates that the server is about to 1178 close the connection. The human-readable text may be displayed to 1179 the user in a status report by the client. The BYE response may 1180 be sent as part of a normal logout sequence, or as a panic 1181 shutdown announcement by the server. It is also used by some 1182 server implementations as an announcement of an inactivity 1183 autologout. 1185 This response is also used as one of two possible greetings at 1187 Internet DRAFT ACAP March 26, 1997 1189 session startup. It indicates that the server is not willing to 1190 accept a session from this client. 1192 Example: S: * BYE "Autologout; idle for too long" 1194 4.3. Non-Authenticated State 1196 In non-authenticated state, the AUTHENTICATE command establishes 1197 authentication and enters authenticated state. The AUTHENTICATE 1198 command provides a general mechanism for a variety of authentication 1199 techniques. 1201 Server implementations may allow non-authenticated access to certain 1202 information. The convention is to use an AUTHENTICATE command with 1203 the userid "anonymous" with the SASL XXX mechanism. 1205 Once authenticated (including as anonymous), it is not possible to 1206 re-enter non-authenticated state. 1208 In addition to the universal commands (NOOP and LOGOUT), the 1209 following commands are valid in non-authenticated state: 1210 AUTHENTICATE. 1212 4.3.1. AUTHENTICATE Command 1214 Arguments: SASL mechanism name 1215 optional initial response 1217 Data: continuation data may be requested 1219 Result: OK - authenticate completed, now in authenticated state 1220 NO - authenticate failure: unsupported authentication 1221 mechanism, credentials rejected 1222 BAD - command unknown or arguments invalid, 1223 authentication exchange cancelled 1225 The AUTHENTICATE command indicates an authentication mechanism to 1226 the server. If the server supports the requested authentication 1227 mechanism, it performs an authentication protocol exchange to 1228 authenticate and identify the user. Optionally, it also 1229 negotiates a security layer for subsequent protocol interactions. 1230 If the requested authentication mechanism is not supported, the 1231 server rejects the AUTHENTICATE command by sending a tagged NO 1232 response. 1234 The authentication protocol exchange consists of a series of 1236 Internet DRAFT ACAP March 26, 1997 1238 server challenges and client answers that are specific to the 1239 authentication mechanism. A server challenge consists of a 1240 command continuation request with the "+" token followed by a 1241 BASE64 encoded string. The client answer consists of a line 1242 consisting of a BASE64 encoded string. If the client wishes to 1243 cancel an authentication exchange, it should issue a line with a 1244 single "*". If the server receives such an answer, it must reject 1245 the AUTHENTICATE command by sending a tagged BAD response. 1247 The optional initial-response argument to the AUTHENTICATE command 1248 is used to save a round trip when using authentication mechanisms 1249 that are defined to send no data in the initial challenge. When 1250 the initial-response argument is used with such a mechanism, the 1251 initial empty challenge is not sent to the client and the server 1252 uses the data in the initial-response argument as if it were sent 1253 in response to the empty challenge. If the initial-response 1254 argument to the AUTHENTICATE command is used with a mechanism 1255 that sends data in the initial challenge, the server rejects the 1256 AUTHENTICATE command by sending a tagged NO response. 1258 The service name specified by this protocol's profile of SASL is 1259 "acap". 1261 If a security layer is negotiated through the SASL authentication 1262 exchange, it takes effect immediately following the CRLF that 1263 concludes the authentication exchange for the client, and the CRLF 1264 of the tagged OK response for the server. 1266 The server is not required to support any particular 1267 authentication mechanism, nor are authentication mechanisms 1268 required to support any protection mechanisms. If an AUTHENTICATE 1269 command fails with a NO response, the client may try another 1270 authentication mechanism by issuing another AUTHENTICATE command. 1271 In other words, the client may request authentication types in 1272 decreasing order of preference. 1274 Example: S: * OK IMPLEMENTATION("Blorfysoft v3.5") 1275 SASL(KERBEROS_V4) 1276 C: A001 AUTHENTICATE KERBEROS_V4 1277 S: + AmFYig== 1278 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1279 +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd 1280 WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh 1281 S: + or//EoAADZI= 1282 C: DiAF5A4gA+oOIALuBkAAmw== 1283 S: A001 OK "Kerberos V4 authentication successful" 1285 Note: the line breaks in the first client answer are for 1287 Internet DRAFT ACAP March 26, 1997 1289 editorial clarity and are not in real authenticators. 1291 4.4. Searching 1293 This section describes the SEARCH command, for retrieving data from 1294 datasets. 1296 4.4.1. SEARCH Command 1298 Arguments: dataset or context name 1299 optional list of modifiers 1300 search criteria 1302 Data: intermediate responses: ENTRY, MODTIME, REFER 1303 untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME 1305 Result: OK - search completed 1306 NO - search failure: can't perform search 1307 BAD - command unknown or arguments invalid 1309 The SEARCH command identifies a subset of entries in a dataset and 1310 returns information on that subset to the client. 1312 The first argument to SEARCH identifies what is to be searched. 1313 If the string begins with a slash ("/"), it is the name of a 1314 dataset to be searched, otherwise it is a name of a context that 1315 was created by a SEARCH command given previously in the session. 1317 A successful SEARCH command MUST result in a MODTIME intermediate 1318 response. 1320 Following that are zero or more modifiers to the search. Each 1321 modifier may be specified at most once. The defined modifiers 1322 are: 1324 DEPTH number The SEARCH command will traverse the dataset tree 1325 up to the specified depth. ENTRY responses will 1326 include the full path to the entry. A value of "0" 1327 indicates that the search should traverse the 1328 entire tree. A value of "1" is the default and 1329 indicates only the specified dataset should be 1330 searched. If a dataset is traversed which is not 1331 located on the current server, then a REFER 1332 intermediate response is returned for that subtree 1333 and the search continues. 1335 Internet DRAFT ACAP March 26, 1997 1337 If this is used in combination with a SORT or 1338 MAKECONTEXT operator, the server MUST return a BAD 1339 command completion result. 1341 HARDLIMIT number 1342 If the SEARCH command would result in more than 1343 number entries, the SEARCH fails with a NO 1344 completion result with a WAYTOOMANY response code. 1346 LIMIT number number 1347 Limits the number of intermediate ENTRY responses 1348 that the search may generate. The first numeric 1349 argument specifies the limit, the second number 1350 specifies the number of entries to return if the 1351 number of matches exceeds the limit. If the limit 1352 is exceeded, the SEARCH command still succeeds, 1353 returning the total number of matches in a TOOMANY 1354 response code in the tagged OK response. 1356 MAKECONTEXT context 1357 The SEARCH command creates a context with the name 1358 given in the argument to refer to the matching 1359 entries. 1361 If the SEARCH is successful, the context name may 1362 then be given as an argument to subsequent SEARCH 1363 commands to search the set of matching entries. 1365 If a context with the specified name already 1366 exists, it is first freed. If a new context may 1367 not be created due to the server's limit on the 1368 number of existing contexts, the command fails, 1369 returning a TRYFREECONTEXT response code in the 1370 tagged NO response. 1372 Contexts are discussed in more detail in section 1373
. 1375 NOTIFYCONTEXT Requests that the server send untagged ADDTO, 1376 REMOVEFROM, CHANGE, and MODTIME responses while the 1377 context created or referenced by this SEARCH 1378 command exists. The server MAY issue untagged 1379 ADDTO, REMOVEFROM, CHANGE and MODTIME notifications 1380 for a context at any time between the issuing of 1381 the SEARCH command with NOTIFYCONTEXT and the 1382 completion of a FREECONTEXT command for the 1383 context. After issuing a sequence of ADDTO, 1384 REMOVEFROM or CHANGE notifications, the server MUST 1386 Internet DRAFT ACAP March 26, 1997 1388 issue an untagged MODTIME notification indicating 1389 that the client has all updates to the entries in 1390 the context up to and including the given modtime 1391 value. 1393 The client MAY issue a subsequent SEARCH on the 1394 context with a NOTIFYCONTEXT modifier, and this MAY 1395 be used to change the list of attributes and 1396 metadata included in ADDTO and CHANGE responses for 1397 the context. 1399 RETURN (metadata...) 1400 Specifies what is to be returned in intermediate 1401 ENTRY responses. If this modifier is not 1402 specified, no intermediate ENTRY responses are 1403 returned. 1405 Inside the parentheses is a list of attributes, 1406 each optionally followed by a parenthesized list of 1407 metadata. If the parenthesized list of metadata is 1408 not specified, it defaults to "(value)". 1410 An attribute name with a trailing "*" requests all 1411 attributes with that prefix. A "*" by itself 1412 requests all attributes. If the parenthesized list 1413 of metadata is not specified for an attribute with 1414 a trailing "*", it defaults to "(attribute value)". 1416 Following the last intermediate ENTRY response, the 1417 server returns a single intermediate MODTIME 1418 response. 1420 SORT (attribute ordering...) 1421 Specifies the order in which any resulting ENTRY 1422 replies are to be returned to the client. The SORT 1423 modifier takes as an argument a parenthesized list 1424 of one or more attribute/ordering pairs. Attribute 1425 lists the attribute to sort on, ordering specifies 1426 the name of the collation rule to apply to the 1427 values of the attribute. Successive 1428 attribute/ordering pairs are used to order two 1429 entries only when all preceeding pairs indicate the 1430 two entries collate the same. 1432 If the SORT modifier is used in conjunction with 1433 the MAKECONTEXT modifier, the SORT modifier 1434 specifies the ordering of entries in the created 1435 context. 1437 Internet DRAFT ACAP March 26, 1997 1439 If no SORT modifier is specified, or none of the 1440 attribute/ordering pairs indicates an order for the 1441 two entries, the server uses the order of the 1442 entries that exists in the context or dataset being 1443 searched. 1445 Following the modifiers is the search criteria. Searching 1446 criteria consist of one or more search keys. Search keys may be 1447 combined using the AND, and OR search keys. For example, the 1448 criteria (the newline is for readability and not part of the 1449 criteria): 1450 AND COMPARE modtime +octet "19951206103400" 1451 COMPARE modtime -octet "19960112000000" 1452 refers to all entries modified between 10:34 December 6 1995 and 1453 midnight January 12, 1996 UTC. 1455 The currently defined search keys are as follows. 1457 ALL This matches all entries. 1459 AND search-key1 search-key2 1460 Entries that match both search keys. 1462 COMPARE attribute ordering value 1463 Entries for which the specified attribute collates using the 1464 specified ordering the same or later than the specified 1465 value. 1467 COMPARESTRICT attribute ordering value 1468 Entries for which the specified attribute collates using the 1469 specified ordering later than the specified value. 1471 EQUAL attribute ordering value 1472 Entries for which the specified attribute collates using the 1473 specified ordering the same as the specified value. 1475 NOT search-key 1476 Entries that do not match the specified search key. 1478 OR search-key1 search-key2 1479 Entries that match either search key. 1481 RANGE start end time 1482 Entries which are within the specified range of the context's 1483 ordering. The lowest-ordered entry in the context is 1484 assigned number one, the next lowest entry is assigned number 1485 two, and so on. The numeric arguments specify the lowest and 1487 Internet DRAFT ACAP March 26, 1997 1489 highest numbers to match. The time specifies that the client 1490 has processed notifications for the context up to the 1491 specified time. If the context has been modified since then, 1492 the server MUST either return a NO with a MODIFIED response 1493 code, or return the results that the SEARCH would have 1494 returned if none of the changes since that time had been 1495 made. 1497 RANGE is only permitted on contexts. If RANGE is used with a 1498 dataset, the server MUST return a BAD command completion 1499 result. 1501 Example: C: [TODO - write examples] 1503 4.4.2. ENTRY Intermediate Response 1505 Data: entry name 1506 entry data 1508 The ENTRY intermediate response occurs as a result of a SEARCH 1509 command. This is the means by which dataset entries are returned 1510 to the client. The entry with the given name matches the search. 1511 Following the entry name is a set of zero or more strings, each 1512 containing the respective metadata, contained in the entry, that 1513 was specified in the RETURN search modifier. 1515 4.4.3. MODTIME Intermediate Response 1517 Data: modtime value 1519 The MODTIME intermediate response occurs as a result of a SEARCH 1520 command. It indicates that the just created context or the 1521 previously returned ENTRY responses include all updates to the 1522 returned entries up to and including the modtime value in the 1523 argument. 1525 4.4.4. REFER Intermediate Response 1527 Data: dataset path 1528 ACAP URL 1530 The REFER intermediate response occurs as a result of a multi- 1531 level SEARCH where one of the levels is located on a different 1532 server. The reponse indicates the dataset which is not located on 1533 the current server and an ACAP URL for where that dataset may be 1534 found. 1536 Internet DRAFT ACAP March 26, 1997 1538 4.5. Contexts 1540 The following commands use contexts created by a SEARCH command with 1541 a MAKECONTEXT modifier. 1543 4.5.1. FREECONTEXT Command 1545 Arguments: context name 1547 Data: no specific data for this command 1549 Result: OK - freecontext completed 1550 NO - freecontext failure: no such context 1551 BAD - command unknown or arguments invalid 1553 The FREECONTEXT command causes the server to free all state 1554 associated with the named context. The context may no longer be 1555 searched and the server will no longer issue any untagged 1556 responses for the context. The context is no longer counted 1557 against the server's limit on the number of contexts. 1559 Example: C: A683 FREECONTEXT "blurdybloop" 1560 S: A683 OK "Freecontext completed" 1562 4.5.2. UPDATECONTEXT Command 1564 Arguments: list of context names 1566 Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME 1568 Result: OK - Updatecontext completed: all updates completed 1569 NO - Updatecontext failed: no such context 1570 BAD - command unknown or arguments invalid 1572 The UPDATECONTEXT command causes the server to ensure that the 1573 client is notified of all changes to the contexts listed as 1574 arguments up to the current time. The contexts listed in the 1575 arguments must have been previously given to a successful SEARCH 1576 command with a NOTIFYCONTEXT modifier. A MODTIME untagged 1577 response MUST be returned if any read-write metadata in the 1578 dataset changed since the last MODTIME on that context. This 1579 includes metadata which is not listed in the RETURN modifier on 1580 the last SEARCH command with a NOTIFYCONTEXT modifier for this 1581 context. 1583 While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and 1585 Internet DRAFT ACAP March 26, 1997 1587 MODTIME at any time, the UPDATECONTEXT command is used to "prod" 1588 the server to send any notifications it has not sent yet. 1590 The UPDATECONTEXT command SHOULD NOT be used to poll for updates. 1592 Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl" 1593 S: Z4S9 OK "client has been notified of all changes" 1595 4.5.3. ADDTO Untagged Response 1597 Data: context name 1598 entry name 1599 position 1600 metadata list 1602 The untagged ADDTO response informs the client that an entry has 1603 been added to a context. The response includes the position 1604 number of the added entry (the first entry in the context is 1605 numbered 1) and those metadata contained in the entry which match 1606 the RETURN statement specified in the last SEARCH command on the 1607 context with a NOTIFYCONTEXT search modifier. 1609 The ADDTO response implicitly adds one to the position of all 1610 members of the context which had position numbers that were 1611 greater than or equal to the ADDTO position number. 1613 Example: S: * ADDTO "blurdybloop" "fred" 15 ("addressbook.email" 1614 "fred@rock.org") 1616 4.5.4. REMOVEFROM Untagged Response 1618 Data: context name 1619 entry name 1620 old position 1622 The untagged REMOVEFROM response informs the client that an entry 1623 has been removed from a context. The response includes the 1624 position number that the removed entry used to have (the first 1625 entry in the context is numbered 1). 1627 The REMOVEFROM response implicity subtracts one from the position 1628 numbers of all members of the context which had position numbers 1629 greater than the REMOVEFROM position number. 1631 Example: S: * REMOVEFROM "blurdybloop" "fred" 15 1633 Internet DRAFT ACAP March 26, 1997 1635 4.5.5. CHANGE Untagged Response 1637 Data: context name 1638 entry name 1639 old position 1640 new position 1641 metadata list 1643 The untagged CHANGE response informs the client that an entry in a 1644 context has either changed position in the context or has changed 1645 the values of one or more of the attributes specified in the last 1646 SEARCH command with a NOTIFYCONTEXT search modifier for the 1647 context. 1649 The response includes the previous and current position numbers of 1650 the entry (the first entry in the context is numbered 1) and those 1651 attribute/value pairs contained in the entry which match 1652 attributes specified in the last SEARCH command with a 1653 NOTIFYCONTEXT search modifier for the context. 1655 The CHANGE reponse implicitly changes the position numbers of all 1656 entries which had position numbers between the old and new 1657 position. If old position is less than new position, than one is 1658 subtracted from all entries which had position numbers in that 1659 range. Otherwise one is added to all entries which had position 1660 numbers in that range. If the old position and new position are 1661 the same, then no implicit position renumbering occurs. 1663 Example: S: * CHANGE "blurdybloop" "fred" 15 10 1664 ("addressbook.email" "fred@stone.org") 1666 4.5.6. MODTIME Untagged Response 1668 Data: context name 1669 modtime value 1671 The untagged MODTIME response informs the client that it has 1672 recieved all updates to entries in the context which have modtime 1673 values less than or equal to the modtime value in the argument. 1675 Example: S: * MODTIME mycontext "19970320162338" 1677 4.6. Dataset modification 1679 The following commands and responses handle modification of datasets. 1681 Internet DRAFT ACAP March 26, 1997 1683 4.6.1. STORE Command 1685 Arguments: entry store list 1687 Data: no specific data for this command 1689 Result: OK - store completed 1690 NO - store failure: can't store that name 1691 UNCHANGEDSINCE specified and entry changed 1692 BAD - command unknown or arguments invalid 1693 invalid UTF-8 syntax 1695 Creates, modifies or deletes the named entries in the named 1696 datasets. The values of metadata not specified in the command are 1697 not changed. Setting the "value" metadata of an attribute to NIL 1698 removes that attribute from the entry. Setting the "value" 1699 metadata of the "entry" attribute to NIL removes that entry from 1700 the dataset. Changing the value of the "entry" attribute 1701 indicates a request to rename the entry. 1703 For each entry listed, an "UNCHANGEDSINCE" time may be included. 1704 If the "modtime" of the entry is later than the unchangedsince 1705 time, then the store fails with a MODIFIED response code. Clients 1706 writing to a shared dataset SHOULD use UNCHANGEDSINCE when 1707 modifying an existing entry. 1709 The server MUST either make all the changes specified or make none 1710 of them. If the STORE command includes no metadata for an entry, 1711 that entry's MODTIME MUST NOT be updated. 1713 The reserved attribute "modtime" may not be included in the 1714 metadata list, but will automatically be updated. 1716 Example: C: A342 STORE ("/addressbook/user/fred/ABC547" 1717 "addressbook.phone" "555-1234" 1718 "addressbook.Common Name" 1719 "Barney Rubble" "addressbook.email" NIL) 1720 S: A342 OK "Store completed" 1721 C: A343 STORE ("/addressbook/group/Tech/ABD42" 1722 UNCHANGEDSINCE "19970320162338" 1723 "addressbook.prs.hair-length" "10 inches") 1724 S: A343 NO (MODIFIED) "'ABD42' has been changed by 1725 somebody else." 1726 C: A344 STORE ("/addressbook/group/Tech/ACD54" "entry" 1727 NIL) 1728 S: A344 OK "Store completed" 1730 Internet DRAFT ACAP March 26, 1997 1732 4.6.2. DELETEDSINCE Command 1734 Arguments: dataset name 1735 time 1737 Data: intermediate response: DELETED 1739 Result: OK - DELETED completed 1740 NO - DELETED failure: can't read dataset 1741 date too far in the past 1742 BAD - command unknown or arguments invalid 1744 The DELETEDSINCE command returns in intermediate DELETED replies 1745 the names of entries that have been deleted from the named dataset 1746 since the given time. 1748 Servers may impose a limit on the number or age of deleted entry 1749 names they keep track of. If the server does not have information 1750 going back to the specified time, the command fails, returning a 1751 TOOOLD response code in the tagged NO response. 1753 Example: C: Z4S9 DELETEDSINCE "/mailboxes/common" 19951205103412 1754 S: Z4S9 DELETED "blurdybloop" 1755 S: Z4S9 DELETED "anteaters" 1756 S: Z4S9 OK "DELETEDSINCE completed" 1757 C: Z4U3 DELETEDSINCE "/mailboxes/common" 19951009040854 1758 S: Z4U3 NO (TOOOLD) "Don't have that information" 1760 4.6.3. DELETED Intermediate Response 1762 Data: entry name 1764 The untagged DELETED response occurs as a result of a DELETEDSINCE 1765 command. It returns an entry that has been deleted from the 1766 dataset specified in the DELETEDSINCE command. 1768 Example: S: Z4S9 DELETED "blurdybloop" 1770 4.7. Access Control Lists 1772 An access control list is a tab-separated set of identifier,rights 1773 pairs. 1775 Identifier is a UTF-8 string. The identifier anyone is reserved to 1776 refer to the universal identity (all authentications, including 1777 anonymous). All user name strings accepted by the AUTHENTICATE 1778 command to authenticate to the ACAP server are reserved as 1780 Internet DRAFT ACAP March 26, 1997 1782 identifiers for the corresponding user. Identifiers starting with a 1783 dash ("-") are reserved for "negative rights", described below. All 1784 other identifier strings have implementation-defined semantics. 1786 Rights is a string listing a (possibly empty) set of alphanumeric 1787 characters, each character listing a set of operations which is being 1788 controlled. Letters are reserved for ``standard'' rights, listed 1789 below. The set of standard rights may only be extended by a 1790 standards-track or IESG approved experimental RFC. Digits are 1791 reserved for implementation or site defined rights. The currently 1792 defined standard rights are: 1794 r - read 1795 w - write 1796 i - insert (store a new value) 1797 o - override (see section
) 1798 a - administer (perform store on ACL attribute/metadata) 1800 An implementation may force rights to always or never be granted. 1801 Rights are never tied, unlike the IMAP ACL extension [IMAP-ACL]. 1803 It is possible for multiple identifiers in an access control list to 1804 apply to a given user (or other authentication identity). For 1805 example, an ACL may include rights to be granted to the identifier 1806 matching the user, one or more implementation-defined identifiers 1807 matching groups which include the user, and/or the identifier 1808 "anyone". How these rights are combined to determine the user's 1809 access is implementation-defined. An implementation may choose, for 1810 example, to use the union of the rights granted to the applicable 1811 identifiers. An implementation may instead choose, for example, to 1812 only use those rights granted to the most specific identifier present 1813 in the ACL. A client may determine the set of rights granted to the 1814 logged-in user for a given mailbox by using the MYRIGHTS command. 1816 When an identifier in an ACL starts with a dash ("-"), that indicates 1817 that associated rights are to be removed from the identifier that is 1818 prefixed by the dash. For example, if the identifier "-fred" is 1819 granted the "w" right, that indicates that the "w" right is to be 1820 removed from users matching the identifier "fred". Implementations 1821 need not support having identifiers which start with a dash in ACLs. 1823 Each attribute of each entry of a dataset may potentially have an 1824 ACL. If an attribute in an entry does not have an ACL, then access 1825 is controlled by a default ACL for that attribute in the dataset, if 1826 it exists. If there is no default ACL for that attribute in the 1827 dataset, access is controlled by a default ACL for that dataset. The 1828 default ACL for a dataset must exist. 1830 Internet DRAFT ACAP March 26, 1997 1832 In order to perform any manipulation on an entry in a dataset, the 1833 client must have 'r' rights on the "entry" attribute of the entry. 1834 Implementations should take care not to reveal via error messages the 1835 existence of an entry for which the client does not have 'r' rights. 1836 A client does not need access to the "subdataset" attribute of the 1837 parent dataset in order to access the contents of a dataset. 1839 Many of the ACL commands and responses include an ``acl object'' 1840 parameter, for specifying what the ACL applies to. This is a 1841 parenthesized list. The list contains just the dataset name when 1842 referring to the default ACL for a dataset. The list contains a 1843 dataset name and an attribute name when referring to the default ACL 1844 for an attribute in a dataset. The list contains a dataset name, an 1845 attribute name, and an entry name when referring to the ACL for an 1846 attribute of an entry of a dataset. 1848 4.7.1. SETACL Command 1850 Arguments: acl object 1851 authentication identifier 1852 access rights 1854 Data: no specific data for this command 1856 Result: OK - setacl completed 1857 NO - setacl failure: can't set acl 1858 BAD - command unknown or arguments invalid 1860 The SETACL command changes the access control list on the 1861 specified object so that the specified identifier is granted the 1862 permissions enumerated in rights. If the object did not 1863 previously have an access control list, one is created. 1865 Example: C: A123 SETACL ("/addressbook/user/joe/public") anyone r 1866 S: A123 OK "Setacl complete" 1867 C: A124 SETACL ("/mailboxes/common") B1FF rwa 1868 S: A124 NO (PERMISSION) "'B1FF' not permitted to modify 1869 access rights 1870 for '/mailboxes/common'" 1872 Internet DRAFT ACAP March 26, 1997 1874 4.7.2. DELETEACL Command 1876 Arguments: acl object 1877 optional authentication identifier 1879 Data: no specific data for this command 1881 Result: OK - deleteacl completed 1882 NO - deleteacl failure: can't delete acl 1883 BAD - command unknown or arguments invalid 1885 If given the optional identifier argument, the DELETEACL command 1886 removes any portion of the access control list on the specified 1887 object for the specified identifier. 1889 If not given the optional identifier argument, the DELETEACL 1890 command removes the ACL from the object entirely, causing access 1891 to be controlled by a higher-level default ACL. This form of the 1892 DELETEACL command is not permitted on the default ACL for a 1893 dataset and servers MUST return a BAD. 1895 Example: C: A223 DELETEACL ("/addressbook/user/joe/public") anyone 1896 S: A223 OK "Deleteacl complete" 1897 C: A224 DELETEACL ("/mailboxes/common") 1898 S: A224 BAD "Can't delete ACL from dataset" 1899 C: A225 DELETEACL ("/addressbook/user/fred" 1900 "addressbook.email" "barney") 1901 S: A225 OK "Deleteacl complete" 1903 4.7.3. MYRIGHTS Command 1905 Arguments: acl object 1907 Data: intermediate responses: MYRIGHTS 1909 Result: OK - myrights completed 1910 NO - myrights failure: can't get rights 1911 BAD - command unknown or arguments invalid 1913 The MYRIGHTS command returns the set of rights that the client has 1914 to the given dataset or dataset attribute. 1916 Example: C: A003 MYRIGHTS ("/mailboxes/common") 1917 S: A003 MYRIGHTS "r" 1919 Internet DRAFT ACAP March 26, 1997 1921 S: A003 OK "Myrights complete" 1923 4.7.4. MYRIGHTS Intermediate Response 1925 Data: rights 1927 The MYRIGHTS response occurs as a result of a MYRIGHTS command. 1928 The argument is the set of rights that the client has for the 1929 object referred to in the MYRIGHTS command. 1931 4.7.5. LISTRIGHTS Command 1933 Arguments: acl object 1934 authentication identifier 1936 Data: untagged responses: LISTRIGHTS 1938 Result: OK - listrights completed 1939 NO - listrights failure: can't get rights list 1940 BAD - command unknown or arguments invalid 1942 The LISTRIGHTS command takes an object and an identifier and 1943 returns information about what rights may be granted to the 1944 identifier in the ACL for the object. 1946 Example: C: a001 LISTRIGHTS ("/mailboxes") smith 1947 S: a001 LISTRIGHTS ("/mailboxes") smith r w 1948 S: a001 OK Listrights completed 1950 C: a005 LISTRIGHTS ("/mailboxes" archive.imap) anyone 1951 S: a005 LISTRIGHTS ("/mailboxes" archive.imap) anyone "" 1952 r w 1953 S: a005 OK Listrights completed 1955 4.7.6. LISTRIGHTS Intermediate Response 1957 Data: acl object 1958 identifier 1959 required rights 1960 list of optional rights 1962 The LISTRIGHTS response occurs as a result of a LISTRIGHTS 1964 Internet DRAFT ACAP March 26, 1997 1966 command. The first two arguments are the object and identifier 1967 for which this rights list applies. Following the identifier is a 1968 string containing the (possibly empty) set of rights the 1969 identifier will always be granted on the dataset or attribute. 1971 Following this are zero or more strings each containing a single 1972 right the identifier may be granted in the dataset or attribute. 1974 The same right may not be listed more than once in the LISTRIGHTS 1975 response. 1977 4.8. Quotas 1979 Quotas are used to manage storage consumed by ACAP datasets. A quota 1980 root is a place where a resource limit may be set which applies to an 1981 implementation dependant subset of datasets. 1983 4.8.1. SETQUOTA Command 1985 Arguments: quota root 1986 resource limit in octets or NIL 1988 Data: intermediate responses: QUOTA 1990 Result: OK - Quota root resource limit modified 1991 NO - Quota failure: can't modify resourse limit 1992 BAD - command unknown or arguments invalid 1994 The SETQUOTA command takes the name of a quota root and a number 1995 indicating the desired resource limit in octets on all datasets 1996 within that root. A value of "0" indicates no resource limit is 1997 desired. A value of NIL indicates the quota root should be 1998 removed. 2000 If the named quota root did not previously exist and a value other 2001 than NIL is specified, an implementation SHOULD create it. If the 2002 quota root exists and a value of NIL is specified, an 2003 implementation SHOULD delete the quota root. In either case the 2004 implementation may change the quota root which applies to any 2005 number of datasets. 2007 Example: C: A042 SETQUOTA "/user/fred" 1048576 2008 S: A042 QUOTA "/user/fred" 1048576 0 2009 S: A042 OK "Setquota completed" 2010 C: A043 SETQUOTA "/usr/fred" NIL 2011 S: A043 OK "Setquota completed" 2013 Internet DRAFT ACAP March 26, 1997 2015 4.8.2. GETQUOTA Command 2017 Arguments: dataset 2019 Data: intermediate responses: QUOTA 2021 Result: OK - Quota information returned 2022 NO - Quota failure: can't access resourse limit 2023 BAD - command unknown or arguments invalid 2025 The GETQUOTA command takes the name of a dataset, and returns in 2026 an intermediate QUOTA response the name of the quota root, the 2027 amount of the resource limit on that root and the amount of that 2028 resource limit which is used. 2030 Example: C: A043 GETQUOTA "/option/user/fred/common" 2031 S: A043 QUOTA "/user/fred" 1024 50 2032 S: A043 OK "Getquota completed" 2034 4.8.3. QUOTA Intermediate Response 2036 Data: quota root 2037 resource limit in octets 2038 amount of resource limit used 2040 The QUOTA intermediate response is generated as a result of a 2041 SETQUOTA or GETQUOTA command. It includes the name of the quota 2042 root, the resource limit in octets and the amount of resource 2043 limit used. 2045 4.9. Extensions 2047 In order to simplify the process of extending the protocol, clients 2048 MUST ignore unknown server responses which meet the syntax of 2049 response-extend. In addition, clients MUST ignore server response 2050 codes which meet the syntax of resp-code-ext. Availability of new 2051 commands MUST be announced via a capability on the initial greeting 2052 line and such commands SHOULD meet the syntax of command-extend. 2054 Servers MUST respond to unknown commands with a BAD command 2055 completion result. Servers MUST skip over non-synchronizing literals 2056 contained in an extension command. This may be done by assuming the 2057 unknown command matches the command-extend syntax, or by reading a 2058 line at a time and checking for the non-synchronizing literal syntax 2059 at the end of the line. 2061 Internet DRAFT ACAP March 26, 1997 2063 5. Dataset Management 2065 The entry with an empty name in the dataset is used to hold 2066 management information for the dataset as a whole. 2068 5.1. Dataset Inheritance 2070 It is possible for a dataset to inherit data from another. Data in 2071 the inherited dataset appears in the inheriting dataset, except where 2072 explicitly overridden by data in the inheriting dataset. 2074 The inherited dataset specifies which values may be overridden in the 2075 inheriting datasets. If an inherited dataset has a non-NIL value for 2076 any given attribute in an entry, the ACL for that attribute in that 2077 entry must grant a user the 'o' right in order for the user to store 2078 a corresponding value in an inheriting dataset. 2080 The inherited dataset is usually a system-wide or group-wide set of 2081 defaults. The system-wide dataset usually has one inheriting dataset 2082 per user, allowing each user to add to or modify the defaults as 2083 appropriate. 2085 An entry which exists in both the inheriting and inherited dataset 2086 has a modtime equal to the greator of the modtimes for the purposes 2087 of a SEARCH command and context notification. Inheritance has no 2088 effect on the STORE command other than that specified by the 'o' 2089 right. 2091 Servers MUST support at least two levels of inheritance. This 2092 permits a user's dataset such as "/options/user/fred/common" to 2093 inherit from a group dataset such as "/options/group/dinosaur 2094 operators/common" which in turn inherits from a server-wide dataset 2095 such as "/options/common/common". 2097 5.2. Dataset attributes 2099 The following attributes apply to management of the dataset when 2100 stored in the "" entry of a dataset. 2102 dataset.acl 2103 This holds the default access control list for the dataset. It 2104 can not be modified by the STORE command, only by the SETACL and 2105 DELETEACL commands. 2107 dataset.acl. 2108 This holds the default access control list for an attribute 2109 within the dataset. It can not be modified by the STORE command, 2111 Internet DRAFT ACAP March 26, 1997 2113 only by the SETACL and DELETEACL commands. 2115 dataset.inherit 2116 This holds the name of a dataset to inherit according to the 2117 rules in section
. 2119 6. Namespace conventions 2121 6.1. Dataset Namespace 2123 The dataset namespace is a slash-separated hierarchy. By convention, 2124 the first component of the dataset namespace is a dataset class. A 2125 dataset class SHOULD be published as an RFC which includes predefined 2126 set of attributes and their meanings. The second component of the 2127 dataset name is "common", "group", or "user" for server-wide, group- 2128 wide, or per-user datasets respectively. For group or user datasets, 2129 the third component of the dataset name is the name of the group or 2130 the AUTHENTICATE identifier for the user. Other components of the 2131 dataset name are specific to the dataset class. 2133 Dataset classes MUST be registered with IANA according to the rules 2134 in section
. Dataset classes which are intended for 2135 interoperable use MUST be published as a standards track or IESG 2136 approved experimental RFC. 2138 6.2. Attribute Namespace 2140 Attribute names which do not contain a dot (".") are reserved for 2141 standardized attributes which have meaning in any dataset. In order 2142 to simplify implementations, the attribute namespace is intended to 2143 be unique across all datasets. To achieve this, attribute names are 2144 prefixed with the dataset class name followed by a dot ("."). 2145 Attributes which effect management of the dataset are prefixed with 2146 "dataset.". In addition, a subtree of the "vnd." or "prs." 2147 namespaces may be registered with IANA according to the rules in 2148 section
. ACAP implementors are encouraged to help define 2149 interoperable dataset classes rather than using the private attribute 2150 namespaces. 2152 7. Registration procedures 2154 ACAP's usefulness comes from providing a structured storage model for 2155 all sorts of configuration data. However, for its potential to be 2156 achieved, it is important that the Internet community strives for the 2157 following goals: 2159 Internet DRAFT ACAP March 26, 1997 2161 (1) Standardization. It is very important to standardize dataset 2162 classes. The authors hope that ACAP achieves the success that SNMP 2163 has seen with the definition of numerous standards track MIBs. 2165 (2) Community Review. In the absence of standardization, it is 2166 important to get community review on a proposal to improve the 2167 engineering quality. Community review is strongly recommended prior 2168 to registration. The ACAP developers mailing list may be used for this purpose. 2171 (3) Registration. Registration serves a two-fold purpose. First it 2172 prevents use of the same name for different purposes, and second it 2173 provides a one-stop list which can be used to locate existing 2174 extensions. 2176 The following registration templates may be used to register ACAP 2177 protocol elements. 2179 7.1. Ordering Functions 2181 Additional ordering functions may be registered with IANA on a 2182 first-come, first-served basis. Ordering functions intended for 2183 interoperable use SHOULD be defined as a standards track or IESG 2184 approved experimental RFC. 2186 To: XXX@XXX.XXX 2187 Subject: Registration of new ACAP ordering function 2189 Ordering name: 2191 Scope: Any Dataset / Specific Dataset class / Specific locality 2193 Published Specification(s): 2195 (If the published specification is not standards track, or no 2196 published specifiction is referenced then the ordering function is 2197 assumed to be for limited use) 2199 Person and email address to contact for further information: 2201 7.2. ACAP Capabilities 2203 New ACAP capabilities MUST be standards track or IESG approved 2204 experimental RFCs. Registration provides a simple way to locate all 2205 extensions. Careful consideration should be made before extending 2206 the protocol, as it can lead to complexity or interoperability 2207 problems. 2209 Internet DRAFT ACAP March 26, 1997 2211 To: XXX@XXX.XXX 2212 Subject: Registration of ACAP capability 2214 Capability name: 2216 Capability keyword: 2218 Capability arguments: 2220 standards track/IESG-approved experimental RFC number: 2222 7.3. Dataset Classes 2224 A dataset class provides a core set of attributes for use in a 2225 specified hierarchy. It may also define rules for the dataset 2226 hierarchy underneath that class. Community review of dataset classes 2227 is strongly encouraged. Classes intended for interoperable use 2228 should be written as standards track or IESG approved experimental 2229 RFCs. 2231 To: XXX@XXX.XXX 2232 Subject: Registration of ACAP dataset class 2234 Dataset class name/attribute prefix: 2236 Purpose: 2238 Required attributes: 2240 Optional attributes: 2242 Published Specification(s): 2244 (The published specification must be freely available on the 2245 Internet or included with the registration. It should include ABNF 2246 [as defined in RFC 822] for the specified attributes.) 2248 Person and email address to contact for further information: 2250 7.4. Private Attribute Subtree 2252 A private attribute subtree may be registered on a first come, first 2253 serve basis. Private attributes may be used to store information 2254 specific to a particular client within an ACAP entry of any dataset 2255 class. Whenever possible, private attributes should be avoided in 2256 favor of improving interoperable dataset class definitions. 2258 Internet DRAFT ACAP March 26, 1997 2260 To: XXX@XXX.XXX 2261 Subject: Registration of ACAP private prefix 2263 Private Prefix: vnd.. or prs.. 2265 Person and email address to contact for further information: 2267 (company names and addresses should be included when appropriate) 2269 8. Formal Syntax 2271 The following syntax specification uses the augmented Backus-Naur 2272 Form (BNF) notation as specified in [IMAIL] with one exception; the 2273 delimiter used with the "#" construct is a single space (SPACE) and 2274 not one or more commas. 2276 Except as noted otherwise, all alphabetic characters are case- 2277 insensitive. The use of upper or lower case characters to define 2278 token strings is for editorial clarity only. Implementations MUST 2279 accept these strings in a case-insensitive fashion. 2281 ALPHA ::= "A" / "B" / "C" / "D" / "E" / "F" / "G" / "H" / "I" / 2282 "J" / "K" / "L" / "M" / "N" / "O" / "P" / "Q" / "R" / 2283 "S" / "T" / "U" / "V" / "W" / "X" / "Y" / "Z" / 2284 "a" / "b" / "c" / "d" / "e" / "f" / "g" / "h" / "i" / 2285 "j" / "k" / "l" / "m" / "n" / "o" / "p" / "q" / "r" / 2286 "s" / "t" / "u" / "v" / "w" / "x" / "y" / "z" / 2287 ;; Case-sensitive 2289 ATOM-CHAR ::= 2291 ATOM-SPECIALS ::= "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS 2293 BASE64-CHAR ::= ALPHA / DIGIT / "+" / "/" 2295 CHAR ::= 2297 CHAR8 ::= 2299 CR ::= 2301 CRLF ::= CR LF 2303 CTL ::= 2305 DIGIT ::= "0" / DIGIT-NZ 2307 DIGIT-NZ ::= "1" / "2" / "3" / "4" / "5" / "6" / "7" / "8" / "9" 2309 Internet DRAFT ACAP March 26, 1997 2311 LF ::= 2313 OCTET ::= 2315 QUOTED-CHAR ::= / 2316 "\" QUOTED-SPECIALS 2318 QUOTED-SPECIALS ::= <"> / "\" 2320 SPACE ::= 2322 TEXT-CHAR ::= 2324 TEXT-UTF8-CHAR ::= 2326 UTF8-CHAR ::= 2328 acl-identifier ::= string 2330 acl-object ::= "(" dataset [SPACE attribute [SPACE entry-name]] ")" 2332 acl-rights ::= quoted 2334 atom ::= 1*1024ATOM-CHAR 2336 attribute ::= string 2337 ;; dot-separated attribute name 2338 ;; ends in ".bin" if value not textual 2339 ;; MUST NOT contain "*" 2341 auth-type ::= atom 2342 ;; as defined in SASL [SASL] 2344 base64-token ::= *(4BASE64-CHAR) [base64-terminal] 2346 base64-terminal ::= (2BASE64-CHAR "==") / (3BASE64-CHAR "=") 2348 command ::= tag SPACE (command-any / command-auth / 2349 command-nonauth) CRLF 2350 ;; Modal based on state 2352 command-authent ::= "AUTHENTICATE" SPACE atom [SPACE base64-token] 2353 *(CRLF base64-token) 2355 command-any ::= "NOOP" 2357 Internet DRAFT ACAP March 26, 1997 2359 command-auth ::= command-delacl / command-dsince / 2360 command-freectx / command-getquota / 2361 command-lrights / command-myrights / 2362 command-search / command-setacl / 2363 command-setquota / command-store 2364 ;; only valid in authenticaticated state 2366 command-delacl ::= "DELETEACL" SPACE acl-object [SPACE acl-identifier] 2368 command-delete ::= "DELETE" SPACE entry-path 2370 command-dsince ::= "DELETEDSINCE" SPACE dataset SPACE time 2372 command-extend ::= atom [SPACE #extension-data] 2374 command-freectx ::= "FREECONTEXT" SPACE context 2376 command-getquota ::= "GETQUOTA" SPACE dataset 2378 command-lrights ::= "LISTRIGHTS" SPACE acl-object 2380 command-myrights ::= "MYRIGHTS" SPACE acl-object 2382 command-nonauth ::= command-authent 2383 ;; only valid in non-authenticated state 2385 command-search ::= "SEARCH" SPACE (dataset / context) 2386 *(SPACE search-modifier) 2387 SPACE search-criteria 2389 command-setacl ::= "SETACL" SPACE acl-object SPACE acl-identifier 2390 SPACE acl-rights 2392 command-setquota ::= "SETQUOTA" SPACE quota-root SPACE (number / nil) 2394 command-store ::= "STORE" SPACE 1#store-entry 2396 context ::= string 2397 ;; MUST NOT begin with slash ("/") 2399 continue-req ::= "+" SPACE (resp-text / base64-token) 2401 dataset ::= string 2402 ;; slash-separated dataset name 2403 ;; begins with slash 2405 entry ::= entry-name / entry-path 2407 Internet DRAFT ACAP March 26, 1997 2409 entry-name ::= string 2410 ;; entry name MUST NOT contain slash 2411 ;; MUST NOT begin with "." 2413 entry-path ::= string 2414 ;; slash-separated path to entry 2415 ;; begins with slash 2417 entry-relative ::= string 2418 ;; potentially relative path to entry 2420 extension-data ::= string / number / "(" #extension-data ")" 2422 initial-greeting ::= "*" SPACE "ACAP" *(SPACE init-capability) CRLF 2424 init-capability ::= atom [ "(" 1#string ")" ] 2426 literal ::= "{" number [ "+" ] "}" CRLF *OCTET 2427 ;; The number represents the number of octets 2428 ;; MUST be literal-utf8 except for values of 2429 ;; attributes whose names end in ".bin" 2431 literal-utf8 ::= "{" number [ "+" ] "}" CRLF *UTF8-CHAR 2432 ;; The number represents the number of octets 2434 metadata ::= attribute [ "(" 1#metadata-type ")" ] 2436 metadata-partial ::= "value<" number "." number ">" 2438 metadata-store ::= 1#(attribute ["(" metadata-write ")"] SPACE 2439 nstring) 2441 metadata-type ::= "acl" / "attribute" / "myrights" / "size" / 2442 metadata-partial / metadata-write 2444 metadata-write ::= "value" 2446 nil ::= "NIL" 2448 nstring ::= nil / string 2450 number ::= 1*DIGIT 2452 nz-number ::= DIGIT-NZ *DIGIT 2454 ordering ::= ("+" / "-") atom 2456 quota-root ::= dataset 2458 Internet DRAFT ACAP March 26, 1997 2460 quoted ::= <"> *QUOTED-CHAR <"> 2462 response ::= *response-data response-done 2464 response-addto ::= "*" SPACE "ADDTO" SPACE context SPACE entry-name 2465 SPACE number SPACE #return-data 2467 response-bye ::= "*" SPACE "BYE" SPACE resp-body CRLF 2468 ;; Server will disconnect condition 2470 response-change ::= "*" SPACE "CHANGE" SPACE context SPACE entry-name 2471 SPACE number SPACE number SPACE #return-data 2473 response-data ::= response-change / response-deleted / 2474 response-entry / response-implic / 2475 response-mtimei / response-mtimeu / 2476 response-myright / response-refer / 2477 response-remove / response-stat / response-bye 2479 response-deleted ::= tag SPACE "DELETED" SPACE entry-name 2481 response-done ::= tag SPACE resp-cond-state CRLF 2483 response-entry ::= tag SPACE "ENTRY" SPACE entry SPACE #return-data 2485 response-extend ::= tag SPACE atom [SPACE 1#extension-data] 2487 response-implic ::= tag SPACE "LISTRIGHTS" SPACE acl-rights 2488 0*(SPACE acl-rights) 2490 response-mtimei ::= tag SPACE "MODTIME" SPACE time 2492 response-mtimeu ::= "*" SPACE "MODTIME" SPACE context SPACE time 2494 response-myright ::= tag SPACE "MYRIGHTS" SPACE acl-rights 2496 response-refer ::= tag SPACE "REFER" SPACE dataset SPACE 2497 <"> url-relative <"> 2499 response-remove ::= "*" SPACE "REMOVEFROM" SPACE context SPACE 2500 entry-name SPACE number 2502 response-stat ::= "*" SPACE resp-cond-state CRLF 2504 resp-body ::= ["(" resp-code ")" SPACE] quoted 2506 Internet DRAFT ACAP March 26, 1997 2508 resp-code ::= "ALERT" / "MODIFIED" / "PERMISSION" / "QUOTA" / 2509 resp-code-refer / resp-code-many / 2510 "TRYFREECONTEXT" / resp-code-ext 2512 resp-code-ext ::= atom [SPACE 1#extension-data] 2513 ;; extension-data MUST NOT contain "]" 2515 resp-code-many ::= "TOOMANY" SPACE nz_number 2517 resp-code-refer ::= "REFER" SPACE 1#(<"> url-relative <">) 2519 resp-cond-state ::= ("OK" / "NO" / "BAD") SPACE resp-body 2520 ;; Status condition 2522 return-data ::= nstring / number 2524 searchkey-equal ::= "EQUAL" SPACE attribute SPACE ordering SPACE value 2526 searchkey-comp ::= "COMPARE" SPACE attribute SPACE ordering SPACE value 2528 searchkey-strict ::= "COMPARESTRICT" SPACE attribute SPACE ordering 2529 SPACE value 2531 searchkey-range ::= "RANGE" SPACE nz-number SPACE nz-number 2532 SPACE time 2534 searchmod-depth ::= "DEPTH" SPACE number 2536 searchmod-hard ::= "HARDLIMIT" SPACE nz-number 2538 searchmod-limit ::= "LIMIT" SPACE number SPACE number 2540 searchmod-make ::= "MAKECONTEXT" SPACE context 2542 searchmod-notify ::= "NOTIFYCONTEXT" 2544 searchmod-return ::= "RETURN" SPACE "(" #metadata ")" 2546 searchmod-sort ::= "SORT" SPACE "(" 1#(attribute SPACE ordering) ")" 2548 search-criteria ::= "ALL" / searchkey-equal / searchkey-comp / 2549 searchkey-strict / searchkey-range / 2550 "NOT" SPACE search-criteria / 2551 "OR" SPACE search-criteria SPACE search-criteria / 2552 "AND" SPACE search-criteria SPACE search-criteria 2554 Internet DRAFT ACAP March 26, 1997 2556 search-modifier ::= searchmod-depth / searchmod-hard / 2557 searchmod-limit / searchmod-make / 2558 searchmod-notify / searchmod-return / 2559 searchmod-sort 2561 store-cond ::= SPACE "UNCHANGEDSINCE" SPACE time 2563 store-entry ::= "(" entry-path [store-cond] 2564 *(SPACE metadata-store) ")" 2566 string ::= quoted / literal 2568 tag ::= 1* 2570 time ::= <"> time-year time-month time-day time-hour 2571 time-minute time-second time-subsecond <"> 2573 time-day ::= 2DIGIT ;; 00-31 2575 time-hour ::= 2DIGIT ;; 00-23 2577 time-minute ::= 2DIGIT ;; 00-59 2579 time-month ::= 2DIGIT ;; 01-12 2581 time-second ::= 2DIGIT ;; 00-60 2583 time-subsecond ::= *DIGIT 2585 time-year ::= 4DIGIT 2587 value ::= nstring 2589 url-acap ::= "acap://" url-server "/" url-enc-entry [url-filter] 2590 ;; url-enc-entry interpreted relative to "/" 2592 url-attr-list ::= url-enc-attr *("&" url-enc-attr) 2594 url-auth ::= ";AUTH=" ("*" / auth-type) 2596 url-achar ::= uchar / "&" / "=" / "~" 2597 ;; See RFC 1738 for definition of "uchar" 2599 url-char ::= uchar / "=" / "~" / ":" / "@" / "/" 2600 ;; See RFC 1738 for definition of "uchar" 2602 url-depth ::= "DEPTH=" number 2604 Internet DRAFT ACAP March 26, 1997 2606 url-enc-attr ::= 1*url-char 2607 ;; encoded version of attribute name 2609 url-enc-auth ::= 1*url-achar 2610 ;; encoded version of auth-type above 2612 url-enc-entry ::= 1*url-char 2613 ;; encoded version of entry-relative above 2615 url-enc-search ::= 1*url-char 2616 ;; encoded version of search-criteria above 2618 url-enc-user ::= *url-achar 2619 ;; encoded version of login userid 2621 url-filter ::= "?" url-attr-list ["?" url-depth ["?" url-enc-search]] 2623 url-relative ::= url-acap / [url-enc-entry] [url-filter] 2624 ;; url-enc-entry is relative to base URL 2626 url-server ::= [url-user [url-auth] "@"] hostport 2627 ;; See RFC 1738 for definition of "hostport" 2629 Internet DRAFT ACAP March 26, 1997 2631 9. Security Considerations 2633 ACAP protocol transactions, including address book and option data, 2634 are sent in the clear over the network unless the optional privacy 2635 protection is negotiated in the AUTHENTICATE command. 2637 Additional security considerations are discussed in the section 2638 discussing the AUTHENTICATE command. 2640 10. Authors' Addresses 2642 Chris Newman 2643 Innosoft International, Inc. 2644 1050 East Garvey Ave. South 2645 West Covina, CA 91790 USA 2647 Email: chris.newman@innosoft.com 2649 John G. Myers 2651 Email: jgm+@cmu.edu 2653 Internet DRAFT ACAP March 26, 1997 2655 Appendices 2657 A. References 2659 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 2660 4rev1", RFC 2060, University of Washington, December 1996. 2662 2664 [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie 2665 Mellon, January 1997. 2667 2669 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 2670 draft-myers-auth-sasl-xx.txt 2672 [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet Text 2673 Messages", STD 11, RFC 822, University of Delaware, August 1982. 2675 2677 [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO 2678 10646", RFC 2044, Alis Technologies, October 1996. 2680 2682 [US-ASCII] "USA Standard Code for Information Interchange," X3.4. 2683 American National Standards Institute: New York (1968). 2685 [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource 2686 Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of 2687 Minnesota, December 1994. 2689 2691 [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, 2692 UC Irvine, June 1995. 2694 2696 Internet DRAFT ACAP March 26, 1997 2698 B. ACAP Keyword Index 2700 ACAP (untagged response) ................................... 19 2701 ADDTO (untagged response) .................................. 31 2702 ALERT (response code) ...................................... 16 2703 ALL (search keyword) ....................................... 28 2704 AND (search keyword) ....................................... 28 2705 AUTHENTICATE (command) ..................................... 23 2706 BAD (response) ............................................. 22 2707 BYE (untagged response) .................................... 22 2708 CHANGE (untagged response) ................................. 32 2709 COMPARE (search keyword) ................................... 28 2710 COMPARESTRICT (search keyword) ............................. 28 2711 CONTEXTLIMIT (ACAP capability) ............................. 20 2712 DELETEACL (command) ........................................ 37 2713 DELETED (intermediate response) ............................ 34 2714 DELETEDSINCE (command) ..................................... 34 2715 DEPTH (search modifier) .................................... 25 2716 ENTRY (intermediate response) .............................. 29 2717 EQUAL (search keyword) ..................................... 28 2718 FREECONTEXT (command) ...................................... 30 2719 GETQUOTA (command) ......................................... 40 2720 HARDLIMIT (search modifier) ................................ 26 2721 IMPLEMENTATION (ACAP capability) ........................... 20 2722 LIMIT (search modifier) .................................... 26 2723 LISTRIGHTS (command) ....................................... 38 2724 LISTRIGHTS (intermediate response) ......................... 38 2725 LOGOUT (command) ........................................... 21 2726 MAKECONTEXT (search modifier) .............................. 26 2727 MODIFIED (response code) ................................... 16 2728 MODTIME (intermediate response) ............................ 29 2729 MODTIME (untagged response) ................................ 32 2730 MYRIGHTS (command) ......................................... 37 2731 MYRIGHTS (intermediate response) ........................... 38 2732 NO (response) .............................................. 21 2733 NOOP (command) ............................................. 20 2734 NOT (search keyword) ....................................... 28 2735 NOTIFYCONTEXT (search modifier) ............................ 26 2736 OK (response) .............................................. 21 2737 OR (search keyword) ........................................ 28 2738 ORDERINGS (ACAP capability) ................................ 20 2739 PERMISSION (response code) ................................. 17 2740 QUOTA (intermediate response) .............................. 40 2741 QUOTA (response code) ...................................... 17 2742 RANGE (search keyword) ..................................... 28 2743 REFER (intermediate response) .............................. 29 2744 REFER (response code) ...................................... 17 2745 REMOVEFROM (untagged response) ............................. 31 2747 Internet DRAFT ACAP March 26, 1997 2749 RETURN (search modifier) ................................... 27 2750 SASL (ACAP capability) ..................................... 20 2751 SEARCH (command) ........................................... 25 2752 SETACL (command) ........................................... 36 2753 SETQUOTA (command) ......................................... 39 2754 SORT (search keyword) ...................................... 27 2755 STORE (command) ............................................ 33 2756 TOOMANY (response code) .................................... 17 2757 TRYFREECONTEXT (response code) ............................. 17 2758 UNCHANGEDSINCE (STORE modifier) ............................ 33 2759 UPDATECONTEXT (command) .................................... 30 2760 WAYTOOMANY (response code) ................................. 17 2761 acl (attribute metadata) ................................... 11 2762 anyone (ACL identifier) .................................... 34 2763 attribute (attribute metadata) ............................. 11 2764 dataset.acl (dataset attribute) ............................ 41 2765 dataset.acl. (dataset attribute) ................ 41 2766 dataset.inherit (dataset attribute) ........................ 42 2767 en-nocase (ordering function) .............................. 16 2768 entry (predefined attribute) ............................... 9 2769 modtime (predefined attribute) ............................. 9 2770 myrights (attribute metadata) .............................. 11 2771 numeric (ordering function) ................................ 16 2772 octet (ordering function) .................................. 15 2773 size (attribute metadata) .................................. 11 2774 subdataset (predefined attribute) .......................... 10 2775 value (attribute metadata) ................................. 11 2776 value (attribute metadata) .................... 11