From 9238fa6abfef0cce949f92e27265714165a0f9a6 Mon Sep 17 00:00:00 2001 From: Robert Burrell Donkin Date: Sat, 10 May 2008 12:37:12 +0000 Subject: [PATCH] Just use links instead git-svn-id: https://svn.apache.org/repos/asf/james/jsieve/trunk@655069 13f79535-47bb-0310-9956-ffa450edef68 --- src/site/resources/rfc2234.txt | 786 -------- src/site/resources/rfc2244.txt | 4034 ---------------------------------------- src/site/resources/rfc2298.txt | 1570 ---------------- src/site/resources/rfc3028.txt | 2018 -------------------- src/site/site.xml | 8 +- 5 files changed, 4 insertions(+), 8412 deletions(-) delete mode 100644 src/site/resources/rfc2234.txt delete mode 100644 src/site/resources/rfc2244.txt delete mode 100644 src/site/resources/rfc2298.txt delete mode 100644 src/site/resources/rfc3028.txt diff --git a/src/site/resources/rfc2234.txt b/src/site/resources/rfc2234.txt deleted file mode 100644 index 7f8eafe..0000000 --- a/src/site/resources/rfc2234.txt +++ /dev/null @@ -1,786 +0,0 @@ - - - - - -Network Working Group D. Crocker, Ed. -Request for Comments: 2234 Internet Mail Consortium -Category: Standards Track P. Overell - Demon Internet Ltd. - November 1997 - - - Augmented BNF for Syntax Specifications: ABNF - - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1997). All Rights Reserved. - -TABLE OF CONTENTS - - 1. INTRODUCTION .................................................. 2 - - 2. RULE DEFINITION ............................................... 2 - 2.1 RULE NAMING .................................................. 2 - 2.2 RULE FORM .................................................... 3 - 2.3 TERMINAL VALUES .............................................. 3 - 2.4 EXTERNAL ENCODINGS ........................................... 5 - - 3. OPERATORS ..................................................... 5 - 3.1 CONCATENATION RULE1 RULE2 ............................. 5 - 3.2 ALTERNATIVES RULE1 / RULE2 ................................... 6 - 3.3 INCREMENTAL ALTERNATIVES RULE1 =/ RULE2 .................... 6 - 3.4 VALUE RANGE ALTERNATIVES %C##-## ........................... 7 - 3.5 SEQUENCE GROUP (RULE1 RULE2) ................................. 7 - 3.6 VARIABLE REPETITION *RULE .................................... 8 - 3.7 SPECIFIC REPETITION NRULE .................................... 8 - 3.8 OPTIONAL SEQUENCE [RULE] ..................................... 8 - 3.9 ; COMMENT .................................................... 8 - 3.10 OPERATOR PRECEDENCE ......................................... 9 - - 4. ABNF DEFINITION OF ABNF ....................................... 9 - - 5. SECURITY CONSIDERATIONS ....................................... 10 - - - - -Crocker & Overell Standards Track [Page 1] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - 6. APPENDIX A - CORE ............................................. 11 - 6.1 CORE RULES ................................................... 11 - 6.2 COMMON ENCODING .............................................. 12 - - 7. ACKNOWLEDGMENTS ............................................... 12 - - 8. REFERENCES .................................................... 13 - - 9. CONTACT ....................................................... 13 - - 10. FULL COPYRIGHT STATEMENT ..................................... 14 - -1. INTRODUCTION - - Internet technical specifications often need to define a format - syntax and are free to employ whatever notation their authors deem - useful. Over the years, a modified version of Backus-Naur Form - (BNF), called Augmented BNF (ABNF), has been popular among many - Internet specifications. It balances compactness and simplicity, - with reasonable representational power. In the early days of the - Arpanet, each specification contained its own definition of ABNF. - This included the email specifications, RFC733 and then RFC822 which - have come to be the common citations for defining ABNF. The current - document separates out that definition, to permit selective - reference. Predictably, it also provides some modifications and - enhancements. - - The differences between standard BNF and ABNF involve naming rules, - repetition, alternatives, order-independence, and value ranges. - Appendix A (Core) supplies rule definitions and encoding for a core - lexical analyzer of the type common to several Internet - specifications. It is provided as a convenience and is otherwise - separate from the meta language defined in the body of this document, - and separate from its formal status. - -2. RULE DEFINITION - -2.1 Rule Naming - - The name of a rule is simply the name itself; that is, a sequence of - characters, beginning with an alphabetic character, and followed by - a combination of alphabetics, digits and hyphens (dashes). - - NOTE: Rule names are case-insensitive - - The names , , and all refer - to the same rule. - - - - -Crocker & Overell Standards Track [Page 2] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - Unlike original BNF, angle brackets ("<", ">") are not required. - However, angle brackets may be used around a rule name whenever their - presence will facilitate discerning the use of a rule name. This is - typically restricted to rule name references in free-form prose, or - to distinguish partial rules that combine into a string not separated - by white space, such as shown in the discussion about repetition, - below. - -2.2 Rule Form - - A rule is defined by the following sequence: - - name = elements crlf - - where is the name of the rule, is one or more rule - names or terminal specifications and is the end-of- line - indicator, carriage return followed by line feed. The equal sign - separates the name from the definition of the rule. The elements - form a sequence of one or more rule names and/or value definitions, - combined according to the various operators, defined in this - document, such as alternative and repetition. - - For visual ease, rule definitions are left aligned. When a rule - requires multiple lines, the continuation lines are indented. The - left alignment and indentation are relative to the first lines of the - ABNF rules and need not match the left margin of the document. - -2.3 Terminal Values - - Rules resolve into a string of terminal values, sometimes called - characters. In ABNF a character is merely a non-negative integer. - In certain contexts a specific mapping (encoding) of values into a - character set (such as ASCII) will be specified. - - Terminals are specified by one or more numeric characters with the - base interpretation of those characters indicated explicitly. The - following bases are currently defined: - - b = binary - - d = decimal - - x = hexadecimal - - - - - - - - -Crocker & Overell Standards Track [Page 3] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - Hence: - - CR = %d13 - - CR = %x0D - - respectively specify the decimal and hexadecimal representation of - [US-ASCII] for carriage return. - - A concatenated string of such values is specified compactly, using a - period (".") to indicate separation of characters within that value. - Hence: - - CRLF = %d13.10 - - ABNF permits specifying literal text string directly, enclosed in - quotation-marks. Hence: - - command = "command string" - - Literal text strings are interpreted as a concatenated set of - printable characters. - - NOTE: ABNF strings are case-insensitive and - the character set for these strings is us-ascii. - - Hence: - - rulename = "abc" - - and: - - rulename = "aBc" - - will match "abc", "Abc", "aBc", "abC", "ABc", "aBC", "AbC" and "ABC". - - To specify a rule which IS case SENSITIVE, - specify the characters individually. - - For example: - - rulename = %d97 %d98 %d99 - - or - - rulename = %d97.98.99 - - - - - -Crocker & Overell Standards Track [Page 4] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - will match only the string which comprises only lowercased - characters, abc. - -2.4 External Encodings - - External representations of terminal value characters will vary - according to constraints in the storage or transmission environment. - Hence, the same ABNF-based grammar may have multiple external - encodings, such as one for a 7-bit US-ASCII environment, another for - a binary octet environment and still a different one when 16-bit - Unicode is used. Encoding details are beyond the scope of ABNF, - although Appendix A (Core) provides definitions for a 7-bit US-ASCII - environment as has been common to much of the Internet. - - By separating external encoding from the syntax, it is intended that - alternate encoding environments can be used for the same syntax. - -3. OPERATORS - -3.1 Concatenation Rule1 Rule2 - - A rule can define a simple, ordered string of values -- i.e., a - concatenation of contiguous characters -- by listing a sequence of - rule names. For example: - - foo = %x61 ; a - - bar = %x62 ; b - - mumble = foo bar foo - - So that the rule matches the lowercase string "aba". - - LINEAR WHITE SPACE: Concatenation is at the core of the ABNF - parsing model. A string of contiguous characters (values) is - parsed according to the rules defined in ABNF. For Internet - specifications, there is some history of permitting linear white - space (space and horizontal tab) to be freelyPand - implicitlyPinterspersed around major constructs, such as - delimiting special characters or atomic strings. - - NOTE: This specification for ABNF does not - provide for implicit specification of linear white - space. - - Any grammar which wishes to permit linear white space around - delimiters or string segments must specify it explicitly. It is - often useful to provide for such white space in "core" rules that are - - - -Crocker & Overell Standards Track [Page 5] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - then used variously among higher-level rules. The "core" rules might - be formed into a lexical analyzer or simply be part of the main - ruleset. - -3.2 Alternatives Rule1 / Rule2 - - Elements separated by forward slash ("/") are alternatives. - Therefore, - - foo / bar - - will accept or . - - NOTE: A quoted string containing alphabetic - characters is special form for specifying alternative - characters and is interpreted as a non-terminal - representing the set of combinatorial strings with the - contained characters, in the specified order but with - any mixture of upper and lower case.. - -3.3 Incremental Alternatives Rule1 =/ Rule2 - - It is sometimes convenient to specify a list of alternatives in - fragments. That is, an initial rule may match one or more - alternatives, with later rule definitions adding to the set of - alternatives. This is particularly useful for otherwise- independent - specifications which derive from the same parent rule set, such as - often occurs with parameter lists. ABNF permits this incremental - definition through the construct: - - oldrule =/ additional-alternatives - - So that the rule set - - ruleset = alt1 / alt2 - - ruleset =/ alt3 - - ruleset =/ alt4 / alt5 - - is the same as specifying - - ruleset = alt1 / alt2 / alt3 / alt4 / alt5 - - - - - - - - -Crocker & Overell Standards Track [Page 6] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -3.4 Value Range Alternatives %c##-## - - A range of alternative numeric values can be specified compactly, - using dash ("-") to indicate the range of alternative values. Hence: - - DIGIT = %x30-39 - - is equivalent to: - - DIGIT = "0" / "1" / "2" / "3" / "4" / "5" / "6" / - - "7" / "8" / "9" - - Concatenated numeric values and numeric value ranges can not be - specified in the same string. A numeric value may use the dotted - notation for concatenation or it may use the dash notation to specify - one value range. Hence, to specify one printable character, between - end of line sequences, the specification could be: - - char-line = %x0D.0A %x20-7E %x0D.0A - -3.5 Sequence Group (Rule1 Rule2) - - Elements enclosed in parentheses are treated as a single element, - whose contents are STRICTLY ORDERED. Thus, - - elem (foo / bar) blat - - which matches (elem foo blat) or (elem bar blat). - - elem foo / bar blat - - matches (elem foo) or (bar blat). - - NOTE: It is strongly advised to use grouping - notation, rather than to rely on proper reading of - "bare" alternations, when alternatives consist of - multiple rule names or literals. - - Hence it is recommended that instead of the above form, the form: - - (elem foo) / (bar blat) - - be used. It will avoid misinterpretation by casual readers. - - The sequence group notation is also used within free text to set off - an element sequence from the prose. - - - - -Crocker & Overell Standards Track [Page 7] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -3.6 Variable Repetition *Rule - - The operator "*" preceding an element indicates repetition. The full - form is: - - *element - - where and are optional decimal values, indicating at least - and at most occurrences of element. - - Default values are 0 and infinity so that * allows any - number, including zero; 1* requires at least one; - 3*3 allows exactly 3 and 1*2 allows one or two. - -3.7 Specific Repetition nRule - - A rule of the form: - - element - - is equivalent to - - *element - - That is, exactly occurrences of . Thus 2DIGIT is a - 2-digit number, and 3ALPHA is a string of three alphabetic - characters. - -3.8 Optional Sequence [RULE] - - Square brackets enclose an optional element sequence: - - [foo bar] - - is equivalent to - - *1(foo bar). - -3.9 ; Comment - - A semi-colon starts a comment that continues to the end of line. - This is a simple way of including useful notes in parallel with the - specifications. - - - - - - - - -Crocker & Overell Standards Track [Page 8] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -3.10 Operator Precedence - - The various mechanisms described above have the following precedence, - from highest (binding tightest) at the top, to lowest and loosest at - the bottom: - - Strings, Names formation - Comment - Value range - Repetition - Grouping, Optional - Concatenation - Alternative - - Use of the alternative operator, freely mixed with concatenations can - be confusing. - - Again, it is recommended that the grouping operator be used to - make explicit concatenation groups. - -4. ABNF DEFINITION OF ABNF - - This syntax uses the rules provided in Appendix A (Core). - - rulelist = 1*( rule / (*c-wsp c-nl) ) - - rule = rulename defined-as elements c-nl - ; continues if next line starts - ; with white space - - rulename = ALPHA *(ALPHA / DIGIT / "-") - - defined-as = *c-wsp ("=" / "=/") *c-wsp - ; basic rules definition and - ; incremental alternatives - - elements = alternation *c-wsp - - c-wsp = WSP / (c-nl WSP) - - c-nl = comment / CRLF - ; comment or newline - - comment = ";" *(WSP / VCHAR) CRLF - - alternation = concatenation - *(*c-wsp "/" *c-wsp concatenation) - - - - -Crocker & Overell Standards Track [Page 9] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - concatenation = repetition *(1*c-wsp repetition) - - repetition = [repeat] element - - repeat = 1*DIGIT / (*DIGIT "*" *DIGIT) - - element = rulename / group / option / - char-val / num-val / prose-val - - group = "(" *c-wsp alternation *c-wsp ")" - - option = "[" *c-wsp alternation *c-wsp "]" - - char-val = DQUOTE *(%x20-21 / %x23-7E) DQUOTE - ; quoted string of SP and VCHAR - without DQUOTE - - num-val = "%" (bin-val / dec-val / hex-val) - - bin-val = "b" 1*BIT - [ 1*("." 1*BIT) / ("-" 1*BIT) ] - ; series of concatenated bit values - ; or single ONEOF range - - dec-val = "d" 1*DIGIT - [ 1*("." 1*DIGIT) / ("-" 1*DIGIT) ] - - hex-val = "x" 1*HEXDIG - [ 1*("." 1*HEXDIG) / ("-" 1*HEXDIG) ] - - prose-val = "<" *(%x20-3D / %x3F-7E) ">" - ; bracketed string of SP and VCHAR - without angles - ; prose description, to be used as - last resort - - -5. SECURITY CONSIDERATIONS - - Security is truly believed to be irrelevant to this document. - - - - - - - - - - - -Crocker & Overell Standards Track [Page 10] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -6. APPENDIX A - CORE - - This Appendix is provided as a convenient core for specific grammars. - The definitions may be used as a core set of rules. - -6.1 Core Rules - - Certain basic rules are in uppercase, such as SP, HTAB, CRLF, - DIGIT, ALPHA, etc. - - ALPHA = %x41-5A / %x61-7A ; A-Z / a-z - - BIT = "0" / "1" - - CHAR = %x01-7F - ; any 7-bit US-ASCII character, - excluding NUL - - CR = %x0D - ; carriage return - - CRLF = CR LF - ; Internet standard newline - - CTL = %x00-1F / %x7F - ; controls - - DIGIT = %x30-39 - ; 0-9 - - DQUOTE = %x22 - ; " (Double Quote) - - HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F" - - HTAB = %x09 - ; horizontal tab - - LF = %x0A - ; linefeed - - LWSP = *(WSP / CRLF WSP) - ; linear white space (past newline) - - OCTET = %x00-FF - ; 8 bits of data - - SP = %x20 - - - -Crocker & Overell Standards Track [Page 11] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - - ; space - - VCHAR = %x21-7E - ; visible (printing) characters - - WSP = SP / HTAB - ; white space - -6.2 Common Encoding - - Externally, data are represented as "network virtual ASCII", namely - 7-bit US-ASCII in an 8-bit field, with the high (8th) bit set to - zero. A string of values is in "network byte order" with the - higher-valued bytes represented on the left-hand side and being sent - over the network first. - -7. ACKNOWLEDGMENTS - - The syntax for ABNF was originally specified in RFC 733. Ken L. - Harrenstien, of SRI International, was responsible for re-coding the - BNF into an augmented BNF that makes the representation smaller and - easier to understand. - - This recent project began as a simple effort to cull out the portion - of RFC 822 which has been repeatedly cited by non-email specification - writers, namely the description of augmented BNF. Rather than simply - and blindly converting the existing text into a separate document, - the working group chose to give careful consideration to the - deficiencies, as well as benefits, of the existing specification and - related specifications available over the last 15 years and therefore - to pursue enhancement. This turned the project into something rather - more ambitious than first intended. Interestingly the result is not - massively different from that original, although decisions such as - removing the list notation came as a surprise. - - The current round of specification was part of the DRUMS working - group, with significant contributions from Jerome Abela , Harald - Alvestrand, Robert Elz, Roger Fajman, Aviva Garrett, Tom Harsch, Dan - Kohn, Bill McQuillan, Keith Moore, Chris Newman , Pete Resnick and - Henning Schulzrinne. - - - - - - - - - - - -Crocker & Overell Standards Track [Page 12] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -8. REFERENCES - - [US-ASCII] Coded Character Set--7-Bit American Standard Code for - Information Interchange, ANSI X3.4-1986. - - [RFC733] Crocker, D., Vittal, J., Pogran, K., and D. Henderson, - "Standard for the Format of ARPA Network Text Message," RFC 733, - November 1977. - - [RFC822] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", STD 11, RFC 822, August 1982. - -9. CONTACT - - David H. Crocker Paul Overell - - Internet Mail Consortium Demon Internet Ltd - 675 Spruce Dr. Dorking Business Park - Sunnyvale, CA 94086 USA Dorking - Surrey, RH4 1HN - UK - - Phone: +1 408 246 8253 - Fax: +1 408 249 6205 - EMail: dcrocker@imc.org paulo@turnpike.com - - - - - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 13] - -RFC 2234 ABNF for Syntax Specifications November 1997 - - -10. Full Copyright Statement - - Copyright (C) The Internet Society (1997). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Crocker & Overell Standards Track [Page 14] - diff --git a/src/site/resources/rfc2244.txt b/src/site/resources/rfc2244.txt deleted file mode 100644 index 8fcb810..0000000 --- a/src/site/resources/rfc2244.txt +++ /dev/null @@ -1,4034 +0,0 @@ - - - - - -Network Working Group C. Newman -Request for Comments: 2244 Innosoft -Category: Standards Track J. G. Myers - Netscape - November 1997 - - - ACAP -- Application Configuration Access Protocol - - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society 1997. All Rights Reserved. - -Abstract - - The Application Configuration Access Protocol (ACAP) is designed to - support remote storage and access of program option, configuration - and preference information. The data store model is designed to - allow a client relatively simple access to interesting data, to allow - new information to be easily added without server re-configuration, - and to promote the use of both standardized data and custom or - proprietary data. Key features include "inheritance" which can be - used to manage default values for configuration settings and access - control lists which allow interesting personal information to be - shared and group information to be restricted. - - - - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page i] - -RFC 2244 ACAP November 1997 - - - - - - Table of Contents - - - -Status of this Memo ............................................... i -Copyright Notice .................................................. i -Abstract .......................................................... i -ACAP Protocol Specification ....................................... 1 -1. Introduction ............................................. 1 -1.1. Conventions Used in this Document ........................ 1 -1.2. ACAP Data Model .......................................... 1 -1.3. ACAP Design Goals ........................................ 1 -1.4. Validation ............................................... 2 -1.5. Definitions .............................................. 2 -1.6. ACAP Command Overview .................................... 4 -2. Protocol Framework ....................................... 4 -2.1. Link Level ............................................... 4 -2.2. Commands and Responses ................................... 4 -2.2.1. Client Protocol Sender and Server Protocol Receiver ...... 4 -2.2.2. Server Protocol Sender and Client Protocol Receiver ...... 5 -2.3. Server States ............................................ 6 -2.3.1. Non-Authenticated State .................................. 6 -2.3.2. Authenticated State ...................................... 6 -2.3.3. Logout State ............................................. 6 -2.4. Operational Considerations ............................... 7 -2.4.1. Untagged Status Updates .................................. 7 -2.4.2. Response when No Command in Progress ..................... 7 -2.4.3. Auto-logout Timer ........................................ 7 -2.4.4. Multiple Commands in Progress ............................ 8 -2.5. Server Command Continuation Request ...................... 8 -2.6. Data Formats ............................................. 8 -2.6.1. Atom ..................................................... 9 -2.6.2. Number ................................................... 9 -2.6.3. String ................................................... 9 -2.6.3.1. 8-bit and Binary Strings ................................. 10 -2.6.4. Parenthesized List ....................................... 10 -2.6.5. NIL ...................................................... 10 -3. Protocol Elements ........................................ 10 -3.1. Entries and Attributes ................................... 10 -3.1.1. Predefined Attributes .................................... 11 -3.1.2. Attribute Metadata ....................................... 12 -3.2. ACAP URL scheme .......................................... 13 -3.2.1. ACAP URL User Name and Authentication Mechanism .......... 13 -3.2.2. Relative ACAP URLs ....................................... 14 -3.3. Contexts ................................................. 14 - - - -Newman & Myers Standards Track [Page ii] - -RFC 2244 ACAP November 1997 - - -3.4. Comparators .............................................. 15 -3.5. Access Control Lists (ACLs) .............................. 17 -3.6. Server Response Codes .................................... 18 -4. Namespace Conventions .................................... 21 -4.1. Dataset Namespace ........................................ 21 -4.2. Attribute Namespace ...................................... 21 -4.3. Formal Syntax for Dataset and Attribute Namespace ........ 22 -5. Dataset Management ....................................... 23 -5.1. Dataset Inheritance ...................................... 23 -5.2. Dataset Attributes ....................................... 24 -5.3. Dataset Creation ......................................... 25 -5.4. Dataset Class Capabilities ............................... 25 -5.5. Dataset Quotas ........................................... 26 -6. Command and Response Specifications ...................... 26 -6.1. Initial Connection ....................................... 26 -6.1.1. ACAP Untagged Response ................................... 26 -6.2. Any State ................................................ 27 -6.2.1. NOOP Command ............................................. 27 -6.2.2. LANG Command ............................................. 28 -6.2.3. LANG Intermediate Response ............................... 28 -6.2.4. LOGOUT Command ........................................... 29 -6.2.5. OK Response .............................................. 29 -6.2.6. NO Response .............................................. 29 -6.2.7. BAD Response ............................................. 30 -6.2.8. BYE Untagged Response .................................... 30 -6.2.9. ALERT Untagged Response .................................. 31 -6.3. Non-Authenticated State .................................. 31 -6.3.1. AUTHENTICATE Command ..................................... 31 -6.4. Searching ................................................ 33 -6.4.1. SEARCH Command ........................................... 33 -6.4.2. ENTRY Intermediate Response .............................. 37 -6.4.3. MODTIME Intermediate Response ............................ 38 -6.4.4. REFER Intermediate Response .............................. 38 -6.4.5. Search Examples .......................................... 38 -6.5. Contexts ................................................. 39 -6.5.1. FREECONTEXT Command ...................................... 39 -6.5.2. UPDATECONTEXT Command .................................... 40 -6.5.3. ADDTO Untagged Response .................................. 40 -6.5.4. REMOVEFROM Untagged Response ............................. 41 -6.5.5. CHANGE Untagged Response ................................. 41 -6.5.6. MODTIME Untagged Response ................................ 42 -6.6. Dataset modification ..................................... 42 -6.6.1. STORE Command ............................................ 42 -6.6.2. DELETEDSINCE Command ..................................... 45 -6.6.3. DELETED Intermediate Response ............................ 45 -6.7. Access Control List Commands ............................. 45 -6.7.1. SETACL Command ........................................... 46 -6.7.2. DELETEACL Command ........................................ 46 - - - -Newman & Myers Standards Track [Page iii] - -RFC 2244 ACAP November 1997 - - -6.7.3. MYRIGHTS Command ......................................... 47 -6.7.4. MYRIGHTS Intermediate Response ........................... 47 -6.7.5. LISTRIGHTS Command ....................................... 47 -6.7.6. LISTRIGHTS Intermediate Response ......................... 48 -6.8. Quotas ................................................... 48 -6.8.1. GETQUOTA Command ......................................... 48 -6.8.3. QUOTA Untagged Response .................................. 49 -6.9. Extensions ............................................... 49 -7. Registration Procedures .................................. 49 -7.1. ACAP Capabilities ........................................ 50 -7.2. ACAP Response Codes ...................................... 50 -7.3. Dataset Classes .......................................... 51 -7.4. Vendor Subtree ........................................... 51 -8. Formal Syntax ............................................ 52 -9. Multi-lingual Considerations ............................. 61 -10. Security Considerations .................................. 62 -11. Acknowledgments .......................................... 63 -12. Authors' Addresses ....................................... 63 -Appendices ........................................................ 64 -A. References ............................................... 64 -B. ACAP Keyword Index ....................................... 66 -C. Full Copyright Statement - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page iv] - RFC 2244 ACAP November 1997 - - -ACAP Protocol Specification - -1. Introduction - -1.1. Conventions Used in this Document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. If such lines are wrapped without a new "C:" or - "S:" label, then the wrapping is for editorial clarity and is not - part of the command. - - The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", - and "MAY" in this document are to be interpreted as described in "Key - words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. - -1.2. ACAP Data Model - - An ACAP server exports a hierarchical tree of entries. Each level of - the tree is called a dataset, and each dataset is made up of a list - of entries. Each entry has a unique name and may contain any number - of named attributes. Each attribute within an entry may be single - valued or multi-valued and may have associated metadata to assist - access and interpretation of the value. - - The rules with which a client interprets the data within a portion of - ACAP's tree of entries are called a dataset class. - -1.3. ACAP Design Goals - - ACAP's primary purpose is to allow users access to their - configuration data from multiple network-connected computers. Users - can then sit down in front of any network-connected computer, run any - ACAP-enabled application and have access to their own configuration - data. Because it is hoped that many applications will become ACAP- - enabled, client simplicity was preferred to server or protocol - simplicity whenever reasonable. - - ACAP is designed to be easily manageable. For this reason, it - includes "inheritance" which allows one dataset to inherit default - attributes from another dataset. In addition, access control lists - are included to permit delegation of management and quotas are - included to control storage. Finally, an ACAP server which is - conformant to this base specification should be able to support most - dataset classes defined in the future without requiring a server - reconfiguration or upgrade. - - - - - - -Newman & Myers Standards Track [Page 1] - -RFC 2244 ACAP November 1997 - - - ACAP is designed to operate well with a client that only has - intermittent access to an ACAP server. For this reason, each entry - has a server maintained modification time so that the client may - detect changes. In addition, the client may ask the server for a - list of entries which have been removed since it last accessed the - server. - - ACAP presumes that a dataset may be potentially large and/or the - client's network connection may be slow, and thus offers server - sorting, selective fetching and change notification for entries - within a dataset. - - As required for most Internet protocols, security, scalability and - internationalization were important design goals. - - Given these design goals, an attempt was made to keep ACAP as simple - as possible. It is a traditional Internet text based protocol which - massively simplifies protocol debugging. It was designed based on - the successful IMAP [IMAP4] protocol framework, with a few - refinements. - -1.4. Validation - - By default, any value may be stored in any attribute for which the - user has appropriate permission and quota. This rule is necessary to - allow the addition of new simple dataset classes without - reconfiguring or upgrading the server. - - In some cases, such as when the value has special meaning to the - server, it is useful to have the server enforce validation by - returning the INVALID response code to a STORE command. These cases - MUST be explicitly identified in the dataset class specification - which SHOULD include specific fixed rules for validation. Since a - given ACAP server may be unaware of any particular dataset class - specification, clients MUST NOT depend on the presence of enforced - validation on the server. - -1.5. Definitions - - - access control list (ACL) - A set of identifier, rights pairs associated with an object. An - ACL is used to determine which operations a user is permitted to - perform on that object. See section 3.5. - - attribute - A named value within an entry. See section 3.1. - - - - -Newman & Myers Standards Track [Page 2] - -RFC 2244 ACAP November 1997 - - - comparator - A named function which can be used to perform one or more of - three comparison operations: ordering, equality and substring - matching. See section 3.4. - - context - An ordered subset of entries in a dataset, created by a SEARCH - command with a MAKECONTEXT modifier. See section 3.3. - - dataset - One level of hierarchy in ACAP's tree of entries. - - dataset class specification - The rules which allow a client to interpret the data within a - portion of ACAP's tree of entries. - - entry - A set of attributes with a unique entry name. See section 3.1. - - metadata - Information describing an attribute, its value and any access - controls associated with that attribute. See section 3.1.2. - - NIL This represents the non-existence of a particular data item. - - NUL A control character encoded as 0 in US-ASCII [US-ASCII]. - - octet - An 8-bit value. On most modern computer systems, an octet is - one byte. - - SASL Simple Authentication and Security Layer [SASL]. - - UTC Universal Coordinated Time as maintained by the Bureau - International des Poids et Mesures (BIPM). - - UTF-8 - An 8-bit transformation format of the Universal Character Set - [UTF8]. Note that an incompatible change was made to the coded - character set referenced by [UTF8], so for the purpose of this - document, UTF-8 refers to the UTF-8 encoding as defined by - version 2.0 of Unicode [UNICODE-2], or ISO 10646 [ISO-10646] - including amendments one through seven. - - - - - - - - -Newman & Myers Standards Track [Page 3] - -RFC 2244 ACAP November 1997 - - -1.6. ACAP Command Overview - - The AUTHENTICATE, NOOP, LANG and LOGOUT commands provide basic - protocol services. The SEARCH command is used to select, sort, fetch - and monitor changes to attribute values and metadata. The - UPDATECONTEXT and FREECONTEXT commands are also used to assist in - monitoring changes in attribute values and metadata. The STORE - command is used to add, modify and delete entries and attributes. - The DELETEDSINCE command is used to assist a client in - re-synchronizing a cache with the server. The GETQUOTA, SETACL, - DELETEACL, LISTRIGHTS and MYRIGHTS commands are used to examine - storage quotas and examine or modify access permissions. - -2. Protocol Framework - -2.1. Link Level - - The ACAP protocol assumes a reliable data stream such as provided by - TCP. When TCP is used, an ACAP server listens on port 674. - -2.2. Commands and Responses - - An ACAP session consists of the establishment of a client/server - connection, an initial greeting from the server, and client/server - interactions. These client/server interactions consist of a client - command, server data, and a server completion result. - - ACAP is a text-based line-oriented protocol. In general, - interactions transmitted by clients and servers are in the form of - lines; that is, sequences of characters that end with a CRLF. The - protocol receiver of an ACAP client or server is either reading a - line, or is reading a sequence of octets with a known count (a - literal) followed by a line. Both clients and servers must be - capable of handling lines of arbitrary length. - -2.2.1. Client Protocol Sender and Server Protocol Receiver - - The client command begins an operation. Each client command is - prefixed with a identifier (an alphanumeric string of no more than 32 - characters, e.g., A0001, A0002, etc.) called a "tag". A different - tag SHOULD be generated by the client for each command. - - There are two cases in which a line from the client does not - represent a complete command. In one case, a command argument is - quoted with an octet count (see the description of literal in section - 2.6.3); in the other case, the command arguments require server - - - - - -Newman & Myers Standards Track [Page 4] - -RFC 2244 ACAP November 1997 - - - feedback (see the AUTHENTICATE command). In some of these cases, the - server sends a command continuation request if it is ready for the - next part of the command. This response is prefixed with the token - "+". - - Note: If, instead, the server detected an error in a - command, it sends a BAD completion response with tag - matching the command (as described below) to reject the - command and prevent the client from sending any more of the - command. - - It is also possible for the server to send a completion or - intermediate response for some other command (if multiple - commands are in progress), or untagged data. In either - case, the command continuation request is still pending; - the client takes the appropriate action for the response, - and reads another response from the server. - - The ACAP server reads a command line from the client, parses the - command and its arguments, and transmits server data and a server - command completion result. - -2.2.2. Server Protocol Sender and Client Protocol Receiver - - Data transmitted by the server to the client come in four forms: - command continuation requests, command completion results, - intermediate responses, and untagged responses. - - A command continuation request is prefixed with the token "+". - - A command completion result indicates the success or failure of the - operation. It is tagged with the same tag as the client command - which began the operation. Thus, if more than one command is in - progress, the tag in a server completion response identifies the - command to which the response applies. There are three possible - server completion responses: OK (indicating success), NO (indicating - failure), or BAD (indicating protocol error such as unrecognized - command or command syntax error). - - An intermediate response returns data which can only be interpreted - within the context of a command in progress. It is tagged with the - same tag as the client command which began the operation. Thus, if - more than one command is in progress, the tag in an intermediate - response identifies the command to which the response applies. A - tagged response other than "OK", "NO", or "BAD" is an intermediate - response. - - - - - -Newman & Myers Standards Track [Page 5] - -RFC 2244 ACAP November 1997 - - - An untagged response returns data or status messages which may be - interpreted outside the context of a command in progress. It is - prefixed with the token "*". Untagged data may be sent as a result - of a client command, or may be sent unilaterally by the server. - There is no syntactic difference between untagged data that resulted - from a specific command and untagged data that were sent - unilaterally. - - The protocol receiver of an ACAP client reads a response line from - the server. It then takes action on the response based upon the - first token of the response, which may be a tag, a "*", or a "+" as - described above. - - A client MUST be prepared to accept any server response at all times. - This includes untagged data that it may not have requested. - - This topic is discussed in greater detail in the Server Responses - section. - -2.3. Server States - - An ACAP server is in one of three states. Most commands are valid in - only certain states. It is a protocol error for the client to - attempt a command while the server is in an inappropriate state for - that command. In this case, a server will respond with a BAD command - completion result. - -2.3.1. Non-Authenticated State - - In non-authenticated state, the user must supply authentication - credentials before most commands will be permitted. This state is - entered when a connection starts. - -2.3.2. Authenticated State - - In authenticated state, the user is authenticated and most commands - will be permitted. This state is entered when acceptable - authentication credentials have been provided. - -2.3.3. Logout State - - In logout state, the session is being terminated, and the server will - close the connection. This state can be entered as a result of a - client request or by unilateral server decision. - - - - - - - -Newman & Myers Standards Track [Page 6] - -RFC 2244 ACAP November 1997 - - - +--------------------------------------+ - |initial connection and server greeting| - +--------------------------------------+ - || (1) || (2) - VV || - +-----------------+ || - |non-authenticated| || - +-----------------+ || - || (4) || (3) || - || VV || - || +----------------+ || - || | authenticated | || - || +----------------+ || - || || (4) || - VV VV VV - +--------------------------------------+ - | logout and close connection | - +--------------------------------------+ - - (1) connection (ACAP greeting) - (2) rejected connection (BYE greeting) - (3) successful AUTHENTICATE command - (4) LOGOUT command, server shutdown, or connection closed - -2.4. Operational Considerations - -2.4.1. Untagged Status Updates - - At any time, a server can send data that the client did not request. - -2.4.2. Response when No Command in Progress - - Server implementations are permitted to send an untagged response - while there is no command in progress. Server implementations that - send such responses MUST deal with flow control considerations. - Specifically, they must either (1) verify that the size of the data - does not exceed the underlying transport's available window size, or - (2) use non-blocking writes. - -2.4.3. Auto-logout Timer - - If a server has an inactivity auto-logout timer, that timer MUST be - of at least 30 minutes duration. The receipt of ANY command from the - client during that interval MUST suffice to reset the auto-logout - timer. - - - - - - -Newman & Myers Standards Track [Page 7] - -RFC 2244 ACAP November 1997 - - -2.4.4. Multiple Commands in Progress - - The client is not required to wait for the completion result of a - command before sending another command, subject to flow control - constraints on the underlying data stream. Similarly, a server is - not required to process a command to completion before beginning - processing of the next command, unless an ambiguity would result - because of a command that would affect the results of other commands. - If there is such an ambiguity, the server executes commands to - completion in the order given by the client. - -2.5. Server Command Continuation Request - - The command continuation request is indicated by a "+" token instead - of a tag. This indicates that the server is ready to accept the - continuation of a command from the client. - - This response is used in the AUTHENTICATE command to transmit server - data to the client, and request additional client data. This - response is also used if an argument to any command is a - synchronizing literal (see section 2.6.3). - - The client is not permitted to send the octets of a synchronizing - literal unless the server indicates that it expects it. This permits - the server to process commands and reject errors on a line-by-line - basis, assuming it checks for non-synchronizing literals at the end - of each line. The remainder of the command, including the CRLF that - terminates a command, follows the octets of the literal. If there - are any additional command arguments the literal octets are followed - by a space and those arguments. - - Example: C: A099 FREECONTEXT {10} - S: + "Ready for additional command text" - C: FRED - C: FOOB - S: A099 OK "FREECONTEXT completed" - C: A044 BLURDYBLOOP {102856} - S: A044 BAD "No such command as 'BLURDYBLOOP'" - - -2.6. Data Formats - - ACAP uses textual commands and responses. Data in ACAP can be in one - of five forms: atom, number, string, parenthesized list or NIL. - - - - - - - -Newman & Myers Standards Track [Page 8] - -RFC 2244 ACAP November 1997 - - -2.6.1. Atom - - An atom consists of one to 1024 non-special characters. It must - begin with a letter. Atoms are used for protocol keywords. - -2.6.2. Number - - A number consists of one or more digit characters, and represents a - numeric value. Numbers are restricted to the range of an unsigned - 32-bit integer: 0 < number < 4,294,967,296. - -2.6.3. String - - A string is in one of two forms: literal and quoted string. The - literal form is the general form of string. The quoted string form - is an alternative that avoids the overhead of processing a literal at - the cost of restrictions of what may be in a quoted string. - - A literal is a sequence of zero or more octets (including CR and LF), - prefix-quoted with an octet count in the form of an open brace ("{"), - the number of octets, close brace ("}"), and CRLF. In the case of - literals transmitted from server to client, the CRLF is immediately - followed by the octet data. - - There are two forms of literals transmitted from client to server. - The form where the open brace ("{") and number of octets is - immediately followed by a close brace ("}") and CRLF is called a - synchronizing literal. When sending a synchronizing literal, the - client must wait to receive a command continuation request before - sending the octet data (and the remainder of the command). The other - form of literal, the non-synchronizing literal, is used to transmit a - string from client to server without waiting for a command - continuation request. The non-synchronizing literal differs from the - synchronizing literal by having a plus ("+") between the number of - octets and the close brace ("}") and by having the octet data - immediately following the CRLF. - - A quoted string is a sequence of zero to 1024 octets excluding NUL, - CR and LF, with double quote (<">) characters at each end. - - The empty string is represented as "" (a quoted string with zero - characters between double quotes), as {0} followed by CRLF (a - synchronizing literal with an octet count of 0), or as {0+} followed - by a CRLF (a non-synchronizing literal with an octet count of 0). - - Note: Even if the octet count is 0, a client transmitting a - synchronizing literal must wait to receive a command - continuation request. - - - -Newman & Myers Standards Track [Page 9] - -RFC 2244 ACAP November 1997 - - -2.6.3.1. 8-bit and Binary Strings - - Most strings in ACAP are restricted to UTF-8 characters and may not - contain NUL octets. Attribute values MAY contain any octets - including NUL. - -2.6.4. Parenthesized List - - Data structures are represented as a "parenthesized list"; a sequence - of data items, delimited by space, and bounded at each end by - parentheses. A parenthesized list can contain other parenthesized - lists, using multiple levels of parentheses to indicate nesting. - - The empty list is represented as () -- a parenthesized list with no - members. - -2.6.5. NIL - - The special atom "NIL" represents the non-existence of a particular - data item that is represented as a string or parenthesized list, as - distinct from the empty string "" or the empty parenthesized list (). - -3. Protocol Elements - - This section defines data formats and other protocol elements used - throughout the ACAP protocol. - -3.1. Entries and Attributes - - Within a dataset, each entry name is made up of zero or more UTF-8 - characters other than slash ("/"). A slash separated list of - entries, one at each level of the hierarchy, forms the full path to - an entry. - - Each entry is made up of a set of attributes. Each attribute has a - hierarchical name in UTF-8, with each component of the name separated - by a period ("."). - - The value of an attribute is either single or multi-valued. A single - value is NIL (has no value), or a string of zero or more octets. A - multi-value is a list of zero or more strings, each of zero or more - octets. - - Attribute names are not permitted to contain asterisk ("*") or - percent ("%") and MUST be valid UTF-8 strings which do not contain - NUL. Invalid attribute names result in a BAD response. Entry names - - - - - -Newman & Myers Standards Track [Page 10] - -RFC 2244 ACAP November 1997 - - - are not permitted to begin with "." or contain slash ("/") and MUST - be valid UTF-8 strings which do not contain NUL. Invalid entry names - in the entry field of a command result in a BAD response. - - Use of non-visible UTF-8 characters in attribute and entry names is - discouraged. - -3.1.1. Predefined Attributes - - Attribute names which do not contain a dot (".") are reserved for - standardized attributes which have meaning in any dataset. The - following attributes are defined by the ACAP protocol. - - entry - Contains the name of the entry. MUST be single valued. - Attempts to use illegal or multi-valued values for the entry - attribute are protocol errors and MUST result in a BAD - completion response. This is a special case. - - modtime - Contains the date and time any read-write metadata in the entry - was last modified. This value MUST be in UTC, MUST be - automatically updated by the server. - - The value consists of 14 or more US-ASCII digits. The first - four indicate the year, the next two indicate the month, the - next two indicate the day of month, the next two indicate the - hour (0 - 23), the next two indicate the minute, and the next - two indicate the second. Any further digits indicate fractions - of a second. - - The time, particularly fractions of a second, need not be - accurate. It is REQUIRED, however, that any two entries in a - dataset changed by successive modifications have strictly - ascending modtime values. In addition, each STORE command - within a dataset (including simultaneous stores from different - connections) MUST use different modtime values. - - This attribute has enforced validation, so any attempt to STORE - a value in this attribute MAY result in a NO response with an - INVALID response code. - - subdataset - If this attribute is set, it indicates the existence of a sub- - dataset of this entry. - - - - - - -Newman & Myers Standards Track [Page 11] - -RFC 2244 ACAP November 1997 - - - The value consists of a list of relative ACAP URLs (see section - 3.2) which may be used to locate the sub-dataset. The base URL - is the full path to the entry followed by a slash ("/"). The - value "." indicates a subdataset is located directly under this - one. Multiple values indicate replicated copies of the - subdataset. - - For example, if the dataset "/folder/site/" has an entry - "public-folder" with a subdataset attribute of ".", then there - exists a dataset "/folder/site/public-folder/". If the value of - the subdataset attribute was instead - "//other.acap.domain//folder/site/public-folder/", that would - indicate the dataset is actually located on a different ACAP - server. - - A dataset can be created by storing a "subdataset" attribute - including ".", and a sub-hierarchy of datasets is deleted by - storing a NIL value to the "subdataset" attribute on the entry - in the parent dataset. - - This attribute has enforced syntax validation. Specifically, if - an attempt is made to STORE a non-list value (other than NIL), - an empty list, or one of the values does not follow the URL - syntax rules [BASIC-URL, REL-URL], then this will result in a NO - response with an INVALID response code. - -3.1.2. Attribute Metadata - - Each attribute is made up of metadata items which describe that - attribute, its value and any associated access controls. Metadata - items may be either read-only, in which case the client is never - permitted to modify the item, or read-write, in which case the client - may modify the item if the access control list (ACL) permits. - - The following metadata items are defined in this specification: - - acl The access control list for the attribute, if one exists. If - the attribute does not have an ACL, NIL is returned. - Read-write. See section 3.5 for the contents of an ACL. - - attribute - The attribute name. Read-only. - - myrights - The set of rights that the client has to the attribute. - Read-only. See section 3.5 for the possible rights. - - - - - -Newman & Myers Standards Track [Page 12] - -RFC 2244 ACAP November 1997 - - - size This is the length of the value. In the case of a - multi-value, this is a list of lengths for each of the values. - Read-only. - - value The value. For a multi-value, this is a list of single - values. Read-write. - - Additional items of metadata may be defined in extensions to this - protocol. Servers MUST respond to unrecognized metadata by returning - a BAD command completion result. - -3.2. ACAP URL scheme - - ACAP URLs are used within the ACAP protocol for the "subdataset" - attribute, referrals and inheritance. They provide a convenient - syntax for referring to other ACAP datasets. The ACAP URL follows - the common Internet scheme syntax as defined in [BASIC-URL] except - that plaintext passwords are not permitted. If : is omitted, - the port defaults to 674. - - An ACAP URL has the following general form: - - url-acap = "acap://" url-server "/" url-enc-entry [url-filter] - [url-extension] - - The element includes the hostname, and optional user - name, authentication mechanism and port number. The - element contains the name of an entry path encoded according to the - rules in [BASIC-URL]. - - The element is an optional list of interesting attribute - names. If omitted, the URL refers to all attributes of the named - entry. The element is reserved for extensions to - this URL scheme. - - Note that unsafe or reserved characters such as " " or "?" MUST be - hex encoded as described in the URL specification [BASIC-URL]. Hex - encoded octets are interpreted according to UTF-8 [UTF8]. - -3.2.1. ACAP URL User Name and Authentication Mechanism - - A user name and/or authentication mechanism may be supplied. They - are used in the "AUTHENTICATE" command after making the connection to - the ACAP server. If no user name or authentication mechanism is - supplied, then the SASL ANONYMOUS [SASL-ANON] mechanism is used by - default. If an authentication mechanism is supplied without a user - - - - - -Newman & Myers Standards Track [Page 13] - -RFC 2244 ACAP November 1997 - - - name, then one SHOULD be obtained from the specified mechanism or - requested from the user as appropriate. If a user name is supplied - without an authentication mechanism then ";AUTH=*" is assumed. - - The ";AUTH=" authentication parameter is interpreted as described in - the IMAP URL Scheme [IMAP-URL]. - - Note that if unsafe or reserved characters such as " " or ";" are - present in the user name or authentication mechanism, they MUST be - encoded as described in the URL specification [BASIC-URL]. - -3.2.2. Relative ACAP URLs - - Because ACAP uses "/" as the hierarchy separator for dataset paths, - it works well with the relative URL rules defined in the relative URL - specification [REL-URL]. - - The grammar element is considered part of the user name for - purposes of resolving relative ACAP URLs. - - The base URL for a relative URL stored in an attribute's value is - formed by taking the path to the dataset containing that attribute, - appending a "/" followed by the entry name of the entry containing - that attribute followed by "/". - -3.3. Contexts - - A context is subset of entries in a dataset or datasets, created by a - SEARCH command with a MAKECONTEXT modifier. Context names are - client-generated strings and must not start with the slash ('/') - character. - - When a client creates a context, it may request automatic - notification of changes. A client may also request enumeration of - entries within a context. Enumeration simplifies the implementation - of a "virtual scrollbar" by the client. - - A context exists only within the ACAP session in which it was - created. When the connection is closed, all contexts associated with - that connection are automatically discarded. A server is required to - support at least 100 active contexts within a session. If the server - supports a larger limit it must advertise it in a CONTEXTLIMIT - capability. - - - - - - - - -Newman & Myers Standards Track [Page 14] - -RFC 2244 ACAP November 1997 - - -3.4. Comparators - - A comparator is a named function which takes two input values and can - be used to perform one or more of four comparison operations: - ordering, equality, prefix and substring matching. - - The ordering operation is used both for the SORT search modifier and - the COMPARE and COMPARESTRICT search keys. Ordering comparators can - determine the ordinal precedence of any two values. When used for - ordering, a comparator's name can be prefixed with "+" or "-" to - indicate that the ordering should be normal order or reversed order - respectively. If no prefix is included, "+" is assumed. - - For the purpose of ordering, a comparator may designate certain - values as having an undefined ordinal precedence. Such values always - collate with equal value after all other values regardless of whether - normal or reversed ordering is used. Unless the comparator - definition specifies otherwise, multi-values and NIL values have an - undefined ordinal precedence. - - The equality operation is used for the EQUAL search modifier, and - simply determines if the two values are considered equal under the - comparator function. When comparing a single value to a multi-value, - the two are considered equal if any one of the multiple values is - equal to the single value. - - The prefix match operation is used for the PREFIX search modifier, - and simply determines if the search value is a prefix of the item - being searched. In the case of prefix search on a multi-value, the - match is successful if the value is a prefix of any one of the - multiple values. - - The substring match operation is used for the SUBSTRING search - modifier, and simply determines if search value is a substring of the - item being searched. In the case of substring search on a multi- - value, the match is successful if the value is a substring of any one - of the multiple values. - - Rules for naming and registering comparators will be defined in a - future specification. Servers MUST respond to unknown or improperly - used comparators with a BAD command completion result. - - - - - - - - - - -Newman & Myers Standards Track [Page 15] - -RFC 2244 ACAP November 1997 - - - The following comparators are defined by this standard and MUST be - implemented: - - i;octet - Operations: Ordering, Equality, Prefix match, Substring match - - For collation, the i;octet comparator interprets the value of - an attribute as a series of unsigned octets with ordinal - values from 0 to 255. When ordering two strings, each octet - pair is compared in sequence until the octets are unequal or - the end of the string is reached. When collating two strings - where the shorter is a prefix of the longer, the shorter - string is interpreted as having a smaller ordinal value. The - "i;octet" or "+i;octet" forms collate smaller ordinal values - earlier, and the "-i;octet" form collates larger ordinal - values earlier. - - For the equality function, two strings are equal if they are - the same length and contain the same octets in the same - order. NIL is equal only to itself. - - For non-binary, non-nil single values, i;octet ordering is - equivalent to the ANSI C [ISO-C] strcmp() function applied to - C string representations of the values. For non-binary, - non-nil single values, i;octet substring match is equivalent - to the ANSI C strstr() function applied to the C string - representations of the values. - - i;ascii-casemap - Operations: Ordering, Equality, Prefix match, Substring match - - The i;ascii-casemap comparator first applies a mapping to the - attribute values which translates all US-ASCII letters to - uppercase (octet values 0x61 to 0x7A are translated to octet - values 0x41 to 0x5A respectively), then applies the i;octet - comparator as described above. With this function the values - "hello" and "HELLO" have the same ordinal value and are - considered equal. - - i;ascii-numeric - Operations: Ordering, Equality - - The i;ascii-numeric comparator interprets strings as decimal - positive integers represented as US-ASCII digits. All values - which do not begin with a US-ASCII digit are considered equal - with an ordinal value higher than all non-NIL single-valued - - - - - -Newman & Myers Standards Track [Page 16] - -RFC 2244 ACAP November 1997 - - - attributes. Otherwise, all US-ASCII digits (octet values - 0x30 to 0x39) are interpreted starting from the beginning of - the string to the first non-digit or the end of the string. - - -3.5. Access Control Lists (ACLs) - - An access control list is a set of identifier, rights pairs used to - restrict access to a given dataset, attribute or attribute within an - entry. An ACL is represented by a multi-value with each value - containing an identifier followed by a tab character followed by the - rights. The syntax is defined by the "acl" rule in the formal syntax - in section 8. - - Identifier is a UTF-8 string. The identifier "anyone" is reserved to - refer to the universal identity (all authentications, including - anonymous). All user name strings accepted by the AUTHENTICATE - command to authenticate to the ACAP server are reserved as - identifiers for the corresponding user. Identifiers starting with a - slash ("/") character are reserved for authorization groups which - will be defined in a future specification. Identifiers MAY be - prefixed with a dash ("-") to indicate a revocation of rights. All - other identifiers have implementation-defined meanings. - - Rights is a string listing a (possibly empty) set of alphanumeric - characters, each character listing a set of operations which is being - controlled. Letters are reserved for "standard" rights, listed - below. The set of standard rights may only be extended by a - standards-track or IESG approved experimental RFC. Digits are - reserved for implementation or site defined rights. The currently - defined standard rights are: - - x - search (use EQUAL search key with i;octet comparator) - r - read (access with SEARCH command) - w - write (modify with STORE command) - i - insert (perform STORE on a previously NIL value) - a - administer (perform SETACL or STORE on ACL attribute/metadata) - - An implementation may force rights to always or never be granted. In - particular, implementations are expected to grant implicit read and - administer rights to a user's personal dataset storage in order to - avoid denial of service problems. Rights are never tied, unlike the - IMAP ACL extension [IMAP-ACL]. - - It is possible for multiple identifiers in an access control list to - apply to a given user (or other authentication identity). For - example, an ACL may include rights to be granted to the identifier - matching the user, one or more implementation-defined identifiers - - - -Newman & Myers Standards Track [Page 17] - -RFC 2244 ACAP November 1997 - - - matching groups which include the user, and/or the identifier - "anyone". These rights are combined by taking the union of all - positive rights which apply to a given user and subtracting the union - of all negative rights which apply to that user. A client MAY avoid - this calculation by using the MYRIGHTS command and metadata items. - - Each attribute of each entry of a dataset may potentially have an - ACL. If an attribute in an entry does not have an ACL, then access - is controlled by a default ACL for that attribute in the dataset, if - it exists. If there is no default ACL for that attribute in the - dataset, access is controlled by a default ACL for that dataset. The - default ACL for a dataset must exist. - - In order to perform any access or manipulation on an entry in a - dataset, the client must have 'r' rights on the "entry" attribute of - the entry. Implementations should take care not to reveal via error - messages the existence of an entry for which the client does not have - 'r' rights. A client does not need access to the "subdataset" - attribute of the parent dataset in order to access the contents of a - dataset. - - Many of the ACL commands and responses include an "acl object" - parameter, for specifying what the ACL applies to. This is a - parenthesized list. The list contains just the dataset name when - referring to the default ACL for a dataset. The list contains a - dataset name and an attribute name when referring to the default ACL - for an attribute in a dataset. The list contains a dataset name, an - attribute name, and an entry name when referring to the ACL for an - attribute of an entry of a dataset. - - -3.6. Server Response Codes - - An OK, NO, BAD, ALERT or BYE response from the server MAY contain a - response code to describe the event in a more detailed machine - parsable fashion. A response code consists of data inside - parentheses in the form of an atom, possibly followed by a space and - arguments. Response codes are defined when there is a specific - action that a client can take based upon the additional information. - In order to support future extension, the response code is - represented as a slash-separated hierarchy with each level of - hierarchy representing increasing detail about the error. Clients - MUST tolerate additional hierarchical response code detail which they - don't understand. - - The currently defined response codes are: - - - - - -Newman & Myers Standards Track [Page 18] - -RFC 2244 ACAP November 1997 - - - AUTH-TOO-WEAK - This response code is returned on a tagged NO result from an - AUTHENTICATE command. It indicates that site security policy - forbids the use of the requested mechanism for the specified - authentication identity. - - ENCRYPT-NEEDED - This response code is returned on a tagged NO result from an - AUTHENTICATE command. It indicates that site security policy - requires the use of a strong encryption mechanism for the - specified authentication identity and mechanism. - - INVALID - This response code indicates that a STORE command included - data which the server implementation does not permit. It - MUST NOT be used unless the dataset class specification for - the attribute in question explicitly permits enforced server - validation. The argument is the attribute which was invalid. - - MODIFIED - This response code indicates that a conditional store failed - because the modtime on the entry is later than the modtime - specified with the STORE command UNCHANGEDSINCE modifier. - The argument is the entry which had been modified. - - NOEXIST - This response code indicates that a search or NOCREATE store - failed because a specified dataset did not exist. The - argument is the dataset which does not exist. - - PERMISSION - A command failed due to insufficient permission based on the - access control list or implicit rights. The argument is the - acl-object which caused the permission failure. - - QUOTA - A STORE or SETACL command which would have increased the size - of the dataset failed due to insufficient quota. - - REFER - This response code may be returned in a tagged NO response to - any command that takes a dataset name as a parameter. It has - one or more arguments with the syntax of relative URLs. It - is a referral, indicating that the command should be retried - using one of the relative URLs. - - - - - - -Newman & Myers Standards Track [Page 19] - -RFC 2244 ACAP November 1997 - - - SASL This response code can occur in the tagged OK response to a - successful AUTHENTICATE command and includes the optional - final server response data from the server as specified by - SASL [SASL]. - - TOOMANY - This response code may be returned in a tagged OK response to - a SEARCH command which includes the LIMIT modifier. The - argument returns the total number of matching entries. - - TOOOLD - The modtime specified in the DELETEDSINCE command is too old, - so deletedsince information is no longer available. - - TRANSITION-NEEDED - This response code occurs on a NO response to an AUTHENTICATE - command. It indicates that the user name is valid, but the - entry in the authentication database needs to be updated in - order to permit authentication with the specified mechanism. - This can happen if a user has an entry in a system - authentication database such as Unix /etc/passwd, but does - not have credentials suitable for use by the specified - mechanism. - - TRYLATER - A command failed due to a temporary server failure. The - client MAY continue using local information and try the - command later. - - TRYFREECONTEXT - This response code may be returned in a tagged NO response to - a SEARCH command which includes the MAKECONTEXT modifier. It - indicates that a new context may not be created due to the - server's limit on the number of existing contexts. - - WAYTOOMANY - This response code may be returned in a tagged NO response to - a SEARCH command which includes a HARDLIMIT search modifier. - It indicates that the SEARCH would have returned more entries - than the HARDLIMIT permitted. - - Additional response codes MUST be registered with IANA according - to the proceedures in section 7.2. Client implementations MUST - tolerate response codes that they do not recognize. - - - - - - - -Newman & Myers Standards Track [Page 20] - -RFC 2244 ACAP November 1997 - - -4. Namespace Conventions - -4.1. Dataset Namespace - - The dataset namespace is a slash-separated hierarchy. The first - component of the dataset namespace is a dataset class. Dataset - classes MUST have a vendor prefix (vendor.) or be - specified in a standards track or IESG approved experimental RFC. - See section 7.3 for the registration template. - - The second component of the dataset name is "site", "group", "host", - or "user" referring to server-wide data, administrative group data, - per-host data and per-user data respectively. - - For "group", "host", and "user" areas, the third component of the - path is the group name, the fully qualified host domain name, or the - user name. A path of the form "//~/" is a convenient - abbreviation for "//user//". - - Dataset names which begin with "/byowner/" are reserved as an - alternate view of the namespace. This provides a way to see all the - dataset classes which a particular owner uses. For example, - "/byowner/~//" is an alternate name for - "//~/". Byowner provides a way to view a list of - dataset classes owned by a given user; this is done using the dataset - "/byowner/user//" with the NOINHERIT SEARCH modifier. - - The dataset "/" may be used to find all dataset classes visible to - the current user. A dataset of the form "//user/" may - be used to find all users which have made a dataset or entry of that - class visible to the current user. - - The formal syntax for a dataset name is defined by the "dataset-name" - rule in section 4.3. - -4.2. Attribute Namespace - - Attribute names which do not contain a dot (".") are reserved for - standardized attributes which have meaning in any dataset. In order - to simplify client implementations, the attribute namespace is - intended to be unique across all datasets. To achieve this, - attribute names are prefixed with the dataset class name followed by - a dot ("."). Attributes which affect management of the dataset are - prefixed with "dataset.". In addition, a subtree of the "vendor." - attribute namespace may be registered with IANA according to the - rules in section 7.4. ACAP implementors are encouraged to help - define interoperable dataset classes specifications rather than using - the private attribute namespace. - - - -Newman & Myers Standards Track [Page 21] - -RFC 2244 ACAP November 1997 - - - Some users or sites may wish to add their own private attributes to - certain dataset classes. In order to enable this, the "user.." and "site." subtrees of the attribute namespace are reserved - for user-specific and site-specific attributes respectively and will - not be standardized. Such attributes are not interoperable so are - discouraged in favor of defining standard attributes. A future - extension is expected to permit discovery of syntax for user or - site-specific attributes. Clients wishing to support display of user - or site-specific attributes should display the value of any non-NIL - single-valued "user.." or "site." attribute which has - valid UTF-8 syntax. - - The formal syntax for an attribute name is defined by the - "attribute-name" rule in the next section. - -4.3. Formal Syntax for Dataset and Attribute Namespace - - The naming conventions for datasets and attributes are defined by the - following ABNF. Note that this grammar is not part of the ACAP - protocol syntax in section 8, as dataset names and attribute names - are encoded as strings within the ACAP protocol. - - attribute-dacl = "dataset.acl" *("." name-component) - - attribute-dset = dataset-std 1*("." name-component) - ;; MUST be defined in a dataset class specification - - attribute-name = attribute-std / attr-site / attr-user / vendor-name - - attribute-std = "entry" / "subdataset" / "modtime" / - "dataset.inherit" / attribute-dacl / attribute-dset - - attr-site = "site" 1*("." name-component) - - attr-user = "user." name-component 1*("." name-component) - - byowner = "/byowner/" owner "/" - [dataset-class "/" dataset-sub] - - dataset-class = dataset-std / vendor-name - - dataset-normal = "/" [dataset-class "/" - (owner-prefix / dataset-tail)] - - dataset-name = byowner / dataset-normal - - - - - - -Newman & Myers Standards Track [Page 22] - -RFC 2244 ACAP November 1997 - - - dataset-std = name-component - ;; MUST be registered with IANA and the spec MUST - ;; be published as a standards track or - ;; IESG-approved experimental RFC - - dataset-sub = *(dname-component "/") - ;; The rules for this portion of the namespace may - ;; be further restricted by the dataset class - ;; specification. - - dataset-tail = owner "/" dataset-sub - - dname-component = 1*UTF8-CHAR - ;; MUST NOT begin with "." or contain "/" - - name-component = 1*UTF8-CHAR - ;; MUST NOT contain ".", "/", "%", or "*" - - owner = "site" / owner-host / owner-group / - owner-user / "~" - - owner-group = "group/" dname-component - - owner-host = "host/" dname-component - - owner-prefix = "group/" / "host/" / "user/" - - owner-user = "user/" dname-component - - vendor-name = vendor-token *("." name-component) - - vendor-token = "vendor." name-component - ;; MUST be registered with IANA - -5. Dataset Management - - The entry with an empty name ("") in the dataset is used to hold - management information for the dataset as a whole. - -5.1. Dataset Inheritance - - It is possible for one dataset to inherit data from another. The - dataset from which the data is inherited is called the base dataset. - Data in the base dataset appears in the inheriting dataset, except - when overridden by a STORE to the inheriting dataset. - - - - - - -Newman & Myers Standards Track [Page 23] - -RFC 2244 ACAP November 1997 - - - The base dataset is usually a system-wide or group-wide set of - defaults. A system-wide dataset usually has one inheriting dataset - per user, allowing each user to add to or modify the defaults as - appropriate. - - An entry which exists in both the inheriting and base dataset - inherits a modtime equal to the greater of the two modtimes. An - attribute in such an entry is inherited from the base dataset if it - was never modified by a STORE command in the inheriting dataset or if - DEFAULT was stored to that attribute. This permits default entries - to be amended rather than replaced in the inheriting dataset. - - The "subdataset" attribute is not directly inherited. If the base - dataset includes a "subdataset" attribute and the inheriting dataset - does not, then the "subdataset" attribute will inherit a virtual - value of a list containing a ".". The subdataset at that node is - said to be a "virtual" dataset as it is simply a virtual copy of the - appropriate base dataset with all "subdataset" attributes changed to - a list containing a ".". A virtual dataset is not visible if - NOINHERIT is specified on the SEARCH command. - - Servers MUST support at least two levels of inheritance. This - permits a user's dataset such as "/options/user/fred/common" to - inherit from a group dataset such as "/options/group/dinosaur - operators/common" which in turn inherits from a server-wide dataset - such as "/options/site/common". - -5.2. Dataset Attributes - - The following attributes apply to management of the dataset when - stored in the "" entry of a dataset. These attributes are not - inherited. - - dataset.acl - This holds the default access control list for the dataset. - This attribute is validated, so an invalid access control list - in a STORE command will result in a NO response with an INVALID - response code. - - dataset.acl. - This holds the default access control list for an attribute - within the dataset. This attribute is validated, so an invalid - access control list in a STORE command will result in a NO - response with an INVALID response code. - - dataset.inherit - This holds the name of a dataset from which to inherit according - to the rules in the previous section. This attribute MAY refer - - - -Newman & Myers Standards Track [Page 24] - -RFC 2244 ACAP November 1997 - - - to a non-existent dataset, in which case nothing is inherited. - This attribute is validated, so illegal dataset syntax or an - attempt to store a multi-value will result in a NO response with - an INVALID response code. - -5.3. Dataset Creation - - When a dataset is first created (by storing a "." in the subdataset - attribute or storing an entry in a previously non-existent dataset), - the dataset attributes are initialized with the values from the - parent dataset in the "/byowner/" hierarchy. In the case of the - "dataset.inherit" attribute, the appropriate hierarchy component is - added. For example, given the following entry (note that \t refers - to the US-ASCII horizontal tab character): - - entry path "/byowner/user/joe/" - dataset.acl ("joe\txrwia" "fred\txr") - dataset.inherit "/byowner/site" - - If a new dataset class "/byowner/user/joe/new" is created, it will - have the following dataset attributes: - - entry path "/byowner/user/joe/new/" - dataset.acl ("joe\txrwia" "fred\txr") - dataset.inherit "/byowner/site/new" - - Note that the dataset "/byowner/user/joe/new/" is equivalent to - "/new/user/joe/". - -5.4. Dataset Class Capabilities - - Certain dataset classes or dataset class features may only be useful - if there is an active updating client or integrated server support - for the feature. The dataset class "capability" is reserved to allow - clients or servers to advertise such features. The "entry" attribute - within this dataset class is the name of the dataset class whose - features are being described. The attributes are prefixed with - "capability.." and are defined by the appropriate - dataset class specification. - - Since it is possible for an unprivileged user to run an active client - for himself, a per-user capability dataset is useful. The dataset - "/capability/~/" holds information about all features available to - the user (via inheritance), and the dataset "/capability/site/" holds - information about all features supported by the site. - - - - - - -Newman & Myers Standards Track [Page 25] - -RFC 2244 ACAP November 1997 - - -5.5. Dataset Quotas - - Management and scope of quotas is implementation dependent. Clients - can check the applicable quota limit and usage (in bytes) with the - GETQUOTA command. Servers can notify the client of a low quota - situation with the QUOTA untagged response. - -6. Command and Response Specifications - - ACAP commands and responses are described in this section. Commands - are organized first by the state in which the command is permitted, - then by a general category of command type. - - Command arguments, identified by "Arguments:" in the command - descriptions below, are described by function, not by syntax. The - precise syntax of command arguments is described in the Formal Syntax - section. - - Some commands cause specific server data to be returned; these are - identified by "Data:" in the command descriptions below. See the - response descriptions in the Responses section for information on - these responses, and the Formal Syntax section for the precise syntax - of these responses. It is possible for server data to be transmitted - as a result of any command; thus, commands that do not specifically - require server data specify "no specific data for this command" - instead of "none". - - The "Result:" in the command description refers to the possible - tagged status responses to a command, and any special interpretation - of these status responses. - -6.1. Initial Connection - - Upon session startup, the server sends one of two untagged responses: - ACAP or BYE. The untagged BYE response is described in section - 6.2.8. - -6.1.1. ACAP Untagged Response - - Data: capability list - - The untagged ACAP response indicates the session is ready to - accept commands and contains a space-separated listing of - capabilities that the server supports. Each capability is - represented by a list containing the capability name optionally - followed by capability specific string arguments. - - - - - -Newman & Myers Standards Track [Page 26] - -RFC 2244 ACAP November 1997 - - - ACAP capability names MUST be registered with IANA according to - the rules in section 7.1. - - Client implementations SHOULD NOT require any capability name - beyond those defined in this specification, and MUST tolerate any - unknown capability names. A client implementation MAY be - configurable to require SASL mechanisms other than CRAM-MD5 - [CRAM-MD5] for site security policy reasons. - - The following initial capabilities are defined: - - CONTEXTLIMIT - The CONTEXTLIMIT capability has one argument which is a - number describing the maximum number of contexts the server - supports per connection. The number 0 indicates the server - has no limit, otherwise this number MUST be greater than - 100. - - IMPLEMENTATION - The IMPLEMENTATION capability has one argument which is a - string describing the server implementation. ACAP clients - MUST NOT alter their behavior based on this value. It is - intended primarily for debugging purposes. - - SASL The SASL capability includes a list of the authentication - mechanisms supported by the server. See section 6.3.1. - - - Example: S: * ACAP (IMPLEMENTATION "ACME v3.5") - (SASL "CRAM-MD5") (CONTEXTLIMIT "200") - -6.2. Any State - - The following commands and responses are valid in any state. - -6.2.1. NOOP Command - - Arguments: none - - Data: no specific data for this command (but see below) - - Result: OK - noop completed - BAD - command unknown or arguments invalid - - The NOOP command always succeeds. It does nothing. It can be - used to reset any inactivity auto-logout timer on the server. - - Example: C: a002 NOOP - - - -Newman & Myers Standards Track [Page 27] - -RFC 2244 ACAP November 1997 - - - S: a002 OK "NOOP completed" - - -6.2.2. LANG Command - - Arguments: list of language preferences - - Data: intermediate response: LANG - - Result: OK - lang completed - NO - no matching language available - BAD - command unknown or arguments invalid - - One or more arguments are supplied to indicate the client's - preferred languages [LANG-TAGS] for error messages. The server - will match each client preference in order against its internal - table of available error string languages. For a client - preference to match a server language, the client's language tag - MUST be a prefix of the server's tag and match up to a "-" or the - end of string. If a match is found, the server returns an - intermediate LANG response and an OK response. The LANG response - indicates the actual language selected and appropriate comparators - for use with the languages listed in the LANG command. - - If no LANG command is issued, all error text strings MUST be in - the registered language "i-default" [CHARSET-LANG-POLICY], - intended for an international audience. - - Example: C: A003 LANG "fr-ca" "fr" "en-ca" "en-uk" - S: A003 LANG "fr-ca" "i;octet" "i;ascii-numeric" - "i;ascii-casemap" "en;primary" "fr;primary" - S: A003 OK "Bonjour" - - -6.2.3. LANG Intermediate Response - - Data: language for error responses - appropriate comparators - - The LANG response indicates the language which will be used for - error responses and the comparators which are appropriate for the - languages listed in the LANG command. The comparators SHOULD be - in approximate order from most efficient (usually "i;octet") to - most appropriate for human text in the preferred language. - - - - - - - -Newman & Myers Standards Track [Page 28] - -RFC 2244 ACAP November 1997 - - -6.2.4. LOGOUT Command - - Arguments: none - - Data: mandatory untagged response: BYE - - Result: OK - logout completed - BAD - command unknown or arguments invalid - - The LOGOUT command informs the server that the client is done with - the session. The server must send a BYE untagged response before - the (tagged) OK response, and then close the network connection. - - Example: C: A023 LOGOUT - S: * BYE "ACAP Server logging out" - S: A023 OK "LOGOUT completed" - (Server and client then close the connection) - - -6.2.5. OK Response - - Data: optional response code - human-readable text - - The OK response indicates an information message from the server. - When tagged, it indicates successful completion of the associated - command. The human-readable text may be presented to the user as - an information message. The untagged form indicates an - information-only message; the nature of the information MAY be - indicated by a response code. - - Example: S: * OK "Master ACAP server is back up" - - -6.2.6. NO Response - - Data: optional response code - human-readable text - - The NO response indicates an operational error message from the - server. When tagged, it indicates unsuccessful completion of the - associated command. The untagged form indicates a warning; the - command may still complete successfully. The human-readable text - describes the condition. - - Example: C: A010 SEARCH "/addressbook/" DEPTH 3 RETURN ("*") - EQUAL "entry" "+i;octet" "bozo" - S: * NO "Master ACAP server is down, your data may - - - -Newman & Myers Standards Track [Page 29] - -RFC 2244 ACAP November 1997 - - - be out of date." - S: A010 OK "search done" - ... - C: A222 STORE ("/folder/site/comp.mail.misc" - "folder.creation-time" "19951206103412") - S: A222 NO (PERMISSION ("/folder/site/")) "Permission - denied" - - -6.2.7. BAD Response - - Data: optional response code - human-readable text - - The BAD response indicates an error message from the server. When - tagged, it reports a protocol-level error in the client's command; - the tag indicates the command that caused the error. The untagged - form indicates a protocol-level error for which the associated - command can not be determined; it may also indicate an internal - server failure. The human-readable text describes the condition. - - Example: C: ...empty line... - S: * BAD "Empty command line" - C: A443 BLURDYBLOOP - S: A443 BAD "Unknown command" - C: A444 NOOP Hello - S: A444 BAD "invalid arguments" - - -6.2.8. BYE Untagged Response - - Data: optional response code - human-readable text - - The untagged BYE response indicates that the server is about to - close the connection. The human-readable text may be displayed to - the user in a status report by the client. The BYE response may - be sent as part of a normal logout sequence, or as a panic - shutdown announcement by the server. It is also used by some - server implementations as an announcement of an inactivity auto- - logout. - - This response is also used as one of two possible greetings at - session startup. It indicates that the server is not willing to - accept a session from this client. - - Example: S: * BYE "Auto-logout; idle for too long" - - - - -Newman & Myers Standards Track [Page 30] - -RFC 2244 ACAP November 1997 - - -6.2.9. ALERT Untagged Response - - Data: optional response code - human-readable text - - The human-readable text contains a special human generated alert - message that MUST be presented to the user in a fashion that calls - the user's attention to the message. This is intended to be used - for vital messages from the server administrator to the user, such - as a warning that the server will soon be shut down for - maintenance. - - Example: S: * ALERT "This ACAP server will be shut down in - 10 minutes for system maintenance." - - -6.3. Non-Authenticated State - - In non-authenticated state, the AUTHENTICATE command establishes - authentication and enters authenticated state. The AUTHENTICATE - command provides a general mechanism for a variety of authentication - techniques. - - Server implementations may allow non-authenticated access to certain - information by supporting the SASL ANONYMOUS [SASL-ANON] mechanism. - - Once authenticated (including as anonymous), it is not possible to - re-enter non-authenticated state. - - Only the any-state commands (NOOP, LANG and LOGOUT) and the - AUTHENTICATE command are valid in non-authenticated state. - - -6.3.1. AUTHENTICATE Command - - Arguments: SASL mechanism name - optional initial response - - Data: continuation data may be requested - - Result: OK - authenticate completed, now in authenticated state - NO - authenticate failure: unsupported authentication - mechanism, credentials rejected - BAD - command unknown or arguments invalid, - authentication exchange cancelled - - - - - - -Newman & Myers Standards Track [Page 31] - -RFC 2244 ACAP November 1997 - - - The AUTHENTICATE command indicates a SASL [SASL] authentication - mechanism to the server. If the server supports the requested - authentication mechanism, it performs an authentication protocol - exchange to authenticate and identify the user. Optionally, it - also negotiates a security layer for subsequent protocol - interactions. If the requested authentication mechanism is not - supported, the server rejects the AUTHENTICATE command by sending - a tagged NO response. - - The authentication protocol exchange consists of a series of - server challenges and client answers that are specific to the - authentication mechanism. A server challenge consists of a - command continuation request with the "+" token followed by a - string. The client answer consists of a line consisting of a - string. If the client wishes to cancel an authentication - exchange, it should issue a line with a single unquoted "*". If - the server receives such an answer, it must reject the - AUTHENTICATE command by sending a tagged BAD response. - - The optional initial-response argument to the AUTHENTICATE command - is used to save a round trip when using authentication mechanisms - that are defined to send no data in the initial challenge. When - the initial-response argument is used with such a mechanism, the - initial empty challenge is not sent to the client and the server - uses the data in the initial-response argument as if it were sent - in response to the empty challenge. If the initial-response - argument to the AUTHENTICATE command is used with a mechanism that - sends data in the initial challenge, the server rejects the - AUTHENTICATE command by sending a tagged NO response. - - The service name specified by this protocol's profile of SASL is - "acap". - - If a security layer is negotiated through the SASL authentication - exchange, it takes effect immediately following the CRLF that - concludes the authentication exchange for the client, and the CRLF - of the tagged OK response for the server. - - All ACAP implementations MUST implement the CRAM-MD5 SASL - mechanism [CRAM-MD5], although they MAY offer a configuration - option to disable it if site security policy dictates. The - example below is the same example described in the CRAM-MD5 - specification. - - If an AUTHENTICATE command fails with a NO response, the client - may try another authentication mechanism by issuing another - AUTHENTICATE command. In other words, the client may request - authentication types in decreasing order of preference. - - - -Newman & Myers Standards Track [Page 32] - -RFC 2244 ACAP November 1997 - - - Example: S: * ACAP (IMPLEMENTATION "Blorfysoft v3.5") - (SASL "CRAM-MD5" "KERBEROS_V4") - C: A001 AUTHENTICATE "CRAM-MD5" - S: + "<1896.697170952@postoffice.reston.mci.net>" - C: "tim b913a602c7eda7a495b4e6e7334d3890" - S: A001 OK "CRAM-MD5 authentication successful" - - -6.4. Searching - - This section describes the SEARCH command, for retrieving data from - datasets. - - -6.4.1. SEARCH Command - - Arguments: dataset or context name - optional list of modifiers - search criteria - - Data: intermediate responses: ENTRY, MODTIME, REFER - untagged responses: ADDTO, REMOVEFROM, CHANGE, MODTIME - - Result: OK - search completed - NO - search failure: can't perform search - BAD - command unknown or arguments invalid - - The SEARCH command identifies a subset of entries in a dataset and - returns information on that subset to the client. Inherited - entries and attributes are included in the search unless the - NOINHERIT search modifier is included or the user does not have - permission to read the attributes in the base dataset. - - The first argument to SEARCH identifies what is to be searched. - If the string begins with a slash ("/"), it is the name of a - dataset to be searched, otherwise it is a name of a context that - was created by a SEARCH command given previously in the session. - - A successful SEARCH command MAY result in intermediate ENTRY - responses and MUST result in a MODTIME intermediate response. - - Following that are zero or more modifiers to the search. Each - modifier may be specified at most once. The defined modifiers - are: - - - - - - - -Newman & Myers Standards Track [Page 33] - -RFC 2244 ACAP November 1997 - - - DEPTH number - The SEARCH command will traverse the dataset tree up to the - specified depth. ENTRY responses will include the full path - to the entry. A value of "0" indicates that the search - should traverse the entire tree. A value of "1" is the - default and indicates only the specified dataset should be - searched. If a dataset is traversed which is not located on - the current server, then a REFER intermediate response is - returned for that subtree and the search continues. - - HARDLIMIT number - If the SEARCH command would result in more than number - entries, the SEARCH fails with a NO completion result with a - WAYTOOMANY response code. - - LIMIT number number - Limits the number of intermediate ENTRY responses that the - search may generate. The first numeric argument specifies - the limit, the second number specifies the number of entries - to return if the number of matches exceeds the limit. If the - limit is exceeded, the SEARCH command still succeeds, - returning the total number of matches in a TOOMANY response - code in the tagged OK response. - - MAKECONTEXT [ENUMERATE] [NOTIFY] context - Causes the SEARCH command to create a context with the name - given in the argument to refer to the matching entries. If - the SEARCH is successful, the context name may then be given - as an argument to subsequent SEARCH commands to search the - set of matching entries. If a context with the specified - name already exists, it is first freed. If a new context may - not be created due to the server's limit on the number of - existing contexts, the command fails, returning a - TRYFREECONTEXT response code in the NO completion response. - - The optional "ENUMERATE" and "NOTIFY" arguments may be - included to request enumeration of the context (for virtual - scroll bars) or change notifications for the context. If - "NOTIFY" is not requested, the context represents a snapshot - of the entries at the time the SEARCH was issued. - - ENUMERATE requests that the contents of the context be - ordered according to the SORT modifier and that sequential - numbers, starting with one, be assigned to the entries in the - context. This permits the RANGE modifier to be used to fetch - portions of the ordered context. - - - - - -Newman & Myers Standards Track [Page 34] - -RFC 2244 ACAP November 1997 - - - NOTIFY requests that the server send untagged ADDTO, - REMOVEFROM, CHANGE, and MODTIME responses while the context - created by this SEARCH command exists. The server MAY issue - untagged ADDTO, REMOVEFROM, CHANGE and MODTIME notifications - for a context at any time between the issuing of the SEARCH - command with MAKECONTEXT NOTIFY and the completion of a - FREECONTEXT command for the context. Notifications are only - issued for changes which occur after the server receives the - SEARCH command which created the context. After issuing a - sequence of ADDTO, REMOVEFROM or CHANGE notifications, the - server MUST issue an untagged MODTIME notification indicating - that the client has all updates to the entries in the context - up to and including the given modtime value. Servers are - permitted a reasonable delay to batch change notifications - before sending them to the client. - - The position arguments of the ADDTO, REMOVEFROM and CHANGE - notifications are 0 if ENUMERATE is not requested. - - NOINHERIT - This causes the SEARCH command to operate without - inheritance. It can be used to tell which values are - explicit overrides. If MAKECONTEXT is also specified, the - created context is also not affected by inheritance. - - RETURN (metadata...) - Specifies what is to be returned in intermediate ENTRY - responses. If this modifier is not specified, no - intermediate ENTRY responses are returned. - - Inside the parentheses is an optional list of attributes, - each optionally followed by a parenthesized list of metadata. - If the parenthesized list of metadata is not specified, it - defaults to "(value)". - - An attribute name with a trailing "*" requests all attributes - with that prefix. A "*" by itself requests all attributes. - If the parenthesized list of metadata is not specified for an - attribute with a trailing "*", it defaults to "(attribute - value)". Results matching such an attribute pattern are - grouped in parentheses. - - Following the last intermediate ENTRY response, the server - returns a single intermediate MODTIME response. - - - - - - - -Newman & Myers Standards Track [Page 35] - -RFC 2244 ACAP November 1997 - - - SORT (attribute comparator ...) - Specifies the order in which any resulting ENTRY replies are - to be returned to the client. The SORT modifier takes as an - argument a parenthesized list of one or more - attribute/comparator pairs. Attribute lists the attribute to - sort on, comparator specifies the name of the collation rule - to apply to the values of the attribute. Successive - attribute/comparator pairs are used to order two entries only - when all preceding pairs indicate the two entries collate the - same. - - If the SORT modifier is used in conjunction with the - MAKECONTEXT modifier, the SORT modifier specifies the - ordering of entries in the created context. - - If no SORT modifier is specified, or none of the - attribute/comparator pairs indicates an order for the two - entries, the server uses the order of the entries that exists - in the context or dataset being searched. - - - Following the modifiers is the search criteria. Searching - criteria consist of one or more search keys. Search keys may be - combined using the AND, and OR search keys. For example, the - criteria (the newline is for readability and not part of the - criteria): - AND COMPARE "modtime" "+i;octet" "19951206103400" - COMPARE "modtime" "-i;octet" "19960112000000" - refers to all entries modified between 10:34 December 6 1995 and - midnight January 12, 1996 UTC. - - The currently defined search keys are as follows. - - ALL This matches all entries. - - AND search-key1 search-key2 - Entries that match both search keys. - - COMPARE attribute comparator value - Entries for which the value of the specified attribute - collates using the specified comparator the same or later - than the specified value. - - COMPARESTRICT attribute comparator value - Entries for which the specified attribute collates using the - specified comparator later than the specified value. - - - - - -Newman & Myers Standards Track [Page 36] - -RFC 2244 ACAP November 1997 - - - EQUAL attribute comparator value - Entries for which the value of the attribute is equal to the - specified value using the specified comparator. - - NOT search-key - Entries that do not match the specified search key. - - OR search-key1 search-key2 - Entries that match either search key. - - PREFIX attribute comparator value - Entries which begin with the specified value using the - specified comparator. If the specified comparator doesn't - support substring matching, a BAD response is returned. - - RANGE start end time - Entries which are within the specified range of the - enumerated context's ordering. The lowest-ordered entry in - the context is assigned number one, the next lowest entry is - assigned number two, and so on. The numeric arguments - specify the lowest and highest numbers to match. The time - specifies that the client has processed notifications for the - context up to the specified time. If the context has been - modified since then, the server MUST either return a NO with - a MODIFIED response code, or return the results that the - SEARCH would have returned if none of the changes since that - time had been made. - - RANGE is only permitted on enumerated contexts. If RANGE is - used with a dataset or non-enumerated context, the server - MUST return a BAD response. - - SUBSTRING attribute comparator value - Entries which contain the specified value, using the - specified comparator. If the specified comparator doesn't - support substring matching, a BAD response is returned. - - -6.4.2. ENTRY Intermediate Response - - Data: entry name - entry data - - The ENTRY intermediate response occurs as a result of a SEARCH or - STORE command. This is the means by which dataset entries are - returned to the client. - - - - - -Newman & Myers Standards Track [Page 37] - -RFC 2244 ACAP November 1997 - - - The ENTRY response begins with the entry name, if a SEARCH command - without the DEPTH modifier was issued, or the entry path in other - cases. This is followed by a set of zero or more items, one for - each metadata item in the RETURN search modifier. Results - matching an attribute pattern or returning multiple metadata items - are grouped in parentheses. - -6.4.3. MODTIME Intermediate Response - - Data: modtime value - - The MODTIME intermediate response occurs as a result of a SEARCH - command. It indicates that the just created context or the - previously returned ENTRY responses include all updates to the - returned entries up to and including the modtime value in the - argument. - -6.4.4. REFER Intermediate Response - - Data: dataset path - relative ACAP URLs - - The REFER intermediate response occurs as a result of a - multi-level SEARCH where one of the levels is located on a - different server. The response indicates the dataset which is not - located on the current server and one or more relative ACAP URLs - for where that dataset may be found. - -6.4.5. Search Examples - - Here are some SEARCH command exchanges between the client and server: - - C: A046 SEARCH "/addressbook/" DEPTH 3 RETURN ("addressbook.Alias" - "addressbook.Email" "addressbook.List") OR NOT EQUAL - "addressbook.Email" "i;octet" NIL NOT EQUAL - "addressbook.List" "i;octet" NIL - S: A046 ENTRY "/addressbook/user/joe/A0345" "fred" - "fred@stone.org" NIL - S: A046 ENTRY "/addressbook/user/fred/A0537" "joe" "joe@stone.org" - NIL - S: A046 ENTRY "/addressbook/group/Dinosaur Operators/A423" - "saurians" NIL "1" - S: A046 MODTIME "19970728105252" - S: A046 OK "SEARCH completed" - - C: A047 SEARCH "/addressbook/user/fred/" RETURN ("*") EQUAL "entry" - "i;octet" "A0345" - S: A047 ENTRY "A0345" (("modtime" "19970728102226") - - - -Newman & Myers Standards Track [Page 38] - -RFC 2244 ACAP November 1997 - - - ("addressbook.Alias" "fred") ("addressbook.Email" - "fred@stone.org") ("addressbook.CommonName" - "Fred Flintstone") ("addressbook.Surname" "Flintstone") - ("addressbook.GivenName" "Fred")) - S: A047 MODTIME "19970728105258" - S: A047 OK "SEARCH completed" - - C: A048 SEARCH "/options/~/vendor.example/" RETURN - ("option.value"("size" "value" "myrights")) - SORT ("entry" "i;octet") COMPARE "modtime" "i;octet" - "19970727123225" - S: A048 ENTRY "blurdybloop" (5 "ghoti" "rwia") - S: A048 ENTRY "buckybits" (2 "10" "rwia") - S: A048 ENTRY "windowSize" (7 "100x100" "rwia") - S: A048 MODTIME "19970728105304" - S: A048 OK "SEARCH completed" - - C: A049 SEARCH "/addressbook/~/public" RETURN ("addressbook.Alias" - "addressbook.Email") MAKECONTEXT ENUMERATE "blob" LIMIT 100 1 - SORT ("addressbook.Alias" "i;octet") NOT EQUAL - "addressbook.Email" NIL - S: A049 ENTRY "A437" "aaguy" "aaguy@stone.org" - S: A049 MODTIME "19970728105308" - S: A049 OK (TOOMANY 347) "Context 'blob' created" - - C: A050 SEARCH "blob" RANGE 2 2 "19970728105308" ALL - S: A050 ENTRY "A238" "abguy" "abguy@stone.org" - S: A050 MODTIME "19970728105310" - S: A050 OK "SEARCH Completed" - -6.5. Contexts - - The following commands use contexts created by a SEARCH command with - a MAKECONTEXT modifier. - - -6.5.1. FREECONTEXT Command - - Arguments: context name - - Data: no specific data for this command - - Result: OK - freecontext completed - NO - freecontext failure: no such context - BAD - command unknown or arguments invalid - - - - - - -Newman & Myers Standards Track [Page 39] - -RFC 2244 ACAP November 1997 - - - The FREECONTEXT command causes the server to free all state - associated with the named context. The context may no longer be - searched and the server will no longer issue any untagged - responses for the context. The context is no longer counted - against the server's limit on the number of contexts. - - Example: C: A683 FREECONTEXT "blurdybloop" - S: A683 OK "Freecontext completed" - - -6.5.2. UPDATECONTEXT Command - - Arguments: list of context names - - Data: untagged responses: ADDTO REMOVEFROM CHANGE MODTIME - - Result: OK - Updatecontext completed: all updates completed - NO - Updatecontext failed: no such context - not a notify context - BAD - command unknown or arguments invalid - - The UPDATECONTEXT command causes the server to ensure that the - client is notified of all changes known to the server for the - contexts listed as arguments up to the current time. The contexts - listed in the arguments must have been previously given to a - successful SEARCH command with a MAKECONTEXT NOTIFY modifier. A - MODTIME untagged response MUST be returned if any read-write - metadata in the context changed since the last MODTIME for that - context. This includes metadata which is not listed in the RETURN - modifier for the context. - - While a server may issue untagged ADDTO, REMOVEFROM, CHANGE, and - MODTIME at any time, the UPDATECONTEXT command is used to "prod" - the server to send any notifications it has not sent yet. - - The UPDATECONTEXT command SHOULD NOT be used to poll for updates. - - Example: C: Z4S9 UPDATECONTEXT "blurdybloop" "blarfl" - S: Z4S9 OK "client has been notified of all changes" - - -6.5.3. ADDTO Untagged Response - - Data: context name - entry name - position - metadata list - - - - -Newman & Myers Standards Track [Page 40] - -RFC 2244 ACAP November 1997 - - - The untagged ADDTO response informs the client that an entry has - been added to a context. The response includes the position - number of the added entry (the first entry in the context is - numbered 1) and those metadata contained in the entry which match - the RETURN statement when the context was created. - - For enumerated contexts, the ADDTO response implicitly adds one to - the position of all members of the context which had position - numbers that were greater than or equal to the ADDTO position - number. For non-enumerated contexts, the position field is always - 0. - - Example: S: * ADDTO "blurdybloop" "fred" 15 - ("addressbook.Email" "fred@stone.org") - - -6.5.4. REMOVEFROM Untagged Response - - Data: context name - entry name - old position - - The untagged REMOVEFROM response informs the client that an entry - has been removed from a context. The response includes the - position number that the removed entry used to have (the first - entry in the context is numbered 1). - - For enumerated contexts, the REMOVEFROM response implicitly - subtracts one from the position numbers of all members of the - context which had position numbers greater than the REMOVEFROM - position number. For non-enumerated contexts, the position field - is always 0. - - Example: S: * REMOVEFROM "blurdybloop" "fred" 15 - - -6.5.5. CHANGE Untagged Response - - Data: context name - entry name - old position - new position - metadata list - - The untagged CHANGE response informs the client that an entry in a - context has either changed position in the context or has changed - the values of one or more of the attributes specified in the - RETURN modifier when the context was created. - - - -Newman & Myers Standards Track [Page 41] - -RFC 2244 ACAP November 1997 - - - The response includes the previous and current position numbers of - the entry (which are 0 if ENUMERATE was not specified on the - context) and the attribute metadata requested in the RETURN - modifier when the context was created. - - For enumerated contexts, the CHANGE response implicitly changes - the position numbers of all entries which had position numbers - between the old and new position. If old position is less than - new position, than one is subtracted from all entries which had - position numbers in that range. Otherwise one is added to all - entries which had position numbers in that range. If the old - position and new position are the same, then no implicit position - renumbering occurs. - - CHANGE responses are not issued for entries which have changed - position implicitly due to another ADDTO, REMOVEFROM or CHANGE - response. - - Example: S: * CHANGE "blurdybloop" "fred" 15 10 - ("addressbook.Email" "fred@stone.org") - - -6.5.6. MODTIME Untagged Response - - Data: context name - modtime value - - The untagged MODTIME response informs the client that it has - received all updates to entries in the context which have modtime - values less than or equal to the modtime value in the argument. - - Example: S: * MODTIME mycontext "19970320162338" - -6.6. Dataset modification - - The following commands and responses handle modification of datasets. - - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page 42] - -RFC 2244 ACAP November 1997 - - -6.6.1. STORE Command - - Arguments: entry store list - - Data: intermediate responses: ENTRY - - Result: OK - store completed - NO - store failure: can't store that name - UNCHANGEDSINCE specified and entry changed - BAD - command unknown or arguments invalid - invalid UTF-8 syntax in attribute name - - - Creates, modifies, or deletes the named entries in the named - datasets. The values of metadata not specified in the command are - not changed. Setting the "value" metadata of an attribute to NIL - removes that attribute from the entry. Setting the "value" of the - "entry" attribute to NIL removes that entry from the dataset and - cancels inheritance for the entire entry. Setting the "value" of - the "entry" attribute to DEFAULT removes that entry from the - inheriting dataset and reverts the entry and its attributes to - inherited values, if any. Changing the value of the "entry" - attribute renames the entry. - - Storing DEFAULT to the "value" metadata of an attribute is - equivalent to storing NIL, except that inheritance is enabled for - that attribute. If a non-NIL value is inherited then an ENTRY - intermediate response is generated to notify the client of the - this change. The ENTRY response includes the entry-path and the - attribute name and value metadata for each attribute which - reverted to a non-NIL inherited setting. - - Storing NIL to the "value" metadata of an attribute MAY be treated - equivalent to storing DEFAULT to that "value" if there is a NIL - value in the base dataset. - - The STORE command is followed by one or more entry store lists. - Each entry store list begins with an entry path followed by STORE - modifiers, followed by zero or more attribute store items. Each - attribute store item is made up of the attribute name followed by - NIL (to remove the attribute's value), DEFAULT (to revert the item - to any inherited value), a single value (to set the attribute's - single value), or a list of metadata items to modify. The - following STORE modifiers may be specified: - - - - - - - -Newman & Myers Standards Track [Page 43] - -RFC 2244 ACAP November 1997 - - - NOCREATE - By default, the server MUST create any datasets necessary to - store the entry, including multiple hierarchy levels. If - NOCREATE is specified, the STORE command will fail with a - NOEXIST error unless the parent dataset already exists. - - UNCHANGEDSINCE - If the "modtime" of the entry is later than the - unchangedsince time, then the store fails with a MODIFIED - response code. Use of UNCHANGEDSINCE with a time of - "00000101000000" will always fail if the entry exists. - Clients writing to a shared dataset are encouraged to use - UNCHANGEDSINCE when modifying an existing entry. - - - The server MUST either make all the changes specified in a single - STORE command or make none of them. If successful, the server - MUST update the "modtime" attribute for every entry which was - changed. - - It is illegal to list any metadata item within an attribute twice, - any attribute within an entry twice or any entry path twice. The - server MUST return a BAD response if this happens. - - The server MAY re-order the strings in a multi-value on STORE and - MAY remove duplicate strings. However, SEARCH MUST return multi- - values and the associated size list metadata in a consistant - order. - - - Example: C: A342 STORE ("/addressbook/user/fred/ABC547" - "addressbook.TelephoneNumber" "555-1234" - "addressbook.CommonName" "Barney Rubble" - "addressbook.AlternateNames" ("value" - ("Barnacus Rubble" "Coco Puffs Thief")) - "addressbook.Email" NIL) - S: A342 OK "Store completed" - C: A343 STORE ("/addressbook/user/joe/ABD42" - UNCHANGEDSINCE "19970320162338" - "user.joe.hair-length" "10 inches") - S: A343 NO (MODIFIED) "'ABD42' has been changed - by somebody else." - C: A344 STORE ("/addressbook/group/Developers/ACD54" - "entry" NIL) - S: A344 OK "Store completed" - C: A345 STORE ("/option/~/common/SMTPserver" - "option.value" DEFAULT) - S: A345 ENTRY "/option/~/common/SMTPserver" - - - -Newman & Myers Standards Track [Page 44] - -RFC 2244 ACAP November 1997 - - - "option.value" "smtp.server.do.main" - S: A345 OK "Store completed" - C: A347 STORE ("/addressbook/~/" "dataset.inherit" - "/addressbook/group/Developers") - S: A347 OK "Store completed" - - -6.6.2. DELETEDSINCE Command - - Arguments: dataset name - time - - Data: intermediate response: DELETED - - Result: OK - DELETEDSINCE completed - NO - DELETEDSINCE failure: can't read dataset - date too far in the past - BAD - command unknown or arguments invalid - - The DELETEDSINCE command returns in intermediate DELETED replies - the names of entries that have been deleted from the named dataset - since the given time. - - Servers may impose a limit on the number or age of deleted entry - names they keep track of. If the server does not have information - going back to the specified time, the command fails, returning a - TOOOLD response code in the tagged NO response. - - Example: C: Z4S9 DELETEDSINCE "/folder/site/" 19951205103412 - S: Z4S9 DELETED "blurdybloop" - S: Z4S9 DELETED "anteaters" - S: Z4S9 OK "DELETEDSINCE completed" - C: Z4U3 DELETEDSINCE "/folder/site/" 19951009040854 - S: Z4U3 NO (TOOOLD) "Don't have that information" - - -6.6.3. DELETED Intermediate Response - - Data: entry name - - The intermediate DELETED response occurs as a result of a - DELETEDSINCE command. It returns an entry that has been deleted - from the dataset specified in the DELETEDSINCE command. - -6.7. Access Control List Commands - - The commands in this section are used to manage access control lists. - - - - -Newman & Myers Standards Track [Page 45] - -RFC 2244 ACAP November 1997 - - -6.7.1. SETACL Command - - Arguments: acl object - authentication identifier - access rights - - Data: no specific data for this command - - Result: OK - setacl completed - NO - setacl failure: can't set acl - BAD - command unknown or arguments invalid - - The SETACL command changes the access control list on the - specified object so that the specified identifier is granted the - permissions enumerated in rights. If the object did not - previously have an access control list, one is created. - - - Example: C: A123 SETACL ("/addressbook/~/public/") "anyone" "r" - S: A123 OK "Setacl complete" - C: A124 SETACL ("/folder/site/") "B1FF" "rwa" - S: A124 NO (PERMISSION ("/folder/site/")) "'B1FF' not - permitted to modify access rights - for '/folder/site/'" - - - -6.7.2. DELETEACL Command - - Arguments: acl object - optional authentication identifier - - Data: no specific data for this command - - Result: OK - deleteacl completed - NO - deleteacl failure: can't delete acl - BAD - command unknown or arguments invalid - - If given the optional identifier argument, the DELETEACL command - removes any portion of the access control list on the specified - object for the specified identifier. - - If not given the optional identifier argument, the DELETEACL - command removes the ACL from the object entirely, causing access - to be controlled by a higher-level default ACL. This form of the - DELETEACL command is not permitted on the default ACL for a - dataset and servers MUST return a BAD. - - - - -Newman & Myers Standards Track [Page 46] - -RFC 2244 ACAP November 1997 - - - Example: C: A223 DELETEACL ("/addressbook/~/public") "anyone" - S: A223 OK "Deleteacl complete" - C: A224 DELETEACL ("/folder/site") - S: A224 BAD "Can't delete ACL from dataset" - C: A225 DELETEACL ("/addressbook/user/fred" - "addressbook.Email" "barney") - S: A225 OK "Deleteacl complete" - - -6.7.3. MYRIGHTS Command - - Arguments: acl object - - Data: intermediate responses: MYRIGHTS - - Result: OK - myrights completed - NO - myrights failure: can't get rights - BAD - command unknown or arguments invalid - - The MYRIGHTS command returns the set of rights that the client has - to the given dataset or dataset attribute. - - - Example: C: A003 MYRIGHTS ("/folder/site") - S: A003 MYRIGHTS "r" - S: A003 OK "Myrights complete" - - -6.7.4. MYRIGHTS Intermediate Response - - Data: rights - - The MYRIGHTS response occurs as a result of a MYRIGHTS command. - The argument is the set of rights that the client has for the - object referred to in the MYRIGHTS command. - -6.7.5. LISTRIGHTS Command - - Arguments: acl object - authentication identifier - - Data: untagged responses: LISTRIGHTS - - Result: OK - listrights completed - NO - listrights failure: can't get rights list - BAD - command unknown or arguments invalid - - - - - -Newman & Myers Standards Track [Page 47] - -RFC 2244 ACAP November 1997 - - - The LISTRIGHTS command takes an object and an identifier and - returns information about what rights the current user may revoke - or grant to that identifier in the ACL for that object. - - Example: C: a001 LISTRIGHTS ("/folder/~/") "smith" - S: a001 LISTRIGHTS "xra" "w" "i" - S: a001 OK Listrights completed - C: a005 LISTRIGHTS ("/folder/site/archive/imap") "anyone" - S: a005 LISTRIGHTS "" "x" "r" "w" "i" - S: a005 OK Listrights completed - - - -6.7.6. LISTRIGHTS Intermediate Response - - Data: required rights - list of optional rights - - The LISTRIGHTS response occurs as a result of a LISTRIGHTS - command. The first argument is a string containing the (possibly - empty) set of rights the identifier will always be granted on the - dataset or attribute. - - Following this are zero or more strings each containing a single - right which the current user may revoke or grant to the identifier - in the dataset or attribute. - - The same right MUST NOT be listed more than once in the LISTRIGHTS - response. - - -6.8. Quotas - - The section defines the commands and responses relating to quotas. - - -6.8.1. GETQUOTA Command - - Arguments: dataset - - Data: untagged responses: QUOTA - - Result: OK - Quota information returned - NO - Quota failure: can't access resource limit - no resource limit - BAD - command unknown or arguments invalid - - - - - -Newman & Myers Standards Track [Page 48] - -RFC 2244 ACAP November 1997 - - - The GETQUOTA command takes the name of a dataset, and returns in - an untagged QUOTA response the name of the dataset, quota limit in - bytes that applies to that dataset and the quota usage within that - limit. The scope of a quota limit is implementation dependent. - - Example: C: A043 GETQUOTA "/option/user/fred/common" - S: * QUOTA "/option/user/fred/common" 1048576 2475 - S: A043 OK "Getquota completed" - - -6.8.3. QUOTA Untagged Response - - Data: dataset - quota limit in bytes - amount of quota limit used - extension data - - The QUOTA untagged response is generated as a result of a GETQUOTA - command or MAY be generated by the server in response to a SEARCH - or STORE command to warn about high usage of a quota. It includes - the name of the applicable dataset, the quota limit in bytes, the - quota usage and some optional extension data. Clients MUST - tolerate the extension data as its use is reserved for a future - extension. - -6.9. Extensions - - In order to simplify the process of extending the protocol, clients - MUST tolerate unknown server responses which meet the syntax of - response-extend. In addition, clients MUST tolerate unknown server - response codes which meet the syntax of resp-code-ext. Availability - of new commands MUST be announced via a capability on the initial - greeting line and such commands SHOULD meet the syntax of - command-extend. - - Servers MUST respond to unknown commands with a BAD command - completion result. Servers MUST skip over non-synchronizing literals - contained in an unknown command. This may be done by assuming the - unknown command matches the command-extend syntax, or by reading a - line at a time and checking for the non-synchronizing literal syntax - at the end of the line. - -7. Registration Procedures - - ACAP's usefulness comes from providing a structured storage model for - all sorts of configuration data. However, for its potential to be - achieved, it is important that the Internet community strives for the - following goals: - - - -Newman & Myers Standards Track [Page 49] - -RFC 2244 ACAP November 1997 - - - (1) Standardization. It is very important to standardize dataset - classes. The authors hope that ACAP achieves the success that SNMP - has seen with the definition of numerous standards track MIBs. - - (2) Community Review. In the absence of standardization, it is - important to get community review on a proposal to improve its - engineering quality. Community review is strongly recommended prior - to registration. The ACAP implementors mailing list - should be used for this purpose. - - (3) Registration. Registration serves a two-fold purpose. First it - prevents use of the same name for different purposes, and second it - provides a one-stop list which can be used to locate existing - extensions or dataset classes to prevent duplicate work. - - The following registration templates may be used to register ACAP - protocol elements with the Internet Assigned Numbers Authority - (IANA). - -7.1. ACAP Capabilities - - New ACAP capabilities MUST be registered prior to use. Careful - consideration should be made before extending the protocol, as it can - lead to complexity or interoperability problems. Review of proposals - on the acap implementors mailing list is strongly encouraged prior to - registration. - - To: iana@iana.org - Subject: Registration of ACAP capability - - Capability name: - - Capability keyword: - - Capability arguments: - - Published Specification(s): - - (Optional, but strongly encouraged) - - Person and email address to contact for further information: - -7.2. ACAP Response Codes - - ACAP response codes are registered on a first come, first served - basis. Review of proposals on the acap implementors mailing list is - strongly encouraged prior to registration. - - - - -Newman & Myers Standards Track [Page 50] - -RFC 2244 ACAP November 1997 - - - To: iana@iana.org - Subject: Registration of ACAP response code - - Response Code: - - Arguments (use ABNF to specify syntax): - - Purpose: - - Published Specification(s): - - (Optional, but strongly encouraged) - - Person and email address to contact for further information: - -7.3. Dataset Classes - - A dataset class provides a core set of attributes for use in a - specified hierarchy. It may also define rules for the dataset - hierarchy underneath that class. Dataset class specifications must - be standards track or IESG approved experimental RFCs. - - To: iana@iana.org - Subject: Registration of ACAP dataset class - - Dataset class name/attribute prefix: - - Purpose: - - Published Specification(s): - - (Standards track or IESG approved experimental RFC) - - Person and email address to contact for further information: - -7.4. Vendor Subtree - - Vendors may reserve a portion of the ACAP namespace for private use. - Dataset class names beginning with "vendor.." - are reserved for use by that company or product. In addition, all - attribute names beginning with "vendor.." are - reserved for use by that company or product once registered. - Registration is on a first come, first served basis. Whenever - possible, private attributes and dataset classes should be avoided in - favor of improving interoperable dataset class definitions. - - - - - - -Newman & Myers Standards Track [Page 51] - -RFC 2244 ACAP November 1997 - - - To: iana@iana.org - Subject: Registration of ACAP vendor subtree - - Private Prefix: vendor.. - - Person and email address to contact for further information: - - (company names and addresses should be included when appropriate) - -8. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) notation as specified in [ABNF]. This uses the ABNF core - rules as specified in Appendix A of the ABNF specification [ABNF]. - - Except as noted otherwise, all alphabetic characters are - case-insensitive. The use of upper or lower case characters to - define token strings is for editorial clarity only. Implementations - MUST accept these strings in a case-insensitive fashion. - - The "initial-greeting" rule below defines the initial ACAP greeting - from the server. The "command" rule below defines the syntax for - commands sent by the client. The "response" rule below defines the - syntax for responses sent by the server. - - ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E - ;; Any CHAR except ATOM-SPECIALS - - ATOM-SPECIALS = "(" / ")" / "{" / SP / CTL / QUOTED-SPECIALS - - CHAR = %x01-7F - - DIGIT-NZ = %x31-39 - ; non-zero digits ("1" - "9") - - QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS - - QUOTED-SPECIALS = <"> / "\" - - SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / - %x23-5B / %x5D-7F - ;; any TEXT-CHAR except QUOTED-SPECIALS - - SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / - UTF8-5 / UTF8-6 - - TAG-CHAR = %x21 / %x23-27 / %x2C-5B / %x5D-7A / %x7C-7E - ;; Any ATOM-CHAR except "*" or "+" - - - -Newman & Myers Standards Track [Page 52] - -RFC 2244 ACAP November 1997 - - - TEXT-CHAR = %x01-09 / %x0B-0C / %x0E-7F - ;; any CHAR except CR and LF - - TEXT-UTF8-CHAR = SAFE-UTF8-CHAR / QUOTED-SPECIALS - - UTF8-1 = %x80-BF - - UTF8-2 = %xC0-DF UTF8-1 - - UTF8-3 = %xE0-EF 2UTF8-1 - - UTF8-4 = %xF0-F7 3UTF8-1 - - UTF8-5 = %xF8-FB 4UTF8-1 - - UTF8-6 = %xFC-FD 5UTF8-1 - - UTF8-CHAR = TEXT-UTF8-CHAR / CR / LF - - acl = "(" [acl-identrights *(SP acl-identrights)] ")" - *(SPACE acl-identrights)] ")" - - acl-identifier = string-utf8 - ;; MUST NOT contain HTAB - - acl-identrights = string-utf8 - ;; The identifier followed by a HTAB, - ;; followed by the rights. - - acl-delobject = "(" dataset SP attribute [SP entry-name] ")" - - acl-object = "(" dataset [SP attribute [SP entry-name]] ")" - - acl-rights = quoted - - atom = ALPHA *1023ATOM-CHAR - - attribute = string-utf8 - ;; dot-separated attribute name - ;; MUST NOT contain "*" or "%" - - attribute-store = attribute SP (value-nildef / - "(" 1*(metadata-write-q SP value-store) ")") - ;; MUST NOT include the same metadata twice - - auth-type = <"> auth-type-name <"> - - - - - -Newman & Myers Standards Track [Page 53] - -RFC 2244 ACAP November 1997 - - - auth-type-name = iana-token - ;; as defined in SASL [SASL] - - command = tag SP (command-any / command-auth / - command-nonauth) CRLF - ;; Modal based on state - - command-authent = "AUTHENTICATE" SP auth-type - [SP string] *(CRLF string) - - command-any = "NOOP" / command-lang / "LOGOUT" / - command-extend - - command-auth = command-delacl / command-dsince / - command-freectx / command-getquota / - command-lrights / command-myrights / - command-search / command-setacl / - command-store - ;; only valid in authenticated state - - command-delacl = "DELETEACL" SP acl-delobject [SP acl-identifier] - - command-dsince = "DELETEDSINCE" SP dataset SP time - - command-extend = extend-token [SP extension-data] - - command-freectx = "FREECONTEXT" SP context - - command-getquota = "GETQUOTA" SP dataset - - command-lang = "LANG" *(SP lang-tag) - - command-lrights = "LISTRIGHTS" SP acl-object - - command-myrights = "MYRIGHTS" SP acl-object - - command-nonauth = command-authent - ;; only valid in non-authenticated state - - command-search = "SEARCH" SP (dataset / context) - *(SP search-modifier) SP search-criteria - ;; MUST NOT include same search-modifier twice - - command-setacl = "SETACL" SP acl-object SP acl-identifier - SP acl-rights - - command-store = "STORE" SP store-entry-list - - - - -Newman & Myers Standards Track [Page 54] - -RFC 2244 ACAP November 1997 - - - comparator = <"> comparator-name <"> - - comparator-name = ["+" / "-"] iana-token - - context = string-utf8 - ;; MUST NOT begin with slash ("/") - - dataset = string-utf8 - ;; slash-separated dataset name - ;; begins with slash - - entry = entry-name / entry-path - - entry-name = string-utf8 - ;; entry name MUST NOT contain slash - ;; MUST NOT begin with "." - - entry-path = string-utf8 - ;; slash-separated path to entry - ;; begins with slash - - entry-relative = string-utf8 - ;; potentially relative path to entry - - extend-token = atom - ;; MUST be defined by a standards track or - ;; IESG approved experimental protocol extension - - extension-data = extension-item *(SP extension-item) - - extension-item = extend-token / string / number / - "(" [extension-data] ")" - - iana-token = atom - ;; MUST be registered with IANA - - initial-greeting = "*" SP "ACAP" *(SP "(" init-capability ")") CRLF - - init-capability = init-cap-context / init-cap-extend / - init-cap-implem / init-cap-sasl - - init-cap-context = "CONTEXTLIMIT" SP string - - init-cap-extend = iana-token [SP string-list] - - init-cap-implem = "IMPLEMENTATION" SP string - - init-cap-sasl = "SASL" SP string-list - - - -Newman & Myers Standards Track [Page 55] - -RFC 2244 ACAP November 1997 - - - lang-tag = <"> Language-Tag <"> - ;; Language-Tag rule is defined in [LANG-TAGS] - - literal = "{" number [ "+" ] "}" CRLF *OCTET - ;; The number represents the number of octets - ;; MUST be literal-utf8 except for values - - literal-utf8 = "{" number [ "+" ] "}" CRLF *UTF8-CHAR - ;; The number represents the number of octets - ;; not the number of characters - - metadata = attribute [ "(" metadata-type-list ")" ] - ;; attribute MAY end in "*" as wildcard. - - metadata-list = metadata *(SP metadata) - - metadata-type = "attribute" / "myrights" / "size" / - "count" / metadata-write - - metadata-type-q = <"> metadata-type <"> - - metadata-type-list = metadata-type-q *(SP metadata-type-q) - - metadata-write = "value" / "acl" - - metadata-write-q = <"> metadata-write <"> - - nil = "NIL" - - number = *DIGIT - ;; A 32-bit unsigned number. - ;; (0 <= n < 4,294,967,296) - - nz-number = DIGIT-NZ *DIGIT - ;; A 32-bit unsigned non-zero number. - ;; (0 < n < 4,294,967,296) - - position = number - ;; "0" if context is not enumerated - ;; otherwise this is non-zero - - quota-limit = number - - quota-usage = number - - quoted = <"> *QUOTED-CHAR <"> - ;; limited to 1024 octets between the <">s - - - - -Newman & Myers Standards Track [Page 56] - -RFC 2244 ACAP November 1997 - - - response = response-addto / response-alert / response-bye / - response-change / response-cont / - response-deleted / response-done / - response-entry / response-extend / - response-listr / response-lang / - response-mtimei / response-mtimeu / - response-myright / response-quota / - response-refer / response-remove / response-stat - - response-addto = "*" SP "ADDTO" SP context SP entry-name - SP position SP return-data-list - - response-alert = "*" SP "ALERT" SP resp-body CRLF - ;; Client MUST display alert text to user - - response-bye = "*" SP "BYE" SP resp-body CRLF - ;; Server will disconnect condition - - response-change = "*" SP "CHANGE" SP context SP entry-name - SP position SP position SP return-data-list - - response-cont = "+" SP string - - response-deleted = tag SP "DELETED" SP entry-name - - response-done = tag SP resp-cond-state CRLF - - response-entry = tag SP "ENTRY" SP entry SP return-data-list - - response-extend = (tag / "*") SP extend-token [SP extension-data] - - response-lang = "*" SP "LANG" SP lang-tag 1*(SP comparator) - - response-listr = tag SP "LISTRIGHTS" SP acl-rights - *(SP acl-rights) - - response-mtimei = tag SP "MODTIME" SP time - - response-mtimeu = "*" SP "MODTIME" SP context SP time - - response-myright = tag SP "MYRIGHTS" SP acl-rights - - response-quota = "*" SP "QUOTA" SP dataset SP quota-limit - SP quota-usage [SP extension-data] - - response-refer = tag SP "REFER" SP dataset - 1*(SP <"> url-relative <">) - - - - -Newman & Myers Standards Track [Page 57] - -RFC 2244 ACAP November 1997 - - - response-remove = "*" SP "REMOVEFROM" SP context SP - entry-name SP position - - response-stat = "*" SP resp-cond-state CRLF - - resp-body = ["(" resp-code ")" SP] quoted - - resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / - resp-code-inval / resp-code-mod / - resp-code-noexist / resp-code-perm / "QUOTA" / - resp-code-refer / resp-code-sasl / - resp-code-toomany / "TOOOLD" / - "TRANSITION-NEEDED" / "TRYFREECONTEXT" / - "TRYLATER" / "WAYTOOMANY" / resp-code-ext - - resp-code-ext = iana-token [SP extension-data] - ;; unknown codes MUST be tolerated by the client - - resp-code-inval = "INVALID" 1*(SP entry-path SP attribute) - - resp-code-mod = "MODIFIED" SP entry-path - - resp-code-noexist = "NOEXIST" SP dataset - - resp-code-perm = "PERMISSION" SP acl-object - - resp-code-refer = "REFER" 1*(SP <"> url-relative <">) - - resp-code-sasl = "SASL" SP string - - resp-code-toomany = "TOOMANY" SP nz-number - - resp-cond-state = ("OK" / "NO" / "BAD") SP resp-body - ;; Status condition - - return-attr-list = "(" return-metalist *(SP return-metalist) ")" - ;; occurs when "*" in RETURN pattern on SEARCH - - return-data = return-metadata / return-metalist / - return-attr-list - - return-data-list = return-data *(SP return-data) - - return-metalist = "(" return-metadata *(SP return-metadata) ")" - ;; occurs when multiple metadata items requested - - return-metadata = nil / string / value-list / acl - - - - -Newman & Myers Standards Track [Page 58] - -RFC 2244 ACAP November 1997 - - - searchkey-equal = "EQUAL" SP attribute SP comparator SP value-nil - - searchkey-comp = "COMPARE" SP attribute SP comparator SP value - - searchkey-prefix = "PREFIX" SP attribute SP comparator SP value - - searchkey-range = "RANGE" SP nz-number SP nz-number SP time - - searchkey-strict = "COMPARESTRICT" SP attribute SP comparator - SP value - - searchkey-substr = "SUBSTRING" SP attribute SP comparator SP value - - searchmod-depth = "DEPTH" SP number - - searchmod-hard = "HARDLIMIT" SP nz-number - - searchmod-limit = "LIMIT" SP number SP number - - searchmod-make = "MAKECONTEXT" [SP "ENUMERATE"] - [SP "NOTIFY"] SP context - - searchmod-ninh = "NOINHERIT" - - searchmod-return = "RETURN" SP "(" [metadata-list] ")" - - searchmod-sort = "SORT" SP "(" sort-list ")" - - search-criteria = "ALL" / searchkey-equal / searchkey-comp / - searchkey-strict / searchkey-range / - searchkey-prefix / searchkey-substr / - "NOT" SP search-criteria / - "OR" SP search-criteria SP search-criteria / - "AND" SP search-criteria SP search-criteria - - search-modifier = searchmod-depth / searchmod-hard / - searchmod-limit / searchmod-make / - searchmod-ninh / searchmod-return / - searchmod-sort - - sort-list = sort-item *(SP sort-item) - - sort-item = attribute SP comparator - - store-entry = "(" entry-path *(SP store-modifier) - *(SP attribute-store) ")" - ;; MUST NOT include same store-modifier twice - ;; MUST NOT include same attribute twice - - - -Newman & Myers Standards Track [Page 59] - -RFC 2244 ACAP November 1997 - - - store-entry-list = store-entry *(SP store-entry) - ;; MUST NOT include same entry twice - - store-modifier = store-mod-unchang / store-mod-nocreate - - store-mod-nocreate = "NOCREATE" - - store-mod-unchang = "UNCHANGEDSINCE" SP time - - string = quoted / literal - - string-list = string *(SP string) - - string-utf8 = quoted / literal-utf8 - - tag = 1*32TAG-CHAR - - time = <"> time-year time-month time-day time-hour - time-minute time-second time-subsecond <"> - ;; Timestamp in UTC - - time-day = 2DIGIT ;; 01-31 - - time-hour = 2DIGIT ;; 00-23 - - time-minute = 2DIGIT ;; 00-59 - - time-month = 2DIGIT ;; 01-12 - - time-second = 2DIGIT ;; 00-60 - - time-subsecond = *DIGIT - - time-year = 4DIGIT - - value = string - - value-list = "(" [value *(SP value)] ")" - - value-nil = value / nil - - value-nildef = value-nil / "DEFAULT" - - value-store = value-nildef / value-list / acl - - url-acap = "acap://" url-server "/" url-enc-entry - [url-filter] [url-extension] - ;; url-enc-entry interpreted relative to "/" - - - -Newman & Myers Standards Track [Page 60] - -RFC 2244 ACAP November 1997 - - - url-attr-list = url-enc-attr *("&" url-enc-attr) - - url-auth = ";AUTH=" ("*" / url-enc-auth) - - url-achar = uchar / "&" / "=" / "~" - ;; See RFC 1738 for definition of "uchar" - - url-char = uchar / "=" / "~" / ":" / "@" / "/" - ;; See RFC 1738 for definition of "uchar" - - url-enc-attr = 1*url-char - ;; encoded version of attribute name - - url-enc-auth = 1*url-achar - ;; encoded version of auth-type-name above - - url-enc-entry = 1*url-char - ;; encoded version of entry-relative above - - url-enc-user = *url-achar - ;; encoded version of login userid - - url-extension = *("?" 1*url-char) - - url-filter = "?" url-attr-list - - url-relative = url-acap / [url-enc-entry] [url-filter] - ;; url-enc-entry is relative to base URL - - url-server = [url-enc-user [url-auth] "@"] hostport - ;; See RFC 1738 for definition of "hostport" - -9. Multi-lingual Considerations - - The IAB charset workshop [IAB-CHARSET] came to a number of - conclusions which influenced the design of ACAP. The decision to use - UTF-8 as the character encoding scheme was based on that work. The - LANG command to negotiate a language for error messages is also - included. - - Section 3.4.5 of the IAB charset workshop report states that there - should be a way to identify the natural language for human readable - strings. Several promising proposals have been made for use within - ACAP, but no clear consensus on a single method is apparent at this - stage. The following rules are likely to permit the addition of - multi-lingual support in the future: - - - - - -Newman & Myers Standards Track [Page 61] - -RFC 2244 ACAP November 1997 - - - (1) A work in progress called Multi-Lingual String Format (MLSF) - proposes a layer on top of UTF-8 which uses otherwise illegal UTF-8 - sequences to store language tags. In order to permit its addition to - a future version of this standard, client-side UTF-8 interpreters - MUST be able to silently ignore illegal multi-byte UTF-8 characters, - and treat illegal single-byte UTF-8 characters as end of string - markers. Servers, for the time being, MUST be able to silently - accept illegal UTF-8 characters, except in attribute names and entry - names. Clients MUST NOT send illegal UTF-8 characters to the server - unless a future standard changes this rule. - - (2) There is a proposal to add language tags to Unicode. To support - this, servers MUST be able to store UTF-8 characters of up to 20 bits - of data. - - (3) The metadata item "language" is reserved for future use. - -10. Security Considerations - - The AUTHENTICATE command uses SASL [SASL] to provide basic - authentication, authorization, integrity and privacy services. This - is described in section 6.3.1. - - When the CRAM-MD5 mechanism is used, the security considerations for - the CRAM-MD5 SASL mechanism [CRAM-MD5] apply. The CRAM-MD5 mechanism - is also susceptible to passive dictionary attacks. This means that - if an authentication session is recorded by a passive observer, that - observer can try common passwords through the CRAM-MD5 mechanism and - see if the results match. This attack is reduced by using hard to - guess passwords. Sites are encouraged to educate users and have the - password change service test candidate passwords against a - dictionary. ACAP implementations of CRAM-MD5 SHOULD permit passwords - of at least 64 characters in length. - - ACAP protocol transactions are susceptible to passive observers or - man in the middle attacks which alter the data, unless the optional - encryption and integrity services of the AUTHENTICATE command are - enabled, or an external security mechanism is used for protection. - It may be useful to allow configuration of both clients and servers - to refuse to transfer sensitive information in the absence of strong - encryption. - - ACAP access control lists provide fine grained authorization for - access to attributes. A number of related security issues are - described in section 3.5. - - ACAP URLs have the same security considerations as IMAP URLs - [IMAP-URL]. - - - -Newman & Myers Standards Track [Page 62] - -RFC 2244 ACAP November 1997 - - - ACAP clients are encouraged to consider the security problems - involved with a lab computer situation. Specifically, a client cache - of ACAP configuration information MUST NOT allow access by an - unauthorized user. One way to assure this is for an ACAP client to - be able to completely flush any non-public cached configuration data - when a user leaves. - - As laptop computers can be easily stolen and a cache of configuration - data may contain sensitive information, a disconnected mode ACAP - client may wish to encrypt and password protect cached configuration - information. - -11. Acknowledgments - - Many thanks to the follow people who have contributed to ACAP over - the past four years: Wallace Colyer, Mark Crispin, Jack DeWinter, Rob - Earhart, Ned Freed, Randy Gellens, Terry Gray, J. S. Greenfield, - Steve Dorner, Steve Hole, Steve Hubert, Dave Roberts, Bart Schaefer, - Matt Wall and other participants of the IETF ACAP working group. - -12. Authors' Addresses - - Chris Newman - Innosoft International, Inc. - 1050 Lakes Drive - West Covina, CA 91790 USA - - Email: chris.newman@innosoft.com - - - John Gardiner Myers - Netscape Communications - 501 East Middlefield Road - Mail Stop MV-029 - Mountain View, CA 94043 - - Email: jgmyers@netscape.com - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page 63] - -RFC 2244 ACAP November 1997 - - -Appendices - -A. References - - [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: - ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, - November 1997. - - - - [BASIC-URL] Berners-Lee, Masinter, McCahill, "Uniform Resource - Locators (URL)", RFC 1738, CERN, Xerox Coproration, University of - Minnesota, December 1994. - - - - [CHARSET-LANG-POLICY] Alvestrand, "IETF Policy on Character Sets and - Languages", work in progress. - - [CRAM-MD5] Klensin, Catoe, Krumviede, "IMAP/POP AUTHorize Extension - for Simple Challenge/Response", RFC 2195, MCI, September 1997. - - - - [IAB-CHARSET] Weider, Preston, Simonsen, Alvestrand, Atkinson, - Crispin, Svanberg, "The Report of the IAB Character Set Workshop held - 29 February - 1 March, 1996", RFC 2130, April 1997. - - - - [IMAP4] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, University of Washington, December 1996. - - - - [IMAP-ACL] Myers, J., "IMAP4 ACL extension", RFC 2086, Carnegie - Mellon, January 1997. - - - - [IMAP-URL] Newman, "IMAP URL Scheme", RFC 2192, Innosoft, July 1997. - - - - [ISO-10646] ISO/IEC 10646-1:1993(E) "Information Technology-- - Universal Multiple-octet Coded Character Set (UCS)." See also - amendments 1 through 7, plus editorial corrections. - - - - -Newman & Myers Standards Track [Page 64] - -RFC 2244 ACAP November 1997 - - - [ISO-C] "Programming languages -- C", ISO/IEC 9899:1990, - International Organization for Standardization. This is effectively - the same as ANSI C standard X3.159-1989. - - [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, Harvard University, March 1997. - - - - [LANG-TAGS] Alvestrand, H., "Tags for the Identification of - Languages", RFC 1766. - - - - [REL-URL] Fielding, "Relative Uniform Resource Locators", RFC 1808, - UC Irvine, June 1995. - - - - [SASL] Myers, J., "Simple Authentication and Security Layer (SASL)", - RFC 2222, Netscape Communications, October 1997. - - - - [SASL-ANON] Newman, C., "Anonymous SASL Mechanism", RFC 2245, - November 1997. - - [UNICODE-2] The Unicode Consortium, "The Unicode Standard, Version - 2.0", Addison-Wesley, 1996. ISBN 0-201-48345-9. - - [US-ASCII] "USA Standard Code for Information Interchange," X3.4. - American National Standards Institute: New York (1968). - - [UTF8] Yergeau, F. "UTF-8, a transformation format of Unicode and ISO - 10646", RFC 2044, Alis Technologies, October 1996. - - - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page 65] - -RFC 2244 ACAP November 1997 - - -B. ACAP Keyword Index - - - ACAP (untagged response) ................................... 26 - ADDTO (untagged response) .................................. 40 - ALERT (untagged response) .................................. 31 - ALL (search keyword) ....................................... 36 - AND (search keyword) ....................................... 36 - AUTH-TOO-WEAK (response code) .............................. 19 - AUTHENTICATE (command) ..................................... 31 - BAD (response) ............................................. 30 - BYE (untagged response) .................................... 30 - CHANGE (untagged response) ................................. 41 - COMPARE (search keyword) ................................... 36 - COMPARESTRICT (search keyword) ............................. 36 - CONTEXTLIMIT (ACAP capability) ............................. 27 - DELETEACL (command) ........................................ 46 - DELETED (intermediate response) ............................ 45 - DELETEDSINCE (command) ..................................... 45 - DEPTH (search modifier) .................................... 34 - ENCRYPT-NEEDED (response code) ............................. 19 - ENTRY (intermediate response) .............................. 37 - EQUAL (search keyword) ..................................... 37 - FREECONTEXT (command) ...................................... 39 - GETQUOTA (command) ......................................... 48 - HARDLIMIT (search modifier) ................................ 34 - IMPLEMENTATION (ACAP capability) ........................... 27 - INVALID (response code) .................................... 19 - LANG (command) ............................................. 28 - LANG (intermediate response) ............................... 28 - LIMIT (search modifier) .................................... 34 - LISTRIGHTS (command) ....................................... 47 - LISTRIGHTS (intermediate response) ......................... 48 - LOGOUT (command) ........................................... 29 - MAKECONTEXT (search modifier) .............................. 34 - MODIFIED (response code) ................................... 19 - MODTIME (intermediate response) ............................ 38 - MODTIME (untagged response) ................................ 42 - MYRIGHTS (command) ......................................... 47 - MYRIGHTS (intermediate response) ........................... 47 - NO (response) .............................................. 29 - NOCREATE (store modifier) .................................. 44 - NOEXIST (response code) .................................... 19 - NOINHERIT (search modifier) ................................ 35 - NOOP (command) ............................................. 27 - NOT (search keyword) ....................................... 37 - OK (response) .............................................. 29 - OR (search keyword) ........................................ 37 - PERMISSION (response code) ................................. 19 - - - -Newman & Myers Standards Track [Page 66] - -RFC 2244 ACAP November 1997 - - - - PREFIX (search keyword) .................................... 37 - QUOTA (response code) ...................................... 19 - QUOTA (untagged response) .................................. 49 - RANGE (search keyword) ..................................... 37 - REFER (intermediate response) .............................. 38 - REFER (response code) ...................................... 19 - REMOVEFROM (untagged response) ............................. 41 - RETURN (search modifier) ................................... 35 - SASL (ACAP capability) ..................................... 27 - SASL (response code) ....................................... 20 - SEARCH (command) ........................................... 33 - SETACL (command) ........................................... 46 - SORT (search modifier) ..................................... 36 - STORE (command) ............................................ 42 - SUBSTRING (search keyword) ................................. 37 - TOOMANY (response code) .................................... 20 - TOOOLD (response code) ..................................... 20 - TRANSITION-NEEDED (response code) .......................... 20 - TRYFREECONTEXT (response code) ............................. 20 - TRYLATER (response code) ................................... 20 - UNCHANGEDSINCE (store modifier) ............................ 44 - UPDATECONTEXT (command) .................................... 40 - WAYTOOMANY (response code) ................................. 20 - acl (attribute metadata) ................................... 12 - anyone (ACL identifier) .................................... 17 - attribute (attribute metadata) ............................. 12 - dataset.acl (dataset attribute) ............................ 24 - dataset.acl. (dataset attribute) ................ 24 - dataset.inherit (dataset attribute) ........................ 24 - entry (predefined attribute) ............................... 11 - i;ascii-casemap (comparator) ............................... 16 - i;ascii-numeric (comparator) ............................... 16 - i;octet (comparator) ....................................... 16 - modtime (predefined attribute) ............................. 11 - myrights (attribute metadata) .............................. 12 - size (attribute metadata) .................................. 13 - subdataset (predefined attribute) .......................... 11 - value (attribute metadata) ................................. 13 - - - - - - - - - - - - - -Newman & Myers Standards Track [Page 67] - -RFC 2244 ACAP November 1997 - - -C. Full Copyright Statement - - Copyright (C) The Internet Society 1997. All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implmentation may be prepared, copied, published and - distributed, in whole or in part, without restriction of any kind, - provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of developing - Internet standards in which case the procedures for copyrights defined - in the Internet Standards process must be followed, or as required to - translate it into languages other than English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT - NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN - WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - - -Newman & Myers Standards Track [Page 68] diff --git a/src/site/resources/rfc2298.txt b/src/site/resources/rfc2298.txt deleted file mode 100644 index dfac0f6..0000000 --- a/src/site/resources/rfc2298.txt +++ /dev/null @@ -1,1570 +0,0 @@ - - - - - -Network Working Group R. Fajman -Request for Comments: 2298 National Institutes of Health -Category: Standards Track March 1998 - - - An Extensible Message Format - for Message Disposition Notifications - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (1998). All Rights Reserved. - -Abstract - - This memo defines a MIME content-type that may be used by a mail user - agent (UA) or electronic mail gateway to report the disposition of a - message after it has been sucessfully delivered to a recipient. This - content-type is intended to be machine-processable. Additional - message headers are also defined to permit Message Disposition - Notifications (MDNs) to be requested by the sender of a message. The - purpose is to extend Internet Mail to support functionality often - found in other messaging systems, such as X.400 and the proprietary - "LAN-based" systems, and often referred to as "read receipts," - "acknowledgements," or "receipt notifications." The intention is to - do this while respecting the privacy concerns that have often been - expressed when such functions have been discussed in the past. - - Because many messages are sent between the Internet and other - messaging systems (such as X.400 or the proprietary "LAN-based" - systems), the MDN protocol is designed to be useful in a multi- - protocol messaging environment. To this end, the protocol described - in this memo provides for the carriage of "foreign" addresses, in - addition to those normally used in Internet Mail. Additional - attributes may also be defined to support "tunneling" of foreign - notifications through Internet Mail. - - - - - - - - -Fajman Standards Track [Page 1] - -RFC 2298 Message Disposition Notifications March 1998 - - -Table of Contents - - 1. Introduction ............................................ 2 - 2. Requesting Message Disposition Notifications ............ 3 - 3. Format of a Message Disposition Notification ............ 7 - 4. Timeline of events ...................................... 17 - 5. Conformance and Usage Requirements ...................... 18 - 6. Security Considerations ................................. 19 - 7. Collected Grammar ....................................... 20 - 8. Guidelines for Gatewaying MDNs .......................... 22 - 9. Example ................................................. 24 - 10. IANA Registration Forms ................................. 25 - 11. Acknowledgments ......................................... 26 - 12. References .............................................. 26 - 13. Author's Address ........................................ 27 - 14. Copyright ............................................... 28 - -1. Introduction - - This memo defines a MIME content-type [5] for message disposition - notifications (MDNs). An MDN can be used to notify the sender of a - message of any of several conditions that may occur after successful - delivery, such as display of the message contents, printing of the - message, deletion (without display) of the message, or the - recipient's refusal to provide MDNs. The "message/disposition- - notification" content-type defined herein is intended for use within - the framework of the "multipart/report" content type defined in RFC - 1892 [7]. - - This memo defines the format of the notifications and the RFC 822 - headers used to request them. - - The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in RFC 2119. - -1.1 Purposes - - The MDNs defined in this memo are expected to serve several purposes: - - (a) Inform human beings of the disposition of messages after - succcessful delivery, in a manner which is largely independent - of human language; - - (b) Allow mail user agents to keep track of the disposition of - messages sent, by associating returned MDNs with earlier message - transmissions; - - - - -Fajman Standards Track [Page 2] - -RFC 2298 Message Disposition Notifications March 1998 - - - (c) Convey disposition notification requests and disposition - notifications between Internet Mail and "foreign" mail systems - via a gateway; - - (d) Allow "foreign" notifications to be tunneled through a MIME- - capable message system and back into the original messaging - system that issued the original notification, or even to a third - messaging system; - - (e) Allow language-independent, yet reasonably precise, indications - of the disposition of a message to be delivered. - -1.2 Requirements - - These purposes place the following constraints on the notification - protocol: - - (a) It must be readable by humans, as well as being machine- - parsable. - - (b) It must provide enough information to allow message senders (or - their user agents) to unambiguously associate an MDN with the - message that was sent and the original recipient address for - which the MDN is issued (if such information is available), even - if the message was forwarded to another recipient address. - - (c) It must also be able to describe the disposition of a message - independent of any particular human language or of the - terminology of any particular mail system. - - (d) The specification must be extensible in order to accomodate - future requirements. - -2. Requesting Message Disposition Notifications - - Message disposition notifications are requested by including a - Disposition-Notification-To header in the message. Further - information to be used by the recipient's UA in generating the MDN - may be provided by including Original-Recipient and/or Disposition- - Notification-Options headers in the message. - -2.1 The Disposition-Notification-To Header - - A request that the receiving user agent issue message disposition - notifications is made by placing a Disposition-Notification-To header - into the message. The syntax of the header, using the ABNF of RFC - 822 [2], is - - - - -Fajman Standards Track [Page 3] - -RFC 2298 Message Disposition Notifications March 1998 - - - mdn-request-header = "Disposition-Notification-To" ":" 1#mailbox - - The mailbox token is as specified in RFC 822 [2]. - - The presence of a Disposition-Notification-To header in a message is - merely a request for an MDN. The recipients' user agents are always - free to silently ignore such a request. Alternatively, an explicit - denial of the request for information about the disposition of the - message may be sent using the "denied" disposition in an MDN. - - An MDN MUST NOT itself have a Disposition-Notification-To header. - An MDN MUST NOT be generated in response to an MDN. - - At most one MDN may be issued on behalf of each particular recipient - by their user agent. That is, once an MDN has been issued on behalf - of a recipient, no further MDNs may be issued on behalf of that - recipient, even if another disposition is performed on the message. - However, if a message is forwarded, an MDN may been issued for the - recipient doing the forwarding and the recipient of the forwarded - message may also cause an MDN to be generated. - - While Internet standards normally do not specify the behavior of user - interfaces, it is strongly recommended that the user agent obtain the - user's consent before sending an MDN. This consent could be obtained - for each message through some sort of prompt or dialog box, or - globally through the user's setting of a preference. The user might - also indicate globally that MDNs are never to be sent or that a - "denied" MDN is always sent in response to a request for an MDN. - - MDNs SHOULD NOT be sent automatically if the address in the - Disposition-Notification-To header differs from the address in the - Return-Path header (see RFC 822 [2]). In this case, confirmation - from the user SHOULD be obtained, if possible. If obtaining consent - is not possible (e.g., because the user is not online at the time), - then an MDN SHOULD NOT be sent. - - Confirmation from the user SHOULD be obtained (or no MDN sent) if - there is no Return-Path header in the message, or if there is more - than one distinct address in the Disposition-Notification-To header. - - The comparison of the addresses should be done using only the addr- - spec (local-part "@" domain) portion, excluding any phrase and route. - The comparison MUST be case-sensitive for the local-part and case- - insensitive for the domain part. - - If the message contains more than one Return-Path header, the - implementation may pick one to use for the comparison, or treat the - situation as a failure of the comparison. - - - -Fajman Standards Track [Page 4] - -RFC 2298 Message Disposition Notifications March 1998 - - - The reason for not automatically sending an MDN if the comparison - fails or more than one address is specified is to reduce the - possibilities for mail loops and use of MDNs for mail bombing. - - A message that contains a Disposition-Notification-To header SHOULD - also contain a Message-ID header as specified in RFC 822 [2]. This - will permit automatic correlation of MDNs with original messages by - user agents. - - If it is desired to request message disposition notifications for - some recipients and not others, two copies of the message should be - sent, one with an Disposition-Notification-To header and one without. - Many of the other headers of the message (e.g., To, cc) will be the - same in both copies. The recipients in the respective message - envelopes determine for whom message disposition notifications are - requested and for whom they are not. If desired, the Message-ID - header may be the same in both copies of the message. Note that - there are other situations (e.g., bcc) in which it is necessary to - send multiple copies of a message with slightly different headers. - The combination of such situations and the need to request MDNs for a - subset of all recipients may result in more than two copies of a - message being sent, some with a Disposition- Notification-To header - and some without. - - Messages posted to newsgroups SHOULD NOT have a Disposition- - Notification-To header. - -2.2 The Disposition-Notification-Options Header - - Future extensions to this specification may require that information - be supplied to the recipient's UA for additional control over how and - what MDNs are generated. The Disposition-Notification-Options header - provides an extensible mechanism for such information. The syntax of - this header, using the ABNF of RFC 822 [2], is - - Disposition-Notification-Options = - "Disposition-Notification-Options" ":" - disposition-notification-parameters - - disposition-notification-parameters = parameter *(";" parameter) - - parameter = attribute "=" importance "," 1#value - - importance = "required" / "optional" - - The definitions of attribute and value are as in the definition of - the Content-Type header in RFC 2045 [4]. - - - - -Fajman Standards Track [Page 5] - -RFC 2298 Message Disposition Notifications March 1998 - - - An importance of "required" indicates that interpretation of the - parameter is necessary for proper generation of an MDN in response to - this request. If a UA does not understand the meaning of the - parameter, it MUST NOT generate an MDN with any disposition type - other than "failed" in response to the request. An importance of - "optional" indicates that a UA that does not understand the meaning - of this parameter MAY generate an MDN in response anyway, ignoring - the value of the parameter. - - No parameters are defined in this specification. Parameters may be - defined in the future by later revisions or extensions to this - specification. Parameter attribute names beginning with "X-" will - never be defined as standard names; such names are reserved for - experimental use. MDN parameter names not beginning with "X-" MUST - be registered with the Internet Assigned Numbers Authority (IANA) and - described in a standards-track RFC or an experimental RFC approved by - the IESG. See Section 10 for a registration form. - - If a required parameter is not understood or contains some sort of - error, the receiving UA SHOULD issue an MDN with a disposition type - of "failed" (see Section 3.2.6) and include a Failure field (see - Section 3.2.7) that further describes the problem. MDNs with the a - disposition type of "failed" and a "Failure" field MAY also be - generated when other types of errors are detected in the parameters - of the Disposition-Notification-Options header. - - However, an MDN with a disposition type of "failed" MUST NOT be - generated if the user has indicated a preferance that MDNs are not to - be sent. If user consent would be required for an MDN of some other - disposition type to be sent, user consent SHOULD also be obtained - before sending an MDN with a disposition type of "failed". - -2.3 The Original-Recipient Header - - Since electronic mail addresses may be rewritten while the message is - in transit, it is useful for the original recipient address to be - made available by the delivering MTA. The delivering MTA may be able - to obtain this information from the ORCPT parameter of the SMTP RCPT - TO command, as defined in RFC 1891 [8]. If this information is - available, the delivering MTA SHOULD insert an Original-Recipient - header at the beginning of the message (along with the Return-Path - header). The delivering MTA MAY delete any other Original-Recipient - headers that occur in the message. The syntax of this header, using - the ABNF of RFC 822 [2], is as follows - - original-recipient-header = - "Original-Recipient" ":" address-type ";" generic-address - - - - -Fajman Standards Track [Page 6] - -RFC 2298 Message Disposition Notifications March 1998 - - - The address-type and generic-address token are as as specified in the - description of the Original-Recipient field in section 3.2.3. - - The purpose of carrying the original recipient information and - returning it in the MDN is to permit automatic correlation of MDNs - with the original message on a per-recipient basis. - -2.4 Use with the Message/Partial Content Type - - The use of the headers Disposition-Notification-To, Disposition- - Notification-Options, and Original-Recipient with the MIME - Message/partial content type (RFC 2046 [5]) requires further - definition. - - When a message is segmented into two or more message/partial - fragments, the three headers mentioned in the above paragraph SHOULD - be placed in the "inner" or "enclosed" message (using the terms of - RFC 2046 [5]). These headers SHOULD NOT be used in the headers of - any of the fragments themselves. - - When the multiple message/partial fragments are reassembled, the - following applies. If these headers occur along with the other - headers of a message/partial fragment message, they pertain to an MDN - to be generated for the fragment. If these headers occur in the - headers of the "inner" or "enclosed" message (using the terms of RFC - 2046 [5]), they pertain to an MDN to be generated for the reassembled - message. Section 5.2.2.1 of RFC 2046 [5]) is amended to specify - that, in addition to the headers specified there, the three headers - described in this specification are to be appended, in order, to the - headers of the reassembled message. Any occurances of the three - headers defined here in the headers of the initial enclosing message - must not be copied to the reassembled message. - -3. Format of a Message Disposition Notification - - A message disposition notification is a MIME message with a top- - level content-type of multipart/report (defined in RFC 1892 [7]). - When a multipart/report content is used to transmit an MDN: - - (a) The report-type parameter of the multipart/report content is - "disposition-notification". - - (b) The first component of the multipart/report contains a human- - readable explanation of the MDN, as described in RFC 1892 [7]. - - (c) The second component of the multipart/report is of content-type - message/disposition-notification, described in section 3.1 of - this document. - - - -Fajman Standards Track [Page 7] - -RFC 2298 Message Disposition Notifications March 1998 - - - (d) If the original message or a portion of the message is to be - returned to the sender, it appears as the third component of the - multipart/report. The decision of whether or not to return the - message or part of the message is up to the UA generating the - MDN. However, in the case of encrypted messages requesting - MDNs, encrypted message text MUST be returned, if it is returned - at all, only in its original encrypted form. - - NOTE: For message dispostion notifications gatewayed from - foreign systems, the headers of the original message may not be - available. In this case the third component of the MDN may be - omitted, or it may contain "simulated" RFC 822 headers which - contain equivalent information. In particular, it is very - desirable to preserve the subject and date fields from the - original message. - - The MDN MUST be addressed (in both the message header and the - transport envelope) to the address(es) from the Disposition- - Notification-To header from the original message for which the MDN is - being generated. - - The From field of the message header of the MDN MUST contain the - address of the person for whom the message disposition notification - is being issued. - - The envelope sender address (i.e., SMTP MAIL FROM) of the MDN MUST be - null (<>), specifying that no Delivery Status Notification messages - or other messages indicating successful or unsuccessful delivery are - to be sent in response to an MDN. - - A message disposition notification MUST NOT itself request an MDN. - That is, it MUST NOT contain a Disposition-Notification-To header. - - The Message-ID header (if present) for an MDN MUST be different from - the Message-ID of the message for which the MDN is being issued. - - A particular MDN describes the disposition of exactly one message for - exactly one recipient. Multiple MDNs may be generated as a result of - one message submission, one per recipient. However, due to the - circumstances described in Section 2.1, MDNs may not be generated for - some recipients for which MDNs were requested. - -3.1 The message/disposition-notification content-type - - The message/disposition-notification content-type is defined as - follows: - - MIME type name: message - - - -Fajman Standards Track [Page 8] - -RFC 2298 Message Disposition Notifications March 1998 - - - MIME subtype name: disposition-notification - Optional parameters: none - Encoding considerations: "7bit" encoding is sufficient and - MUST be used to maintain readability - when viewed by non-MIME mail - readers. - Security considerations: discussed in section 6 of this memo. - - The message/disposition-notification report type for use in the - multipart/report is "disposition-notification". - - The body of a message/disposition-notification consists of one or - more "fields" formatted according to the ABNF of RFC 822 header - "fields" (see [2]). Using the ABNF of RFC 822, the syntax of the - message/disposition-notification content is as follows: - - disposition-notification-content = [ reporting-ua-field CRLF ] - [ mdn-gateway-field CRLF ] - [ original-recipient-field CRLF ] - final-recipient-field CRLF - [ original-message-id-field CRLF ] - disposition-field CRLF - *( failure-field CRLF ) - *( error-field CRLF ) - *( warning-field CRLF ) - *( extension-field CRLF ) - -3.1.1 General conventions for fields - - Since these fields are defined according to the rules of RFC 822 [2], - the same conventions for continuation lines and comments apply. - Notification fields may be continued onto multiple lines by beginning - each additional line with a SPACE or HTAB. Text which appears in - parentheses is considered a comment and not part of the contents of - that notification field. Field names are case-insensitive, so the - names of notification fields may be spelled in any combination of - upper and lower case letters. Comments in notification fields may - use the "encoded-word" construct defined in RFC 2047 [6]. - -3.1.2 "*-type" subfields - - Several fields consist of a "-type" subfield, followed by a semi- - colon, followed by "*text". For these fields, the keyword used in - the address-type or MTA-type subfield indicates the expected format - of the address or MTA-name that follows. - - The "-type" subfields are defined as follows: - - - - -Fajman Standards Track [Page 9] - -RFC 2298 Message Disposition Notifications March 1998 - - - (a) An "address-type" specifies the format of a mailbox address. - For example, Internet Mail addresses use the "rfc822" address- - type. - - address-type = atom - - (b) An "MTA-name-type" specifies the format of a mail transfer - agent name. For example, for an SMTP server on an Internet - host, the MTA name is the domain name of that host, and the - "dns" MTA-name-type is used. - - mta-name-type = atom - - Values for address-type and mta-name-type are case-insensitive. Thus - address-type values of "RFC822" and "rfc822" are equivalent. - - The Internet Assigned Numbers Authority (IANA) will maintain a - registry of address-type and mta-name-type values, along with - descriptions of the meanings of each, or a reference to a one or more - specifications that provide such descriptions. (The "rfc822" - address-type is defined in RFC 1891 [8].) Registration forms for - address-type and mta-name-type appear in RFC 1894 [9]. - - IANA will not accept registrations for any address-type name that - begins with "X-". These type names are reserved for experimental - use. - -3.1.3 Lexical tokens imported from RFC 822 - - The following lexical tokens, defined in RFC 822 [2], are used in the - ABNF grammar for MDNs: atom, CRLF, mailbox, msg-id, text. - -3.2 Message/disposition-notification Fields - -3.2.1 The Reporting-UA field - - reporting-ua-field = "Reporting-UA" ":" ua-name - [ ";" ua-product ] - - ua-name = *text - - ua-product = *text - - The Reporting-UA field is defined as follows: - - A MDN describes the disposition of a message after it has been - delivered to a recipient. In all cases, the Reporting-UA is the UA - that performed the disposition described in the MDN. This field is - - - -Fajman Standards Track [Page 10] - -RFC 2298 Message Disposition Notifications March 1998 - - - optional, but recommended. For Internet Mail user agents, it is - recommended that this field contain both the DNS name of the - particular instance of the UA that generated the MDN and the name of - the product. For example, - - Reporting-UA: rogers-mac.dcrt.nih.gov; Foomail 97.1 - - If the reporting UA consists of more than one component (e.g., a base - program and plug-ins), this may be indicated by including a list of - product names. - -3.2.2 The MDN-Gateway field - - The MDN-Gateway field indicates the name of the gateway or MTA that - translated a foreign (non-Internet) message disposition notification - into this MDN. This field MUST appear in any MDN which was - translated by a gateway from a foreign system into MDN format, and - MUST NOT appear otherwise. - - mdn-gateway-field = "MDN-Gateway" ":" mta-name-type ";" mta-name - - mta-name = *text - - For gateways into Internet Mail, the MTA-name-type will normally be - "smtp", and the mta-name will be the Internet domain name of the - gateway. - -3.2.3 Original-Recipient field - - The Original-Recipient field indicates the original recipient address - as specified by the sender of the message for which the MDN is being - issued. For Internet Mail messages the value of the - - Original-Recipient field is obtained from the Original-Recipient - header from the message for which the MDN is being generated. If - there is no Original-Recipient header in the message, then the - Original-Recipient field MUST be omitted, unless the same information - is reliably available some other way. If there is an Original- - Recipient header in the original message (or original recipient - information is reliably available some other way), then the - Original-Recipient field must be supplied. If there is more than one - Original-Recipient header in the message, the UA may choose the one - to use or act as if no Original-Recipient header is present. - - original-recipient-field = - "Original-Recipient" ":" address-type ";" generic-address - - generic-address = *text - - - -Fajman Standards Track [Page 11] - -RFC 2298 Message Disposition Notifications March 1998 - - - The address-type field indicates the type of the original recipient - address. If the message originated within the Internet, the - address-type field field will normally be "rfc822", and the address - will be according to the syntax specified in RFC 822 [2]. The value - "unknown" should be used if the Reporting UA cannot determine the - type of the original recipient address from the message envelope. - This address is the same as that provided by the sender and can be - used to automatically correlate MDN reports with original messages on - a per recipient basis. - -3.2.4 Final-Recipient field - - The Final-Recipient field indicates the recipient for which the MDN - is being issued. This field MUST be present. - - The syntax of the field is as follows: - - final-recipient-field = - "Final-Recipient" ":" address-type ";" generic-address - - The generic-address subfield of the Final-Recipient field MUST - contain the mailbox address of the recipient (from the From header of - the MDN) as it was when the MDN was generated by the UA. - - The Final-Recipient address may differ from the address originally - provided by the sender, because it may have been transformed during - forwarding and gatewaying into an totally unrecognizable mess. - However, in the absence of the optional Original-Recipient field, the - Final-Recipient field and any returned content may be the only - information available with which to correlate the MDN with a - particular message recipient. - - The address-type subfield indicates the type of address expected by - the reporting MTA in that context. Recipient addresses obtained via - SMTP will normally be of address-type "rfc822". - - Since mailbox addresses (including those used in the Internet) may be - case sensitive, the case of alphabetic characters in the address MUST - be preserved. - -3.2.5 Original-Message-ID field - - The Original-Message-ID field indicates the message-ID of the message - for which the MDN is being issued. It is obtained from the Message- - ID header of the message for which the MDN is issued. This field - MUST be present if the original message contained a Message-ID - header. The syntax of the field is - - - - -Fajman Standards Track [Page 12] - -RFC 2298 Message Disposition Notifications March 1998 - - - original-message-id-field = "Original-Message-ID" ":" msg-id - - The msg-id token is as specified in RFC 822 [2]. - -3.2.6 Disposition field - - The Disposition field indicates the action performed by the - Reporting-UA on behalf of the user. This field MUST be present. - - The syntax for the Disposition field is: - - disposition-field = "Disposition" ":" disposition-mode ";" - disposition-type - [ '/' disposition-modifier - *( "," dispostion-modifier ) ] - - disposition-mode = action-mode "/" sending-mode - - action-mode = "manual-action" / "automatic-action" - - sending-mode = "MDN-sent-manually" / "MDN-sent-automatically" - - disposition-type = "displayed" - / "dispatched" - / "processed" - / "deleted" - / "denied" - / "failed" - - disposition-modifier = ( "error" / "warning" ) - / ( "superseded" / "expired" / - "mailbox-terminated" ) - / disposition-modifier-extension - - disposition-modifier-extension = atom - - The disposition-mode, disposition-type and disposition-modifier may - be spelled in any combination of upper and lower case characters. - -3.2.6.1 Disposition modes - - The following disposition modes are defined: - - "manual-action" The disposition described by the - disposition type was a result of an - explicit instruction by the user rather - than some sort of automatically performed - action. - - - -Fajman Standards Track [Page 13] - -RFC 2298 Message Disposition Notifications March 1998 - - - "automatic-action" The disposition described by the - disposition type was a result of an - automatic action, rather than an explicit - instruction by the user for this message. - - "Manual-action" and "automatic-action" are - mutually exclusive. One or the other must - be specified. - - "MDN-sent-manually" The user explicity gave permission for - this particular MDN to be sent. - - "MDN-sent-automatically" The MDN was sent because the UA had - previously been configured to do so - automatically. - - "MDN-sent-manually" and "MDN-sent- - automatically" are mutually exclusive. - One or the other must be specified. - -3.2.6.2 Disposition types - - The following disposition-types are defined: - - "displayed" The message has been displayed by the UA to someone - reading the recipient's mailbox. There is - no guarantee that the content has been - read or understood. - - - "dispatched" The message has been sent somewhere in some manner - (e.g., printed, faxed, forwarded) without - necessarily having been previously - displayed to the user. The user may or - may not see the message later. - - "processed" The message has been processed in some manner (i.e., - by some sort of rules or server) without - being displayed to the user. The user may - or may not see the message later, or there - may not even be a human user associated - with the mailbox. - - "deleted" The message has been deleted. The recipient may or - may not have seen the message. The - recipient might "undelete" the message at - a later time and read the message. - - - - -Fajman Standards Track [Page 14] - -RFC 2298 Message Disposition Notifications March 1998 - - - "denied" The recipient does not wish the sender to be informed - of the message's disposition. A UA may - also siliently ignore message disposition - requests in this situation. - - "failed" A failure occurred that prevented the proper - generation of an MDN. More information - about the cause of the failure may be - contained in a Failure field. The - "failed" disposition type is not to be - used for the situation in which there is - is some problem in processing the message - other than interpreting the request for an - MDN. The "processed" or other disposition - type with appropriate disposition - modifiers is to be used in such - situations. - -3.2.6.3 Disposition modifiers - - The following disposition modifiers are defined: - - "error" An error of some sort occurred - that prevented successful - processing of the message. - Further information is contained - in an Error field. - - "warning" The message was successfully - processed but some sort of - exceptional condition occurred. - Further information is contained - in a Warning field. - - "superseded" The message has been - automatically rendered obsolete by - another message received. The - recipient may still access and - read the message later. - - "expired" The message has reached its - expiration date and has been - automatically removed from the - recipient's mailbox. - - "mailbox-terminated" The recipient's mailbox has been - terminated and all message in it - automatically removed. - - - -Fajman Standards Track [Page 15] - -RFC 2298 Message Disposition Notifications March 1998 - - - "Obsoleted", "expired", and - "terminated" are to be used with - the "deleted" disposition type and - the "autoaction" and "autosent" - disposition modifiers. - - disposition-modifier-extension Additional disposition modifiers - may be defined in the future by - later revisions or extensions to - this specification. Disposition - value names beginning with "X-" - will never be defined as standard - values; such names are reserved - for experimental use. MDN - disposition value names NOT - beginning with "X-" MUST be - registered with the Internet - Assigned Numbers Authority (IANA) - and described in a standards- - track RFC or an experimental RFC - approved by the IESG. See Section - 10 for a registration form. MDNs - with disposition modifier names - not understood by the receiving UA - MAY be silently ignored or placed - in the user's mailbox without - special inter- pretation. They - MUST not cause any error message - to be sent to the sender of the - MDN. - - If an UA developer does not wish - to register the meanings of such - disposition modifier extensions, - "X-" modifiers may be used for - this purpose. To avoid name - collisions, the name of the UA - implementation should follow the - "X-", (e.g. "X-Foomail-fratzed"). - - It is not required that a UA be able to generate all of the possible - values of the Disposition field. - - One and only one MDN may be issued on behalf of each particular - recipient by their user agent. That is, once an MDN has been issued - on behalf of a recipient, no further MDNs may be issued on behalf of - that recipient, even if another disposition is performed on the - message. However, if a message is forwarded, a "dispatched" MDN may - - - -Fajman Standards Track [Page 16] - -RFC 2298 Message Disposition Notifications March 1998 - - - been issued for the recipient doing the forwarding and the recipient - of the forwarded message may also cause an MDN to be generated. - -3.2.7 Failure, Error and Warning fields - - The Failure, Error and Warning fields are used to supply additional - information in the form of text messages when the "failure" - disposition type, "error" disposition modifier, and/or the "warning" - disposition modifer appear. The syntax is - - failure-field = "Failure" ":" *text - - error-field = "Error" ":" *text - - warning-field = "Warning" ":" *text - -3.3 Extension fields - - Additional MDN fields may be defined in the future by later revisions - or extensions to this specification. Extension-field names beginning - with "X-" will never be defined as standard fields; such names are - reserved for experimental use. MDN field names NOT beginning with - "X-" MUST be registered with the Internet Assigned Numbers Authority - (IANA) and described in a standards-track RFC or an experimental RFC - approved by the IESG. See Section 10 for a registration form. - - Extension MDN fields may be defined for the following reasons: - - (a) To allow additional information from foreign disposition - reports to be tunneled through Internet MDNs. The names of such - MDN fields should begin with an indication of the foreign - environment name (e.g. X400-Physical-Forwarding-Address). - - (b) To allow transmission of diagnostic information which is - specific to a particular user agent (UA). The names of such MDN - fields should begin with an indication of the UA implementation - which produced the MDN. (e.g. Foomail-information). - - If an application developer does not wish to register the meanings of - such extension fields, "X-" fields may be used for this purpose. To - avoid name collisions, the name of the application implementation - should follow the "X-", (e.g. "X-Foomail-Log-ID" or "X-EDI-info"). - -4. Timeline of events - - The following timeline shows when various events in the processing of - a message and generation of MDNs take place: - - - - -Fajman Standards Track [Page 17] - -RFC 2298 Message Disposition Notifications March 1998 - - - -- User composes message - - -- User tells UA to send message - - -- UA passes message to MTA (original recipient information - passed along) - - -- MTA sends message to next MTA - - -- Final MTA receives message - - -- Final MTA delivers message to UA (possibily generating DSN) - - -- UA performs automatic processing and generates corresponding - MDNs ("dispatched", "processed", "deleted", "denied" or "failed" - disposition type with "automatic-action" and "MDN-sent- - automatically" disposition modes) - - -- UA displays list of messages to user - - -- User selects a message and requests that some action be - performed on it. - - -- UA performs requested action and, with user's permission, - sends appropriate MDN ("displayed", "dispatched", "processed", - "deleted", "denied" or "failed" disposition type with "manual- - action" and "MDN-sent-manually" or "MDN-sent-automatically" - disposition mode). - - -- User possibly performs other actions on message, but no - further MDNs are generated. - -5. Conformance and Usage Requirements - - A UA or gateway conforms to this specification if it generates MDNs - according to the protocol defined in this memo. It is not necessary - to be able to generate all of the possible values of the Disposition - field. - - UAs and gateways MUST NOT generate the Original-Recipient field of an - MDN unless the mail protocols provide the address originally - specified by the sender at the time of submission. Ordinary SMTP - does not make that guarantee, but the SMTP extension defined in RFC - 1891 [8] permits such information to be carried in the envelope if it - is available. The Original-Recipient header defined in this document - provides a way for the MTA to pass the original recipient address to - the UA. - - - - -Fajman Standards Track [Page 18] - -RFC 2298 Message Disposition Notifications March 1998 - - - Each sender-specified recipient address may result in more than one - MDN. If an MDN is requested for a recipient that is forwarded to - multiple recipients of an "alias" (as defined in RFC 1891 [8], - section 6.2.7.3), each of the recipients may issue an MDN. - - Successful distribution of a message to a mailing list exploder - SHOULD be considered final disposition of the message. A mailing - list exploder may issue an MDN with a disposition type of "processed" - and disposition modes of "automatic-action" and "MDN- sent- - automatically" indicating that the message has been forwarded to the - list. In this case, the request for MDNs is not propogated to the - members of the list. - - Alternaively, the mailing list exploder may issue no MDN and - propogate the request for MDNs to all members of the list. The - latter behavior is not recommended for any but small, closely knit - lists, as it might cause large numbers of MDNs to be generated and - may cause confidential subscribers to the list to be revealed. It is - also permissible for the mailing list exploder to direct MDNs to - itself, correlate them, and produce a report to the original sender - of the message. - - This specification places no restrictions on the processing of MDNs - received by user agents or mailing lists. - -6. Security Considerations - - The following security considerations apply when using MDNs: - -6.1 Forgery - - MDNs may be forged as easily as ordinary Internet electronic mail. - User agents and automatic mail handling facilities (such as mail - distribution list exploders) that wish to make automatic use of MDNs - should take appropriate precautions to minimize the potential damage - from denial-of-service attacks. - - Security threats related to forged MDNs include the sending of: - - (a) A falsified disposition notification when the indicated - disposition of the message has not actually ocurred, - - (b) Unsolicited MDNs - -6.2 Confidentiality - - Another dimension of security is confidentiality. There may be cases - in which a message recipient does not wish the disposition of - - - -Fajman Standards Track [Page 19] - -RFC 2298 Message Disposition Notifications March 1998 - - - messages addressed to him to be known or is concerned that the - sending of MDNs may reveal other confidential information (e.g., when - the message was read). In this situation, it is acceptable for the - UA to issue "denied" MDNs or to silently ignore requests for MDNs. - - If the Disposition-Notification-To header is passed on unmodified - when a message is distributed to the subscribers of a mailing list, - the subscribers to the list may be revealed to the sender of the - original message by the generation of MDNs. - - Headers of the original message returned in part 3 of the - multipart/report could reveal confidential information about host - names and/or network topology inside a firewall. - - An unencrypted MDN could reveal confidential information about an - encrypted message, especially if all or part of the original message - is returned in part 3 of the multipart/report. Encrypted MDNs are - not defined in this specification. - - In general, any optional MDN field may be omitted if the Reporting UA - site or user determines that inclusion of the field would impose too - great a compromise of site confidentiality. The need for such - confidentiality must be balanced against the utility of the omitted - information in MDNs. - -6.3 Non-Repudiation - - Within the framework of today's Internet Mail, the MDNs defined in - this document provide valuable information to the mail user; however, - MDNs can not be relied upon as a guarantee that a message was or was - not not seen by the recipient. Even if MDNs are not actively forged, - they may be lost in transit. The MDN issuing mechanism may be - bypassed in some manner by the recipient. - -7. Collected Grammar - - NOTE: The following lexical tokens are defined in RFC 822: atom, - CRLF, mailbox, msg-id, text. The definitions of attribute and value - are as in the definition of the Content-Type header in RFC 2045 [4]. - - Message headers: - - mdn-request-header = "Disposition-Notification-To" ":" 1#mailbox - - Disposition-Notification-Options = - "Disposition-Notification-Options" ":" - disposition-notification-parameters - - - - -Fajman Standards Track [Page 20] - -RFC 2298 Message Disposition Notifications March 1998 - - - disposition-notification-parameters = parameter *(";" parameter) - - parameter = attribute "=" importance "," 1#value - - importance = "required" / "optional" - - original-recipient-header = - "Original-Recipient" ":" address-type ";" generic-address - - - Report content: - - disposition-notification-content = [ reporting-ua-field CRLF ] - [ mdn-gateway-field CRLF ] - [ original-recipient-field CRLF ] - final-recipient-field CRLF - [ original-message-id-field CRLF ] - disposition-field CRLF - *( failure-field CRLF ) - *( error-field CRLF ) - *( warning-field CRLF ) - *( extension-field CRLF ) - - address-type = atom - - mta-name-type = atom - - reporting-ua-field = "Reporting-UA" ":" ua-name - [ ";" ua-product ] - - ua-name = *text - - ua-product = *text - - mdn-gateway-field = "MDN-Gateway" ":" mta-name-type ";" mta-name - - mta-name = *text - - original-recipient-field = - "Original-Recipient" ":" address-type ";" generic-address - - generic-address = *text - - final-recipient-field = - "Final-Recipient" ":" address-type ";" generic-address - - disposition-field = "Disposition" ":" disposition-mode ";" - disposition-type - - - -Fajman Standards Track [Page 21] - -RFC 2298 Message Disposition Notifications March 1998 - - - [ '/' disposition-modifier - *( "," dispostion-modifier ) ] - - disposition-mode = action-mode "/" sending-mode - - action-mode = "manual-action" / "automatic-action" - - sending-mode = "MDN-sent-manually" / "MDN-sent-automatically" - - disposition-type = "displayed" - / "dispatched" - / "processed" - / "deleted" - / "denied" - / "failed" - - disposition-modifier = ( "error" / "warning" ) - / ( "superseded" / "expired" / - "mailbox-terminated" ) - / disposition-modifier-extension - - disposition-modifier-extension = atom - - original-message-id-field = "Original-Message-ID" ":" msg-id - - failure-field = "Failure" ":" *text - - error-field = "Error" ":" *text - - warning-field = "Warning" ":" *text - - extension-field = extension-field-name ":" *text - - extension-field-name = atom - -8. Guidelines for Gatewaying MDNs - - NOTE: This section provides non-binding recommendations for the - construction of mail gateways that wish to provide semi-transparent - disposition notifications between the Internet and another electronic - mail system. Specific MDN gateway requirements for a particular pair - of mail systems may be defined by other documents. - -8.1 Gatewaying from other mail systems to MDNs - - A mail gateway may issue an MDN to convey the contents of a "foreign" - disposition notification over Internet Mail. When there are - appropriate mappings from the foreign notification elements to MDN - - - -Fajman Standards Track [Page 22] - -RFC 2298 Message Disposition Notifications March 1998 - - - fields, the information may be transmitted in those MDN fields. - Additional information (such as might be needed to tunnel the foreign - notification through the Internet) may be defined in extension MDN - fields. (Such fields should be given names that identify the foreign - mail protocol, e.g. X400-* for X.400 protocol elements) - - The gateway must attempt to supply reasonable values for the - Reporting-UA, Final-Recipient, and Disposition fields. These will - normally be obtained by translating the values from the foreign - notification into their Internet-style equivalents. However, some - loss of information is to be expected. - - The sender-specified recipient address, and the original message-id, - if present in the foreign notification, should be preserved in the - Original-Recipient and Original-Message-ID fields. - - The gateway should also attempt to preserve the "final" recipient - address from the foreign system. Whenever possible, foreign protocol - elements should be encoded as meaningful printable ASCII strings. - - For MDNs produced from foreign disposition notifications, the name of - the gateway MUST appear in the MDN-Gateway field of the MDN. - -8.2 Gatewaying from MDNs to other mail systems - - It may be possible to gateway MDNs from the Internet into a foreign - mail system. The primary purpose of such gatewaying is to convey - disposition information in a form that is usable by the destination - system. A secondary purpose is to allow "tunneling" of MDNs through - foreign mail systems, in case the MDN may be gatewayed back into the - Internet. - - In general, the recipient of the MDN (i.e., the sender of the - original message) will want to know, for each recipient: the closest - available approximation to the original recipient address, and the - disposition (displayed, printed, etc.). - - If possible, the gateway should attempt to preserve the Original- - Recipient address and Original-Message-ID (if present), in the - resulting foreign disposition report. - - If it is possible to tunnel an MDN through the destination - environment, the gateway specification may define a means of - preserving the MDN information in the disposition reports used by - that environment. - - - - - - -Fajman Standards Track [Page 23] - -RFC 2298 Message Disposition Notifications March 1998 - - -9. Example - - NOTE: This example is provided as illustration only, and is not - considered part of the MDN protocol specification. If the example - conflicts with the protocol definition above, the example is wrong. - - Likewise, the use of *-type subfield names or extension fields in - this example is not to be construed as a definition for those type - names or extension fields. - -9.1 This is an MDN issued after a message has been displayed to the user - of an Internet Mail user agent. - - Date: Wed, 20 Sep 1995 00:19:00 (EDT) -0400 - From: Joe Recipient - Message-Id: <199509200019.12345@mega.edu> - Subject: Disposition notification - To: Jane Sender - MIME-Version: 1.0 - Content-Type: multipart/report; report-type=disposition-notification; - boundary="RAA14128.773615765/mega.edu" - - --RAA14128.773615765/mega.edu - - The message sent on 1995 Sep 19 at 13:30:00 (EDT) -0400 to Joe - Recipient with subject "First draft of - report" has been displayed. This is no guarantee that the message - has been read or understood. - - --RAA14128.773615765/mega.edu - content-type: message/disposition-notification - - Reporting-UA: joes-pc.cs.mega.edu; Foomail 97.1 - Original-Recipient: rfc822;Joe_Recipient@mega.edu - Final-Recipient: rfc822;Joe_Recipient@mega.edu - Original-Message-ID: <199509192301.23456@huge.com> - Disposition: manual-action/MDN-sent-manually; displayed - - --RAA14128.773615765/mega.edu - content-type: message/rfc822 - - [original message goes here] - - --RAA14128.773615765/mega.edu-- - - - - - - - -Fajman Standards Track [Page 24] - -RFC 2298 Message Disposition Notifications March 1998 - - -10. IANA Registration Forms - - The forms below are for use when registering a new parameter name for - the Disposition-Notification-Options header, a new disposition - modifier name, or a new MDN extension field. Each piece of - information required by a registration form may be satisfied either - by providing the information on the form itself, or by including a - reference to a published, publicly available specification that - includes the necessary information. IANA MAY reject registrations - because of incomplete registration forms, imprecise specifications, - or inappropriate names. - - To register, complete the applicable form below and send it via - electronic mail to . - -10.1 IANA registration form for Disposition-Notification-Options header - parameter names - - A registration for a Disposition-Notification-Options header - parameter name MUST include the following information: - - (a) The proposed parameter name. - - (b) The syntax for parameter values, specified using BNF, ABNF, - regular expressions, or other non-ambiguous language. - - (c) If parameter values are not composed entirely of graphic - characters from the US-ASCII repertoire, a specification for how they - are to be encoded as graphic US-ASCII characters in a Disposition- - Notification-Options header. - - (d) A reference to a standards track RFC or experimental RFC approved - by the IESG that describes the semantics of the parameter values. - -10.2 IANA registration form for disposition modifer names - - A registration for a disposition-modifier name MUST include the - following information: - - (a) The proposed disposition-modifier name. - - (b) A reference to a standards track RFC or experimental RFC approved - by the IESG that describes the semantics of the disposition modifier. - -10.3 IANA registration form for MDN extension field names - - A registration for an MDN extension field name MUST include the - following information: - - - -Fajman Standards Track [Page 25] - -RFC 2298 Message Disposition Notifications March 1998 - - - (a) The proposed extension field name. - - (b) The syntax for extension values, specified using BNF, ABNF, - regular expressions, or other non-ambiguous language. - - (c) If extension field values are not composed entirely of graphic - characters from the US-ASCII repertoire, a specification for how they - are to be encoded as graphic US-ASCII characters in a Disposition- - Notification-Options header. - - (d) A reference to a standards track RFC or experimental RFC approved - by the IESG that describes the semantics of the extension field. - -11. Acknowledgments - - This document is based on the Delivery Status Notifications document, - RFC 1894 [9], by Keith Moore and Greg Vaudreuil. Contributions were - made by members of the IETF Receipt Working Group, including Harald - Alverstrand, Ian Bell, Urs Eppenberger, Claus Andri Faerber, Ned - Freed, Jim Galvin, Carl Hage, Mike Lake, Keith Moore, Paul Overell, - Pete Resnick, Chuck Shih. - -12. References - - [1] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC 821, - August 1982. - - [2] Crocker, D., "Standard for the Format of ARPA Internet Text - Messages", STD 11, RFC 822, August 1982. - - [3] Braden, R. (ed.), "Requirements for Internet Hosts - - Application and Support", STD 3, RFC 1123, October 1989. - - [4] Freed, N., and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [5] Freed, N., and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part Two: Media Types", RFC 2046, November - 1996. - - [6] Moore, K., "Multipurpose Internet Mail Extensions (MIME) Part - Three: Message Header Extensions for Non-Ascii Text", RFC - 2047, November 1996. - - [7] Vaudreuil, G., "The Multipart/Report Content Type for the - Reporting of Mail System Administrative Messages", RFC 1892, - January 1996. - - - -Fajman Standards Track [Page 26] - -RFC 2298 Message Disposition Notifications March 1998 - - - [8] Moore, K., "SMTP Service Extension for Delivery Status - Notifications", RFC 1891, January 1996. - - [9] Moore, K., and G. Vaudreuil, "An Extensible Format for - Delivery Status Notifications, RFC 1894, January 1996. - - [10] Bradner, S., "Key Words for Use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - -13. Author's Address - - Roger Fajman - National Institutes of Health - Building 12A, Room 3063 - 12 South Drive MSC 5659 - Bethesda, Maryland 20892-5659 - USA - - EMail: raf@cu.nih.gov - Phone: +1 301 402 4265 - Fax: +1 301 480 6241 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Fajman Standards Track [Page 27] - -RFC 2298 Message Disposition Notifications March 1998 - - -14. Full Copyright Statement - - Copyright (C) The Internet Society (1998). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - - - - - - - - - - - - - - - - - - - - - - - - -Fajman Standards Track [Page 28] - diff --git a/src/site/resources/rfc3028.txt b/src/site/resources/rfc3028.txt deleted file mode 100644 index 962ec7c..0000000 --- a/src/site/resources/rfc3028.txt +++ /dev/null @@ -1,2018 +0,0 @@ - - - - - -Network Working Group T. Showalter -Request for Comments: 3028 Mirapoint, Inc. -Category: Standards Track January 2001 - - - Sieve: A Mail Filtering Language - -Status of this Memo - - This document specifies an Internet standards track protocol for the - Internet community, and requests discussion and suggestions for - improvements. Please refer to the current edition of the "Internet - Official Protocol Standards" (STD 1) for the standardization state - and status of this protocol. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2001). All Rights Reserved. - -Abstract - - This document describes a language for filtering e-mail messages at - time of final delivery. It is designed to be implementable on either - a mail client or mail server. It is meant to be extensible, simple, - and independent of access protocol, mail architecture, and operating - system. It is suitable for running on a mail server where users may - not be allowed to execute arbitrary programs, such as on black box - Internet Message Access Protocol (IMAP) servers, as it has no - variables, loops, or ability to shell out to external programs. - -Table of Contents - - 1. Introduction ........................................... 3 - 1.1. Conventions Used in This Document ..................... 4 - 1.2. Example mail messages ................................. 4 - 2. Design ................................................. 5 - 2.1. Form of the Language .................................. 5 - 2.2. Whitespace ............................................ 5 - 2.3. Comments .............................................. 6 - 2.4. Literal Data .......................................... 6 - 2.4.1. Numbers ............................................... 6 - 2.4.2. Strings ............................................... 7 - 2.4.2.1. String Lists .......................................... 7 - 2.4.2.2. Headers ............................................... 8 - 2.4.2.3. Addresses ............................................. 8 - 2.4.2.4. MIME Parts ............................................ 9 - 2.5. Tests ................................................. 9 - 2.5.1. Test Lists ............................................ 9 - - - -Showalter Standards Track [Page 1] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - 2.6. Arguments ............................................. 9 - 2.6.1. Positional Arguments .................................. 9 - 2.6.2. Tagged Arguments ...................................... 10 - 2.6.3. Optional Arguments .................................... 10 - 2.6.4. Types of Arguments .................................... 10 - 2.7. String Comparison ..................................... 11 - 2.7.1. Match Type ............................................ 11 - 2.7.2. Comparisons Across Character Sets ..................... 12 - 2.7.3. Comparators ........................................... 12 - 2.7.4. Comparisons Against Addresses ......................... 13 - 2.8. Blocks ................................................ 14 - 2.9. Commands .............................................. 14 - 2.10. Evaluation ............................................ 15 - 2.10.1. Action Interaction .................................... 15 - 2.10.2. Implicit Keep ......................................... 15 - 2.10.3. Message Uniqueness in a Mailbox ....................... 15 - 2.10.4. Limits on Numbers of Actions .......................... 16 - 2.10.5. Extensions and Optional Features ...................... 16 - 2.10.6. Errors ................................................ 17 - 2.10.7. Limits on Execution ................................... 17 - 3. Control Commands ....................................... 17 - 3.1. Control Structure If .................................. 18 - 3.2. Control Structure Require ............................. 19 - 3.3. Control Structure Stop ................................ 19 - 4. Action Commands ........................................ 19 - 4.1. Action reject ......................................... 20 - 4.2. Action fileinto ....................................... 20 - 4.3. Action redirect ....................................... 21 - 4.4. Action keep ........................................... 21 - 4.5. Action discard ........................................ 22 - 5. Test Commands .......................................... 22 - 5.1. Test address .......................................... 23 - 5.2. Test allof ............................................ 23 - 5.3. Test anyof ............................................ 24 - 5.4. Test envelope ......................................... 24 - 5.5. Test exists ........................................... 25 - 5.6. Test false ............................................ 25 - 5.7. Test header ........................................... 25 - 5.8. Test not .............................................. 26 - 5.9. Test size ............................................. 26 - 5.10. Test true ............................................. 26 - 6. Extensibility .......................................... 26 - 6.1. Capability String ..................................... 27 - 6.2. IANA Considerations ................................... 28 - 6.2.1. Template for Capability Registrations ................. 28 - 6.2.2. Initial Capability Registrations ...................... 28 - 6.3. Capability Transport .................................. 29 - 7. Transmission ........................................... 29 - - - -Showalter Standards Track [Page 2] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - 8. Parsing ................................................ 30 - 8.1. Lexical Tokens ........................................ 30 - 8.2. Grammar ............................................... 31 - 9. Extended Example ....................................... 32 - 10. Security Considerations ................................ 34 - 11. Acknowledgments ........................................ 34 - 12. Author's Address ....................................... 34 - 13. References ............................................. 34 - 14. Full Copyright Statement ............................... 36 - -1. Introduction - - This memo documents a language that can be used to create filters for - electronic mail. It is not tied to any particular operating system or - mail architecture. It requires the use of [IMAIL]-compliant - messages, but should otherwise generalize to many systems. - - The language is powerful enough to be useful but limited in order to - allow for a safe server-side filtering system. The intention is to - make it impossible for users to do anything more complex (and - dangerous) than write simple mail filters, along with facilitating - the use of GUIs for filter creation and manipulation. The language is - not Turing-complete: it provides no way to write a loop or a function - and variables are not provided. - - Scripts written in Sieve are executed during final delivery, when the - message is moved to the user-accessible mailbox. In systems where - the MTA does final delivery, such as traditional Unix mail, it is - reasonable to sort when the MTA deposits mail into the user's - mailbox. - - There are a number of reasons to use a filtering system. Mail - traffic for most users has been increasing due to increased usage of - e-mail, the emergence of unsolicited email as a form of advertising, - and increased usage of mailing lists. - - Experience at Carnegie Mellon has shown that if a filtering system is - made available to users, many will make use of it in order to file - messages from specific users or mailing lists. However, many others - did not make use of the Andrew system's FLAMES filtering language - [FLAMES] due to difficulty in setting it up. - - Because of the expectation that users will make use of filtering if - it is offered and easy to use, this language has been made simple - enough to allow many users to make use of it, but rich enough that it - can be used productively. However, it is expected that GUI-based - editors will be the preferred way of editing filters for a large - number of users. - - - -Showalter Standards Track [Page 3] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -1.1. Conventions Used in This Document - - In the sections of this document that discuss the requirements of - various keywords and operators, the following conventions have been - adopted. - - The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and - "MAY" in this document are to be interpreted as defined in - [KEYWORDS]. - - Each section on a command (test, action, or control structure) has a - line labeled "Syntax:". This line describes the syntax of the - command, including its name and its arguments. Required arguments - are listed inside angle brackets ("<" and ">"). Optional arguments - are listed inside square brackets ("[" and "]"). Each argument is - followed by its type, so "" represents an argument - called "key" that is a string. Literal strings are represented with - double-quoted strings. Alternatives are separated with slashes, and - parenthesis are used for grouping, similar to [ABNF]. - - In the "Syntax" line, there are three special pieces of syntax that - are frequently repeated, MATCH-TYPE, COMPARATOR, and ADDRESS-PART. - These are discussed in sections 2.7.1, 2.7.3, and 2.7.4, - respectively. - - The formal grammar for these commands in section 10 and is the - authoritative reference on how to construct commands, but the formal - grammar does not specify the order, semantics, number or types of - arguments to commands, nor the legal command names. The intent is to - allow for extension without changing the grammar. - -1.2. Example mail messages - - The following mail messages will be used throughout this document in - examples. - - Message A - ----------------------------------------------------------- - Date: Tue, 1 Apr 1997 09:06:31 -0800 (PST) - From: coyote@desert.example.org - To: roadrunner@acme.example.com - Subject: I have a present for you - - Look, I'm sorry about the whole anvil thing, and I really - didn't mean to try and drop it on you from the top of the - cliff. I want to try to make it up to you. I've got some - great birdseed over here at my place--top of the line - - - - -Showalter Standards Track [Page 4] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - stuff--and if you come by, I'll have it all wrapped up - for you. I'm really sorry for all the problems I've caused - for you over the years, but I know we can work this out. - -- - Wile E. Coyote "Super Genius" coyote@desert.example.org - ----------------------------------------------------------- - - Message B - ----------------------------------------------------------- - From: youcouldberich!@reply-by-postal-mail.invalid - Sender: b1ff@de.res.example.com - To: rube@landru.example.edu - Date: Mon, 31 Mar 1997 18:26:10 -0800 - Subject: $$$ YOU, TOO, CAN BE A MILLIONAIRE! $$$ - - YOU MAY HAVE ALREADY WON TEN MILLION DOLLARS, BUT I DOUBT - IT! SO JUST POST THIS TO SIX HUNDRED NEWSGROUPS! IT WILL - GUARANTEE THAT YOU GET AT LEAST FIVE RESPONSES WITH MONEY! - MONEY! MONEY! COLD HARD CASH! YOU WILL RECEIVE OVER - $20,000 IN LESS THAN TWO MONTHS! AND IT'S LEGAL!!!!!!!!! - !!!!!!!!!!!!!!!!!!111111111!!!!!!!11111111111!!1 JUST - SEND $5 IN SMALL, UNMARKED BILLS TO THE ADDRESSES BELOW! - ----------------------------------------------------------- - -2. Design - -2.1. Form of the Language - - The language consists of a set of commands. Each command consists of - a set of tokens delimited by whitespace. The command identifier is - the first token and it is followed by zero or more argument tokens. - Arguments may be literal data, tags, blocks of commands, or test - commands. - - The language is represented in UTF-8, as specified in [UTF-8]. - - Tokens in the ASCII range are considered case-insensitive. - -2.2. Whitespace - - Whitespace is used to separate tokens. Whitespace is made up of - tabs, newlines (CRLF, never just CR or LF), and the space character. - The amount of whitespace used is not significant. - - - - - - - - -Showalter Standards Track [Page 5] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -2.3. Comments - - Two types of comments are offered. Comments are semantically - equivalent to whitespace and can be used anyplace that whitespace is - (with one exception in multi-line strings, as described in the - grammar). - - Hash comments begin with a "#" character that is not contained within - a string and continue until the next CRLF. - - Example: if size :over 100K { # this is a comment - discard; - } - - Bracketed comments begin with the token "/*" and end with "*/" outside - of a string. Bracketed comments may span multiple lines. Bracketed - comments do not nest. - - Example: if size :over 100K { /* this is a comment - this is still a comment */ discard /* this is a comment - */ ; - } - -2.4. Literal Data - - Literal data means data that is not executed, merely evaluated "as - is", to be used as arguments to commands. Literal data is limited to - numbers and strings. - -2.4.1. Numbers - - Numbers are given as ordinary decimal numbers. However, those - numbers that have a tendency to be fairly large, such as message - sizes, MAY have a "K", "M", or "G" appended to indicate a multiple of - a power of two. To be comparable with the power-of-two-based - versions of SI units that computers frequently use, K specifies - kibi-, or 1,024 (2^10) times the value of the number; M specifies - mebi-, or 1,048,576 (2^20) times the value of the number; and G - specifies tebi-, or 1,073,741,824 (2^30) times the value of the - number [BINARY-SI]. - - Implementations MUST provide 31 bits of magnitude in numbers, but MAY - provide more. - - Only positive integers are permitted by this specification. - - - - - - -Showalter Standards Track [Page 6] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -2.4.2. Strings - - Scripts involve large numbers of strings as they are used for pattern - matching, addresses, textual bodies, etc. Typically, short quoted - strings suffice for most uses, but a more convenient form is provided - for longer strings such as bodies of messages. - - A quoted string starts and ends with a single double quote (the <"> - character, ASCII 34). A backslash ("\", ASCII 92) inside of a quoted - string is followed by either another backslash or a double quote. - This two-character sequence represents a single backslash or double- - quote within the string, respectively. - - No other characters should be escaped with a single backslash. - - An undefined escape sequence (such as "\a" in a context where "a" has - no special meaning) is interpreted as if there were no backslash (in - this case, "\a" is just "a"). - - Non-printing characters such as tabs, CR and LF, and control - characters are permitted in quoted strings. Quoted strings MAY span - multiple lines. NUL (ASCII 0) is not allowed in strings. - - For entering larger amounts of text, such as an email message, a - multi-line form is allowed. It starts with the keyword "text:", - followed by a CRLF, and ends with the sequence of a CRLF, a single - period, and another CRLF. In order to allow the message to contain - lines with a single-dot, lines are dot-stuffed. That is, when - composing a message body, an extra `.' is added before each line - which begins with a `.'. When the server interprets the script, - these extra dots are removed. Note that a line that begins with a - dot followed by a non-dot character is not interpreted dot-stuffed; - that is, ".foo" is interpreted as ".foo". However, because this is - potentially ambiguous, scripts SHOULD be properly dot-stuffed so such - lines do not appear. - - Note that a hashed comment or whitespace may occur in between the - "text:" and the CRLF, but not within the string itself. Bracketed - comments are not allowed here. - -2.4.2.1. String Lists - - When matching patterns, it is frequently convenient to match against - groups of strings instead of single strings. For this reason, a list - of strings is allowed in many tests, implying that if the test is - true using any one of the strings, then the test is true. - Implementations are encouraged to use short-circuit evaluation in - these cases. - - - -Showalter Standards Track [Page 7] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - For instance, the test `header :contains ["To", "Cc"] - ["me@example.com", "me00@landru.example.edu"]' is true if either the - To header or Cc header of the input message contains either of the - e-mail addresses "me@example.com" or "me00@landru.example.edu". - - Conversely, in any case where a list of strings is appropriate, a - single string is allowed without being a member of a list: it is - equivalent to a list with a single member. This means that the test - `exists "To"' is equivalent to the test `exists ["To"]'. - -2.4.2.2. Headers - - Headers are a subset of strings. In the Internet Message - Specification [IMAIL] [RFC1123], each header line is allowed to have - whitespace nearly anywhere in the line, including after the field - name and before the subsequent colon. Extra spaces between the - header name and the ":" in a header field are ignored. - - A header name never contains a colon. The "From" header refers to a - line beginning "From:" (or "From :", etc.). No header will match - the string "From:" due to the trailing colon. - - Folding of long header lines (as described in [IMAIL] 3.4.8) is - removed prior to interpretation of the data. The folding syntax (the - CRLF that ends a line plus any leading whitespace at the beginning of - the next line that indicates folding) are interpreted as if they were - a single space. - -2.4.2.3. Addresses - - A number of commands call for email addresses, which are also a - subset of strings. When these addresses are used in outbound - contexts, addresses must be compliant with [IMAIL], but are further - constrained. Using the symbols defined in [IMAIL], section 6.1, the - syntax of an address is: - - sieve-address = addr-spec ; simple address - / phrase "<" addr-spec ">" ; name & addr-spec - - That is, routes and group syntax are not permitted. If multiple - addresses are required, use a string list. Named groups are not used - here. - - Implementations MUST ensure that the addresses are syntactically - valid, but need not ensure that they actually identify an email - recipient. - - - - - -Showalter Standards Track [Page 8] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -2.4.2.4. MIME Parts - - In a few places, [MIME] body parts are represented as strings. These - parts include MIME headers and the body. This provides a way of - embedding typed data within a Sieve script so that, among other - things, character sets other than UTF-8 can be used for output - messages. - -2.5. Tests - - Tests are given as arguments to commands in order to control their - actions. In this document, tests are given to if/elsif/else to - decide which block of code is run. - - Tests MUST NOT have side effects. That is, a test cannot affect the - state of the filter or message. No tests in this specification have - side effects, and side effects are forbidden in extension tests as - well. - - The rationale for this is that tests with side effects impair - readability and maintainability and are difficult to represent in a - graphic interface for generating scripts. Side effects are confined - to actions where they are clearer. - -2.5.1. Test Lists - - Some tests ("allof" and "anyof", which implement logical "and" and - logical "or", respectively) may require more than a single test as an - argument. The test-list syntax element provides a way of grouping - tests. - - Example: if anyof (not exists ["From", "Date"], - header :contains "from" "fool@example.edu") { - discard; - } - -2.6. Arguments - - In order to specify what to do, most commands take arguments. There - are three types of arguments: positional, tagged, and optional. - -2.6.1. Positional Arguments - - Positional arguments are given to a command which discerns their - meaning based on their order. When a command takes positional - arguments, all positional arguments must be supplied and must be in - the order prescribed. - - - - -Showalter Standards Track [Page 9] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -2.6.2. Tagged Arguments - - This document provides for tagged arguments in the style of - CommonLISP. These are also similar to flags given to commands in - most command-line systems. - - A tagged argument is an argument for a command that begins with ":" - followed by a tag naming the argument, such as ":contains". This - argument means that zero or more of the next tokens have some - particular meaning depending on the argument. These next tokens may - be numbers or strings but they are never blocks. - - Tagged arguments are similar to positional arguments, except that - instead of the meaning being derived from the command, it is derived - from the tag. - - Tagged arguments must appear before positional arguments, but they - may appear in any order with other tagged arguments. For simplicity - of the specification, this is not expressed in the syntax definitions - with commands, but they still may be reordered arbitrarily provided - they appear before positional arguments. Tagged arguments may be - mixed with optional arguments. - - To simplify this specification, tagged arguments SHOULD NOT take - tagged arguments as arguments. - -2.6.3. Optional Arguments - - Optional arguments are exactly like tagged arguments except that they - may be left out, in which case a default value is implied. Because - optional arguments tend to result in shorter scripts, they have been - used far more than tagged arguments. - - One particularly noteworthy case is the ":comparator" argument, which - allows the user to specify which [ACAP] comparator will be used to - compare two strings, since different languages may impose different - orderings on UTF-8 [UTF-8] characters. - -2.6.4. Types of Arguments - - Abstractly, arguments may be literal data, tests, or blocks of - commands. In this way, an "if" control structure is merely a command - that happens to take a test and a block as arguments and may execute - the block of code. - - However, this abstraction is ambiguous from a parsing standpoint. - The grammar in section 9.2 presents a parsable version of this: - Arguments are string-lists, numbers, and tags, which may be followed - - - -Showalter Standards Track [Page 10] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - by a test or a test-list, which may be followed by a block of - commands. No more than one test or test list, nor more than one - block of commands, may be used, and commands that end with blocks of - commands do not end with semicolons. - -2.7. String Comparison - - When matching one string against another, there are a number of ways - of performing the match operation. These are accomplished with three - types of matches: an exact match, a substring match, and a wildcard - glob-style match. These are described below. - - In order to provide for matches between character sets and case - insensitivity, Sieve borrows ACAP's comparator registry. - - However, when a string represents the name of a header, the - comparator is never user-specified. Header comparisons are always - done with the "i;ascii-casemap" operator, i.e., case-insensitive - comparisons, because this is the way things are defined in the - message specification [IMAIL]. - -2.7.1. Match Type - - There are three match types describing the matching used in this - specification: ":is", ":contains", and ":matches". Match type - arguments are supplied to those commands which allow them to specify - what kind of match is to be performed. - - These are used as tagged arguments to tests that perform string - comparison. - - The ":contains" match type describes a substring match. If the value - argument contains the key argument as a substring, the match is true. - For instance, the string "frobnitzm" contains "frob" and "nit", but - not "fbm". The null key ("") is contained in all values. - - The ":is" match type describes an absolute match; if the contents of - the first string are absolutely the same as the contents of the - second string, they match. Only the string "frobnitzm" is the string - "frobnitzm". The null key ":is" and only ":is" the null value. - - The ":matches" version specifies a wildcard match using the - characters "*" and "?". "*" matches zero or more characters, and "?" - matches a single character. "?" and "*" may be escaped as "\\?" and - "\\*" in strings to match against themselves. The first backslash - escapes the second backslash; together, they escape the "*". This is - awkward, but it is commonplace in several programming languages that - use globs and regular expressions. - - - -Showalter Standards Track [Page 11] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - In order to specify what type of match is supposed to happen, - commands that support matching take optional tagged arguments - ":matches", ":is", and ":contains". Commands default to using ":is" - matching if no match type argument is supplied. Note that these - modifiers may interact with comparators; in particular, some - comparators are not suitable for matching with ":contains" or - ":matches". It is an error to use a comparator with ":contains" or - ":matches" that is not compatible with it. - - It is an error to give more than one of these arguments to a given - command. - - For convenience, the "MATCH-TYPE" syntax element is defined here as - follows: - - Syntax: ":is" / ":contains" / ":matches" - -2.7.2. Comparisons Across Character Sets - - All Sieve scripts are represented in UTF-8, but messages may involve - a number of character sets. In order for comparisons to work across - character sets, implementations SHOULD implement the following - behavior: - - Implementations decode header charsets to UTF-8. Two strings are - considered equal if their UTF-8 representations are identical. - Implementations should decode charsets represented in the forms - specified by [MIME] for both message headers and bodies. - Implementations must be capable of decoding US-ASCII, ISO-8859-1, - the ASCII subset of ISO-8859-* character sets, and UTF-8. - - If implementations fail to support the above behavior, they MUST - conform to the following: - - No two strings can be considered equal if one contains octets - greater than 127. - -2.7.3. Comparators - - In order to allow for language-independent, case-independent matches, - the match type may be coupled with a comparator name. Comparators - are described for [ACAP]; a registry is defined for ACAP, and this - specification uses that registry. - - ACAP defines multiple comparator types. Only equality types are used - in this specification. - - - - - -Showalter Standards Track [Page 12] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - All implementations MUST support the "i;octet" comparator (simply - compares octets) and the "i;ascii-casemap" comparator (which treats - uppercase and lowercase characters in the ASCII subset of UTF-8 as - the same). If left unspecified, the default is "i;ascii-casemap". - - Some comparators may not be usable with substring matches; that is, - they may only work with ":is". It is an error to try and use a - comparator with ":matches" or ":contains" that is not compatible with - it. - - A comparator is specified by the ":comparator" option with commands - that support matching. This option is followed by a string providing - the name of the comparator to be used. For convenience, the syntax - of a comparator is abbreviated to "COMPARATOR", and (repeated in - several tests) is as follows: - - Syntax: ":comparator" - - So in this example, - - Example: if header :contains :comparator "i;octet" "Subject" - "MAKE MONEY FAST" { - discard; - } - - would discard any message with subjects like "You can MAKE MONEY - FAST", but not "You can Make Money Fast", since the comparator used - is case-sensitive. - - Comparators other than i;octet and i;ascii-casemap must be declared - with require, as they are extensions. If a comparator declared with - require is not known, it is an error, and execution fails. If the - comparator is not declared with require, it is also an error, even if - the comparator is supported. (See 2.10.5.) - - Both ":matches" and ":contains" match types are compatible with the - "i;octet" and "i;ascii-casemap" comparators and may be used with - them. - - It is an error to give more than one of these arguments to a given - command. - -2.7.4. Comparisons Against Addresses - - Addresses are one of the most frequent things represented as strings. - These are structured, and being able to compare against the local- - part or the domain of an address is useful, so some tests that act - - - - -Showalter Standards Track [Page 13] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - exclusively on addresses take an additional optional argument that - specifies what the test acts on. - - These optional arguments are ":localpart", ":domain", and ":all", - which act on the local-part (left-side), the domain part (right- - side), and the whole address. - - The kind of comparison done, such as whether or not the test done is - case-insensitive, is specified as a comparator argument to the test. - - If an optional address-part is omitted, the default is ":all". - - It is an error to give more than one of these arguments to a given - command. - - For convenience, the "ADDRESS-PART" syntax element is defined here as - follows: - - Syntax: ":localpart" / ":domain" / ":all" - -2.8. Blocks - - Blocks are sets of commands enclosed within curly braces. Blocks are - supplied to commands so that the commands can implement control - commands. - - A control structure is a command that happens to take a test and a - block as one of its arguments; depending on the result of the test - supplied as another argument, it runs the code in the block some - number of times. - - With the commands supplied in this memo, there are no loops. The - control structures supplied--if, elsif, and else--run a block either - once or not at all. So there are two arguments, the test and the - block. - -2.9. Commands - - Sieve scripts are sequences of commands. Commands can take any of - the tokens above as arguments, and arguments may be either tagged or - positional arguments. Not all commands take all arguments. - - There are three kinds of commands: test commands, action commands, - and control commands. - - The simplest is an action command. An action command is an - identifier followed by zero or more arguments, terminated by a - semicolon. Action commands do not take tests or blocks as arguments. - - - -Showalter Standards Track [Page 14] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - A control command is similar, but it takes a test as an argument, and - ends with a block instead of a semicolon. - - A test command is used as part of a control command. It is used to - specify whether or not the block of code given to the control command - is executed. - -2.10. Evaluation - -2.10.1. Action Interaction - - Some actions cannot be used with other actions because the result - would be absurd. These restrictions are noted throughout this memo. - - Extension actions MUST state how they interact with actions defined - in this specification. - -2.10.2. Implicit Keep - - Previous experience with filtering systems suggests that cases tend - to be missed in scripts. To prevent errors, Sieve has an "implicit - keep". - - An implicit keep is a keep action (see 4.4) performed in absence of - any action that cancels the implicit keep. - - An implicit keep is performed if a message is not written to a - mailbox, redirected to a new address, or explicitly thrown out. That - is, if a fileinto, a keep, a redirect, or a discard is performed, an - implicit keep is not. - - Some actions may be defined to not cancel the implicit keep. These - actions may not directly affect the delivery of a message, and are - used for their side effects. None of the actions specified in this - document meet that criteria, but extension actions will. - - For instance, with any of the short messages offered above, the - following script produces no actions. - - Example: if size :over 500K { discard; } - - As a result, the implicit keep is taken. - -2.10.3. Message Uniqueness in a Mailbox - - Implementations SHOULD NOT deliver a message to the same folder more - than once, even if a script explicitly asks for a message to be - written to a mailbox twice. - - - -Showalter Standards Track [Page 15] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - The test for equality of two messages is implementation-defined. - - If a script asks for a message to be written to a mailbox twice, it - MUST NOT be treated as an error. - -2.10.4. Limits on Numbers of Actions - - Site policy MAY limit numbers of actions taken and MAY impose - restrictions on which actions can be used together. In the event - that a script hits a policy limit on the number of actions taken for - a particular message, an error occurs. - - Implementations MUST prohibit more than one reject. - - Implementations MUST allow at least one keep or one fileinto. If - fileinto is not implemented, implementations MUST allow at least one - keep. - - Implementations SHOULD prohibit reject when used with other actions. - -2.10.5. Extensions and Optional Features - - Because of the differing capabilities of many mail systems, several - features of this specification are optional. Before any of these - extensions can be executed, they must be declared with the "require" - action. - - If an extension is not enabled with "require", implementations MUST - treat it as if they did not support it at all. - - If a script does not understand an extension declared with require, - the script must not be used at all. Implementations MUST NOT execute - scripts which require unknown capability names. - - Note: The reason for this restriction is that prior experiences with - languages such as LISP and Tcl suggest that this is a workable - way of noting that a given script uses an extension. - - Experience with PostScript suggests that mechanisms that allow - a script to work around missing extensions are not used in - practice. - - Extensions which define actions MUST state how they interact with - actions discussed in the base specification. - - - - - - - -Showalter Standards Track [Page 16] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -2.10.6. Errors - - In any programming language, there are compile-time and run-time - errors. - - Compile-time errors are ones in syntax that are detectable if a - syntax check is done. - - Run-time errors are not detectable until the script is run. This - includes transient failures like disk full conditions, but also - includes issues like invalid combinations of actions. - - When an error occurs in a Sieve script, all processing stops. - - Implementations MAY choose to do a full parse, then evaluate the - script, then do all actions. Implementations might even go so far as - to ensure that execution is atomic (either all actions are executed - or none are executed). - - Other implementations may choose to parse and run at the same time. - Such implementations are simpler, but have issues with partial - failure (some actions happen, others don't). - - Implementations might even go so far as to ensure that scripts can - never execute an invalid set of actions (e.g., reject + fileinto) - before execution, although this could involve solving the Halting - Problem. - - This specification allows any of these approaches. Solving the - Halting Problem is considered extra credit. - - When an error happens, implementations MUST notify the user that an - error occurred, which actions (if any) were taken, and do an implicit - keep. - -2.10.7. Limits on Execution - - Implementations may limit certain constructs. However, this - specification places a lower bound on some of these limits. - - Implementations MUST support fifteen levels of nested blocks. - - Implementations MUST support fifteen levels of nested test lists. - -3. Control Commands - - Control structures are needed to allow for multiple and conditional - actions. - - - -Showalter Standards Track [Page 17] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -3.1. Control Structure If - - There are three pieces to if: "if", "elsif", and "else". Each is - actually a separate command in terms of the grammar. However, an - elsif MUST only follow an if, and an else MUST follow only either an - if or an elsif. An error occurs if these conditions are not met. - - Syntax: if - - Syntax: elsif - - Syntax: else - - The semantics are similar to those of any of the many other - programming languages these control commands appear in. When the - interpreter sees an "if", it evaluates the test associated with it. - If the test is true, it executes the block associated with it. - - If the test of the "if" is false, it evaluates the test of the first - "elsif" (if any). If the test of "elsif" is true, it runs the - elsif's block. An elsif may be followed by an elsif, in which case, - the interpreter repeats this process until it runs out of elsifs. - - When the interpreter runs out of elsifs, there may be an "else" case. - If there is, and none of the if or elsif tests were true, the - interpreter runs the else case. - - This provides a way of performing exactly one of the blocks in the - chain. - - In the following example, both Message A and B are dropped. - - Example: require "fileinto"; - if header :contains "from" "coyote" { - discard; - } elsif header :contains ["subject"] ["$$$"] { - discard; - } else { - fileinto "INBOX"; - } - - - When the script below is run over message A, it redirects the message - to acm@example.edu; message B, to postmaster@example.edu; any other - message is redirected to field@example.edu. - - - - - - -Showalter Standards Track [Page 18] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Example: if header :contains ["From"] ["coyote"] { - redirect "acm@example.edu"; - } elsif header :contains "Subject" "$$$" { - redirect "postmaster@example.edu"; - } else { - redirect "field@example.edu"; - } - - Note that this definition prohibits the "... else if ..." sequence - used by C. This is intentional, because this construct produces a - shift-reduce conflict. - -3.2. Control Structure Require - - Syntax: require - - The require action notes that a script makes use of a certain - extension. Such a declaration is required to use the extension, as - discussed in section 2.10.5. Multiple capabilities can be declared - with a single require. - - The require command, if present, MUST be used before anything other - than a require can be used. An error occurs if a require appears - after a command other than require. - - Example: require ["fileinto", "reject"]; - - Example: require "fileinto"; - require "vacation"; - -3.3. Control Structure Stop - - Syntax: stop - - The "stop" action ends all processing. If no actions have been - executed, then the keep action is taken. - -4. Action Commands - - This document supplies five actions that may be taken on a message: - keep, fileinto, redirect, reject, and discard. - - Implementations MUST support the "keep", "discard", and "redirect" - actions. - - Implementations SHOULD support "reject" and "fileinto". - - - - - -Showalter Standards Track [Page 19] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Implementations MAY limit the number of certain actions taken (see - section 2.10.4). - -4.1. Action reject - - Syntax: reject - - The optional "reject" action refuses delivery of a message by sending - back an [MDN] to the sender. It resends the message to the sender, - wrapping it in a "reject" form, noting that it was rejected by the - recipient. In the following script, message A is rejected and - returned to the sender. - - Example: if header :contains "from" "coyote@desert.example.org" { - reject "I am not taking mail from you, and I don't want - your birdseed, either!"; - } - - A reject message MUST take the form of a failure MDN as specified by - [MDN]. The human-readable portion of the message, the first - component of the MDN, contains the human readable message describing - the error, and it SHOULD contain additional text alerting the - original sender that mail was refused by a filter. This part of the - MDN might appear as follows: - - ------------------------------------------------------------ - Message was refused by recipient's mail filtering program. Reason - given was as follows: - - I am not taking mail from you, and I don't want your birdseed, - either! - ------------------------------------------------------------ - - The MDN action-value field as defined in the MDN specification MUST - be "deleted" and MUST have the MDN-sent-automatically and automatic- - action modes set. - - Because some implementations can not or will not implement the reject - command, it is optional. The capability string to be used with the - require command is "reject". - -4.2. Action fileinto - - Syntax: fileinto - - The "fileinto" action delivers the message into the specified folder. - Implementations SHOULD support fileinto, but in some environments - this may be impossible. - - - -Showalter Standards Track [Page 20] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - The capability string for use with the require command is "fileinto". - - In the following script, message A is filed into folder - "INBOX.harassment". - - Example: require "fileinto"; - if header :contains ["from"] "coyote" { - fileinto "INBOX.harassment"; - } - -4.3. Action redirect - - Syntax: redirect - - The "redirect" action is used to send the message to another user at - a supplied address, as a mail forwarding feature does. The - "redirect" action makes no changes to the message body or existing - headers, but it may add new headers. The "redirect" modifies the - envelope recipient. - - The redirect command performs an MTA-style "forward"--that is, what - you get from a .forward file using sendmail under UNIX. The address - on the SMTP envelope is replaced with the one on the redirect command - and the message is sent back out. (This is not an MUA-style forward, - which creates a new message with a different sender and message ID, - wrapping the old message in a new one.) - - A simple script can be used for redirecting all mail: - - Example: redirect "bart@example.edu"; - - Implementations SHOULD take measures to implement loop control, - possibly including adding headers to the message or counting received - headers. If an implementation detects a loop, it causes an error. - -4.4. Action keep - - Syntax: keep - - The "keep" action is whatever action is taken in lieu of all other - actions, if no filtering happens at all; generally, this simply means - to file the message into the user's main mailbox. This command - provides a way to execute this action without needing to know the - name of the user's main mailbox, providing a way to call it without - needing to understand the user's setup, or the underlying mail - system. - - - - - -Showalter Standards Track [Page 21] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - For instance, in an implementation where the IMAP server is running - scripts on behalf of the user at time of delivery, a keep command is - equivalent to a fileinto "INBOX". - - Example: if size :under 1M { keep; } else { discard; } - - Note that the above script is identical to the one below. - - Example: if not size :under 1M { discard; } - -4.5. Action discard - - Syntax: discard - - Discard is used to silently throw away the message. It does so by - simply canceling the implicit keep. If discard is used with other - actions, the other actions still happen. Discard is compatible with - all other actions. (For instance fileinto+discard is equivalent to - fileinto.) - - Discard MUST be silent; that is, it MUST NOT return a non-delivery - notification of any kind ([DSN], [MDN], or otherwise). - - In the following script, any mail from "idiot@example.edu" is thrown - out. - - Example: if header :contains ["from"] ["idiot@example.edu"] { - discard; - } - - While an important part of this language, "discard" has the potential - to create serious problems for users: Students who leave themselves - logged in to an unattended machine in a public computer lab may find - their script changed to just "discard". In order to protect users in - this situation (along with similar situations), implementations MAY - keep messages destroyed by a script for an indefinite period, and MAY - disallow scripts that throw out all mail. - -5. Test Commands - - Tests are used in conditionals to decide which part(s) of the - conditional to execute. - - Implementations MUST support these tests: "address", "allof", - "anyof", "exists", "false", "header", "not", "size", and "true". - - Implementations SHOULD support the "envelope" test. - - - - -Showalter Standards Track [Page 22] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -5.1. Test address - - Syntax: address [ADDRESS-PART] [COMPARATOR] [MATCH-TYPE] - - - The address test matches Internet addresses in structured headers - that contain addresses. It returns true if any header contains any - key in the specified part of the address, as modified by the - comparator and the match keyword. - - Like envelope and header, this test returns true if any combination - of the header-list and key-list arguments match. - - Internet email addresses [IMAIL] have the somewhat awkward - characteristic that the local-part to the left of the at-sign is - considered case sensitive, and the domain-part to the right of the - at-sign is case insensitive. The "address" command does not deal - with this itself, but provides the ADDRESS-PART argument for allowing - users to deal with it. - - The address primitive never acts on the phrase part of an email - address, nor on comments within that address. It also never acts on - group names, although it does act on the addresses within the group - construct. - - Implementations MUST restrict the address test to headers that - contain addresses, but MUST include at least From, To, Cc, Bcc, - Sender, Resent-From, Resent-To, and SHOULD include any other header - that utilizes an "address-list" structured header body. - - Example: if address :is :all "from" "tim@example.com" { - discard; - -5.2. Test allof - - Syntax: allof - - The allof test performs a logical AND on the tests supplied to it. - - Example: allof (false, false) => false - allof (false, true) => false - allof (true, true) => true - - The allof test takes as its argument a test-list. - - - - - - - -Showalter Standards Track [Page 23] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -5.3. Test anyof - - Syntax: anyof - - The anyof test performs a logical OR on the tests supplied to it. - - Example: anyof (false, false) => false - anyof (false, true) => true - anyof (true, true) => true - -5.4. Test envelope - - Syntax: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] - - - The "envelope" test is true if the specified part of the SMTP (or - equivalent) envelope matches the specified key. - - If one of the envelope-part strings is (case insensitive) "from", - then matching occurs against the FROM address used in the SMTP MAIL - command. - - If one of the envelope-part strings is (case insensitive) "to", then - matching occurs against the TO address used in the SMTP RCPT command - that resulted in this message getting delivered to this user. Note - that only the most recent TO is available, and only the one relevant - to this user. - - The envelope-part is a string list and may contain more than one - parameter, in which case all of the strings specified in the key-list - are matched against all parts given in the envelope-part list. - - Like address and header, this test returns true if any combination of - the envelope-part and key-list arguments is true. - - All tests against envelopes MUST drop source routes. - - If the SMTP transaction involved several RCPT commands, only the data - from the RCPT command that caused delivery to this user is available - in the "to" part of the envelope. - - If a protocol other than SMTP is used for message transport, - implementations are expected to adapt this command appropriately. - - The envelope command is optional. Implementations SHOULD support it, - but the necessary information may not be available in all cases. - - - - - -Showalter Standards Track [Page 24] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Example: require "envelope"; - if envelope :all :is "from" "tim@example.com" { - discard; - } - -5.5. Test exists - - Syntax: exists - - The "exists" test is true if the headers listed in the header-names - argument exist within the message. All of the headers must exist or - the test is false. - - The following example throws out mail that doesn't have a From header - and a Date header. - - Example: if not exists ["From","Date"] { - discard; - } - -5.6. Test false - - Syntax: false - - The "false" test always evaluates to false. - -5.7. Test header - - Syntax: header [COMPARATOR] [MATCH-TYPE] - - - The "header" test evaluates to true if any header name matches any - key. The type of match is specified by the optional match argument, - which defaults to ":is" if not specified, as specified in section - 2.6. - - Like address and envelope, this test returns true if any combination - of the string-list and key-list arguments match. - - If a header listed in the header-names argument exists, it contains - the null key (""). However, if the named header is not present, it - does not contain the null key. So if a message contained the header - - X-Caffeine: C8H10N4O2 - - - - - - - -Showalter Standards Track [Page 25] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - these tests on that header evaluate as follows: - - header :is ["X-Caffeine"] [""] => false - header :contains ["X-Caffeine"] [""] => true - -5.8. Test not - - Syntax: not - - The "not" test takes some other test as an argument, and yields the - opposite result. "not false" evaluates to "true" and "not true" - evaluates to "false". - -5.9. Test size - - Syntax: size <":over" / ":under"> - - The "size" test deals with the size of a message. It takes either a - tagged argument of ":over" or ":under", followed by a number - representing the size of the message. - - If the argument is ":over", and the size of the message is greater - than the number provided, the test is true; otherwise, it is false. - - If the argument is ":under", and the size of the message is less than - the number provided, the test is true; otherwise, it is false. - - Exactly one of ":over" or ":under" must be specified, and anything - else is an error. - - The size of a message is defined to be the number of octets from the - initial header until the last character in the message body. - - Note that for a message that is exactly 4,000 octets, the message is - neither ":over" 4000 octets or ":under" 4000 octets. - -5.10. Test true - - Syntax: true - - The "true" test always evaluates to true. - -6. Extensibility - - New control structures, actions, and tests can be added to the - language. Sites must make these features known to their users; this - document does not define a way to discover the list of extensions - supported by the server. - - - -Showalter Standards Track [Page 26] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Any extensions to this language MUST define a capability string that - uniquely identifies that extension. If a new version of an extension - changes the functionality of a previously defined extension, it MUST - use a different name. - - In a situation where there is a submission protocol and an extension - advertisement mechanism aware of the details of this language, - scripts submitted can be checked against the mail server to prevent - use of an extension that the server does not support. - - Extensions MUST state how they interact with constraints defined in - section 2.10, e.g., whether they cancel the implicit keep, and which - actions they are compatible and incompatible with. - -6.1. Capability String - - Capability strings are typically short strings describing what - capabilities are supported by the server. - - Capability strings beginning with "vnd." represent vendor-defined - extensions. Such extensions are not defined by Internet standards or - RFCs, but are still registered with IANA in order to prevent - conflicts. Extensions starting with "vnd." SHOULD be followed by the - name of the vendor and product, such as "vnd.acme.rocket-sled". - - The following capability strings are defined by this document: - - envelope The string "envelope" indicates that the implementation - supports the "envelope" command. - - fileinto The string "fileinto" indicates that the implementation - supports the "fileinto" command. - - reject The string "reject" indicates that the implementation - supports the "reject" command. - - comparator- The string "comparator-elbonia" is provided if the - implementation supports the "elbonia" comparator. - Therefore, all implementations have at least the - "comparator-i;octet" and "comparator-i;ascii-casemap" - capabilities. However, these comparators may be used - without being declared with require. - - - - - - - - - -Showalter Standards Track [Page 27] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -6.2. IANA Considerations - - In order to provide a standard set of extensions, a registry is - provided by IANA. Capability names may be registered on a first- - come, first-served basis. Extensions designed for interoperable use - SHOULD be defined as standards track or IESG approved experimental - RFCs. - -6.2.1. Template for Capability Registrations - - The following template is to be used for registering new Sieve - extensions with IANA. - - To: iana@iana.org - Subject: Registration of new Sieve extension - - Capability name: - Capability keyword: - Capability arguments: - Standards Track/IESG-approved experimental RFC number: - Person and email address to contact for further information: - -6.2.2. Initial Capability Registrations - - The following are to be added to the IANA registry for Sieve - extensions as the initial contents of the capability registry. - - Capability name: fileinto - Capability keyword: fileinto - Capability arguments: fileinto - Standards Track/IESG-approved experimental RFC number: - RFC 3028 (Sieve base spec) - Person and email address to contact for further information: - Tim Showalter - tjs@mirapoint.com - - Capability name: reject - Capability keyword: reject - Capability arguments: reject - Standards Track/IESG-approved experimental RFC number: - RFC 3028 (Sieve base spec) - Person and email address to contact for further information: - Tim Showalter - tjs@mirapoint.com - - - - - - - -Showalter Standards Track [Page 28] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Capability name: envelope - Capability keyword: envelope - Capability arguments: - envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] - - Standards Track/IESG-approved experimental RFC number: - RFC 3028 (Sieve base spec) - Person and email address to contact for further information: - Tim Showalter - tjs@mirapoint.com - - Capability name: comparator-* - Capability keyword: - comparator-* (anything starting with "comparator-") - Capability arguments: (none) - Standards Track/IESG-approved experimental RFC number: - RFC 3028, Sieve, by reference of - RFC 2244, Application Configuration Access Protocol - Person and email address to contact for further information: - Tim Showalter - tjs@mirapoint.com - -6.3. Capability Transport - - As the range of mail systems that this document is intended to apply - to is quite varied, a method of advertising which capabilities an - implementation supports is difficult due to the wide range of - possible implementations. Such a mechanism, however, should have - property that the implementation can advertise the complete set of - extensions that it supports. - -7. Transmission - - The MIME type for a Sieve script is "application/sieve". - - The registration of this type for RFC 2048 requirements is as - follows: - - Subject: Registration of MIME media type application/sieve - - MIME media type name: application - MIME subtype name: sieve - Required parameters: none - Optional parameters: none - Encoding considerations: Most sieve scripts will be textual, - written in UTF-8. When non-7bit characters are used, - quoted-printable is appropriate for transport systems - that require 7bit encoding. - - - -Showalter Standards Track [Page 29] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - Security considerations: Discussed in section 10 of RFC 3028. - Interoperability considerations: Discussed in section 2.10.5 - of RFC 3028. - Published specification: RFC 3028. - Applications which use this media type: sieve-enabled mail servers - Additional information: - Magic number(s): - File extension(s): .siv - Macintosh File Type Code(s): - Person & email address to contact for further information: - See the discussion list at ietf-mta-filters@imc.org. - Intended usage: - COMMON - Author/Change controller: - See Author information in RFC 3028. - -8. Parsing - - The Sieve grammar is separated into tokens and a separate grammar as - most programming languages are. - -8.1. Lexical Tokens - - Sieve scripts are encoded in UTF-8. The following assumes a valid - UTF-8 encoding; special characters in Sieve scripts are all ASCII. - - The following are tokens in Sieve: - - - identifiers - - tags - - numbers - - quoted strings - - multi-line strings - - other separators - - Blanks, horizontal tabs, CRLFs, and comments ("white space") are - ignored except as they separate tokens. Some white space is required - to separate otherwise adjacent tokens and in specific places in the - multi-line strings. - - The other separators are single individual characters, and are - mentioned explicitly in the grammar. - - The lexical structure of sieve is defined in the following BNF (as - described in [ABNF]): - - - - - - -Showalter Standards Track [Page 30] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - bracket-comment = "/*" *(CHAR-NOT-STAR / ("*" CHAR-NOT-SLASH)) "*/" - ;; No */ allowed inside a comment. - ;; (No * is allowed unless it is the last character, - ;; or unless it is followed by a character that isn't a - ;; slash.) - - CHAR-NOT-DOT = (%x01-09 / %x0b-0c / %x0e-2d / %x2f-ff) - ;; no dots, no CRLFs - - CHAR-NOT-CRLF = (%x01-09 / %x0b-0c / %x0e-ff) - - CHAR-NOT-SLASH = (%x00-57 / %x58-ff) - - CHAR-NOT-STAR = (%x00-51 / %x53-ff) - - comment = bracket-comment / hash-comment - - hash-comment = ( "#" *CHAR-NOT-CRLF CRLF ) - - identifier = (ALPHA / "_") *(ALPHA DIGIT "_") - - tag = ":" identifier - - number = 1*DIGIT [QUANTIFIER] - - QUANTIFIER = "K" / "M" / "G" - - quoted-string = DQUOTE *CHAR DQUOTE - ;; in general, \ CHAR inside a string maps to CHAR - ;; so \" maps to " and \\ maps to \ - ;; note that newlines and other characters are all allowed - ;; strings - - multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF) - *(multi-line-literal / multi-line-dotstuff) - "." CRLF - multi-line-literal = [CHAR-NOT-DOT *CHAR-NOT-CRLF] CRLF - multi-line-dotstuff = "." 1*CHAR-NOT-CRLF CRLF - ;; A line containing only "." ends the multi-line. - ;; Remove a leading '.' if followed by another '.'. - - white-space = 1*(SP / CRLF / HTAB) / comment - -8.2. Grammar - - The following is the grammar of Sieve after it has been lexically - interpreted. No white space or comments appear below. The start - symbol is "start". - - - -Showalter Standards Track [Page 31] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - argument = string-list / number / tag - - arguments = *argument [test / test-list] - - block = "{" commands "}" - - command = identifier arguments ( ";" / block ) - - commands = *command - - start = commands - - string = quoted-string / multi-line - - string-list = "[" string *("," string) "]" / string ;; if - there is only a single string, the brackets are optional - - test = identifier arguments - - test-list = "(" test *("," test) ")" - -9. Extended Example - - The following is an extended example of a Sieve script. Note that it - does not make use of the implicit keep. - - # - # Example Sieve Filter - # Declare any optional features or extension used by the script - # - require ["fileinto", "reject"]; - - # - # Reject any large messages (note that the four leading dots get - # "stuffed" to three) - # - if size :over 1M - { - reject text: - Please do not send me large attachments. - Put your file on a server and send me the URL. - Thank you. - .... Fred - . - ; - stop; - } - # - - - -Showalter Standards Track [Page 32] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - # Handle messages from known mailing lists - # Move messages from IETF filter discussion list to filter folder - # - if header :is "Sender" "owner-ietf-mta-filters@imc.org" - { - fileinto "filter"; # move to "filter" folder - } - # - # Keep all messages to or from people in my company - # - elsif address :domain :is ["From", "To"] "example.com" - { - keep; # keep in "In" folder - } - - # - # Try and catch unsolicited email. If a message is not to me, - # or it contains a subject known to be spam, file it away. - # - elsif anyof (not address :all :contains - ["To", "Cc", "Bcc"] "me@example.com", - header :matches "subject" - ["*make*money*fast*", "*university*dipl*mas*"]) - { - # If message header does not contain my address, - # it's from a list. - fileinto "spam"; # move to "spam" folder - } - else - { - # Move all other (non-company) mail to "personal" - # folder. - fileinto "personal"; - } - - - - - - - - - - - - - - - - - -Showalter Standards Track [Page 33] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -10. Security Considerations - - Users must get their mail. It is imperative that whatever method - implementations use to store the user-defined filtering scripts be - secure. - - It is equally important that implementations sanity-check the user's - scripts, and not allow users to create on-demand mailbombs. For - instance, an implementation that allows a user to reject or redirect - multiple times to a single message might also allow a user to create - a mailbomb triggered by mail from a specific user. Site- or - implementation-defined limits on actions are useful for this. - - Several commands, such as "discard", "redirect", and "fileinto" allow - for actions to be taken that are potentially very dangerous. - - Implementations SHOULD take measures to prevent languages from - looping. - -11. Acknowledgments - - I am very thankful to Chris Newman for his support and his ABNF - syntax checker, to John Myers and Steve Hole for outlining the - requirements for the original drafts, to Larry Greenfield for nagging - me about the grammar and finally fixing it, to Greg Sereda for - repeatedly fixing and providing examples, to Ned Freed for fixing - everything else, to Rob Earhart for an early implementation and a - great deal of help, and to Randall Gellens for endless amounts of - proofreading. I am grateful to Carnegie Mellon University where most - of the work on this document was done. I am also indebted to all of - the readers of the ietf-mta-filters@imc.org mailing list. - -12. Author's Address - - Tim Showalter - Mirapoint, Inc. - 909 Hermosa Court - Sunnyvale, CA 94085 - - EMail: tjs@mirapoint.com - -13. References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 2234, November 1997. - - - - - - -Showalter Standards Track [Page 34] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - - [ACAP] Newman, C. and J. G. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November 1997. - - [BINARY-SI] "Standard IEC 60027-2: Letter symbols to be used in - electrical technology - Part 2: Telecommunications and - electronics", January 1999. - - [DSN] Moore, K. and G. Vaudreuil, "An Extensible Message Format - for Delivery Status Notifications", RFC 1894, January - 1996. - - [FLAMES] Borenstein, N, and C. Thyberg, "Power, Ease of Use, and - Cooperative Work in a Practical Multimedia Message - System", Int. J. of Man-Machine Studies, April, 1991. - Reprinted in Computer-Supported Cooperative Work and - Groupware, Saul Greenberg, editor, Harcourt Brace - Jovanovich, 1991. Reprinted in Readings in Groupware and - Computer-Supported Cooperative Work, Ronald Baecker, - editor, Morgan Kaufmann, 1993. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [IMAP] Crispin, M., "Internet Message Access Protocol - version - 4rev1", RFC 2060, December 1996. - - [IMAIL] Crocker, D., "Standard for the Format of ARPA Internet - Text Messages", STD 11, RFC 822, August 1982. - - [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [MDN] Fajman, R., "An Extensible Message Format for Message - Disposition Notifications", RFC 2298, March 1998. - - [RFC1123] Braden, R., "Requirements for Internet Hosts -- - Application and Support", STD 3, RFC 1123, November 1989. - - [SMTP] Postel, J., "Simple Mail Transfer Protocol", STD 10, RFC - 821, August 1982. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of Unicode - and ISO 10646", RFC 2044, October 1996. - - - - - - - -Showalter Standards Track [Page 35] - -RFC 3028 Sieve: A Mail Filtering Language January 2001 - - -14. Full Copyright Statement - - Copyright (C) The Internet Society (2001). All Rights Reserved. - - This document and translations of it may be copied and furnished to - others, and derivative works that comment on or otherwise explain it - or assist in its implementation may be prepared, copied, published - and distributed, in whole or in part, without restriction of any - kind, provided that the above copyright notice and this paragraph are - included on all such copies and derivative works. However, this - document itself may not be modified in any way, such as by removing - the copyright notice or references to the Internet Society or other - Internet organizations, except as needed for the purpose of - developing Internet standards in which case the procedures for - copyrights defined in the Internet Standards process must be - followed, or as required to translate it into languages other than - English. - - The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. - - This document and the information contained herein is provided on an - "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING - TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING - BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION - HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF - MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - - - - - - - - - - - - - -Showalter Standards Track [Page 36] - diff --git a/src/site/site.xml b/src/site/site.xml index 2b397c4..c9d2e6f 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -36,10 +36,10 @@ - - - - + + + + ${reports} -- 1.9.1