idnits 2.17.1 draft-ietf-acap-spec-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** There are 26 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 286: '... MUST be explicitly identified in th...' RFC 2119 keyword, line 287: '... which SHOULD include specific fixed...' RFC 2119 keyword, line 289: '...ication, clients MUST NOT depend on th...' RFC 2119 keyword, line 452: '... A client MUST be prepared to accept...' RFC 2119 keyword, line 518: '...d such responses MUST deal with flow c...' (95 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 1997) is 9782 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? 'KEYWORDS' on line 3133 looks like a reference -- Missing reference section? 'IMAP4' on line 3111 looks like a reference -- Missing reference section? 'US-ASCII' on line 3161 looks like a reference -- Missing reference section? 'SASL' on line 3148 looks like a reference -- Missing reference section? 'UTF8' on line 3164 looks like a reference -- Missing reference section? 'UNICODE-2' on line 3158 looks like a reference -- Missing reference section? 'ISO-10646' on line 3125 looks like a reference -- Missing reference section? 'BASIC-URL' on line 3099 looks like a reference -- Missing reference section? 'SASL-ANON' on line 3151 looks like a reference -- Missing reference section? 'IMAP-URL' on line 3121 looks like a reference -- Missing reference section? 'REL-URL' on line 3143 looks like a reference -- Missing reference section? 'ISO-C' on line 3129 looks like a reference -- Missing reference section? 'IMAP-ACL' on line 3116 looks like a reference -- Missing reference section? 'SASL-PLAIN' on line 3154 looks like a reference -- Missing reference section? 'ENUMERATE' on line 1736 looks like a reference -- Missing reference section? 'NOTIFY' on line 1736 looks like a reference -- Missing reference section? 'ABNF' on line 3096 looks like a reference -- Missing reference section? 'LANG-TAGS' on line 3138 looks like a reference -- Missing reference section? 'IAB-CHARSET' on line 3105 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 1 warning (==), 21 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Newman 3 Internet Draft: ACAP Innosoft 4 Document: draft-ietf-acap-spec-05.txt J. G. Myers 5 Netscape 6 July 1997 7 Expires in six months 9 ACAP -- Application Configuration Access Protocol 11 Status of this Memo 13 This document is an Internet-Draft. Internet-Drafts are working 14 documents of the Internet Engineering Task Force (IETF), its areas, 15 and its working groups. Note that other groups may also distribute 16 working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 To view the entire list of current Internet-Drafts, please check the 24 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 25 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), 26 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 27 ftp.isi.edu (US West Coast). 29 Abstract 31 The Application Configuration Access Protocol (ACAP) is designed to 32 support remote storage and access of program option, configuration 33 and preference information. The data store model is designed to 34 allow a client relatively simple access to interesting data, to allow 35 new information to be easily added without server re-configuration, 36 and to promote the use of both standardized data and custom or 37 proprietary data. Key features include "inheritance" which can be 38 used to manage default values for configuration settings and access 39 control lists which allow interesting personal information to be 40 shared and group information to be restricted. 42 Table of Contents 44 Status of this Memo ............................................... i 45 Abstract .......................................................... i 46 ACAP Protocol Specification ....................................... 1 47 0. Changes from version -04 to version -05 .................. 1 48 1. Introduction ............................................. 2 49 1.1. Conventions Used in this Document ........................ 2 50 1.2. ACAP Data Model .......................................... 2 51 1.3. ACAP Design Goals ........................................ 2 52 1.4. Validation ............................................... 3 53 1.5. Definitions .............................................. 3 54 1.6. ACAP Command Overview .................................... 5 55 2. Protocol Framework ....................................... 5 56 2.1. Link Level ............................................... 5 57 2.2. Commands and Responses ................................... 5 58 2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 5 59 2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 6 60 2.3. Server States ............................................ 7 61 2.3.1. Non-Authenticated State .................................. 7 62 2.3.2. Authenticated State ...................................... 7 63 2.3.3. Logout State ............................................. 7 64 2.4. Operational Considerations ............................... 8 65 2.4.1. Untagged Status Updates .................................. 8 66 2.4.2. Response when No Command in Progress ..................... 8 67 2.4.3. Auto-logout Timer ........................................ 8 68 2.4.4. Multiple Commands in Progress ............................ 9 69 2.5. Server Command Continuation Request ...................... 9 70 2.6. Data Formats ............................................. 9 71 2.6.1. Atom ..................................................... 10 72 2.6.2. Number ................................................... 10 73 2.6.3. String ................................................... 10 74 2.6.3.1. 8-bit and Binary Strings ................................. 11 75 2.6.4. Parenthesized List ....................................... 11 76 2.6.5. NIL ...................................................... 11 77 3. Protocol Elements ........................................ 11 78 3.1. Entries and Attributes ................................... 11 79 3.1.1. Predefined Attributes .................................... 12 80 3.1.2. Attribute Metadata ....................................... 13 81 3.2. ACAP URL scheme .......................................... 14 82 3.2.1. ACAP URL User Name and Authentication Mechanism .......... 14 83 3.2.2. Relative ACAP URLs ....................................... 15 84 3.3. Contexts ................................................. 15 85 3.4. Comparators .............................................. 15 86 3.5. Access Control Lists (ACLs) .............................. 17 87 3.6. Server Response Codes .................................... 19 88 4. Namespace Conventions .................................... 21 89 4.1. Dataset Namespace ........................................ 21 90 4.2. Attribute Namespace ...................................... 22 91 4.3. Formal Syntax for Dataset and Attribute Namespace ........ 22 92 5. Dataset Management ....................................... 24 93 5.1. Dataset Inheritance ...................................... 24 94 5.2. Dataset Attributes ....................................... 24 95 5.3. Dataset Creation ......................................... 25 96 5.4. Dataset Class Capabilities ............................... 25 97 5.5. Dataset Quotas ........................................... 26 98 6. Command and Response Specifications ...................... 26 99 6.1. Initial Connection ....................................... 26 100 6.1.1. ACAP Untagged Response ................................... 27 101 6.2. Any State ................................................ 27 102 6.2.1. NOOP Command ............................................. 28 103 6.2.2. LANG Command ............................................. 28 104 6.2.3. LANG Intermediate Response ............................... 29 105 6.2.4. LOGOUT Command ........................................... 29 106 6.2.5. OK Response .............................................. 29 107 6.2.6. NO Response .............................................. 30 108 6.2.7. BAD Response ............................................. 30 109 6.2.8. BYE Untagged Response .................................... 31 110 6.2.9. ALERT Untagged Response .................................. 31 111 6.3. Non-Authenticated State .................................. 31 112 6.3.1. AUTHENTICATE Command ..................................... 32 113 6.4. Searching ................................................ 33 114 6.4.1. SEARCH Command ........................................... 33 115 6.4.2. ENTRY Intermediate Response .............................. 38 116 6.4.3. MODTIME Intermediate Response ............................ 38 117 6.4.4. REFER Intermediate Response .............................. 38 118 6.4.5. Search Examples ....................................... 39 119 6.5. Contexts ................................................. 40 120 6.5.1. FREECONTEXT Command ...................................... 40 121 6.5.2. UPDATECONTEXT Command .................................... 40 122 6.5.3. ADDTO Untagged Response .................................. 41 123 6.5.4. REMOVEFROM Untagged Response ............................. 41 124 6.5.5. CHANGE Untagged Response ................................. 42 125 6.5.6. MODTIME Untagged Response ................................ 43 126 6.6. Dataset modification ..................................... 43 127 6.6.1. STORE Command ............................................ 43 128 6.6.2. DELETEDSINCE Command ..................................... 45 129 6.6.3. DELETED Intermediate Response ............................ 46 130 6.7. Access Control List Commands ............................. 46 131 6.7.1. SETACL Command ........................................... 46 132 6.7.2. DELETEACL Command ........................................ 47 133 6.7.3. MYRIGHTS Command ......................................... 47 134 6.7.4. MYRIGHTS Intermediate Response ........................... 48 135 6.7.5. LISTRIGHTS Command ....................................... 48 136 6.7.6. LISTRIGHTS Intermediate Response ......................... 48 137 6.8. Quotas ................................................... 49 138 6.8.1. GETQUOTA Command ......................................... 49 139 6.8.3. QUOTA Untagged Response .................................. 49 140 6.9. Extensions ............................................... 50 141 7. Registration Procedures .................................. 50 142 7.1. ACAP Capabilities ........................................ 50 143 7.2. ACAP Response Codes ...................................... 51 144 7.3. Dataset Classes .......................................... 51 145 7.4. Vendor Subtree ........................................... 52 146 8. Formal Syntax ............................................ 52 147 9. Multi-lingual Considerations ............................. 62 148 10. Security Considerations .................................. 63 149 11. Acknowledgments .......................................... 63 150 12. Authors' Addresses ....................................... 64 151 Appendices ........................................................ 64 152 A. References ............................................... 64 153 B. ACAP Keyword Index ....................................... 66 154 ACAP Protocol Specification 156 0. Changes from version -04 to version -05 158 1) Disallow syntax for DELETEACL with dataset level ACL. 160 2) TRYCACHE -> TRYLATER. 162 3) PLAINTEXT-DENIED -> AUTH-TOO-WEAK. 164 4) ENCRYPT-NEEDED also based on mechanism. 166 5) Documented TOOOLD in grammar and response code summary (it was 167 missing). 169 6) extensions: *unknown* server response codes ignored by client. 171 7) removed quota management stuff. 173 8) Updated LANG default language text to better match proposed IESG 174 rules. 176 9) Require AFS-style semantics on ACLs. 178 10) Added extension slot to URL scheme and reference IMAP URL spec to 179 avoid a bunch of duplicate text for ;AUTH= meaning and security 180 issues. 182 11) Added DEFAULT token and cleaned up associated inheritance 183 language. 185 12) Clarified entry-path vs. entry-name for ENTRY responses. 187 13) Deferred comparator naming and registration for a future 188 specification. 190 14) Changed LANG response to return language selected and list of 191 appropriate comparators. Removed COMPARATORS item from the 192 capability list. 194 15) Added "snapshot" sentence to MAKECONTEXT. 196 16) Permit STORE to re-order multi-values. 198 17) Added note that SEARCH returns inherited attributes unless 199 NOINHERIT or the user doesn't have permission to read attributes in 200 base dataset. 202 18) Changed .. to - in ABNF. 204 19) Made response codes hierarchical (likely to be an issue for 205 TRYLATER). 207 20) Changed ENTRY grammar to remove unnecessary parentheses. 209 21) Added examples. 211 1. Introduction 213 1.1. Conventions Used in this Document 215 In examples, "C:" and "S:" indicate lines sent by the client and 216 server respectively. If such lines are wrapped without a new "C:" or 217 "S:" label, then the wrapping is for editorial clarity and is not 218 part of the command. 220 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", 221 and "MAY" in this document are to be interpreted as described in "Key 222 words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. 224 1.2. ACAP Data Model 226 An ACAP server exports a hierarchical tree of entries. Each level of 227 the tree is called a dataset, and each dataset is made up of a list 228 of entries. Each entry has a unique name and may contain any number 229 of named attributes. Each attribute within an entry may be single 230 valued or multi-valued and may have associated metadata to assist 231 access and interpretation of the value. 233 The rules with which a client interprets the data within a portion of 234 ACAP's tree of entries are called a dataset class. 236 1.3. ACAP Design Goals 238 ACAP's primary purpose is to allow users access to their 239 configuration data from multiple network-connected computers. Users 240 can then sit down in front of any network-connected computer, run any 241 ACAP-enabled application and have access to their own configuration 242 data. Because it is hoped that many applications will become ACAP- 243 enabled, client simplicity was preferred to server or protocol 244 simplicity whenever reasonable. 246 ACAP is designed to be easily manageable. For this reason, it 247 includes "inheritance" which allows one dataset to inherit default 248 attributes from another dataset. In addition, access control lists 249 are included to permit delegation of management and quotas are 250 included to prevent storage abuse. Finally, an ACAP server which is 251 conformant to this base specification should be able to support most 252 dataset classes defined in the future without requiring a server 253 reconfiguration or upgrade. 255 ACAP is designed to operate well with a client that only has 256 intermittent access to an ACAP server. For this reason, each entry 257 has a server maintained modification time so that the client may 258 detect changes. In addition, the client may ask the server for a 259 list of entries which have been removed since it last accessed the 260 server. 262 ACAP presumes that a dataset may be potentially large and/or the 263 client's network connection may be slow, and thus offers server 264 sorting, selective fetching and change notification for entries 265 within a dataset. 267 As required for most Internet protocols, security, scalability and 268 internationalization were important design goals. 270 Given these design goals, an attempt was made to keep ACAP as simple 271 as possible. It is a traditional Internet text based protocol which 272 massively simplifies protocol debugging. It was designed based on 273 the successful IMAP [IMAP4] protocol framework, with a few 274 refinements. 276 1.4. Validation 278 By default, any value may be stored in any attribute for which the 279 user has appropriate permission and quota. This rule is necessary to 280 allow the addition of new simple dataset classes without 281 reconfiguring or upgrading the server. 283 In some cases, such as when the value has special meaning to the 284 server, it is useful to have the server enforce validation by 285 returning the INVALID response code to a STORE command. These cases 286 MUST be explicitly identified in the dataset class specification 287 which SHOULD include specific fixed rules for validation. Since a 288 given ACAP server may be unaware of any particular dataset class 289 specification, clients MUST NOT depend on the presence of enforced 290 validation on the server. 292 1.5. Definitions 294 access control list (ACL) 295 A set of identifier, rights pairs associated with an object. An 296 ACL is used to determine which operations a user is permitted to 297 perform on that object. See section 3.5. 299 attribute 300 A named value within an entry. See section 3.1. 302 comparator 303 A named function which can be used to perform one or more of 304 three comparison operations: ordering, equality and substring 305 matching. See section 3.4. 307 context 308 An ordered subset of entries in a dataset, created by a SEARCH 309 command with a MAKECONTEXT modifier. See section 3.3. 311 dataset 312 One level of hierarchy in ACAP's tree of entries. 314 dataset class specification 315 The rules which allow a client to interpret the data within a 316 portion of ACAP's tree of entries. 318 entry 319 A set of attributes with a unique entry name. See section 3.1. 321 metadata 322 Information describing an attribute, its value and any access 323 controls associated with that attribute. See section 3.1.2. 325 NIL This represents the non-existence of a particular data item. 327 NUL A control character encoded as 0 in US-ASCII [US-ASCII]. 329 octet 330 An 8-bit value. On most modern computer systems, an octet is 331 one byte. 333 SASL Simple Authentication and Security Layer [SASL]. 335 UTC Universal Coordinated Time as maintained by the Bureau 336 International des Poids et Mesures (BIPM). 338 UTF-8 339 An 8-bit transformation format of the Universal Character Set 340 [UTF8]. Note that an incompatible change was made to the coded 341 character set referenced by [UTF8], so for the purpose of this 342 document, UTF-8 refers to the UTF-8 encoding as defined by 343 version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646] 344 including amendments one through seven. 346 1.6. ACAP Command Overview 348 The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic 349 protocol services. The SEARCH command is used to select, sort, fetch 350 and monitor changes to attribute values and metadata. The 351 UPDATECONTEXT and FREECONTEXT commands are also used to assist in 352 monitoring changes in attribute values and metadata. The STORE 353 command is used to add, modify and delete entries and attributes. 354 The DELETEDSINCE command is used to assist a client in 355 re-synchronizing a cache with the server. The GETQUOTA, SETACL, 356 DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine 357 storage quotas and examine or modify access permissions. 359 2. Protocol Framework 361 2.1. Link Level 363 The ACAP protocol assumes a reliable data stream such as provided by 364 TCP. When TCP is used, an ACAP server listens on port 674. 366 2.2. Commands and Responses 368 An ACAP session consists of the establishment of a client/server 369 connection, an initial greeting from the server, and client/server 370 interactions. These client/server interactions consist of a client 371 command, server data, and a server completion result. 373 All interactions transmitted by client and server are in the form of 374 lines; that is, strings that end with a CRLF. The protocol receiver 375 of an ACAP client or server is either reading a line, or is reading a 376 sequence of octets with a known count followed by a line. Both 377 clients and servers must be capable of handling lines of arbitrary 378 length. 380 2.2.1. Client Protocol Sender and Server Protocol Receiver 382 The client command begins an operation. Each client command is 383 prefixed with a identifier (an alphanumeric string of no more than 32 384 characters, e.g., A0001, A0002, etc.) called a "tag". A different 385 tag is generated by the client for each command. 387 There are two cases in which a line from the client does not 388 represent a complete command. In one case, a command argument is 389 quoted with an octet count (see the description of literal in section 390 2.6.3); in the other case, the command arguments require server 391 feedback (see the AUTHENTICATE command). In some of these cases, the 392 server sends a command continuation request if it is ready for the 393 next part of the command. This response is prefixed with the token 394 "+". 396 Note: If, instead, the server detected an error in the 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. 443 There is no syntactic difference between untagged data that resulted 444 from a specific command and untagged data that were sent 445 unilaterally. 447 The protocol receiver of an ACAP client reads a response line from 448 the server. It then takes action on the response based upon the 449 first token of the response, which may be a tag, a "*", or a "+" as 450 described above. 452 A client MUST be prepared to accept any server response at all times. 453 This includes untagged data that it may not have requested. 455 This topic is discussed in greater detail in the Server Responses 456 section. 458 2.3. Server States 460 An ACAP server is in one of three states. Most commands are valid in 461 only certain states. It is a protocol error for the client to 462 attempt a command while the server is in an inappropriate state for 463 that command. In this case, a server will respond with a BAD command 464 completion result. 466 2.3.1. Non-Authenticated State 468 In non-authenticated state, the user must supply authentication 469 credentials before most commands will be permitted. This state is 470 entered when a connection starts. 472 2.3.2. Authenticated State 474 In authenticated state, the user is authenticated and most commands 475 will be permitted. This state is entered when acceptable 476 authentication credentials have been provided. 478 2.3.3. Logout State 480 In logout state, the session is being terminated, and the server will 481 close the connection. This state can be entered as a result of a 482 client request or by unilateral server decision. 484 +--------------------------------------+ 485 |initial connection and server greeting| 486 +--------------------------------------+ 487 || (1) || (2) 488 VV || 489 +-----------------+ || 490 |non-authenticated| || 491 +-----------------+ || 492 || (4) || (3) || 493 || VV || 494 || +----------------+ || 495 || | authenticated | || 496 || +----------------+ || 497 || || (4) || 498 VV VV VV 499 +--------------------------------------+ 500 | logout and close connection | 501 +--------------------------------------+ 503 (1) connection (ACAP greeting) 504 (2) rejected connection (BYE greeting) 505 (3) successful AUTHENTICATE command 506 (4) LOGOUT command, server shutdown, or connection closed 508 2.4. Operational Considerations 510 2.4.1. Untagged Status Updates 512 At any time, a server can send data that the client did not request. 514 2.4.2. Response when No Command in Progress 516 Server implementations are permitted to send an untagged response 517 while there is no command in progress. Server implementations that 518 send such responses MUST deal with flow control considerations. 519 Specifically, they must either (1) verify that the size of the data 520 does not exceed the underlying transport's available window size, or 521 (2) use non-blocking writes. 523 2.4.3. Auto-logout Timer 525 If a server has an inactivity auto-logout timer, that timer MUST be 526 of at least 30 minutes duration. The receipt of ANY command from the 527 client during that interval MUST suffice to reset the auto-logout 528 timer. 530 2.4.4. Multiple Commands in Progress 532 The client is not required to wait for the completion result of a 533 command before sending another command, subject to flow control 534 constraints on the underlying data stream. Similarly, a server is 535 not required to process a command to completion before beginning 536 processing of the next command, unless an ambiguity would result 537 because of a command that would affect the results of other commands. 538 If there is such an ambiguity, the server executes commands to 539 completion in the order given by the client. 541 2.5. Server Command Continuation Request 543 The command continuation request is indicated by a "+" token instead 544 of a tag. This indicates that the server is ready to accept the 545 continuation of a command from the client. 547 This response is used in the AUTHENTICATE command to transmit server 548 data to the client, and request additional client data. This 549 response is also used if an argument to any command is a 550 synchronizing literal. 552 The client is not permitted to send the octets of a synchronizing 553 literal unless the server indicates that it expects it. This permits 554 the server to process commands and reject errors on a line-by-line 555 basis, assuming it checks for non-synchronizing literals at the end 556 of each line. The remainder of the command, including the CRLF that 557 terminates a command, follows the octets of the literal. If there 558 are any additional command arguments the literal octets are followed 559 by a space and those arguments. 561 Example: C: A099 FREECONTEXT {10} 562 S: + "Ready for additional command text" 563 C: FRED 564 C: FOOB 565 S: A099 OK "FREECONTEXT completed" 566 C: A044 BLURDYBLOOP {102856} 567 S: A044 BAD "No such command as 'BLURDYBLOOP'" 569 2.6. Data Formats 571 ACAP uses textual commands and responses. Data in ACAP can be in one 572 of five forms: atom, number, string, parenthesized list or NIL. 574 2.6.1. Atom 576 An atom consists of one to 1024 non-special characters. It must 577 begin with a letter. Atoms are used for protocol keywords. 579 2.6.2. Number 581 A number consists of one or more digit characters, and represents a 582 numeric value. Numbers are restricted to the range of an unsigned 583 32-bit integer: 0 < number < 4,294,967,296. 585 2.6.3. String 587 A string is in one of two forms: literal and quoted string. The 588 literal form is the general form of string. The quoted string form 589 is an alternative that avoids the overhead of processing a literal at 590 the cost of restrictions of what may be in a quoted string. 592 A literal is a sequence of zero or more octets (including CR and LF), 593 prefix-quoted with an octet count in the form of an open brace ("{"), 594 the number of octets, close brace ("}"), and CRLF. In the case of 595 literals transmitted from server to client, the CRLF is immediately 596 followed by the octet data. 598 There are two forms of literals transmitted from client to server. 599 The form where the open brace ("{") and number of octets is 600 immediately followed by a close brace ("}") and CRLF is called a 601 synchronizing literal. When sending a synchronizing literal, the 602 client must wait to receive a command continuation request (described 603 later in this document) before sending the octet data (and the 604 remainder of the command). The other form of literal, the 605 non-synchronizing literal, is used to transmit a string from client 606 to server without waiting for a command continuation request. The 607 non-synchronizing literal differs from the synchronizing literal by 608 having a plus ("+") between the number of octets and the close brace 609 ("}") and by having the octet data immediately following the CRLF. 611 A quoted string is a sequence of zero to 1024 octets excluding NUL, 612 CR and LF, with double quote (<">) characters at each end. 614 The empty string is represented as "" (a quoted string with zero 615 characters between double quotes), as {0} followed by CRLF (a 616 synchronizing literal with an octet count of 0), or as {0+} followed 617 by a CRLF (a non-synchronizing literal with an octet count of 0). 619 Note: Even if the octet count is 0, a client transmitting a 620 synchronizing literal must wait to receive a command 621 continuation request. 623 2.6.3.1. 8-bit and Binary Strings 625 Most strings in ACAP are restricted to UTF-8 characters and may not 626 contain NUL octets. Attribute values MAY contain any octets 627 including NUL. 629 2.6.4. Parenthesized List 631 Data structures are represented as a "parenthesized list"; a sequence 632 of data items, delimited by space, and bounded at each end by 633 parentheses. A parenthesized list can contain other parenthesized 634 lists, using multiple levels of parentheses to indicate nesting. 636 The empty list is represented as () -- a parenthesized list with no 637 members. 639 2.6.5. NIL 641 The special atom "NIL" represents the non-existence of a particular 642 data item that is represented as a string or parenthesized list, as 643 distinct from the empty string "" or the empty parenthesized list (). 645 3. Protocol Elements 647 This section defines data formats and other protocol elements used 648 throughout the ACAP protocol. 650 3.1. Entries and Attributes 652 Within a dataset, each entry name is made up of zero or more UTF-8 653 characters other than slash ("/"). A slash separated list of 654 entries, one at each level of the hierarchy, forms the full path to 655 an entry. 657 Each entry is made up of a set of attributes. Each attribute has a 658 hierarchical name in UTF-8, with each component of the name separated 659 by a period ("."). 661 The value of an attribute is either single or multi-valued. A single 662 value is NIL (has no value), or a string of zero or more octets. A 663 multi-value is a list of zero or more strings, each of zero or more 664 octets. 666 Attribute names are not permitted to contain asterisk ("*") or 667 percent ("%") and MUST be valid UTF-8 strings which do not contain 668 NUL. Invalid attribute names result in a BAD response. Entry names 669 are not permitted to begin with "." or contain slash ("/") and MUST 670 be valid UTF-8 strings which do not contain NUL. Invalid entry names 671 in the entry field of a command result in a BAD response. 673 Use of non-visible UTF-8 characters in attribute and entry names is 674 discouraged. 676 3.1.1. Predefined Attributes 678 Attribute names which do not contain a dot (".") are reserved for 679 standardized attributes which have meaning in any dataset. The 680 following attributes are defined by the ACAP protocol. 682 entry 683 Contains the name of the entry. MUST be single valued. 684 Attempts to use illegal or multi-valued values for the entry 685 attribute are protocol errors and MUST result in a BAD 686 completion response. This is a special case. 688 modtime 689 Contains the date and time any read-write metadata in the entry 690 was last modified. This value MUST be in UTC, MUST be 691 automatically updated by the server. 693 The value consists of 14 or more US-ASCII digits. The first 694 four indicate the year, the next two indicate the month, the 695 next two indicate the day of month, the next two indicate the 696 hour (0 - 23), the next two indicate the minute, and the next 697 two indicate the second. Any further digits indicate fractions 698 of a second. 700 The time, particularly fractions of a second, need not be 701 accurate. It is REQUIRED, however, that any two entries in a 702 dataset changed by successive modifications have strictly 703 ascending modtime values. In addition, each STORE command 704 within a dataset (including simultaneous stores from different 705 connections) MUST use different modtime values. 707 This attribute has enforced validation, so any attempt to STORE 708 a value in this attribute MUST result in a NO response with an 709 INVALID response code. 711 subdataset 712 If this attribute is set, it indicates the existence of a sub- 713 dataset of this entry. 715 The value consists of a list of relative ACAP URLs (see section 716 3.2) which may be used to locate the sub-dataset. The base URL 717 is the full path to the entry followed by a slash ("/"). The 718 value "." indicates a subdataset is located directly under this 719 one. Multiple values indicate replicated copies of the 720 subdataset. 722 For example, if the dataset "/folder/site/" has an entry 723 "public-folder" with a subdataset attribute of ".", then there 724 exists a dataset "/folder/site/public-folder/". If the value of 725 the subdataset attribute was instead 726 "//other.acap.domain//folder/site/public-folder/" that would 727 indicate the dataset is actually located on a different ACAP 728 server. 730 A dataset can be created by storing a "subdataset" attribute 731 including ".", and a sub-hierarchy of datasets is deleted by 732 storing a NIL value to the "subdataset" attribute on the entry 733 in the parent dataset. 735 This attribute has enforced syntax validation. Specifically, if 736 an attempt is made to STORE a single-value (other than NIL), an 737 empty list, or one of the values does not follow the URL syntax 738 rules [BASIC-URL], then this will result in a NO response with 739 an INVALID response code. 741 3.1.2. Attribute Metadata 743 Each attribute is made up of metadata items which describe that 744 attribute, its value and any associated access controls. Metadata 745 items may be either read-only, in which case the client is never 746 permitted to modify the item, or read-write, in which case the client 747 may modify the item if the access control list (ACL) permits. 749 The following metadata items are defined in this specification: 751 acl The access control list for the attribute, if one exists. If 752 the attribute does not have an ACL, NIL is returned. 753 Read-write. See section 3.5 for the contents of an ACL. 755 attribute 756 The attribute name. Read-only. 758 myrights 759 The set of rights that the client has to the attribute. 760 Read-only. See section 3.5 for the possible rights. 762 size This is the length of the value. In the case of a 763 multi-value, this is a list of lengths for each of the values. 765 Read-only. 767 value The value. For a multi-value, this is a list of single 768 values. Read-write. 770 Additional items of metadata may be defined in extensions to this 771 protocol. Servers MUST respond to unrecognized metadata by returning 772 a BAD command completion result. 774 3.2. ACAP URL scheme 776 ACAP URLs are used within the ACAP protocol for the "subdataset" 777 attribute, referrals and inheritance. They provide a convenient 778 syntax for referring to other ACAP datasets. The ACAP URL follows 779 the common Internet scheme syntax as defined in [BASIC-URL] except 780 that plaintext passwords are not permitted. If : is omitted, 781 the port defaults to 674. 783 An ACAP URL has the following general form: 785 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 786 [url-extension] 788 The element includes the hostname, and optional user 789 name, authentication mechanism and port number. The 790 element contains the name of an entry path encoded according to the 791 rules in [BASIC-URL]. 793 The element is an optional list of interesting attribute 794 names. If omitted, the URL refers to all attributes of the named 795 entry. The element is reserved for extensions to 796 this URL scheme. 798 Note that unsafe or reserved characters such as " " or "?" MUST be 799 hex encoded as described in the URL specification [BASIC-URL]. Hex 800 encoded octets are interpreted according to UTF-8 [UTF8]. 802 3.2.1. ACAP URL User Name and Authentication Mechanism 804 A user name and/or authentication mechanism may be supplied. They 805 are used in the "AUTHENTICATE" command after making the connection to 806 the ACAP server. If no user name or authentication mechanism is 807 supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by 808 default. If an authentication mechanism is supplied without a user 809 name, then one SHOULD be obtained from the specified mechanism or 810 requested from the user as appropriate. If a user name is supplied 811 without an authentication mechanism then ";AUTH=*" is assumed. 813 The ";AUTH=" authentication parameter is interpreted as described in 814 the IMAP URL Scheme [IMAP-URL]. 816 Note that if unsafe or reserved characters such as " " or ";" are 817 present in the user name or authentication mechanism, they MUST be 818 encoded as described in the URL specification [BASIC-URL]. 820 3.2.2. Relative ACAP URLs 822 Because ACAP uses "/" as the hierarchy separator for dataset paths, 823 it works well with the relative URL rules defined in the relative URL 824 specification [REL-URL]. 826 The grammar element is considered part of the user name for 827 purposes of resolving relative ACAP URLs. 829 The base URL for a relative URL stored in an attribute's value is 830 formed by taking the path to the dataset containing that attribute, 831 appending a "/" followed by the entry name of the entry containing 832 that attribute followed by "/". 834 3.3. Contexts 836 A context is subset of entries in a dataset or datasets, created by a 837 SEARCH command with a MAKECONTEXT modifier. Context names are 838 client-generated strings and must not start with the slash ('/') 839 character. 841 When a client creates a context, it may request automatic 842 notification of changes. A client may also request enumeration of 843 entries within a context. Enumeration simplifies the implementation 844 of a "virtual scrollbar" by the client. 846 A context exists only within the ACAP session in which it was 847 created. When the connection is closed, all contexts associated with 848 that connection are automatically discarded. A server is required to 849 support at least 100 active contexts within a session. If the server 850 supports a larger limit it must advertise it in a CONTEXTLIMIT 851 capability. 853 3.4. Comparators 855 A comparator is a named function which takes two input values and can 856 be used to perform one or more of four comparison operations: 857 ordering, equality, prefix and substring matching. 859 The ordering operation is used both for the SORT search modifier and 860 the COMPARE and COMPARESTRICT search keys. Ordering comparators can 861 determine the ordinal precedence of any two values. When used for 862 ordering, a comparator's name can be prefixed with "+" or "-" to 863 indicate that the ordering should be normal order or reversed order 864 respectively. If no prefix is included, "+" is assumed. 866 For the purpose of ordering, a comparator may designate certain 867 values as having an undefined ordinal precedence. Such values always 868 collate with equal value after all other values regardless of whether 869 normal or reversed ordering is used. Unless the comparator 870 definition specifies otherwise, multi-values and NIL values have an 871 undefined ordinal precedence. 873 The equality operation is used for the EQUAL search modifier, and 874 simply determines if the two values are considered equal under the 875 comparator function. When comparing a single value to a multi-value, 876 the two are considered equal if any one of the multiple values is 877 equal to the single value. 879 The prefix match operation is used for the PREFIX search modifier, 880 and simply determines if search value is a prefix of the item being 881 searched. In the case of prefix search on a multi-valued, the match 882 is successful if the value is a prefix of any one of the multiple 883 values. 885 The substring match operation is used for the SUBSTRING search 886 modifier, and simply determines if search value is a substring of the 887 item being searched. In the case of substring search on a multi- 888 value, the match is successful if the value is a substring of any one 889 of the multiple values. 891 Rules for naming and registering comparators will be defined in a 892 future specification. Servers MUST respond to unknown or improperly 893 used comparators with a BAD command completion result. 895 The following comparators are defined by this standard: 897 i;octet 898 Operations: Ordering, Equality, Prefix match, Substring match 900 For collation, the i;octet comparator interprets the value of 901 an attribute as a series of unsigned octets with ordinal 902 values from 0 to 255. When ordering two strings, each octet 903 pair is compared in sequence until the octets are unequal or 904 the end of the string is reached. When collating two strings 905 where the shorter is a prefix of the longer, the shorter 906 string is interpreted as having a smaller ordinal value. The 907 "i;octet" or "+i;octet" forms collate smaller ordinal values 908 earlier, and the "-i;octet" form collates larger ordinal 909 values earlier. 911 For the equality function, two strings are equal if they are 912 the same length and contain the same octets in the same 913 order. NIL is equal only to itself. 915 For non-binary, non-nil single values, i;octet ordering is 916 equivalent to the ANSI C [ISO-C] strcmp() function applied to 917 C string representations of the values. For non-binary, 918 non-nil single values, i;octet substring match is equivalent 919 to the ANSI C strstr() function applied to the C string 920 representations of the values. 922 en;nocase;octet 923 Operations: Ordering, Equality, Prefix match, Substring match 925 The en;nocase;octet comparator first applies a mapping to the 926 attribute values which translates all US-ASCII letters to 927 uppercase (octet values 0x61 to 0x7A are translated to octet 928 values 0x41 to 0x5A respectively), then applies the i;octet 929 comparator as described above. With this function the values 930 "hello" and "HELLO" have the same ordinal value and are 931 considered equal. 933 i;numeric 934 Operations: Ordering, Equality 936 The i;numeric comparator interprets strings as decimal 937 positive integers represented as US-ASCII digits. All values 938 which do not begin with a US-ASCII digit are considered equal 939 with an ordinal value higher than all non-NIL single-valued 940 attributes. Otherwise, all US-ASCII digits (octet values 941 0x30 to 0x39) are interpreted starting from the beginning of 942 the string to the first non-digit or the end of the string. 944 3.5. Access Control Lists (ACLs) 946 An access control list is a set of identifier, rights pairs used to 947 restrict access to a given dataset, attribute or attribute within an 948 entry. An ACL is represented by a multi-value with each value 949 containing an identifier followed by a tab character followed by the 950 rights. The syntax is defined by the "acl" rule in the formal syntax 951 in section 8. 953 Identifier is a UTF-8 string. The identifier "anyone" is reserved to 954 refer to the universal identity (all authentications, including 955 anonymous). All user name strings accepted by the AUTHENTICATE 956 command to authenticate to the ACAP server are reserved as 957 identifiers for the corresponding user. Identifiers starting with a 958 slash ("/") character are reserved for authorization groups which 959 will be defined in a future specification. Identifiers MAY be 960 prefixed with a dash ("-") to indicate a revocation of rights. All 961 other identifier strings have implementation-defined meanings. 963 Rights is a string listing a (possibly empty) set of alphanumeric 964 characters, each character listing a set of operations which is being 965 controlled. Letters are reserved for "standard" rights, listed 966 below. The set of standard rights may only be extended by a 967 standards-track or IESG approved experimental RFC. Digits are 968 reserved for implementation or site defined rights. The currently 969 defined standard rights are: 971 r - read 972 w - write 973 i - insert (perform store on a previously NIL value) 974 a - administer (perform store on ACL attribute/metadata) 976 An implementation may force rights to always or never be granted. In 977 particular, implementations are expected to grant implicit read and 978 administer rights to a user's personal dataset storage in order to 979 avoid denial of service problems. Rights are never tied, unlike the 980 IMAP ACL extension [IMAP-ACL]. 982 It is possible for multiple identifiers in an access control list to 983 apply to a given user (or other authentication identity). For 984 example, an ACL may include rights to be granted to the identifier 985 matching the user, one or more implementation-defined identifiers 986 matching groups which include the user, and/or the identifier 987 "anyone". These rights are combined by taking the union of all 988 positive rights which apply to a given user and subtracting the union 989 of all negative rights which apply to that user. A client MAY avoid 990 this calculation by using the MYRIGHTS command and metadata items. 992 Each attribute of each entry of a dataset may potentially have an 993 ACL. If an attribute in an entry does not have an ACL, then access 994 is controlled by a default ACL for that attribute in the dataset, if 995 it exists. If there is no default ACL for that attribute in the 996 dataset, access is controlled by a default ACL for that dataset. The 997 default ACL for a dataset must exist. 999 In order to perform any access or manipulation on an entry in a 1000 dataset, the client must have 'r' rights on the "entry" attribute of 1001 the entry. Implementations should take care not to reveal via error 1002 messages the existence of an entry for which the client does not have 1003 'r' rights. A client does not need access to the "subdataset" 1004 attribute of the parent dataset in order to access the contents of a 1005 dataset. 1007 Many of the ACL commands and responses include an "acl object" 1008 parameter, for specifying what the ACL applies to. This is a 1009 parenthesized list. The list contains just the dataset name when 1010 referring to the default ACL for a dataset. The list contains a 1011 dataset name and an attribute name when referring to the default ACL 1012 for an attribute in a dataset. The list contains a dataset name, an 1013 attribute name, and an entry name when referring to the ACL for an 1014 attribute of an entry of a dataset. 1016 3.6. Server Response Codes 1018 An OK, NO, BAD, ALERT or BYE response from the server MAY contain a 1019 response code to describe the event in a more detailed machine 1020 parsable fashion. A response code consists of data inside 1021 parentheses in the form of an atom, possibly followed by a space and 1022 arguments. Response codes are defined when there is a specific 1023 action that a client can take based upon the additional information. 1024 In order to support future extension, the response code is 1025 represented as a slash-separated hierarchy with each level of 1026 hierarchy representing increasing detail about the error. Clients 1027 MUST ignore additional hierarchical response code detail which they 1028 don't understand. 1030 The currently defined response codes are: 1032 AUTH-TOO-WEAK 1033 This response code is returned on a tagged NO result from an 1034 AUTHENTICATE command. It indicates that site security policy 1035 forbids the use of the requested mechanism for the specified 1036 authentication identity. 1038 ENCRYPT-NEEDED 1039 This response code is returned on a tagged NO result from an 1040 AUTHENTICATE command. It indicates that site security policy 1041 requires the use of a strong encryption mechanism for the 1042 specified authentication identity and mechanism. 1044 INVALID 1045 This response code indicates that a STORE command included 1046 data which the server implementation does not permit. It 1047 MUST NOT be used unless the dataset class specification for 1048 the attribute in question explicitly permits enforced server 1049 validation. The argument is the attribute which was invalid. 1051 MODIFIED 1052 This response code indicates that a conditional store failed 1053 because the modtime on the entry is later than the modtime 1054 specified with the STORE command UNCHANGEDSINCE modifier. 1055 The argument is the entry which had been modified. 1057 NOEXIST 1058 This response code indicates that a search or NOCREATE store 1059 failed because a specified dataset did not exist. The 1060 argument is the dataset which does not exist. 1062 PERMISSION 1063 A command failed due to insufficient permission based on the 1064 access control list or implicit rights. The argument is the 1065 acl-object which caused the permission failure. 1067 QUOTA 1068 A STORE or SETACL command which would have increased the size 1069 of the dataset failed due to insufficient quota. 1071 REFER 1072 This response code may be returned in a tagged NO response to 1073 any command that takes a dataset name as a parameter. It has 1074 one or more arguments with the syntax of relative URLs. It 1075 is a referral, indicating that the command should be retried 1076 using one of the relative URLs. 1078 TOOMANY 1079 This response code may be returned in a tagged OK response to 1080 a SEARCH command which includes the LIMIT modifier. The 1081 argument returns the total number of matching entries. 1083 TOOOLD 1084 The modtime specified in the DELETEDSINCE command is too old, 1085 so deletedsince information is no longer available. 1087 TRANSITION-NEEDED 1088 This response code occurs on a NO response to an AUTHENTICATE 1089 command with a mechanism other than PLAIN or ANONYMOUS. It 1090 indicates that the PLAIN SASL [SASL-PLAIN] mechanism is 1091 needed prior to using the stronger mechanism requested. 1093 TRYLATER 1094 A command failed due to a temporary server failure. The 1095 client MAY continue using local information and try the 1096 command later. 1098 TRYFREECONTEXT 1099 This response code may be returned in a tagged NO response to 1100 a SEARCH command which includes the MAKECONTEXT modifier. It 1101 indicates that a new context may not be created due to the 1102 server's limit on the number of existing contexts. 1104 WAYTOOMANY 1105 This response code may be returned in a tagged NO response to 1106 a SEARCH command which includes a HARDLIMIT search modifier. 1107 It indicates that the SEARCH would have returned more entries 1108 than the HARDLIMIT permitted. 1110 Additional response codes MUST be registered with IANA according 1111 to the proceedures in section 7.2. Client implementations MUST 1112 ignore response codes that they do not recognize. 1114 4. Namespace Conventions 1116 4.1. Dataset Namespace 1118 The dataset namespace is a slash-separated hierarchy. The first 1119 component of the dataset namespace is a dataset class. Dataset 1120 classes MUST have a vendor prefix (vendor.) or be 1121 specified in a standards track or IESG approved experimental RFC. 1122 See section 7.3 for the registration template. 1124 The second component of the dataset name is "site", "group", "host", 1125 or "user" referring to server-wide data, administrative group data, 1126 per-host data and per-user data respectively. 1128 For "group", "host", and "user" areas, the third component of the 1129 path is the group name, the fully qualified host domain name, or the 1130 user name. A path of the form "//~/" is a convenient 1131 abbreviation for "//user//". 1133 Dataset names which begin with "/byowner/" are reserved as an 1134 alternate view of the namespace. This provides a way to see all the 1135 dataset classes which a particular owner uses. For example, 1136 "/byowner/~//" is an alternate name for "//~/". Byowner provides a way to view a list of dataset classes 1138 owned by a given user; this is done using the dataset 1139 "/byowner/user//" with the NOINHERIT SEARCH modifier. 1141 The dataset "/" may be used to find all dataset classes visible to 1142 the current user. A dataset of the form "//user/" may 1143 be used to find all users which have made a dataset or entry of that 1144 class visible to the current user. 1146 The formal syntax for a dataset name is defined by the "dataset-name" 1147 terminal in section 4.3. 1149 4.2. Attribute Namespace 1151 Attribute names which do not contain a dot (".") are reserved for 1152 standardized attributes which have meaning in any dataset. In order 1153 to simplify client implementations, the attribute namespace is 1154 intended to be unique across all datasets. To achieve this, 1155 attribute names are prefixed with the dataset class name followed by 1156 a dot ("."). Attributes which effect management of the dataset are 1157 prefixed with "dataset.". In addition, a subtree of the "vendor." 1158 attribute namespace may be registered with IANA according to the 1159 rules in section 7.4. ACAP implementors are encouraged to help 1160 define interoperable dataset classes specifications rather than using 1161 the private attribute namespace. 1163 Finally, the "user.." and "site." subtrees of the 1164 attribute namespace are reserved for user-specific and site-specific 1165 attributes respectively. Such attributes are not interoperable so 1166 are discouraged in favor of defining standard attributes. A future 1167 extension is expected to permit discovery of syntax for user or 1168 site-specific attributes. Clients wishing to support display of user 1169 or site-specific attributes should display the value of any non-NIL 1170 single-valued "user.." or "site." attribute which has 1171 valid UTF-8 syntax. 1173 The formal syntax for an attribute name is defined by the 1174 "attribute-name" terminal in the next section. 1176 4.3. Formal Syntax for Dataset and Attribute Namespace 1178 The naming conventions for datasets and attributes are defined by the 1179 following ABNF. Note that this grammar is not part of the ACAP 1180 protocol syntax in section 8, as dataset names and attribute names 1181 are encoded as strings within the ACAP protocol. 1183 attribute-dacl = "dataset.acl" *("." name-component) 1185 attribute-dset = dataset-std 1*("." name-component) 1186 ;; MUST be defined in a dataset class specification 1188 attribute-name = attribute-std / attr-site / attr-user / vendor-name 1190 attribute-std = "entry" / "subdataset" / "modtime" / "dataset.inherit" 1191 / attribute-dacl / attribute-dset 1193 attr-site = "site" 1*("." name-component) 1195 attr-user = "user." name-component 1*("." name-component) 1197 byowner = "/byowner/" owner "/" [dataset-class "/" dataset-sub] 1199 dataset-class = dataset-std / vendor-name 1201 dataset-normal = "/" [dataset-class "/" (owner-prefix / dataset-tail)] 1203 dataset-name = byowner / dataset-normal 1205 dataset-std = name-component 1206 ;; MUST be registered with IANA and the spec MUST 1207 ;; be published as a standards track or 1208 ;; IESG-approved experimental RFC 1210 dataset-sub = *(dname-component "/") 1211 ;; The rules for this portion of the namespace may 1212 ;; be further restricted by the dataset class 1213 ;; specification. 1215 dataset-tail = owner "/" dataset-sub 1217 dname-component = 1*UTF8-CHAR 1218 ;; MUST NOT begin with "." or contain "/" 1220 name-component = 1*UTF8-CHAR 1221 ;; MUST NOT contain ".", "/", "%", or "*" 1223 owner = "site" / owner-host / owner-group / owner-user / "~" 1225 owner-group = "group/" dname-component 1227 owner-host = "host/" dname-component 1229 owner-prefix = "group/" / "host/" / "user/" 1231 owner-user = "user/" dname-component 1233 vendor-name = vendor-token *("." name-component) 1235 vendor-token = "vendor." name-component 1236 ;; MUST be registered with IANA 1238 5. Dataset Management 1240 The entry with an empty name ("") in the dataset is used to hold 1241 management information for the dataset as a whole. 1243 5.1. Dataset Inheritance 1245 It is possible for one dataset to inherit data from another. The 1246 dataset from which the data is inherited is called the base dataset. 1247 Data in the base dataset appears in the inheriting dataset, except 1248 when overridden by a STORE to the inheriting dataset. 1250 The base dataset is usually a system-wide or group-wide set of 1251 defaults. A system-wide dataset usually has one inheriting dataset 1252 per user, allowing each user to add to or modify the defaults as 1253 appropriate. 1255 An entry which exists in both the inheriting and base dataset 1256 inherits a modtime equal to the greater of the two modtimes. An 1257 attribute in such an entry is inherited from the base dataset if it 1258 was never modified by a STORE command in the inheriting dataset or if 1259 DEFAULT was stored to that attribute. This permits default entries 1260 to be amended rather than replaced in the inheriting dataset. 1262 The "subdataset" attribute is not directly inherited. If the base 1263 dataset includes a "subdataset" attribute and the inheriting dataset 1264 does not, then the "subdataset" attribute will inherit a virtual 1265 value of a list containing a ".". The subdataset at that node is 1266 said to be a "virtual" dataset as it is simply a virtual copy of the 1267 appropriate base dataset with all "subdataset" attributes changed to 1268 a list containing a ".". A virtual dataset is not visible if 1269 NOINHERIT is specified on the SEARCH command. 1271 Servers MUST support at least two levels of inheritance. This 1272 permits a user's dataset such as "/options/user/fred/common" to 1273 inherit from a group dataset such as "/options/group/dinosaur 1274 operators/common" which in turn inherits from a server-wide dataset 1275 such as "/options/site/common". 1277 5.2. Dataset Attributes 1279 The following attributes apply to management of the dataset when 1280 stored in the "" entry of a dataset. These attributes are not 1281 inherited. 1283 dataset.acl 1284 This holds the default access control list for the dataset. It 1285 can not be modified by the STORE command, only by the SETACL and 1286 DELETEACL commands. 1288 dataset.acl. 1289 This holds the default access control list for an attribute 1290 within the dataset. It can not be modified by the STORE command, 1291 only by the SETACL and DELETEACL commands. 1293 dataset.inherit 1294 This holds the name of a dataset from which to inherit according 1295 to the rules in the previous section. This attribute MAY refer 1296 to a non-existent dataset, in which case nothing is inherited. 1298 5.3. Dataset Creation 1300 When a dataset is first created (by storing a "." in the subdataset 1301 attribute or storing an entry in a previously non-existent dataset), 1302 the dataset attributes are initialized with the values from the 1303 parent dataset in the "/byowner/" hierarchy. In the case of the 1304 "dataset.inherit" attribute, the appropriate hierarchy component is 1305 added. For example, given the following entry: 1307 entry path "/byowner/user/joe/" 1308 dataset.acl ("joe" "rwia") 1309 dataset.inherit "/byowner/site" 1311 If a new dataset class "/byowner/~/new" is created, it will have the 1312 following dataset attributes: 1314 entry path "/byowner/user/joe/new/" 1315 dataset.acl ("joe" "rwia") 1316 dataset.inherit "/byowner/site/new" 1318 Note that the dataset "/byowner/user/joe/new/" is equivalent to 1319 "/new/user/joe/". 1321 5.4. Dataset Class Capabilities 1323 Certain dataset classes or dataset class features may only be useful 1324 if there is an active updating client or integrated server support 1325 for the feature. The dataset class "capability" is reserved to allow 1326 clients or servers to advertise such features. The "entry" attribute 1327 within this dataset class is the name of the dataset class whose 1328 features are being described. The attributes are prefixed with 1329 "capability.." and are defined by the appropriate 1330 dataset class specification. 1332 Since it is possible for an unprivileged user to run an active client 1333 for himself, a per-user capability dataset is useful. The dataset 1334 "/capability/~/" holds information about all features available to 1335 the user (via inheritance), and the dataset "/capability/site/" holds 1336 information about all features supported by the site. 1338 5.5. Dataset Quotas 1340 Management and scope of quotas is implementation dependent. Clients 1341 can check the applicable quota limit and usage (in bytes) with the 1342 GETQUOTA command. Servers can notify the client of a low quota 1343 situation with the QUOTA untagged response. 1345 6. Command and Response Specifications 1347 ACAP commands and responses are described in this section. Commands 1348 are organized first by the state in which the command is permitted, 1349 then by a general category of command type. 1351 Command arguments, identified by "Arguments:" in the command 1352 descriptions below, are described by function, not by syntax. The 1353 precise syntax of command arguments is described in the Formal Syntax 1354 section. 1356 Some commands cause specific server data to be returned; these are 1357 identified by "Data:" in the command descriptions below. See the 1358 response descriptions in the Responses section for information on 1359 these responses, and the Formal Syntax section for the precise syntax 1360 of these responses. It is possible for server data to be transmitted 1361 as a result of any command; thus, commands that do not specifically 1362 require server data specify "no specific data for this command" 1363 instead of "none". 1365 The "Result:" in the command description refers to the possible 1366 tagged status responses to a command, and any special interpretation 1367 of these status responses. 1369 6.1. Initial Connection 1371 Upon session startup, the server sends one of two untagged responses: 1372 ACAP or BYE. The untagged BYE response is described in section 1373 6.2.8. 1375 6.1.1. ACAP Untagged Response 1377 Data: capability list 1379 The untagged ACAP response indicates the session is ready to 1380 accept commands and contains a space-separated listing of 1381 capabilities that the server supports. Each capability is 1382 represented by a list containing the capability name optionally 1383 followed by capability specific string arguments. 1385 ACAP capability names MUST be defined in a standards track or IESG 1386 approved experimental RFC and registered with IANA according to 1387 the rules in section 7.1. 1389 Client implementations SHOULD NOT require any capability name, and 1390 MUST ignore any unknown capability names. 1392 The following initial capabilities are defined: 1394 CONTEXTLIMIT 1395 The CONTEXTLIMIT capability has one argument which is a 1396 number describing the maximum number of contexts the server 1397 supports per connection. The number 0 indicates the server 1398 has no limit, otherwise this number MUST be greater than 1399 100. 1401 IMPLEMENTATION 1402 The IMPLEMENTATION capability has one argument which is a 1403 string describing the server implementation. ACAP clients 1404 MUST NOT alter their behavior based on this value. It is 1405 intended primarily for debugging purposes. 1407 SASL The SASL capability includes a list of the authentication 1408 mechanisms supported by the server. See section 6.3.1. 1410 Example: S: * ACAP (IMPLEMENTATION "ACME v3.5") 1411 (SASL "CRAM-MD5" "PLAIN") (CONTEXTLIMIT "200") 1413 6.2. Any State 1415 The following commands and responses are valid in any state. 1417 6.2.1. NOOP Command 1419 Arguments: none 1421 Data: no specific data for this command (but see below) 1423 Result: OK - noop completed 1424 BAD - command unknown or arguments invalid 1426 The NOOP command always succeeds. It does nothing. It can be 1427 used to reset any inactivity auto-logout timer on the server. 1429 Example: C: a002 NOOP 1430 S: a002 OK "NOOP completed" 1432 6.2.2. LANG Command 1434 Arguments: list of language preferences 1436 Data: intermediate response: LANG 1438 Result: OK - lang completed 1439 NO - no matching language available 1440 BAD - command unknown or arguments invalid 1442 One or more arguments are supplied to indicate the client's 1443 preferred languages for error messages. The server will match 1444 each client preference in order against its internal table of 1445 available error strings languages. For a client preference to 1446 match a server language table, the client's language tag MUST be a 1447 prefix of the server's tag and match up to a "-" or the end of 1448 string. If a match is found, the server returns an intermediate 1449 LANG response and an OK response. The LANG response indicates the 1450 actual language selected and appropriate comparators for use with 1451 that language. 1453 If no LANG command is issued, all error text strings MUST be in 1454 technical English intended for an international audience. This 1455 rule is necessary because the default error text has to be in a 1456 language which is most likely to be useful to any pair of client 1457 and server vendors (since both have to diagnose problems). In 1458 addition, the default language for errors has to use the US-ASCII 1459 subset of UTF-8, since it can be displayed on the largest number 1460 of computers. Explicitly negotiating "en" or a dialect such as 1461 "en-us" indicates a preference for messages intended for the end 1462 user and MAY be different from the default language. 1464 Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" 1465 C: A003 LANG "fr-ca" "i;octet" "i;numeric" 1466 "fr;nocase;octet" 1467 S: A003 OK "Bonjour" 1469 6.2.3. LANG Intermediate Response 1471 Data: language for error responses 1472 list of appropriate comparators 1474 The LANG response indicates the language which will be used for 1475 error responses and a list of comparators which are appropriate 1476 for that language. The list of comparators should be in 1477 approximate order from most efficient (usually "i;octet") to most 1478 appropriate for human text. 1480 6.2.4. LOGOUT Command 1482 Arguments: none 1484 Data: mandatory untagged response: BYE 1486 Result: OK - logout completed 1487 BAD - command unknown or arguments invalid 1489 The LOGOUT command informs the server that the client is done with 1490 the session. The server must send a BYE untagged response before 1491 the (tagged) OK response, and then close the network connection. 1493 Example: C: A023 LOGOUT 1494 S: * BYE "ACAP Server logging out" 1495 S: A023 OK "LOGOUT completed" 1496 (Server and client then close the connection) 1498 6.2.5. OK Response 1500 Data: optional response code 1501 human-readable text 1503 The OK response indicates an information message from the server. 1504 When tagged, it indicates successful completion of the associated 1505 command. The human-readable text may be presented to the user as 1506 an information message. The untagged form indicates an 1507 information-only message; the nature of the information MAY be 1508 indicated by a response code. 1510 Example: S: * OK "Master ACAP server is back up" 1512 6.2.6. NO Response 1514 Data: optional response code 1515 human-readable text 1517 The NO response indicates an operational error message from the 1518 server. When tagged, it indicates unsuccessful completion of the 1519 associated command. The untagged form indicates a warning; the 1520 command may still complete successfully. The human-readable text 1521 describes the condition. 1523 Example: C: A010 SEARCH "/addressbook/" DEPTH 3 RETURN ("*") 1524 EQUAL "entry" "+i;octet" "bozo" 1525 S: * NO "Master ACAP server is down, your data may 1526 be out of date." 1527 S: A010 OK "search done" 1528 ... 1529 C: A222 STORE ("/folder/site/comp.mail.misc" 1530 "folder.creation-time" "19951206103412") 1531 S: A222 NO (PERMISSION ("/folder/site/")) "Permission 1532 denied" 1534 6.2.7. BAD Response 1536 Data: optional response code 1537 human-readable text 1539 The BAD response indicates an error message from the server. When 1540 tagged, it reports a protocol-level error in the client's command; 1541 the tag indicates the command that caused the error. The untagged 1542 form indicates a protocol-level error for which the associated 1543 command can not be determined; it may also indicate an internal 1544 server failure. The human-readable text describes the condition. 1546 Example: C: ...empty line... 1547 S: * BAD "Empty command line" 1548 C: A443 BLURDYBLOOP 1549 S: A443 BAD "Unknown command" 1550 C: A444 NOOP Hello 1551 S: A444 BAD "invalid arguments" 1553 6.2.8. BYE Untagged Response 1555 Data: optional response code 1556 human-readable text 1558 The untagged BYE response indicates that the server is about to 1559 close the connection. The human-readable text may be displayed to 1560 the user in a status report by the client. The BYE response may 1561 be sent as part of a normal logout sequence, or as a panic 1562 shutdown announcement by the server. It is also used by some 1563 server implementations as an announcement of an inactivity auto- 1564 logout. 1566 This response is also used as one of two possible greetings at 1567 session startup. It indicates that the server is not willing to 1568 accept a session from this client. 1570 Example: S: * BYE "Auto-logout; idle for too long" 1572 6.2.9. ALERT Untagged Response 1574 Data: optional response code 1575 human-readable text 1577 The human-readable text contains a special human generated alert 1578 message that MUST be presented to the user in a fashion that calls 1579 the user's attention to the message. This is intended to be used 1580 for vital messages from the server administrator to the user, such 1581 as a warning that the server will soon be shut down for 1582 maintenance. 1584 Example: S: * ALERT "This ACAP server will be shut down in 1585 10 minutes for system maintenance." 1587 6.3. Non-Authenticated State 1589 In non-authenticated state, the AUTHENTICATE command establishes 1590 authentication and enters authenticated state. The AUTHENTICATE 1591 command provides a general mechanism for a variety of authentication 1592 techniques. 1594 Server implementations may allow non-authenticated access to certain 1595 information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism. 1597 Once authenticated (including as anonymous), it is not possible to 1598 re-enter non-authenticated state. 1600 Only the any-state commands (NOOP, LANG and LOGOUT) and the 1601 AUTHENTICATE command are valid in non-authenticated state. 1603 6.3.1. AUTHENTICATE Command 1605 Arguments: SASL mechanism name 1606 optional initial response 1608 Data: continuation data may be requested 1610 Result: OK - authenticate completed, now in authenticated state 1611 NO - authenticate failure: unsupported authentication 1612 mechanism, credentials rejected 1613 BAD - command unknown or arguments invalid, 1614 authentication exchange cancelled 1616 The AUTHENTICATE command indicates a SASL [SASL] authentication 1617 mechanism to the server. If the server supports the requested 1618 authentication mechanism, it performs an authentication protocol 1619 exchange to authenticate and identify the user. Optionally, it 1620 also negotiates a security layer for subsequent protocol 1621 interactions. If the requested authentication mechanism is not 1622 supported, the server rejects the AUTHENTICATE command by sending 1623 a tagged NO response. 1625 The authentication protocol exchange consists of a series of 1626 server challenges and client answers that are specific to the 1627 authentication mechanism. A server challenge consists of a 1628 command continuation request with the "+" token followed by a 1629 BASE64 encoded string. The client answer consists of a line 1630 consisting of a BASE64 encoded string. If the client wishes to 1631 cancel an authentication exchange, it should issue a line with a 1632 single "*". If the server receives such an answer, it must reject 1633 the AUTHENTICATE command by sending a tagged BAD response. 1635 The optional initial-response argument to the AUTHENTICATE command 1636 is used to save a round trip when using authentication mechanisms 1637 that are defined to send no data in the initial challenge. When 1638 the initial-response argument is used with such a mechanism, the 1639 initial empty challenge is not sent to the client and the server 1640 uses the data in the initial-response argument as if it were sent 1641 in response to the empty challenge. If the initial-response 1642 argument to the AUTHENTICATE command is used with a mechanism 1643 that sends data in the initial challenge, the server rejects the 1644 AUTHENTICATE command by sending a tagged NO response. 1646 The service name specified by this protocol's profile of SASL is 1647 "acap". 1649 If a security layer is negotiated through the SASL authentication 1650 exchange, it takes effect immediately following the CRLF that 1651 concludes the authentication exchange for the client, and the CRLF 1652 of the tagged OK response for the server. 1654 All ACAP implementations MUST support the PLAIN SASL mechanism 1655 [SASL-PLAIN], although they MAY offer a configuration option to 1656 disable plaintext passwords if site security policy dictates. 1657 ACAP implementations SHOULD support an external encryption service 1658 or a stronger standards track SASL mechanism. 1660 If an AUTHENTICATE command fails with a NO response, the client 1661 may try another authentication mechanism by issuing another 1662 AUTHENTICATE command. In other words, the client may request 1663 authentication types in decreasing order of preference. 1665 Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5") 1666 (SASL "PLAIN" "KERBEROS_V4") 1667 C: A001 AUTHENTICATE KERBEROS_V4 1668 S: + AmFYig== 1669 C: BAcAQU5EUkVXLkNNVS5FRFUAOCAsho84kLN3/IJmrMG+25a4DT 1670 +nZImJjnTNHJUtxAA+o0KPKfHEcAFs9a3CL5Oebe/ydHJUwYFd 1671 WwuQ1MWiy6IesKvjL5rL9WjXUb9MwT9bpObYLGOKi1Qh 1672 S: + or//EoAADZI= 1673 C: DiAF5A4gA+oOIALuBkAAmw== 1674 S: A001 OK "Kerberos V4 authentication successful" 1676 6.4. Searching 1678 This section describes the SEARCH command, for retrieving data from 1679 datasets. 1681 6.4.1. SEARCH Command 1683 Arguments: dataset or context name 1684 optional list of modifiers 1685 search criteria 1687 Data: intermediate responses: ENTRY, MODTIME, REFER 1688 untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME 1690 Result: OK - search completed 1691 NO - search failure: can't perform search 1692 BAD - command unknown or arguments invalid 1694 The SEARCH command identifies a subset of entries in a dataset and 1695 returns information on that subset to the client. Inherited 1696 entries and attributes are included in the search unless the 1697 NOINHERIT search modifier is included or the user does not have 1698 permission to read the attributes in the base dataset. 1700 The first argument to SEARCH identifies what is to be searched. 1701 If the string begins with a slash ("/"), it is the name of a 1702 dataset to be searched, otherwise it is a name of a context that 1703 was created by a SEARCH command given previously in the session. 1705 A successful SEARCH command MAY result in intermediate ENTRY 1706 responses and MUST result in a MODTIME intermediate response. 1708 Following that are zero or more modifiers to the search. Each 1709 modifier may be specified at most once. The defined modifiers 1710 are: 1712 DEPTH number 1713 The SEARCH command will traverse the dataset tree up to the 1714 specified depth. ENTRY responses will include the full path 1715 to the entry. A value of "0" indicates that the search 1716 should traverse the entire tree. A value of "1" is the 1717 default and indicates only the specified dataset should be 1718 searched. If a dataset is traversed which is not located on 1719 the current server, then a REFER intermediate response is 1720 returned for that subtree and the search continues. 1722 HARDLIMIT number 1723 If the SEARCH command would result in more than number 1724 entries, the SEARCH fails with a NO completion result with a 1725 WAYTOOMANY response code. 1727 LIMIT number number 1728 Limits the number of intermediate ENTRY responses that the 1729 search may generate. The first numeric argument specifies 1730 the limit, the second number specifies the number of entries 1731 to return if the number of matches exceeds the limit. If the 1732 limit is exceeded, the SEARCH command still succeeds, 1733 returning the total number of matches in a TOOMANY response 1734 code in the tagged OK response. 1736 MAKECONTEXT [ENUMERATE] [NOTIFY] context 1737 The SEARCH command creates a context with the name given in 1738 the argument to refer to the matching entries. If the SEARCH 1739 is successful, the context name may then be given as an 1740 argument to subsequent SEARCH commands to search the set of 1741 matching entries. If a context with the specified name 1742 already exists, it is first freed. If a new context may not 1743 be created due to the server's limit on the number of 1744 existing contexts, the command fails, returning a 1745 TRYFREECONTEXT response code in the NO completion response. 1747 The optional "ENUMERATE" and "NOTIFY" arguments may be 1748 included to request enumeration of the context (for virtual 1749 scroll bars) or change notifications for the context. If 1750 "NOTIFY" is not requested, the context represents a snapshot 1751 of the entries at the time the SEARCH was issued. 1753 ENUMERATE requests that the contents of the context be 1754 ordered according to the SORT modifier and that sequential 1755 numbers, starting with one, be assigned to the entries in the 1756 context. This permits the RANGE modifier to be used to fetch 1757 portions of the ordered context. 1759 NOTIFY requests that the server send untagged ADDTO, 1760 REMOVEFROM, CHANGE, and MODTIME responses while the context 1761 created by this SEARCH command exists. The server MAY issue 1762 untagged ADDTO, REMOVEFROM, CHANGE and MODTIME notifications 1763 for a context at any time between the issuing of the SEARCH 1764 command with MAKECONTEXT NOTIFY and the completion of a 1765 FREECONTEXT command for the context. Notifications are only 1766 issued for changes which occur after the server receives the 1767 SEARCH command which created the context. After issuing a 1768 sequence of ADDTO, REMOVEFROM or CHANGE notifications, the 1769 server MUST issue an untagged MODTIME notification indicating 1770 that the client has all updates to the entries in the context 1771 up to and including the given modtime value. Servers are 1772 permitted a reasonable delay to batch change notifications 1773 before sending them to the client. 1775 The position arguments of the ADDTO, REMOVEFROM and CHANGE 1776 notifications are 0 if ENUMERATE is not requested. 1778 NOINHERIT 1779 This causes the SEARCH command to operate without 1780 inheritance. It can be used to tell which values are 1781 explicit overrides. If MAKECONTEXT is also specified, the 1782 created context is also not effected by inheritance. 1784 RETURN (metadata...) 1785 Specifies what is to be returned in intermediate ENTRY 1786 responses. If this modifier is not specified, no 1787 intermediate ENTRY responses are returned. 1789 Inside the parentheses is an optional list of attributes, 1790 each optionally followed by a parenthesized list of metadata. 1791 If the parenthesized list of metadata is not specified, it 1792 defaults to "(value)". 1794 An attribute name with a trailing "*" requests all attributes 1795 with that prefix. A "*" by itself requests all attributes. 1796 If the parenthesized list of metadata is not specified for an 1797 attribute with a trailing "*", it defaults to "(attribute 1798 value)". Results matching such an attribute pattern are 1799 grouped in parentheses. 1801 Following the last intermediate ENTRY response, the server 1802 returns a single intermediate MODTIME response. 1804 SORT (attribute comparator ...) 1805 Specifies the order in which any resulting ENTRY replies are 1806 to be returned to the client. The SORT modifier takes as an 1807 argument a parenthesized list of one or more 1808 attribute/comparator pairs. Attribute lists the attribute to 1809 sort on, comparator specifies the name of the collation rule 1810 to apply to the values of the attribute. Successive 1811 attribute/comparator pairs are used to order two entries only 1812 when all preceding pairs indicate the two entries collate the 1813 same. 1815 If the SORT modifier is used in conjunction with the 1816 MAKECONTEXT modifier, the SORT modifier specifies the 1817 ordering of entries in the created context. 1819 If no SORT modifier is specified, or none of the 1820 attribute/comparator pairs indicates an order for the two 1821 entries, the server uses the order of the entries that exists 1822 in the context or dataset being searched. 1824 Following the modifiers is the search criteria. Searching 1825 criteria consist of one or more search keys. Search keys may be 1826 combined using the AND, and OR search keys. For example, the 1827 criteria (the newline is for readability and not part of the 1828 criteria): 1829 AND COMPARE "modtime" "+i;octet" "19951206103400" 1830 COMPARE "modtime" "-i;octet" "19960112000000" 1831 refers to all entries modified between 10:34 December 6 1995 and 1832 midnight January 12, 1996 UTC. 1834 The currently defined search keys are as follows. 1836 ALL This matches all entries. 1838 AND search-key1 search-key2 1839 Entries that match both search keys. 1841 COMPARE attribute comparator value 1842 Entries for which the value of the specified attribute 1843 collates using the specified comparator the same or later 1844 than the specified value. 1846 COMPARESTRICT attribute comparator value 1847 Entries for which the specified attribute collates using the 1848 specified comparator later than the specified value. 1850 EQUAL attribute comparator value 1851 Entries for which the value of the attribute is equal to the 1852 specified value using the specified comparator. 1854 NOT search-key 1855 Entries that do not match the specified search key. 1857 OR search-key1 search-key2 1858 Entries that match either search key. 1860 PREFIX attribute comparator value 1861 Entries which begin with the specified value using the 1862 specified comparator. If the specified comparator doesn't 1863 support substring matching, a BAD response is returned. 1865 RANGE start end time 1866 Entries which are within the specified range of the 1867 enumerated context's ordering. The lowest-ordered entry in 1868 the context is assigned number one, the next lowest entry is 1869 assigned number two, and so on. The numeric arguments 1870 specify the lowest and highest numbers to match. The time 1871 specifies that the client has processed notifications for the 1872 context up to the specified time. If the context has been 1873 modified since then, the server MUST either return a NO with 1874 a MODIFIED response code, or return the results that the 1875 SEARCH would have returned if none of the changes since that 1876 time had been made. 1878 RANGE is only permitted on contexts. If RANGE is used with a 1879 dataset, the server MUST return a BAD response. 1881 SUBSTRING attribute comparator value 1882 Entries which contain the specified value, using the 1883 specified comparator. If the specified comparator doesn't 1884 support substring matching, a BAD response is returned. 1886 6.4.2. ENTRY Intermediate Response 1888 Data: entry name 1889 entry data 1891 The ENTRY intermediate response occurs as a result of a SEARCH or 1892 STORE command. This is the means by which dataset entries are 1893 returned to the client. 1895 The ENTRY response beings with the entry name, if a SEARCH command 1896 without the DEPTH modifier was issued, or the entry path in other 1897 cases. This is followed by a set of zero or more items, one for 1898 each metadata item in the RETURN search modifier. Results 1899 matching an attribute pattern are grouped in parentheses. 1901 6.4.3. MODTIME Intermediate Response 1903 Data: modtime value 1905 The MODTIME intermediate response occurs as a result of a SEARCH 1906 command. It indicates that the just created context or the 1907 previously returned ENTRY responses include all updates to the 1908 returned entries up to and including the modtime value in the 1909 argument. 1911 6.4.4. REFER Intermediate Response 1913 Data: dataset path 1914 ACAP URL 1916 The REFER intermediate response occurs as a result of a 1917 multi-level SEARCH where one of the levels is located on a 1918 different server. The response indicates the dataset which is not 1919 located on the current server and an ACAP URL for where that 1920 dataset may be found. 1922 6.4.5. Search Examples 1924 Here are some SEARCH command exchanges between the client and server: 1926 C: A046 SEARCH "/addressbook/" DEPTH 3 RETURN ("addressbook.Alias" 1927 "addressbook.Email" "addressbook.List") OR NOT EQUAL 1928 "addressbook.Email" "i;octet" NIL NOT EQUAL "addressbook.List" 1929 "i;octet" NIL 1930 S: A046 ENTRY "/addressbook/user/joe/A0345" "fred" 1931 "fred@stone.org" NIL 1932 S: A046 ENTRY "/addressbook/user/fred/A0537" "joe" "joe@stone.org" 1933 NIL 1934 S: A046 ENTRY "/addressbook/group/Dinosaur Operators/A423" 1935 "saurians" NIL "1" 1936 S: A046 MODTIME "19970728105252" 1937 S: A046 OK "SEARCH completed" 1939 C: A047 SEARCH "/addressbook/user/fred/" RETURN ("*") EQUAL "entry" 1940 "i;octet" "A0345" 1941 S: A047 ENTRY "A0345" ("modtime" "19970728102226" "addressbook.Alias" 1942 "fred" "addressbook.Email" "fred@stone.org" 1943 "addressbook.CommonName" "Fred Flintstone" 1944 "addressbook.Surname" "Flintstone" "addressbook.GivenName" 1945 "Fred") 1946 S: A046 MODTIME "19970728105258" 1947 S: A047 OK "SEARCH completed" 1949 C: A048 SEARCH "/options/~/vendor.example/" RETURN 1950 ("option.value"("size" "value" "myrights")) 1951 SORT ("entry" "i;octet") COMPARE "modtime" "i;octet" 1952 "19970727123225" 1953 S: A048 ENTRY "blurdybloop" 5 "ghoti" "rwia" 1954 S: A048 ENTRY "buckybits" 2 "10" "rwia" 1955 S: A048 ENTRY "windowSize" 7 "100x100" "rwia" 1956 S: A046 MODTIME "19970728105304" 1957 S: A048 OK "SEARCH completed" 1959 C: A049 SEARCH "/addressbook/~/public" RETURN ("addressbook.Alias" 1960 "addressbook.Email") MAKECONTEXT ENUMERATE "blob" LIMIT 100 1 1961 SORT ("addressbook.Alias" "i;octet") NOT EQUAL 1962 "addressbook.Email" NIL 1963 S: A049 ENTRY "A437" "aaguy" "aaguy@stone.org" 1964 S: A046 MODTIME "19970728105308" 1965 S: A049 OK (TOOMANY 347) "Context 'blob' created" 1966 C: A050 SEARCH "blob" RANGE 2 2 "19970728105308" ALL 1967 S: A050 ENTRY "A238" "abguy" "abguy@stone.org" 1968 S: A050 OK "SEARCH Completed" 1970 6.5. Contexts 1972 The following commands use contexts created by a SEARCH command with 1973 a MAKECONTEXT modifier. 1975 6.5.1. FREECONTEXT Command 1977 Arguments: context name 1979 Data: no specific data for this command 1981 Result: OK - freecontext completed 1982 NO - freecontext failure: no such context 1983 BAD - command unknown or arguments invalid 1985 The FREECONTEXT command causes the server to free all state 1986 associated with the named context. The context may no longer be 1987 searched and the server will no longer issue any untagged 1988 responses for the context. The context is no longer counted 1989 against the server's limit on the number of contexts. 1991 Example: C: A683 FREECONTEXT "blurdybloop" 1992 S: A683 OK "Freecontext completed" 1994 6.5.2. UPDATECONTEXT Command 1996 Arguments: list of context names 1998 Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME 2000 Result: OK - Updatecontext completed: all updates completed 2001 NO - Updatecontext failed: no such context 2002 not a notify context 2003 BAD - command unknown or arguments invalid 2005 The UPDATECONTEXT command causes the server to ensure that the 2006 client is notified of all changes to the contexts listed as 2007 arguments up to the current time. The contexts listed in the 2008 arguments must have been previously given to a successful SEARCH 2009 command with a MAKECONTEXT NOTIFY modifier. A MODTIME untagged 2010 response MUST be returned if any read-write metadata in the 2011 context changed since the last MODTIME for that context. This 2012 includes metadata which is not listed in the RETURN modifier for 2013 the context. 2015 While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and 2016 MODTIME at any time, the UPDATECONTEXT command is used to "prod" 2017 the server to send any notifications it has not sent yet. 2019 The UPDATECONTEXT command SHOULD NOT be used to poll for updates. 2020 If two or more UPDATECONTEXT commands occur between the delay 2021 period the server uses to generate unsolicited change 2022 notifications, then the server MAY treat all UPDATECONTEXT 2023 commands after the first as NOOP commands to discourage client 2024 polling. 2026 Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl" 2027 S: Z4S9 OK "client has been notified of all changes" 2029 6.5.3. ADDTO Untagged Response 2031 Data: context name 2032 entry name 2033 position 2034 metadata list 2036 The untagged ADDTO response informs the client that an entry has 2037 been added to a context. The response includes the position 2038 number of the added entry (the first entry in the context is 2039 numbered 1) and those metadata contained in the entry which match 2040 the RETURN statement when the context was created. 2042 For enumerated contexts, the ADDTO response implicitly adds one to 2043 the position of all members of the context which had position 2044 numbers that were greater than or equal to the ADDTO position 2045 number. 2047 Example: S: * ADDTO "blurdybloop" "fred" 15 2048 ("addressbook.Email" "fred@rock.org") 2050 6.5.4. REMOVEFROM Untagged Response 2052 Data: context name 2053 entry name 2054 old position 2056 The untagged REMOVEFROM response informs the client that an entry 2057 has been removed from a context. The response includes the 2058 position number that the removed entry used to have (the first 2059 entry in the context is numbered 1). 2061 For enumerated contexts, the REMOVEFROM response implicitly 2062 subtracts one from the position numbers of all members of the 2063 context which had position numbers greater than the REMOVEFROM 2064 position number. 2066 Example: S: * REMOVEFROM "blurdybloop" "fred" 15 2068 6.5.5. CHANGE Untagged Response 2070 Data: context name 2071 entry name 2072 old position 2073 new position 2074 metadata list 2076 The untagged CHANGE response informs the client that an entry in a 2077 context has either changed position in the context or has changed 2078 the values of one or more of the attributes specified in the 2079 RETURN modifier when the context was created. 2081 The response includes the previous and current position numbers of 2082 the entry (which are 0 if ENUMERATE was not specified on the 2083 context) and the attribute metadata requested in the RETURN 2084 modifier when the context was created. 2086 For enumerated contexts, the CHANGE response implicitly changes 2087 the position numbers of all entries which had position numbers 2088 between the old and new position. If old position is less than 2089 new position, than one is subtracted from all entries which had 2090 position numbers in that range. Otherwise one is added to all 2091 entries which had position numbers in that range. If the old 2092 position and new position are the same, then no implicit position 2093 renumbering occurs. 2095 CHANGE responses are not issued for entries which have changed 2096 position implicitly due to another ADDTO, REMOVEFROM or CHANGE 2097 response. 2099 Example: S: * CHANGE "blurdybloop" "fred" 15 10 2100 ("addressbook.Email" "fred@stone.org") 2102 6.5.6. MODTIME Untagged Response 2104 Data: context name 2105 modtime value 2107 The untagged MODTIME response informs the client that it has 2108 received all updates to entries in the context which have modtime 2109 values less than or equal to the modtime value in the argument. 2111 Example: S: * MODTIME mycontext "19970320162338" 2113 6.6. Dataset modification 2115 The following commands and responses handle modification of datasets. 2117 6.6.1. STORE Command 2119 Arguments: entry store list 2121 Data: intermediate responses: ENTRY 2123 Result: OK - store completed 2124 NO - store failure: can't store that name 2125 UNCHANGEDSINCE specified and entry changed 2126 BAD - command unknown or arguments invalid 2127 invalid UTF-8 syntax in attribute name 2129 Creates, modifies, or deletes the named entries in the named 2130 datasets. The values of metadata not specified in the command are 2131 not changed. Setting the "value" metadata of an attribute to NIL 2132 removes that attribute from the entry. Setting the "value" of the 2133 "entry" attribute to NIL removes that entry from the dataset and 2134 cancels inheritance for the entire entry. Setting the "value" of 2135 the "entry" attribute to DEFAULT removes that entry from the 2136 inheriting dataset and reverts the entry and its attributes to 2137 inherited values, if any. Changing the value of the "entry" 2138 attribute renames the entry. 2140 Storing DEFAULT to the "value" metadata of an attribute is 2141 equivalent to storing NIL, except that inheritance is enabled for 2142 that attribute. If a non-NIL value is inherited then an ENTRY 2143 intermediate response is generated to notify the client of the 2144 this change. The ENTRY response includes the entry-path and the 2145 attribute name and value metadata for each attribute which 2146 reverted to a non-NIL inherited setting. 2148 Storing NIL to the "value" metadata of an attribute MAY be treated 2149 equivalent to storing DEFAULT to that "value" if there is not a 2150 non-NIL value in the base dataset. 2152 The STORE command is followed by one or more entry store lists. 2153 Each entry store list begins with an entry path followed by STORE 2154 modifiers, followed by zero or more attribute store items. Each 2155 attribute store item is made up of the attribute name followed by 2156 NIL (to remove the attribute's value), DEFAULT (to revert the item 2157 to any inherited value), a single value (to set the attribute's 2158 single value), or a list of metadata items to modify. The 2159 following STORE modifiers may be specified: 2161 NOCREATE 2162 By default, the server MUST create any datasets necessary to 2163 store the entry. If NOCREATE is specified, the STORE command 2164 will fail with a NOEXIST error unless the containing dataset 2165 already exists. 2167 UNCHANGEDSINCE 2168 If the "modtime" of the entry is later than the 2169 unchangedsince time, then the store fails with a MODIFIED 2170 response code. Use of UNCHANGEDSINCE with a time of 2171 "00000101000000" will always fail if the entry exists. 2172 Clients writing to a shared dataset are encouraged to use 2173 UNCHANGEDSINCE when modifying an existing entry. 2175 The server MUST either make all the changes specified or make none 2176 of them. If successful, the server MUST update the "modtime" 2177 attribute for every entry which was changed. 2179 It is illegal to list any metadata item within an attribute twice, 2180 any attribute within an entry twice or any entry path twice. The 2181 server MUST return a BAD response if this happens. If the 2182 "modtime" attribute is included in the STORE command, then the 2183 server MUST return a NO response with an ILLEGAL response code. 2185 A STORE of a multi-value MAY re-order the strings in the multi- 2186 value and MAY remove duplicate strings. However, SEARCH MUST 2187 return multi-values and the associated size list metadata in a 2188 consistant order. 2190 Example: C: A342 STORE ("/addressbook/user/fred/ABC547" 2191 "addressbook.TelephoneNumber" "555-1234" 2192 "addressbook.CommonName" "Barney Rubble" 2193 "addressbook.AlternateNames" ("value" 2194 ("Barnacus Rubble" "Coco Puffs Thief")) 2195 "addressbook.Email" NIL) 2196 S: A342 OK "Store completed" 2197 C: A343 STORE ("/addressbook/user/joe/ABD42" 2198 UNCHANGEDSINCE "19970320162338" 2199 "user.joe.hair-length" "10 inches") 2200 S: A343 NO (MODIFIED) "'ABD42' has been changed 2201 by somebody else." 2202 C: A344 STORE ("/addressbook/group/Developers/ACD54" 2203 "entry" NIL) 2204 S: A344 OK "Store completed" 2205 C: A345 STORE ("/option/~/common/SMTPserver" 2206 "option.value" DEFAULT) 2207 S: A345 ENTRY "/option/~/common/SMTPserver" 2208 "option.value" "smtp.server.do.main" 2209 S: A345 OK "Store completed" 2210 C: A347 STORE ("/addressbook/~/" "dataset.inherit" 2211 "/addressbook/group/Developers") 2212 S: A347 OK "Store completed" 2214 6.6.2. DELETEDSINCE Command 2216 Arguments: dataset name 2217 time 2219 Data: intermediate response: DELETED 2221 Result: OK - DELETED completed 2222 NO - DELETED failure: can't read dataset 2223 date too far in the past 2224 BAD - command unknown or arguments invalid 2226 The DELETEDSINCE command returns in intermediate DELETED replies 2227 the names of entries that have been deleted from the named dataset 2228 since the given time. 2230 Servers may impose a limit on the number or age of deleted entry 2231 names they keep track of. If the server does not have information 2232 going back to the specified time, the command fails, returning a 2233 TOOOLD response code in the tagged NO response. 2235 Example: C: Z4S9 DELETEDSINCE "/folder/site/" 19951205103412 2236 S: Z4S9 DELETED "blurdybloop" 2237 S: Z4S9 DELETED "anteaters" 2238 S: Z4S9 OK "DELETEDSINCE completed" 2239 C: Z4U3 DELETEDSINCE "/folder/site/" 19951009040854 2240 S: Z4U3 NO (TOOOLD) "Don't have that information" 2242 6.6.3. DELETED Intermediate Response 2244 Data: entry name 2246 The intermediate DELETED response occurs as a result of a 2247 DELETEDSINCE command. It returns an entry that has been deleted 2248 from the dataset specified in the DELETEDSINCE command. 2249 6.7. Access Control List Commands 2251 The commands in this section are used to manage access control lists. 2253 6.7.1. SETACL Command 2255 Arguments: acl object 2256 authentication identifier 2257 access rights 2259 Data: no specific data for this command 2261 Result: OK - setacl completed 2262 NO - setacl failure: can't set acl 2263 BAD - command unknown or arguments invalid 2265 The SETACL command changes the access control list on the 2266 specified object so that the specified identifier is granted the 2267 permissions enumerated in rights. If the object did not 2268 previously have an access control list, one is created. 2270 Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r" 2271 S: A123 OK "Setacl complete" 2272 C: A124 SETACL ("/folder/site/") "B1FF" "rwa" 2273 S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not 2274 permitted to modify access rights 2275 for '/folder/site/'" 2277 6.7.2. DELETEACL Command 2279 Arguments: acl object 2280 optional authentication identifier 2282 Data: no specific data for this command 2284 Result: OK - deleteacl completed 2285 NO - deleteacl failure: can't delete acl 2286 BAD - command unknown or arguments invalid 2288 If given the optional identifier argument, the DELETEACL command 2289 removes any portion of the access control list on the specified 2290 object for the specified identifier. 2292 If not given the optional identifier argument, the DELETEACL 2293 command removes the ACL from the object entirely, causing access 2294 to be controlled by a higher-level default ACL. This form of the 2295 DELETEACL command is not permitted on the default ACL for a 2296 dataset and servers MUST return a BAD. 2298 Example: C: A223 DELETEACL ("/addressbook/~/public") "anyone" 2299 S: A223 OK "Deleteacl complete" 2300 C: A224 DELETEACL ("/folder/site") 2301 S: A224 BAD "Can't delete ACL from dataset" 2302 C: A225 DELETEACL ("/addressbook/user/fred" 2303 "addressbook.Email" "barney") 2304 S: A225 OK "Deleteacl complete" 2306 6.7.3. MYRIGHTS Command 2308 Arguments: acl object 2310 Data: intermediate responses: MYRIGHTS 2312 Result: OK - myrights completed 2313 NO - myrights failure: can't get rights 2314 BAD - command unknown or arguments invalid 2316 The MYRIGHTS command returns the set of rights that the client has 2317 to the given dataset or dataset attribute. 2319 Example: C: A003 MYRIGHTS ("/folder/site") 2320 S: A003 MYRIGHTS "r" 2321 S: A003 OK "Myrights complete" 2323 6.7.4. MYRIGHTS Intermediate Response 2325 Data: rights 2327 The MYRIGHTS response occurs as a result of a MYRIGHTS command. 2328 The argument is the set of rights that the client has for the 2329 object referred to in the MYRIGHTS command. 2331 6.7.5. LISTRIGHTS Command 2333 Arguments: acl object 2334 authentication identifier 2336 Data: untagged responses: LISTRIGHTS 2338 Result: OK - listrights completed 2339 NO - listrights failure: can't get rights list 2340 BAD - command unknown or arguments invalid 2342 The LISTRIGHTS command takes an object and an identifier and 2343 returns information about what rights may be granted to the 2344 identifier in the ACL for the object. 2346 Example: C: a001 LISTRIGHTS ("/folder/~/") "smith" 2347 S: a001 LISTRIGHTS "ra" "w" 2348 S: a001 OK Listrights completed 2349 C: a005 LISTRIGHTS ("/folder/site/archive/imap") "anyone" 2350 S: a005 LISTRIGHTS "" "r" "w" 2351 S: a005 OK Listrights completed 2353 6.7.6. LISTRIGHTS Intermediate Response 2355 Data: required rights 2356 list of optional rights 2358 The LISTRIGHTS response occurs as a result of a LISTRIGHTS 2359 command. The first argument is a string containing the (possibly 2360 empty) set of rights the identifier will always be granted on the 2361 dataset or attribute. 2363 Following this are zero or more strings each containing a single 2364 right the identifier may be granted in the dataset or attribute. 2366 The same right MUST NOT be listed more than once in the LISTRIGHTS 2367 response. 2369 6.8. Quotas 2371 The section defines the commands and responses relating to quotas. 2373 6.8.1. GETQUOTA Command 2375 Arguments: dataset 2377 Data: untagged responses: QUOTA 2379 Result: OK - Quota information returned 2380 NO - Quota failure: can't access resource limit 2381 no resource limit 2382 BAD - command unknown or arguments invalid 2384 The GETQUOTA command takes the name of a dataset, and returns in 2385 an untagged QUOTA response the name of the dataset, quota limit in 2386 bytes that applies to that dataset and the quota usage within that 2387 limit. The scope of a quota limit is implementation dependent. 2389 Example: C: A043 GETQUOTA "/option/user/fred/common" 2390 S: * QUOTA "/option/user/fred/common" 1048576 2475 2391 S: A043 OK "Getquota completed" 2393 6.8.3. QUOTA Untagged Response 2395 Data: dataset 2396 quota limit in bytes 2397 amount of quota limit used 2398 extension data 2400 The QUOTA untagged response is generated as a result of a GETQUOTA 2401 command or MAY be generated by the server in response to a SEARCH 2402 or STORE command to warn about high usage of a quota. It includes 2403 the name of the applicable dataset, the quota limit in bytes, the 2404 quota usage and some optional extension data. Clients MUST ignore 2405 the extension data as its use is reserved for a future extension. 2407 6.9. Extensions 2409 In order to simplify the process of extending the protocol, clients 2410 MUST ignore unknown server responses which meet the syntax of 2411 response-extend. In addition, clients MUST ignore unknown server 2412 response codes which meet the syntax of resp-code-ext. Availability 2413 of new commands MUST be announced via a capability on the initial 2414 greeting line and such commands SHOULD meet the syntax of command- 2415 extend. 2417 Servers MUST respond to unknown commands with a BAD command 2418 completion result. Servers MUST skip over non-synchronizing literals 2419 contained in an unknown command. This may be done by assuming the 2420 unknown command matches the command-extend syntax, or by reading a 2421 line at a time and checking for the non-synchronizing literal syntax 2422 at the end of the line. 2424 7. Registration Procedures 2426 ACAP's usefulness comes from providing a structured storage model for 2427 all sorts of configuration data. However, for its potential to be 2428 achieved, it is important that the Internet community strives for the 2429 following goals: 2431 (1) Standardization. It is very important to standardize dataset 2432 classes. The authors hope that ACAP achieves the success that SNMP 2433 has seen with the definition of numerous standards track MIBs. 2435 (2) Community Review. In the absence of standardization, it is 2436 important to get community review on a proposal to improve its 2437 engineering quality. Community review is strongly recommended prior 2438 to registration. The ACAP implementors mailing list 2439 should be used for this purpose. 2441 (3) Registration. Registration serves a two-fold purpose. First it 2442 prevents use of the same name for different purposes, and second it 2443 provides a one-stop list which can be used to locate existing 2444 extensions or dataset classes to prevent duplicate work. 2446 The following registration templates may be used to register ACAP 2447 protocol elements. 2449 7.1. ACAP Capabilities 2451 New ACAP capabilities MUST be standards track or IESG approved 2452 experimental RFCs. Registration provides a simple way to locate all 2453 extensions. Careful consideration should be made before extending 2454 the protocol, as it can lead to complexity or interoperability 2455 problems. 2457 To: iana@iana.org 2458 Subject: Registration of ACAP capability 2460 Capability name: 2462 Capability keyword: 2464 Capability arguments: 2466 Published Specification(s): 2468 (Standards track or IESG approved experimental RFC) 2470 Person and email address to contact for further information: 2472 7.2. ACAP Response Codes 2474 ACAP response codes are registered on a first come, first served 2475 basis. Proposals SHOULD be reviewed by the acap implementors mailing 2476 list mentioned above. 2478 To: iana@iana.org 2479 Subject: Registration of ACAP response code 2481 Response Code: 2483 Arguments: 2485 Purpose: 2487 Published Specification(s): 2489 (Optional, but encouraged) 2491 Person and email address to contact for further information: 2493 7.3. Dataset Classes 2495 A dataset class provides a core set of attributes for use in a 2496 specified hierarchy. It may also define rules for the dataset 2497 hierarchy underneath that class. Dataset class specifications must 2498 be standards track or IESG approved experimental RFCs. 2500 To: iana@iana.org 2501 Subject: Registration of ACAP dataset class 2502 Dataset class name/attribute prefix: 2504 Purpose: 2506 Published Specification(s): 2508 (Standards track or IESG approved experimental RFC) 2510 Person and email address to contact for further information: 2512 7.4. Vendor Subtree 2514 Vendors may reserve a portion of the ACAP namespace for private use. 2515 Dataset class names beginning with "vendor.." 2516 are reserved for use by that company or product. In addition, all 2517 attribute names beginning with "vendor.." are 2518 reserved for use by that company or product. Registration is on a 2519 first come, first served basis. Whenever possible, private 2520 attributes and dataset classes should be avoided in favor of 2521 improving interoperable dataset class definitions. 2523 To: iana@iana.org 2524 Subject: Registration of ACAP vendor subtree 2526 Private Prefix: vendor.. 2528 Person and email address to contact for further information: 2530 (company names and addresses should be included when appropriate) 2532 8. Formal Syntax 2534 The following syntax specification uses the augmented Backus-Naur 2535 Form (BNF) notation as specified in [ABNF]. 2537 Except as noted otherwise, all alphabetic characters are 2538 case-insensitive. The use of upper or lower case characters to 2539 define token strings is for editorial clarity only. Implementations 2540 MUST accept these strings in a case-insensitive fashion. 2542 The "command" rule below defines the syntax for commands sent by the 2543 client. The "response" rule below defines the syntax for responses 2544 sent by the server. 2546 ALPHA = %x41-5A / %x61-7A 2547 ;; alphabetic letters 2549 ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E 2550 ;; Any CHAR except ATOM-SPECIALS 2552 ATOM-SPECIALS = "(" / ")" / "{" / SPACE / CTL / QUOTED-SPECIALS 2554 BASE64-CHAR = ALPHA / DIGIT / "+" / "/" 2555 ;; case-sensitive 2557 CHAR = %x01-7F 2559 CR = %x0C 2561 CRLF = CR LF 2563 CTL = %x00-1F / %x7F 2565 DIGIT = "0" / DIGIT-NZ 2567 DIGIT-NZ = %x31-39 2568 ; non-zero digits ("1" - "9") 2570 LF = %x0A 2572 OCTET = %x00-FF 2574 QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS 2576 QUOTED-SPECIALS = <"> / "\" 2578 SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / 2579 %x23-5B / %x5D-7F 2580 ;; any TEXT-CHAR except QUOTED-SPECIALS 2582 SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / 2583 UTF8-5 / UTF8-6 2585 SPACE = %x20 2587 TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E 2588 ;; Any ATOM-CHAR except "*" or "+" 2590 TEXT-CHAR = %x01-09 / %x0B-0C / %x0E-7F 2591 ;; any CHAR except CR and LF 2593 TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS 2595 UTF8-1 = %x80-BF 2596 UTF8-2 = %xC0-DF UTF8-1 2598 UTF8-3 = %xE0-EF 2UTF8-1 2600 UTF8-4 = %xF0-F7 3UTF8-1 2602 UTF8-5 = %xF8-FB 4UTF8-1 2604 UTF8-6 = %xFC-FD 5UTF8-1 2606 UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF 2608 acl = "(" *acl-identrights ")" 2610 acl-identifier = string-utf8 2611 ;; MUST NOT contain TAB 2613 acl-identrights = string-utf8 2614 ;; The identifier followed by a TAB, followed by 2615 ;; the rights. 2617 acl-delobject = "(" dataset SPACE attribute [SPACE entry-name] ")" 2619 acl-object = "(" dataset [SPACE attribute [SPACE entry-name]] ")" 2621 acl-rights = quoted 2623 atom = ALPHA *1023ATOM-CHAR 2625 attribute = string-utf8 2626 ;; dot-separated attribute name 2627 ;; MUST NOT contain "*" or "%" 2629 attribute-store = attribute SPACE (value-nildef / 2630 "(" 1*(metadata-write-q SPACE value-store) ")") 2631 ;; MUST NOT include the same metadata twice 2633 auth-type = iana-token 2634 ;; as defined in SASL [SASL] 2636 base64-token = *(4BASE64-CHAR) [base64-terminal] 2638 base64-terminal = (2BASE64-CHAR "==") / (3BASE64-CHAR "=") 2640 command = tag SPACE (command-any / command-auth / 2641 command-nonauth) CRLF 2642 ;; Modal based on state 2644 command-authent = "AUTHENTICATE" SPACE auth-type [SPACE base64-token] 2645 *(CRLF base64-token) 2647 command-any = "NOOP" / command-lang / "LOGOUT" 2649 command-auth = command-delacl / command-dsince / 2650 command-freectx / command-getquota / 2651 command-lrights / command-myrights / 2652 command-search / command-setacl / 2653 command-store 2654 ;; only valid in authenticated state 2656 command-delacl = "DELETEACL" SPACE acl-delobject [SPACE acl-identifier] 2658 command-dsince = "DELETEDSINCE" SPACE dataset SPACE time 2660 command-extend = extend-token [SPACE extension-data] 2662 command-freectx = "FREECONTEXT" SPACE context 2664 command-getquota = "GETQUOTA" SPACE dataset 2666 command-lang = "LANG" *(SPACE lang-tag) 2668 command-lrights = "LISTRIGHTS" SPACE acl-object 2670 command-myrights = "MYRIGHTS" SPACE acl-object 2672 command-nonauth = command-authent 2673 ;; only valid in non-authenticated state 2675 command-search = "SEARCH" SPACE (dataset / context) 2676 *(SPACE search-modifier) 2677 SPACE search-criteria 2678 ;; MUST NOT include same search-modifier twice 2680 command-setacl = "SETACL" SPACE acl-object SPACE acl-identifier 2681 SPACE acl-rights 2683 command-store = "STORE" SPACE store-entry-list 2685 comparator = <"> comparator-name <"> 2687 comparator-name = ["+" / "-"] iana-token 2689 context = string-utf8 2690 ;; MUST NOT begin with slash ("/") 2692 dataset = string-utf8 2693 ;; slash-separated dataset name 2694 ;; begins with slash 2696 entry = entry-name / entry-path 2698 entry-name = string-utf8 2699 ;; entry name MUST NOT contain slash 2700 ;; MUST NOT begin with "." 2702 entry-path = string-utf8 2703 ;; slash-separated path to entry 2704 ;; begins with slash 2706 entry-relative = string-utf8 2707 ;; potentially relative path to entry 2709 extend-token = atom 2710 ;; MUST be defined by a standards track or 2711 ;; IESG approved experimental protocol extension 2713 extension-data = extension-item *(SPACE extension-item) 2715 extension-item = extend-token / string / number / 2716 "(" [extension-data] ")" 2718 iana-token = atom 2719 ;; MUST be registered with IANA 2721 initial-greeting = "*" SPACE "ACAP" *(SPACE "(" init-capability ")") CRLF 2723 init-capability = init-cap-context / init-cap-extend / 2724 init-cap-implem / init-cap-sasl 2726 init-cap-context = "CONTEXTLIMIT" SPACE string 2728 init-cap-extend = iana-token [SPACE string-list] 2730 init-cap-implem = "IMPLEMENTATION" SPACE string 2732 init-cap-sasl = "SASL" SPACE string-list 2734 lang-tag = <"> Language-Tag <"> 2735 ;; Language-Tag rule is defined in [LANG-TAGS] 2737 literal = "{" number [ "+" ] "}" CRLF *OCTET 2738 ;; The number represents the number of octets 2739 ;; MUST be literal-utf8 except for values 2741 literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR 2742 ;; The number represents the number of octets 2743 ;; not the number of characters 2745 metadata = attribute [ "(" metadata-type-list ")" ] 2746 ;; attribute MAY end in "*" as wildcard. 2748 metadata-list = metadata *(SPACE metadata) 2750 metadata-type = "attribute" / "myrights" / "size" / 2751 "count" / metadata-write 2753 metadata-type-q = <"> metadata-type <"> 2755 metadata-type-list = metadata-type-q *(SPACE metadata-type-q) 2757 metadata-write = "value" / "acl" 2759 metadata-write-q = <"> metadata-write <"> 2761 nil = "NIL" 2763 number = *DIGIT 2764 ;; A 32-bit unsigned number. 2765 ;; (0 <= n < 4,294,967,296) 2767 nz-number = DIGIT-NZ *DIGIT 2768 ;; A 32-bit unsigned non-zero number. 2769 ;; (0 < n < 4,294,967,296) 2771 position = number 2772 ;; "0" if context is not enumerated 2773 ;; otherwise this is non-zero 2775 quota-limit = number 2777 quota-usage = number 2779 quoted = <"> *QUOTED-CHAR <"> 2780 ;; limited to 1024 octets between the <">s 2782 response = response-addto / response-alert / response-bye / 2783 response-change / response-cont / 2784 response-deleted / response-done / response-entry / 2785 response-extend / response-listr / 2786 response-lang / response-mtimei / response-mtimeu / 2787 response-myright / response-quota / 2788 response-refer / response-remove / response-stat 2790 response-addto = "*" SPACE "ADDTO" SPACE context SPACE entry-name 2791 SPACE position SPACE return-data-list 2793 response-alert = "*" SPACE "ALERT" SPACE resp-body CRLF 2794 ;; Client MUST display alert text to user 2796 response-bye = "*" SPACE "BYE" SPACE resp-body CRLF 2797 ;; Server will disconnect condition 2799 response-change = "*" SPACE "CHANGE" SPACE context SPACE entry-name 2800 SPACE position SPACE position SPACE return-data-list 2802 response-cont = "+" SPACE (quoted / base64-token) 2804 response-deleted = tag SPACE "DELETED" SPACE entry-name 2806 response-done = tag SPACE resp-cond-state CRLF 2808 response-entry = tag SPACE "ENTRY" SPACE entry SPACE return-data-list 2810 response-extend = (tag / "*") SPACE extend-token [SPACE extension-data] 2812 response-lang = "*" SPACE "LANG" SPACE lang-tag 1*(SPACE comparator) 2814 response-listr = tag SPACE "LISTRIGHTS" SPACE acl-rights 2815 *(SPACE acl-rights) 2817 response-mtimei = tag SPACE "MODTIME" SPACE time 2819 response-mtimeu = "*" SPACE "MODTIME" SPACE context SPACE time 2821 response-myright = tag SPACE "MYRIGHTS" SPACE acl-rights 2823 response-quota = "*" SPACE "QUOTA" SPACE dataset SPACE quota-limit 2824 SPACE quota-usage [SPACE extension-data] 2826 response-refer = tag SPACE "REFER" SPACE dataset 1*(SPACE 2827 <"> url-relative <">) 2829 response-remove = "*" SPACE "REMOVEFROM" SPACE context SPACE 2830 entry-name SPACE position 2832 response-stat = "*" SPACE resp-cond-state CRLF 2834 resp-body = ["(" resp-code ")" SPACE] quoted 2835 resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / 2836 resp-code-inval / resp-code-mod / 2837 resp-code-noexist / resp-code-perm / "QUOTA" / 2838 resp-code-refer / resp-code-toomany / "TOOOLD" / 2839 "TRANSITION-NEEDED" / "TRYFREECONTEXT" / 2840 "TRYLATER" / "WAYTOOMANY" / resp-code-ext 2842 resp-code-ext = iana-token [SPACE extension-data] 2843 ;; unknown response codes are ignored by the client. 2845 resp-code-inval = "INVALID" 1*(SPACE entry-path SPACE attribute) 2847 resp-code-mod = "MODIFIED" SPACE entry-path 2849 resp-code-noexist = "NOEXIST" SPACE dataset 2851 resp-code-perm = "PERMISSION" SPACE acl-object 2853 resp-code-refer = "REFER" 1*(SPACE <"> url-relative <">) 2855 resp-code-toomany = "TOOMANY" SPACE nz-number 2857 resp-cond-state = ("OK" / "NO" / "BAD") SPACE resp-body 2858 ;; Status condition 2860 return-data = return-metadata / return-meta-list 2861 ;; return-meta-list format is used when "*" is 2862 ;; in the RETURN pattern on SEARCH 2864 return-data-list = return-data *(SPACE return-data) 2866 return-meta-list = "(" return-metadata *(SPACE return-metadata) ")" 2868 return-metadata = nil / string / value-list / acl 2870 searchkey-equal = "EQUAL" SPACE attribute SPACE comparator 2871 SPACE value-nil 2873 searchkey-comp = "COMPARE" SPACE attribute SPACE comparator SPACE value 2875 searchkey-prefix = "PREFIX" SPACE attribute SPACE comparator SPACE value 2877 searchkey-range = "RANGE" SPACE nz-number SPACE nz-number 2878 SPACE time 2880 searchkey-strict = "COMPARESTRICT" SPACE attribute SPACE comparator 2881 SPACE value 2883 searchkey-substr = "SUBSTRING" SPACE attribute SPACE comparator 2884 SPACE value 2886 searchmod-depth = "DEPTH" SPACE number 2888 searchmod-hard = "HARDLIMIT" SPACE nz-number 2890 searchmod-limit = "LIMIT" SPACE number SPACE number 2892 searchmod-make = "MAKECONTEXT" [SPACE "ENUMERATE"] 2893 [SPACE "NOTIFY"] SPACE context 2895 searchmod-ninh = "NOINHERIT" 2897 searchmod-return = "RETURN" SPACE "(" [metadata-list] ")" 2899 searchmod-sort = "SORT" SPACE "(" sort-list ")" 2901 search-criteria = "ALL" / searchkey-equal / searchkey-comp / 2902 searchkey-strict / searchkey-range / 2903 searchkey-prefix / searchkey-substr / 2904 "NOT" SPACE search-criteria / 2905 "OR" SPACE search-criteria SPACE search-criteria / 2906 "AND" SPACE search-criteria SPACE search-criteria 2908 search-modifier = searchmod-depth / searchmod-hard / 2909 searchmod-limit / searchmod-make / searchmod-ninh / 2910 searchmod-return / searchmod-sort 2912 sort-list = sort-item *(SPACE sort-item) 2914 sort-item = attribute SPACE comparator 2916 store-entry = "(" entry-path *(SPACE store-modifier) 2917 *(SPACE attribute-store) ")" 2918 ;; MUST NOT include the same store-modifier twice 2919 ;; MUST NOT include the same attribute twice 2921 store-entry-list = store-entry *(SPACE store-entry) 2922 ;; MUST NOT include the same entry twice 2924 store-modifier = store-mod-unchang / store-mod-nocreate 2926 store-mod-nocreate = "NOCREATE" 2928 store-mod-unchang = "UNCHANGEDSINCE" SPACE time 2930 string = quoted / literal 2931 string-list = string *(SPACE string) 2933 string-utf8 = quoted / literal-utf8 2935 tag = 1*32TAG-CHAR 2937 time = <"> time-year time-month time-day time-hour 2938 time-minute time-second time-subsecond <"> 2939 ;; Timestamp in UTC 2941 time-day = 2DIGIT ;; 01-31 2943 time-hour = 2DIGIT ;; 00-23 2945 time-minute = 2DIGIT ;; 00-59 2947 time-month = 2DIGIT ;; 01-12 2949 time-second = 2DIGIT ;; 00-60 2951 time-subsecond = *DIGIT 2953 time-year = 4DIGIT 2955 value = string 2957 value-any = value-nil / value-list 2959 value-list = "(" [value *(SPACE value)] ")" 2961 value-nil = value / nil 2963 value-nildef = value-nil / "DEFAULT" 2965 value-store = value-nildef / value-list / acl 2967 url-acap = "acap://" url-server "/" url-enc-entry [url-filter] 2968 [url-extension] 2969 ;; url-enc-entry interpreted relative to "/" 2971 url-attr-list = url-enc-attr *("&" url-enc-attr) 2973 url-auth = ";AUTH=" ("*" / url-enc-auth) 2975 url-achar = uchar / "&" / "=" / "~" 2976 ;; See RFC 1738 for definition of "uchar" 2978 url-char = uchar / "=" / "~" / ":" / "@" / "/" 2979 ;; See RFC 1738 for definition of "uchar" 2981 url-enc-attr = 1*url-char 2982 ;; encoded version of attribute name 2984 url-enc-auth = 1*url-achar 2985 ;; encoded version of auth-type above 2987 url-enc-entry = 1*url-char 2988 ;; encoded version of entry-relative above 2990 url-enc-user = *url-achar 2991 ;; encoded version of login userid 2993 url-extension = *("?" 1*url-char) 2995 url-filter = "?" url-attr-list 2997 url-relative = url-acap / [url-enc-entry] [url-filter] 2998 ;; url-enc-entry is relative to base URL 3000 url-server = [url-user [url-auth] "@"] hostport 3001 ;; See RFC 1738 for definition of "hostport" 3003 9. Multi-lingual Considerations 3005 The IAB charset workshop [IAB-CHARSET] came to a number of 3006 conclusions which influenced the design of ACAP. The decision to use 3007 UTF-8 as the character encoding scheme was based on that work. The 3008 LANG command to negotiate a language for error messages is also 3009 included. 3011 Section 3.4.5 of the IAB charset workshop report states that there 3012 should be a way to identify the natural language for human readable 3013 strings. Several promising proposals have been made for use within 3014 ACAP, but no clear consensus on a single method is apparent at this 3015 stage. The following rules are likely to permit the addition of 3016 multi-lingual support in the future: 3018 (1) A work in progress called Multi-Lingual String Format (MLSF) 3019 proposes a layer on top of UTF-8 which uses otherwise illegal UTF-8 3020 sequences to store language tags. In order to permit its addition to 3021 a future version of this standard, client-side UTF-8 interpreters 3022 SHOULD silently ignore illegal multi-byte UTF-8 characters, and treat 3023 illegal single-byte UTF-8 characters as end of string markers. 3024 Servers, for the time being, MUST silently accept illegal UTF-8 3025 characters, except in attribute names and entry names. Clients MUST 3026 NOT send illegal UTF-8 characters to the server unless a future 3027 standard changes this rule. 3028 (2) There is a proposal to add language tags to Unicode. To support 3029 this, servers MUST be able to store UTF-8 characters of up to 20 bits 3030 of data. 3031 (3) The metadata item "language" is reserved for future use. 3033 10. Security Considerations 3035 The AUTHENTICATE command uses SASL [SASL] to provide basic 3036 authentication, authorization, integrity and privacy services. This 3037 is described in section 6.3.1. The security considerations for the 3038 PLAIN SASL mechanism [SASL-PLAIN] also apply. 3040 ACAP protocol transactions are susceptible to passive observers or 3041 man in the middle attacks which alter the data, unless the optional 3042 encryption and integrity services of the AUTHENTICATE command are 3043 offered, or an external security mechanism is used for protection. 3044 It may be useful to allow configuration of both clients and servers 3045 to refuse to transfer sensitive information in the absence of strong 3046 encryption. 3048 ACAP access control lists provide fine grained authorization for 3049 access to attributes. A number of related security issues are 3050 described in section 3.5. 3052 ACAP URLs have the same security considerations as IMAP URLs 3053 [IMAP-URL]. 3055 ACAP clients are encouraged to consider the security problems 3056 involved with a lab computer situation. Specifically, a client cache 3057 of ACAP configuration information MUST NOT allow access by an 3058 unauthorized user. One way to assure this is for an ACAP client to 3059 be able to completely flush any non-public cached configuration data 3060 when a user leaves. 3062 As laptop computers can be easily stolen and a cache of configuration 3063 data may contain sensitive information, a disconnected mode ACAP 3064 client may wish to encrypt and password protect cached configuration 3065 information. 3067 11. Acknowledgments 3069 Many thanks to the follow people who helped design ACAP over the past 3070 four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob Earhart, 3071 Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, Steve Hole, 3072 Steve Hubert, Dave Roberts, Bart Schaefer, Matt Wall and other 3073 participants of the IETF ACAP working group. 3075 12. Authors' Addresses 3077 Chris Newman 3078 Innosoft International, Inc. 3079 1050 Lakes Drive 3080 West Covina, CA 91790 USA 3082 Email: chris.newman@innosoft.com 3084 John Gardiner Myers 3085 Netscape Communications 3086 501 East Middlefield Road 3087 Mail Stop MV-029 3088 Mountain View, CA 94043 3090 Email: jgmyers@netscape.com 3092 Appendices 3094 A. References 3096 [ABNF] Crocker, D., "Augmented BNF for Syntax Specifications: ABNF", 3097 Work in progress: draft-ietf-drums-abnf-xx.txt 3099 [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource 3100 Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of 3101 Minnesota, December 1994. 3103 3105 [IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson, 3106 Crispin, Svanberg, "The Report of the IAB Character Set Workshop held 3107 29 February - 1 March, 1996", RFC 2130, April 1997. 3109 3111 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 3112 4rev1", RFC 2060, University of Washington, December 1996. 3114 3116 [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie 3117 Mellon, January 1997. 3119 3121 [IMAP-URL] Newman, "IMAP URL Scheme", RFC XXXX, Innosoft, July 1997. 3123 3125 [ISO-10646] ISO/IEC 10646-1:1993(E) "Information Technology-- 3126 Universal Multiple-octet Coded Character Set (UCS)." See also 3127 amendments 1 through 7, plus editorial corrections. 3129 [ISO-C] "Programming languages -- C", ISO/IEC 9899:1990, 3130 International Organization for Standardization. This is effectively 3131 the same as ANSI C standard X3.159-1989. 3133 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 3134 Requirement Levels", RFC 2119, Harvard University, March 1997. 3136 3138 [LANG-TAGS] Alvestrand, H., "Tags for the Identification of 3139 Languages", RFC 1766. 3141 3143 [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, 3144 UC Irvine, June 1995. 3146 3148 [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", 3149 Work in progress: draft-myers-auth-sasl-xx.txt 3151 [SASL-ANON] Newman, "Anonymous SASL Mechanism", Work in progress: 3152 draft-newman-sasl-anon-xx.txt. 3154 [SASL-PLAIN] Newman, "Plaintext Password SASL Mechanism and 3155 Transition Codes", Work in progress: draft-newman-sasl-plaintrans- 3156 xx.txt. 3158 [UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version 3159 2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9. 3161 [US-ASCII] "USA Standard Code for Information Interchange," X3.4. 3162 American National Standards Institute: New York (1968). 3164 [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO 3165 10646", RFC 2044, Alis Technologies, October 1996. 3167 3169 B. ACAP Keyword Index 3171 ACAP (untagged response) ................................... 27 3172 ADDTO (untagged response) .................................. 41 3173 ALERT (untagged response) .................................. 31 3174 ALL (search keyword) ....................................... 37 3175 AND (search keyword) ....................................... 37 3176 AUTH-TOO-WEAK (response code) .............................. 19 3177 AUTHENTICATE (command) ..................................... 32 3178 BAD (response) ............................................. 30 3179 BYE (untagged response) .................................... 31 3180 CHANGE (untagged response) ................................. 42 3181 COMPARE (search keyword) ................................... 37 3182 COMPARESTRICT (search keyword) ............................. 37 3183 CONTEXTLIMIT (ACAP capability) ............................. 27 3184 DELETEACL (command) ........................................ 47 3185 DELETED (intermediate response) ............................ 46 3186 DELETEDSINCE (command) ..................................... 45 3187 DEPTH (search modifier) .................................... 34 3188 ENCRYPT-NEEDED (response code) ............................. 19 3189 ENTRY (intermediate response) .............................. 38 3190 EQUAL (search keyword) ..................................... 37 3191 FREECONTEXT (command) ...................................... 40 3192 GETQUOTA (command) ......................................... 49 3193 HARDLIMIT (search modifier) ................................ 34 3194 IMPLEMENTATION (ACAP capability) ........................... 27 3195 INVALID (response code) .................................... 19 3196 LANG (command) ............................................. 28 3197 LANG (intermediate response) ............................... 29 3198 LIMIT (search modifier) .................................... 34 3199 LISTRIGHTS (command) ....................................... 48 3200 LISTRIGHTS (intermediate response) ......................... 48 3201 LOGOUT (command) ........................................... 29 3202 MAKECONTEXT (search modifier) .............................. 35 3203 MODIFIED (response code) ................................... 20 3204 MODTIME (intermediate response) ............................ 38 3205 MODTIME (untagged response) ................................ 43 3206 MYRIGHTS (command) ......................................... 47 3207 MYRIGHTS (intermediate response) ........................... 48 3208 NO (response) .............................................. 30 3209 NOCREATE (store modifier) .................................. 44 3210 NOEXIST (response code) .................................... 20 3211 NOINHERIT (search modifier) ................................ 36 3212 NOOP (command) ............................................. 28 3213 NOT (search keyword) ....................................... 37 3214 OK (response) .............................................. 29 3215 OR (search keyword) ........................................ 37 3216 PERMISSION (response code) ................................. 20 3217 PREFIX (search keyword) .................................... 37 3218 QUOTA (response code) ...................................... 20 3219 QUOTA (untagged response) .................................. 49 3220 RANGE (search keyword) ..................................... 37 3221 REFER (intermediate response) .............................. 38 3222 REFER (response code) ...................................... 20 3223 REMOVEFROM (untagged response) ............................. 41 3224 RETURN (search modifier) ................................... 36 3225 SASL (ACAP capability) ..................................... 27 3226 SEARCH (command) ........................................... 33 3227 SETACL (command) ........................................... 46 3228 SORT (search modifier) ..................................... 36 3229 STORE (command) ............................................ 43 3230 SUBSTRING (search keyword) ................................. 38 3231 TOOMANY (response code) .................................... 20 3232 TOOOLD (response code) ..................................... 20 3233 TRANSITION-NEEDED (response code) .......................... 20 3234 TRYFREECONTEXT (response code) ............................. 21 3235 TRYLATER (response code) ................................... 20 3236 UNCHANGEDSINCE (store modifier) ............................ 44 3237 UPDATECONTEXT (command) .................................... 40 3238 WAYTOOMANY (response code) ................................. 21 3239 acl (attribute metadata) ................................... 13 3240 anyone (ACL identifier) .................................... 18 3241 attribute (attribute metadata) ............................. 13 3242 dataset.acl (dataset attribute) ............................ 25 3243 dataset.acl. (dataset attribute) ................ 25 3244 dataset.inherit (dataset attribute) ........................ 25 3245 en;nocase;octet (comparator) ............................... 17 3246 entry (predefined attribute) ............................... 12 3247 i;numeric (comparator) ..................................... 17 3248 i;octet (comparator) ....................................... 16 3249 modtime (predefined attribute) ............................. 12 3250 myrights (attribute metadata) .............................. 13 3251 size (attribute metadata) .................................. 13 3252 subdataset (predefined attribute) .......................... 12 3253 value (attribute metadata) ................................. 14