diff options
| author | Thomas Schmid <schmid-thomas@gmx.net> | 2018-12-18 23:57:25 +0300 |
|---|---|---|
| committer | Thomas Schmid <schmid-thomas@gmx.net> | 2018-12-18 23:57:25 +0300 |
| commit | 7718470582eb5b68f9d7ce31b43fbc73eeec57f2 (patch) | |
| tree | badef6b32477ac722903653fbe1c114f95827266 /docs | |
| parent | e57be7ea990b897132d50abdd970fb5208e7f0dc (diff) | |
Move RFCs to separate folder as doc is already use by github pages
Diffstat (limited to 'docs')
24 files changed, 0 insertions, 21063 deletions
diff --git a/docs/Cyrus IMAP Server Protocol Specifications.URL b/docs/Cyrus IMAP Server Protocol Specifications.URL deleted file mode 100755 index 76949fa9..00000000 --- a/docs/Cyrus IMAP Server Protocol Specifications.URL +++ /dev/null @@ -1,2 +0,0 @@ -[InternetShortcut]
-URL=http://asg.web.cmu.edu/cyrus/download/imapd/specs.html
diff --git a/docs/Sieve Status Pages.URL b/docs/Sieve Status Pages.URL deleted file mode 100755 index f7871f68..00000000 --- a/docs/Sieve Status Pages.URL +++ /dev/null @@ -1,2 +0,0 @@ -[InternetShortcut]
-URL=http://tools.ietf.org/wg/sieve/draft-ietf-sieve-3028bis/
diff --git a/docs/[rfc2014] HMAC/rfc2104.pdf b/docs/[rfc2014] HMAC/rfc2104.pdf Binary files differdeleted file mode 100755 index abf678a2..00000000 --- a/docs/[rfc2014] HMAC/rfc2104.pdf +++ /dev/null diff --git a/docs/[rfc2014] HMAC/rfc2104.txt b/docs/[rfc2014] HMAC/rfc2104.txt deleted file mode 100755 index 1fb8fe11..00000000 --- a/docs/[rfc2014] HMAC/rfc2104.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - - - - -Network Working Group H. Krawczyk -Request for Comments: 2104 IBM -Category: Informational M. Bellare - UCSD - R. Canetti - IBM - February 1997 - - - HMAC: Keyed-Hashing for Message Authentication - -Status of This Memo - - This memo provides information for the Internet community. This memo - does not specify an Internet standard of any kind. Distribution of - this memo is unlimited. - -Abstract - - This document describes HMAC, a mechanism for message authentication - using cryptographic hash functions. HMAC can be used with any - iterative cryptographic hash function, e.g., MD5, SHA-1, in - combination with a secret shared key. The cryptographic strength of - HMAC depends on the properties of the underlying hash function. - -1. Introduction - - Providing a way to check the integrity of information transmitted - over or stored in an unreliable medium is a prime necessity in the - world of open computing and communications. Mechanisms that provide - such integrity check based on a secret key are usually called - "message authentication codes" (MAC). Typically, message - authentication codes are used between two parties that share a secret - key in order to validate information transmitted between these - parties. In this document we present such a MAC mechanism based on - cryptographic hash functions. This mechanism, called HMAC, is based - on work by the authors [BCK1] where the construction is presented and - cryptographically analyzed. We refer to that work for the details on - the rationale and security analysis of HMAC, and its comparison to - other keyed-hash methods. - - - - - - - - - - - -Krawczyk, et. al. Informational [Page 1] - -RFC 2104 HMAC February 1997 - - - HMAC can be used in combination with any iterated cryptographic hash - function. MD5 and SHA-1 are examples of such hash functions. HMAC - also uses a secret key for calculation and verification of the - message authentication values. The main goals behind this - construction are - - * To use, without modifications, available hash functions. - In particular, hash functions that perform well in software, - and for which code is freely and widely available. - - * To preserve the original performance of the hash function without - incurring a significant degradation. - - * To use and handle keys in a simple way. - - * To have a well understood cryptographic analysis of the strength of - the authentication mechanism based on reasonable assumptions on the - underlying hash function. - - * To allow for easy replaceability of the underlying hash function in - case that faster or more secure hash functions are found or - required. - - This document specifies HMAC using a generic cryptographic hash - function (denoted by H). Specific instantiations of HMAC need to - define a particular hash function. Current candidates for such hash - functions include SHA-1 [SHA], MD5 [MD5], RIPEMD-128/160 [RIPEMD]. - These different realizations of HMAC will be denoted by HMAC-SHA1, - HMAC-MD5, HMAC-RIPEMD, etc. - - Note: To the date of writing of this document MD5 and SHA-1 are the - most widely used cryptographic hash functions. MD5 has been recently - shown to be vulnerable to collision search attacks [Dobb]. This - attack and other currently known weaknesses of MD5 do not compromise - the use of MD5 within HMAC as specified in this document (see - [Dobb]); however, SHA-1 appears to be a cryptographically stronger - function. To this date, MD5 can be considered for use in HMAC for - applications where the superior performance of MD5 is critical. In - any case, implementers and users need to be aware of possible - cryptanalytic developments regarding any of these cryptographic hash - functions, and the eventual need to replace the underlying hash - function. (See section 6 for more information on the security of - HMAC.) - - - - - - - - -Krawczyk, et. al. Informational [Page 2] - -RFC 2104 HMAC February 1997 - - -2. Definition of HMAC - - The definition of HMAC requires a cryptographic hash function, which - we denote by H, and a secret key K. We assume H to be a cryptographic - hash function where data is hashed by iterating a basic compression - function on blocks of data. We denote by B the byte-length of such - blocks (B=64 for all the above mentioned examples of hash functions), - and by L the byte-length of hash outputs (L=16 for MD5, L=20 for - SHA-1). The authentication key K can be of any length up to B, the - block length of the hash function. Applications that use keys longer - than B bytes will first hash the key using H and then use the - resultant L byte string as the actual key to HMAC. In any case the - minimal recommended length for K is L bytes (as the hash output - length). See section 3 for more information on keys. - - We define two fixed and different strings ipad and opad as follows - (the 'i' and 'o' are mnemonics for inner and outer): - - ipad = the byte 0x36 repeated B times - opad = the byte 0x5C repeated B times. - - To compute HMAC over the data `text' we perform - - H(K XOR opad, H(K XOR ipad, text)) - - Namely, - - (1) append zeros to the end of K to create a B byte string - (e.g., if K is of length 20 bytes and B=64, then K will be - appended with 44 zero bytes 0x00) - (2) XOR (bitwise exclusive-OR) the B byte string computed in step - (1) with ipad - (3) append the stream of data 'text' to the B byte string resulting - from step (2) - (4) apply H to the stream generated in step (3) - (5) XOR (bitwise exclusive-OR) the B byte string computed in - step (1) with opad - (6) append the H result from step (4) to the B byte string - resulting from step (5) - (7) apply H to the stream generated in step (6) and output - the result - - For illustration purposes, sample code based on MD5 is provided as an - appendix. - - - - - - - -Krawczyk, et. al. Informational [Page 3] - -RFC 2104 HMAC February 1997 - - -3. Keys - - The key for HMAC can be of any length (keys longer than B bytes are - first hashed using H). However, less than L bytes is strongly - discouraged as it would decrease the security strength of the - function. Keys longer than L bytes are acceptable but the extra - length would not significantly increase the function strength. (A - longer key may be advisable if the randomness of the key is - considered weak.) - - Keys need to be chosen at random (or using a cryptographically strong - pseudo-random generator seeded with a random seed), and periodically - refreshed. (Current attacks do not indicate a specific recommended - frequency for key changes as these attacks are practically - infeasible. However, periodic key refreshment is a fundamental - security practice that helps against potential weaknesses of the - function and keys, and limits the damage of an exposed key.) - -4. Implementation Note - - HMAC is defined in such a way that the underlying hash function H can - be used with no modification to its code. In particular, it uses the - function H with the pre-defined initial value IV (a fixed value - specified by each iterative hash function to initialize its - compression function). However, if desired, a performance - improvement can be achieved at the cost of (possibly) modifying the - code of H to support variable IVs. - - The idea is that the intermediate results of the compression function - on the B-byte blocks (K XOR ipad) and (K XOR opad) can be precomputed - only once at the time of generation of the key K, or before its first - use. These intermediate results are stored and then used to - initialize the IV of H each time that a message needs to be - authenticated. This method saves, for each authenticated message, - the application of the compression function of H on two B-byte blocks - (i.e., on (K XOR ipad) and (K XOR opad)). Such a savings may be - significant when authenticating short streams of data. We stress - that the stored intermediate values need to be treated and protected - the same as secret keys. - - Choosing to implement HMAC in the above way is a decision of the - local implementation and has no effect on inter-operability. - - - - - - - - - -Krawczyk, et. al. Informational [Page 4] - -RFC 2104 HMAC February 1997 - - -5. Truncated output - - A well-known practice with message authentication codes is to - truncate the output of the MAC and output only part of the bits - (e.g., [MM, ANSI]). Preneel and van Oorschot [PV] show some - analytical advantages of truncating the output of hash-based MAC - functions. The results in this area are not absolute as for the - overall security advantages of truncation. It has advantages (less - information on the hash result available to an attacker) and - disadvantages (less bits to predict for the attacker). Applications - of HMAC can choose to truncate the output of HMAC by outputting the t - leftmost bits of the HMAC computation for some parameter t (namely, - the computation is carried in the normal way as defined in section 2 - above but the end result is truncated to t bits). We recommend that - the output length t be not less than half the length of the hash - output (to match the birthday attack bound) and not less than 80 bits - (a suitable lower bound on the number of bits that need to be - predicted by an attacker). We propose denoting a realization of HMAC - that uses a hash function H with t bits of output as HMAC-H-t. For - example, HMAC-SHA1-80 denotes HMAC computed using the SHA-1 function - and with the output truncated to 80 bits. (If the parameter t is not - specified, e.g. HMAC-MD5, then it is assumed that all the bits of the - hash are output.) - -6. Security - - The security of the message authentication mechanism presented here - depends on cryptographic properties of the hash function H: the - resistance to collision finding (limited to the case where the - initial value is secret and random, and where the output of the - function is not explicitly available to the attacker), and the - message authentication property of the compression function of H when - applied to single blocks (in HMAC these blocks are partially unknown - to an attacker as they contain the result of the inner H computation - and, in particular, cannot be fully chosen by the attacker). - - These properties, and actually stronger ones, are commonly assumed - for hash functions of the kind used with HMAC. In particular, a hash - function for which the above properties do not hold would become - unsuitable for most (probably, all) cryptographic applications, - including alternative message authentication schemes based on such - functions. (For a complete analysis and rationale of the HMAC - function the reader is referred to [BCK1].) - - - - - - - - -Krawczyk, et. al. Informational [Page 5] - -RFC 2104 HMAC February 1997 - - - Given the limited confidence gained so far as for the cryptographic - strength of candidate hash functions, it is important to observe the - following two properties of the HMAC construction and its secure use - for message authentication: - - 1. The construction is independent of the details of the particular - hash function H in use and then the latter can be replaced by any - other secure (iterative) cryptographic hash function. - - 2. Message authentication, as opposed to encryption, has a - "transient" effect. A published breaking of a message authentication - scheme would lead to the replacement of that scheme, but would have - no adversarial effect on information authenticated in the past. This - is in sharp contrast with encryption, where information encrypted - today may suffer from exposure in the future if, and when, the - encryption algorithm is broken. - - The strongest attack known against HMAC is based on the frequency of - collisions for the hash function H ("birthday attack") [PV,BCK2], and - is totally impractical for minimally reasonable hash functions. - - As an example, if we consider a hash function like MD5 where the - output length equals L=16 bytes (128 bits) the attacker needs to - acquire the correct message authentication tags computed (with the - _same_ secret key K!) on about 2**64 known plaintexts. This would - require the processing of at least 2**64 blocks under H, an - impossible task in any realistic scenario (for a block length of 64 - bytes this would take 250,000 years in a continuous 1Gbps link, and - without changing the secret key K during all this time). This attack - could become realistic only if serious flaws in the collision - behavior of the function H are discovered (e.g. collisions found - after 2**30 messages). Such a discovery would determine the immediate - replacement of the function H (the effects of such failure would be - far more severe for the traditional uses of H in the context of - digital signatures, public key certificates, etc.). - - Note: this attack needs to be strongly contrasted with regular - collision attacks on cryptographic hash functions where no secret key - is involved and where 2**64 off-line parallelizable (!) operations - suffice to find collisions. The latter attack is approaching - feasibility [VW] while the birthday attack on HMAC is totally - impractical. (In the above examples, if one uses a hash function - with, say, 160 bit of output then 2**64 should be replaced by 2**80.) - - - - - - - - -Krawczyk, et. al. Informational [Page 6] - -RFC 2104 HMAC February 1997 - - - A correct implementation of the above construction, the choice of - random (or cryptographically pseudorandom) keys, a secure key - exchange mechanism, frequent key refreshments, and good secrecy - protection of keys are all essential ingredients for the security of - the integrity verification mechanism provided by HMAC. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Krawczyk, et. al. Informational [Page 7] - -RFC 2104 HMAC February 1997 - - -Appendix -- Sample Code - - For the sake of illustration we provide the following sample code for - the implementation of HMAC-MD5 as well as some corresponding test - vectors (the code is based on MD5 code as described in [MD5]). - -/* -** Function: hmac_md5 -*/ - -void -hmac_md5(text, text_len, key, key_len, digest) -unsigned char* text; /* pointer to data stream */ -int text_len; /* length of data stream */ -unsigned char* key; /* pointer to authentication key */ -int key_len; /* length of authentication key */ -caddr_t digest; /* caller digest to be filled in */ - -{ - MD5_CTX context; - unsigned char k_ipad[65]; /* inner padding - - * key XORd with ipad - */ - unsigned char k_opad[65]; /* outer padding - - * key XORd with opad - */ - unsigned char tk[16]; - int i; - /* if key is longer than 64 bytes reset it to key=MD5(key) */ - if (key_len > 64) { - - MD5_CTX tctx; - - MD5Init(&tctx); - MD5Update(&tctx, key, key_len); - MD5Final(tk, &tctx); - - key = tk; - key_len = 16; - } - - /* - * the HMAC_MD5 transform looks like: - * - * MD5(K XOR opad, MD5(K XOR ipad, text)) - * - * where K is an n byte key - * ipad is the byte 0x36 repeated 64 times - - - -Krawczyk, et. al. Informational [Page 8] - -RFC 2104 HMAC February 1997 - - - * opad is the byte 0x5c repeated 64 times - * and text is the data being protected - */ - - /* start out by storing key in pads */ - bzero( k_ipad, sizeof k_ipad); - bzero( k_opad, sizeof k_opad); - bcopy( key, k_ipad, key_len); - bcopy( key, k_opad, key_len); - - /* XOR key with ipad and opad values */ - for (i=0; i<64; i++) { - k_ipad[i] ^= 0x36; - k_opad[i] ^= 0x5c; - } - /* - * perform inner MD5 - */ - MD5Init(&context); /* init context for 1st - * pass */ - MD5Update(&context, k_ipad, 64) /* start with inner pad */ - MD5Update(&context, text, text_len); /* then text of datagram */ - MD5Final(digest, &context); /* finish up 1st pass */ - /* - * perform outer MD5 - */ - MD5Init(&context); /* init context for 2nd - * pass */ - MD5Update(&context, k_opad, 64); /* start with outer pad */ - MD5Update(&context, digest, 16); /* then results of 1st - * hash */ - MD5Final(digest, &context); /* finish up 2nd pass */ -} - -Test Vectors (Trailing '\0' of a character string not included in test): - - key = 0x0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b0b - key_len = 16 bytes - data = "Hi There" - data_len = 8 bytes - digest = 0x9294727a3638bb1c13f48ef8158bfc9d - - key = "Jefe" - data = "what do ya want for nothing?" - data_len = 28 bytes - digest = 0x750c783e6ab0b503eaa86e310a5db738 - - key = 0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA - - - -Krawczyk, et. al. Informational [Page 9] - -RFC 2104 HMAC February 1997 - - - key_len 16 bytes - data = 0xDDDDDDDDDDDDDDDDDDDD... - ..DDDDDDDDDDDDDDDDDDDD... - ..DDDDDDDDDDDDDDDDDDDD... - ..DDDDDDDDDDDDDDDDDDDD... - ..DDDDDDDDDDDDDDDDDDDD - data_len = 50 bytes - digest = 0x56be34521d144c88dbb8c733f0e8b3f6 - -Acknowledgments - - Pau-Chen Cheng, Jeff Kraemer, and Michael Oehler, have provided - useful comments on early drafts, and ran the first interoperability - tests of this specification. Jeff and Pau-Chen kindly provided the - sample code and test vectors that appear in the appendix. Burt - Kaliski, Bart Preneel, Matt Robshaw, Adi Shamir, and Paul van - Oorschot have provided useful comments and suggestions during the - investigation of the HMAC construction. - -References - - [ANSI] ANSI X9.9, "American National Standard for Financial - Institution Message Authentication (Wholesale)," American - Bankers Association, 1981. Revised 1986. - - [Atk] Atkinson, R., "IP Authentication Header", RFC 1826, August - 1995. - - [BCK1] M. Bellare, R. Canetti, and H. Krawczyk, - "Keyed Hash Functions and Message Authentication", - Proceedings of Crypto'96, LNCS 1109, pp. 1-15. - (http://www.research.ibm.com/security/keyed-md5.html) - - [BCK2] M. Bellare, R. Canetti, and H. Krawczyk, - "Pseudorandom Functions Revisited: The Cascade Construction", - Proceedings of FOCS'96. - - [Dobb] H. Dobbertin, "The Status of MD5 After a Recent Attack", - RSA Labs' CryptoBytes, Vol. 2 No. 2, Summer 1996. - http://www.rsa.com/rsalabs/pubs/cryptobytes.html - - [PV] B. Preneel and P. van Oorschot, "Building fast MACs from hash - functions", Advances in Cryptology -- CRYPTO'95 Proceedings, - Lecture Notes in Computer Science, Springer-Verlag Vol.963, - 1995, pp. 1-14. - - [MD5] Rivest, R., "The MD5 Message-Digest Algorithm", - RFC 1321, April 1992. - - - -Krawczyk, et. al. Informational [Page 10] - -RFC 2104 HMAC February 1997 - - - [MM] Meyer, S. and Matyas, S.M., Cryptography, New York Wiley, - 1982. - - [RIPEMD] H. Dobbertin, A. Bosselaers, and B. Preneel, "RIPEMD-160: A - strengthened version of RIPEMD", Fast Software Encryption, - LNCS Vol 1039, pp. 71-82. - ftp://ftp.esat.kuleuven.ac.be/pub/COSIC/bosselae/ripemd/. - - [SHA] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995. - - [Tsu] G. Tsudik, "Message authentication with one-way hash - functions", In Proceedings of Infocom'92, May 1992. - (Also in "Access Control and Policy Enforcement in - Internetworks", Ph.D. Dissertation, Computer Science - Department, University of Southern California, April 1991.) - - [VW] P. van Oorschot and M. Wiener, "Parallel Collision - Search with Applications to Hash Functions and Discrete - Logarithms", Proceedings of the 2nd ACM Conf. Computer and - Communications Security, Fairfax, VA, November 1994. - -Authors' Addresses - - Hugo Krawczyk - IBM T.J. Watson Research Center - P.O.Box 704 - Yorktown Heights, NY 10598 - - EMail: hugo@watson.ibm.com - - Mihir Bellare - Dept of Computer Science and Engineering - Mail Code 0114 - University of California at San Diego - 9500 Gilman Drive - La Jolla, CA 92093 - - EMail: mihir@cs.ucsd.edu - - Ran Canetti - IBM T.J. Watson Research Center - P.O.Box 704 - Yorktown Heights, NY 10598 - - EMail: canetti@watson.ibm.com - - - - - - -Krawczyk, et. al. Informational [Page 11] - diff --git a/docs/[rfc2195]/rfc2195.pdf b/docs/[rfc2195]/rfc2195.pdf Binary files differdeleted file mode 100755 index bc089319..00000000 --- a/docs/[rfc2195]/rfc2195.pdf +++ /dev/null diff --git a/docs/[rfc2195]/rfc2195.txt b/docs/[rfc2195]/rfc2195.txt deleted file mode 100755 index 4a2725bf..00000000 --- a/docs/[rfc2195]/rfc2195.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Network Working Group J. Klensin -Request for Comments: 2195 R. Catoe -Category: Standards Track P. Krumviede -Obsoletes: 2095 MCI - September 1997 - - - IMAP/POP AUTHorize Extension for Simple Challenge/Response - -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. - -Abstract - - While IMAP4 supports a number of strong authentication mechanisms as - described in RFC 1731, it lacks any mechanism that neither passes - cleartext, reusable passwords across the network nor requires either - a significant security infrastructure or that the mail server update - a mail-system-wide user authentication file on each mail access. - This specification provides a simple challenge-response - authentication protocol that is suitable for use with IMAP4. Since - it utilizes Keyed-MD5 digests and does not require that the secret be - stored in the clear on the server, it may also constitute an - improvement on APOP for POP3 use as specified in RFC 1734. - -1. Introduction - - Existing Proposed Standards specify an AUTHENTICATE mechanism for the - IMAP4 protocol [IMAP, IMAP-AUTH] and a parallel AUTH mechanism for - the POP3 protocol [POP3-AUTH]. The AUTHENTICATE mechanism is - intended to be extensible; the four methods specified in [IMAP-AUTH] - are all fairly powerful and require some security infrastructure to - support. The base POP3 specification [POP3] also contains a - lightweight challenge-response mechanism called APOP. APOP is - associated with most of the risks associated with such protocols: in - particular, it requires that both the client and server machines have - access to the shared secret in cleartext form. CRAM offers a method - for avoiding such cleartext storage while retaining the algorithmic - simplicity of APOP in using only MD5, though in a "keyed" method. - - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 1] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - At present, IMAP [IMAP] lacks any facility corresponding to APOP. - The only alternative to the strong mechanisms identified in [IMAP- - AUTH] is a presumably cleartext username and password, supported - through the LOGIN command in [IMAP]. This document describes a - simple challenge-response mechanism, similar to APOP and PPP CHAP - [PPP], that can be used with IMAP (and, in principle, with POP3). - - This mechanism also has the advantage over some possible alternatives - of not requiring that the server maintain information about email - "logins" on a per-login basis. While mechanisms that do require such - per-login history records may offer enhanced security, protocols such - as IMAP, which may have several connections between a given client - and server open more or less simultaneous, may make their - implementation particularly challenging. - -2. Challenge-Response Authentication Mechanism (CRAM) - - The authentication type associated with CRAM is "CRAM-MD5". - - The data encoded in the first ready response contains an - presumptively arbitrary string of random digits, a timestamp, and the - fully-qualified primary host name of the server. The syntax of the - unencoded form must correspond to that of an RFC 822 'msg-id' - [RFC822] as described in [POP3]. - - The client makes note of the data and then responds with a string - consisting of the user name, a space, and a 'digest'. The latter is - computed by applying the keyed MD5 algorithm from [KEYED-MD5] where - the key is a shared secret and the digested text is the timestamp - (including angle-brackets). - - This shared secret is a string known only to the client and server. - The `digest' parameter itself is a 16-octet value which is sent in - hexadecimal format, using lower-case ASCII characters. - - When the server receives this client response, it verifies the digest - provided. If the digest is correct, the server should consider the - client authenticated and respond appropriately. - - Keyed MD5 is chosen for this application because of the greater - security imparted to authentication of short messages. In addition, - the use of the techniques described in [KEYED-MD5] for precomputation - of intermediate results make it possible to avoid explicit cleartext - storage of the shared secret on the server system by instead storing - the intermediate results which are known as "contexts". - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 2] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - CRAM does not support a protection mechanism. - - Example: - - The examples in this document show the use of the CRAM mechanism with - the IMAP4 AUTHENTICATE command [IMAP-AUTH]. The base64 encoding of - the challenges and responses is part of the IMAP4 AUTHENTICATE - command, not part of the CRAM specification itself. - - S: * OK IMAP4 Server - C: A0001 AUTHENTICATE CRAM-MD5 - S: + PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+ - C: dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw - S: A0001 OK CRAM authentication successful - - In this example, the shared secret is the string - 'tanstaaftanstaaf'. Hence, the Keyed MD5 digest is produced by - calculating - - MD5((tanstaaftanstaaf XOR opad), - MD5((tanstaaftanstaaf XOR ipad), - <1896.697170952@postoffice.reston.mci.net>)) - - where ipad and opad are as defined in the keyed-MD5 Work in - Progress [KEYED-MD5] and the string shown in the challenge is the - base64 encoding of <1896.697170952@postoffice.reston.mci.net>. The - shared secret is null-padded to a length of 64 bytes. If the - shared secret is longer than 64 bytes, the MD5 digest of the - shared secret is used as a 16 byte input to the keyed MD5 - calculation. - - This produces a digest value (in hexadecimal) of - - b913a602c7eda7a495b4e6e7334d3890 - - The user name is then prepended to it, forming - - tim b913a602c7eda7a495b4e6e7334d3890 - - Which is then base64 encoded to meet the requirements of the IMAP4 - AUTHENTICATE command (or the similar POP3 AUTH command), yielding - - dGltIGI5MTNhNjAyYzdlZGE3YTQ5NWI0ZTZlNzMzNGQzODkw - - - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 3] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - -3. References - - [CHAP] Lloyd, B., and W. Simpson, "PPP Authentication Protocols", - RFC 1334, October 1992. - - [IMAP] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, University of Washington, December 1996. - - [IMAP-AUTH] Myers, J., "IMAP4 Authentication Mechanisms", - RFC 1731, Carnegie Mellon, December 1994. - - [KEYED-MD5] Krawczyk, Bellare, Canetti, "HMAC: Keyed-Hashing for - Message Authentication", RFC 2104, February 1997. - - [MD5] Rivest, R., "The MD5 Message Digest Algorithm", - RFC 1321, MIT Laboratory for Computer Science, April 1992. - - [POP3] Myers, J., and M. Rose, "Post Office Protocol - Version 3", - STD 53, RFC 1939, Carnegie Mellon, May 1996. - - [POP3-AUTH] Myers, J., "POP3 AUTHentication command", RFC 1734, - Carnegie Mellon, December, 1994. - -4. Security Considerations - - It is conjectured that use of the CRAM authentication mechanism - provides origin identification and replay protection for a session. - Accordingly, a server that implements both a cleartext password - command and this authentication type should not allow both methods of - access for a given user. - - While the saving, on the server, of "contexts" (see section 2) is - marginally better than saving the shared secrets in cleartext as is - required by CHAP [CHAP] and APOP [POP3], it is not sufficient to - protect the secrets if the server itself is compromised. - Consequently, servers that store the secrets or contexts must both be - protected to a level appropriate to the potential information value - in user mailboxes and identities. - - As the length of the shared secret increases, so does the difficulty - of deriving it. - - While there are now suggestions in the literature that the use of MD5 - and keyed MD5 in authentication procedures probably has a limited - effective lifetime, the technique is now widely deployed and widely - understood. It is believed that this general understanding may - assist with the rapid replacement, by CRAM-MD5, of the current uses - of permanent cleartext passwords in IMAP. This document has been - - - -Klensin, Catoe & Krumviede Standards Track [Page 4] - -RFC 2195 IMAP/POP AUTHorize Extension September 1997 - - - deliberately written to permit easy upgrading to use SHA (or whatever - alternatives emerge) when they are considered to be widely available - and adequately safe. - - Even with the use of CRAM, users are still vulnerable to active - attacks. An example of an increasingly common active attack is 'TCP - Session Hijacking' as described in CERT Advisory CA-95:01 [CERT95]. - - See section 1 above for additional discussion. - -5. Acknowledgements - - This memo borrows ideas and some text liberally from [POP3] and - [RFC-1731] and thanks are due the authors of those documents. Ran - Atkinson made a number of valuable technical and editorial - contributions to the document. - -6. Authors' Addresses - - John C. Klensin - MCI Telecommunications - 800 Boylston St, 7th floor - Boston, MA 02199 - USA - - EMail: klensin@mci.net - Phone: +1 617 960 1011 - - Randy Catoe - MCI Telecommunications - 2100 Reston Parkway - Reston, VA 22091 - USA - - EMail: randy@mci.net - Phone: +1 703 715 7366 - - Paul Krumviede - MCI Telecommunications - 2100 Reston Parkway - Reston, VA 22091 - USA - - EMail: paul@mci.net - Phone: +1 703 715 7251 - - - - - - -Klensin, Catoe & Krumviede Standards Track [Page 5] - diff --git a/docs/[rfc2898] PKCS #5/rfc2898.pdf b/docs/[rfc2898] PKCS #5/rfc2898.pdf Binary files differdeleted file mode 100755 index a1baab6f..00000000 --- a/docs/[rfc2898] PKCS #5/rfc2898.pdf +++ /dev/null diff --git a/docs/[rfc2898] PKCS #5/rfc2898.txt b/docs/[rfc2898] PKCS #5/rfc2898.txt deleted file mode 100755 index 79af9b84..00000000 --- a/docs/[rfc2898] PKCS #5/rfc2898.txt +++ /dev/null @@ -1,1907 +0,0 @@ - - - - - - -Network Working Group B. Kaliski -Request for Comments: 2898 RSA Laboratories -Category: Informational September 2000 - - - PKCS #5: Password-Based Cryptography Specification - Version 2.0 - -Status of this Memo - - This memo provides information for the Internet community. It does - not specify an Internet standard of any kind. Distribution of this - memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2000). All Rights Reserved. - -Abstract - - This memo represents a republication of PKCS #5 v2.0 from RSA - Laboratories' Public-Key Cryptography Standards (PKCS) series, and - change control is retained within the PKCS process. The body of this - document, except for the security considerations section, is taken - directly from that specification. - - This document provides recommendations for the implementation of - password-based cryptography, covering key derivation functions, - encryption schemes, message-authentication schemes, and ASN.1 syntax - identifying the techniques. - - The recommendations are intended for general application within - computer and communications systems, and as such include a fair - amount of flexibility. They are particularly intended for the - protection of sensitive information such as private keys, as in PKCS - #8 [25]. It is expected that application standards and implementation - profiles based on these specifications may include additional - constraints. - - Other cryptographic techniques based on passwords, such as password- - based key entity authentication and key establishment protocols - [4][5][26] are outside the scope of this document. Guidelines for - the selection of passwords are also outside the scope. - - - - - - - - -Kaliski Informational [Page 1] - -RFC 2898 Password-Based Cryptography September 2000 - - -Table of Contents - - 1. Introduction ............................................... 3 - 2. Notation ................................................... 3 - 3. Overview ................................................... 4 - 4. Salt and iteration count ................................... 6 - 4.1 Salt ................................................... 6 - 4.2 Iteration count ........................................ 8 - 5. Key derivation functions ................................... 8 - 5.1 PBKDF1 ................................................. 9 - 5.2 PBKDF2 ................................................. 9 - 6. Encryption schemes ......................................... 11 - 6.1 PBES1 .................................................. 12 - 6.1.1 Encryption operation ............................ 12 - 6.1.2 Decryption operation ............................ 13 - 6.2 PBES2 .................................................. 14 - 6.2.1 Encryption operation ............................ 14 - 6.2.2 Decryption operation ............................ 15 - 7. Message authentication schemes ............................. 15 - 7.1 PBMAC1 ................................................. 16 - 7.1.1 MAC generation .................................. 16 - 7.1.2 MAC verification ................................ 16 - 8. Security Considerations .................................... 17 - 9. Author's Address............................................ 17 - A. ASN.1 syntax ............................................... 18 - A.1 PBKDF1 ................................................. 18 - A.2 PBKDF2 ................................................. 18 - A.3 PBES1 .................................................. 20 - A.4 PBES2 .................................................. 20 - A.5 PBMAC1 ................................................. 21 - B. Supporting techniques ...................................... 22 - B.1 Pseudorandom functions ................................. 22 - B.2 Encryption schemes ..................................... 23 - B.3 Message authentication schemes ......................... 26 - C. ASN.1 module ............................................... 26 - Intellectual Property Considerations ............................ 30 - Revision history ................................................ 30 - References ...................................................... 31 - Contact Information & About PKCS ................................ 33 - Full Copyright Statement ........................................ 34 - - - - - - - - - - - -Kaliski Informational [Page 2] - -RFC 2898 Password-Based Cryptography September 2000 - - -1. Introduction - - This document provides recommendations for the implementation of - password-based cryptography, covering the following aspects: - - - key derivation functions - - encryption schemes - - message-authentication schemes - - ASN.1 syntax identifying the techniques - - The recommendations are intended for general application within - computer and communications systems, and as such include a fair - amount of flexibility. They are particularly intended for the - protection of sensitive information such as private keys, as in PKCS - #8 [25]. It is expected that application standards and implementation - profiles based on these specifications may include additional - constraints. - - Other cryptographic techniques based on passwords, such as password- - based key entity authentication and key establishment protocols - [4][5][26] are outside the scope of this document. Guidelines for - the selection of passwords are also outside the scope. - - This document supersedes PKCS #5 version 1.5 [24], but includes - compatible techniques. - -2. Notation - - C ciphertext, an octet string - - c iteration count, a positive integer - - DK derived key, an octet string - - dkLen length in octets of derived key, a positive integer - - EM encoded message, an octet string - - Hash underlying hash function - - hLen length in octets of pseudorandom function output, a positive - integer - - l length in blocks of derived key, a positive integer - - IV initialization vector, an octet string - - K encryption key, an octet string - - - -Kaliski Informational [Page 3] - -RFC 2898 Password-Based Cryptography September 2000 - - - KDF key derivation function - - M message, an octet string - - P password, an octet string - - PRF underlying pseudorandom function - - PS padding string, an octet string - - psLen length in octets of padding string, a positive integer - - S salt, an octet string - - T message authentication code, an octet string - - T_1, ..., T_l, U_1, ..., U_c - intermediate values, octet strings - - 01, 02, ..., 08 - octets with value 1, 2, ..., 8 - - \xor bit-wise exclusive-or of two octet strings - - || || octet length operator - - || concatenation operator - - <i..j> substring extraction operator: extracts octets i through j, - 0 <= i <= j - -3. Overview - - In many applications of public-key cryptography, user security is - ultimately dependent on one or more secret text values or passwords. - Since a password is not directly applicable as a key to any - conventional cryptosystem, however, some processing of the password - is required to perform cryptographic operations with it. Moreover, as - passwords are often chosen from a relatively small space, special - care is required in that processing to defend against search attacks. - - A general approach to password-based cryptography, as described by - Morris and Thompson [8] for the protection of password tables, is to - combine a password with a salt to produce a key. The salt can be - viewed as an index into a large set of keys derived from the - password, and need not be kept secret. Although it may be possible - for an opponent to construct a table of possible passwords (a so- - called "dictionary attack"), constructing a table of possible keys - - - -Kaliski Informational [Page 4] - -RFC 2898 Password-Based Cryptography September 2000 - - - will be difficult, since there will be many possible keys for each - password. An opponent will thus be limited to searching through - passwords separately for each salt. - - Another approach to password-based cryptography is to construct key - derivation techniques that are relatively expensive, thereby - increasing the cost of exhaustive search. One way to do this is to - include an iteration count in the key derivation technique, - indicating how many times to iterate some underlying function by - which keys are derived. A modest number of iterations, say 1000, is - not likely to be a burden for legitimate parties when computing a - key, but will be a significant burden for opponents. - - Salt and iteration count formed the basis for password-based - encryption in PKCS #5 v1.5, and adopted here as well for the various - cryptographic operations. Thus, password-based key derivation as - defined here is a function of a password, a salt, and an iteration - count, where the latter two quantities need not be kept secret. - - From a password-based key derivation function, it is straightforward - to define password-based encryption and message authentication - schemes. As in PKCS #5 v1.5, the password-based encryption schemes - here are based on an underlying, conventional encryption scheme, - where the key for the conventional scheme is derived from the - password. Similarly, the password-based message authentication scheme - is based on an underlying conventional scheme. This two-layered - approach makes the password-based techniques modular in terms of the - underlying techniques they can be based on. - - It is expected that the password-based key derivation functions may - find other applications than just the encryption and message - authentication schemes defined here. For instance, one might derive a - set of keys with a single application of a key derivation function, - rather than derive each key with a separate application of the - function. The keys in the set would be obtained as substrings of the - output of the key derivation function. This approach might be - employed as part of key establishment in a session-oriented protocol. - Another application is password checking, where the output of the key - derivation function is stored (along with the salt and iteration - count) for the purposes of subsequent verification of a password. - - Throughout this document, a password is considered to be an octet - string of arbitrary length whose interpretation as a text string is - unspecified. In the interest of interoperability, however, it is - recommended that applications follow some common text encoding rules. - ASCII and UTF-8 [27] are two possibilities. (ASCII is a subset of - UTF-8.) - - - - -Kaliski Informational [Page 5] - -RFC 2898 Password-Based Cryptography September 2000 - - - Although the selection of passwords is outside the scope of this - document, guidelines have been published [17] that may well be taken - into account. - -4. Salt and Iteration Count - - Inasmuch as salt and iteration count are central to the techniques - defined in this document, some further discussion is warranted. - -4.1 Salt - - A salt in password-based cryptography has traditionally served the - purpose of producing a large set of keys corresponding to a given - password, among which one is selected at random according to the - salt. An individual key in the set is selected by applying a key - derivation function KDF, as - - DK = KDF (P, S) - - where DK is the derived key, P is the password, and S is the salt. - This has two benefits: - - 1. It is difficult for an opponent to precompute all the keys - corresponding to a dictionary of passwords, or even the most - likely keys. If the salt is 64 bits long, for instance, there - will be as many as 2^64 keys for each password. An opponent is - thus limited to searching for passwords after a password-based - operation has been performed and the salt is known. - - 2. It is unlikely that the same key will be selected twice. - Again, if the salt is 64 bits long, the chance of "collision" - between keys does not become significant until about 2^32 keys - have been produced, according to the Birthday Paradox. This - addresses some of the concerns about interactions between - multiple uses of the same key, which may apply for some - encryption and authentication techniques. - - In password-based encryption, the party encrypting a message can gain - assurance that these benefits are realized simply by selecting a - large and sufficiently random salt when deriving an encryption key - from a password. A party generating a message authentication code can - gain such assurance in a similar fashion. - - The party decrypting a message or verifying a message authentication - code, however, cannot be sure that a salt supplied by another party - has actually been generated at random. It is possible, for instance, - that the salt may have been copied from another password-based - operation, in an attempt to exploit interactions between multiple - - - -Kaliski Informational [Page 6] - -RFC 2898 Password-Based Cryptography September 2000 - - - uses of the same key. For instance, suppose two legitimate parties - exchange a encrypted message, where the encryption key is an 80-bit - key derived from a shared password with some salt. An opponent could - take the salt from that encryption and provide it to one of the - parties as though it were for a 40-bit key. If the party reveals the - result of decryption with the 40-bit key, the opponent may be able to - solve for the 40-bit key. In the case that 40-bit key is the first - half of the 80-bit key, the opponent can then readily solve for the - remaining 40 bits of the 80-bit key. - - To defend against such attacks, either the interaction between - multiple uses of the same key should be carefully analyzed, or the - salt should contain data that explicitly distinguishes between - different operations. For instance, the salt might have an - additional, non-random octet that specifies whether the derived key - is for encryption, for message authentication, or for some other - operation. - - Based on this, the following is recommended for salt selection: - - 1. If there is no concern about interactions between multiple uses - of the same key (or a prefix of that key) with the password- - based encryption and authentication techniques supported for a - given password, then the salt may be generated at random and - need not be checked for a particular format by the party - receiving the salt. It should be at least eight octets (64 - bits) long. - - 2. Otherwise, the salt should contain data that explicitly - distinguishes between different operations and different key - lengths, in addition to a random part that is at least eight - octets long, and this data should be checked or regenerated by - the party receiving the salt. For instance, the salt could have - an additional non-random octet that specifies the purpose of - the derived key. Alternatively, it could be the encoding of a - structure that specifies detailed information about the derived - key, such as the encryption or authentication technique and a - sequence number among the different keys derived from the - password. The particular format of the additional data is left - to the application. - - Note. If a random number generator or pseudorandom generator is not - available, a deterministic alternative for generating the salt (or - the random part of it) is to apply a password-based key derivation - function to the password and the message M to be processed. For - instance, the salt could be computed with a key derivation function - as S = KDF (P, M). This approach is not recommended if the message M - - - - -Kaliski Informational [Page 7] - -RFC 2898 Password-Based Cryptography September 2000 - - - is known to belong to a small message space (e.g., "Yes" or "No"), - however, since then there will only be a small number of possible - salts. - -4.2 Iteration Count - - An iteration count has traditionally served the purpose of increasing - the cost of producing keys from a password, thereby also increasing - the difficulty of attack. For the methods in this document, a minimum - of 1000 iterations is recommended. This will increase the cost of - exhaustive search for passwords significantly, without a noticeable - impact in the cost of deriving individual keys. - -5. Key Derivation Functions - - A key derivation function produces a derived key from a base key and - other parameters. In a password-based key derivation function, the - base key is a password and the other parameters are a salt value and - an iteration count, as outlined in Section 3. - - The primary application of the password-based key derivation - functions defined here is in the encryption schemes in Section 6 and - the message authentication scheme in Section 7. Other applications - are certainly possible, hence the independent definition of these - functions. - - Two functions are specified in this section: PBKDF1 and PBKDF2. - PBKDF2 is recommended for new applications; PBKDF1 is included only - for compatibility with existing applications, and is not recommended - for new applications. - - A typical application of the key derivation functions defined here - might include the following steps: - - 1. Select a salt S and an iteration count c, as outlined in - Section 4. - - 2. Select a length in octets for the derived key, dkLen. - - 3. Apply the key derivation function to the password, the salt, - the iteration count and the key length to produce a derived - key. - - 4. Output the derived key. - - Any number of keys may be derived from a password by varying the - salt, as described in Section 3. - - - - -Kaliski Informational [Page 8] - -RFC 2898 Password-Based Cryptography September 2000 - - -5.1 PBKDF1 - - PBKDF1 applies a hash function, which shall be MD2 [6], MD5 [19] or - SHA-1 [18], to derive keys. The length of the derived key is bounded - by the length of the hash function output, which is 16 octets for MD2 - and MD5 and 20 octets for SHA-1. PBKDF1 is compatible with the key - derivation process in PKCS #5 v1.5. - - PBKDF1 is recommended only for compatibility with existing - applications since the keys it produces may not be large enough for - some applications. - - PBKDF1 (P, S, c, dkLen) - - Options: Hash underlying hash function - - Input: P password, an octet string - S salt, an eight-octet string - c iteration count, a positive integer - dkLen intended length in octets of derived key, - a positive integer, at most 16 for MD2 or - MD5 and 20 for SHA-1 - - Output: DK derived key, a dkLen-octet string - - Steps: - - 1. If dkLen > 16 for MD2 and MD5, or dkLen > 20 for SHA-1, output - "derived key too long" and stop. - - 2. Apply the underlying hash function Hash for c iterations to the - concatenation of the password P and the salt S, then extract - the first dkLen octets to produce a derived key DK: - - T_1 = Hash (P || S) , - T_2 = Hash (T_1) , - ... - T_c = Hash (T_{c-1}) , - DK = Tc<0..dkLen-1> - - 3. Output the derived key DK. - -5.2 PBKDF2 - - PBKDF2 applies a pseudorandom function (see Appendix B.1 for an - example) to derive keys. The length of the derived key is essentially - unbounded. (However, the maximum effective search space for the - - - - -Kaliski Informational [Page 9] - -RFC 2898 Password-Based Cryptography September 2000 - - - derived key may be limited by the structure of the underlying - pseudorandom function. See Appendix B.1 for further discussion.) - PBKDF2 is recommended for new applications. - - PBKDF2 (P, S, c, dkLen) - - Options: PRF underlying pseudorandom function (hLen - denotes the length in octets of the - pseudorandom function output) - - Input: P password, an octet string - S salt, an octet string - c iteration count, a positive integer - dkLen intended length in octets of the derived - key, a positive integer, at most - (2^32 - 1) * hLen - - Output: DK derived key, a dkLen-octet string - - Steps: - - 1. If dkLen > (2^32 - 1) * hLen, output "derived key too long" and - stop. - - 2. Let l be the number of hLen-octet blocks in the derived key, - rounding up, and let r be the number of octets in the last - block: - - l = CEIL (dkLen / hLen) , - r = dkLen - (l - 1) * hLen . - - Here, CEIL (x) is the "ceiling" function, i.e. the smallest - integer greater than, or equal to, x. - - 3. For each block of the derived key apply the function F defined - below to the password P, the salt S, the iteration count c, and - the block index to compute the block: - - T_1 = F (P, S, c, 1) , - T_2 = F (P, S, c, 2) , - ... - T_l = F (P, S, c, l) , - - where the function F is defined as the exclusive-or sum of the - first c iterates of the underlying pseudorandom function PRF - applied to the password P and the concatenation of the salt S - and the block index i: - - - - -Kaliski Informational [Page 10] - -RFC 2898 Password-Based Cryptography September 2000 - - - F (P, S, c, i) = U_1 \xor U_2 \xor ... \xor U_c - - where - - U_1 = PRF (P, S || INT (i)) , - U_2 = PRF (P, U_1) , - ... - U_c = PRF (P, U_{c-1}) . - - Here, INT (i) is a four-octet encoding of the integer i, most - significant octet first. - - 4. Concatenate the blocks and extract the first dkLen octets to - produce a derived key DK: - - DK = T_1 || T_2 || ... || T_l<0..r-1> - - 5. Output the derived key DK. - - Note. The construction of the function F follows a "belt-and- - suspenders" approach. The iterates U_i are computed recursively to - remove a degree of parallelism from an opponent; they are exclusive- - ored together to reduce concerns about the recursion degenerating - into a small set of values. - -6. Encryption Schemes - - An encryption scheme, in the symmetric setting, consists of an - encryption operation and a decryption operation, where the encryption - operation produces a ciphertext from a message under a key, and the - decryption operation recovers the message from the ciphertext under - the same key. In a password-based encryption scheme, the key is a - password. - - A typical application of a password-based encryption scheme is a - private-key protection method, where the message contains private-key - information, as in PKCS #8. The encryption schemes defined here would - be suitable encryption algorithms in that context. - - Two schemes are specified in this section: PBES1 and PBES2. PBES2 is - recommended for new applications; PBES1 is included only for - compatibility with existing applications, and is not recommended for - new applications. - - - - - - - - -Kaliski Informational [Page 11] - -RFC 2898 Password-Based Cryptography September 2000 - - -6.1 PBES1 - - PBES1 combines the PBKDF1 function (Section 5.1) with an underlying - block cipher, which shall be either DES [15] or RC2(tm) [21] in CBC - mode [16]. PBES1 is compatible with the encryption scheme in PKCS #5 - v1.5. - - PBES1 is recommended only for compatibility with existing - applications, since it supports only two underlying encryption - schemes, each of which has a key size (56 or 64 bits) that may not be - large enough for some applications. - -6.1.1 Encryption Operation - - The encryption operation for PBES1 consists of the following steps, - which encrypt a message M under a password P to produce a ciphertext - C: - - 1. Select an eight-octet salt S and an iteration count c, as - outlined in Section 4. - - 2. Apply the PBKDF1 key derivation function (Section 5.1) to the - password P, the salt S, and the iteration count c to produce at - derived key DK of length 16 octets: - - DK = PBKDF1 (P, S, c, 16) . - - 3. Separate the derived key DK into an encryption key K consisting - of the first eight octets of DK and an initialization vector IV - consisting of the next eight octets: - - K = DK<0..7> , - IV = DK<8..15> . - - 4. Concatenate M and a padding string PS to form an encoded - message EM: - - EM = M || PS , - - where the padding string PS consists of 8-(||M|| mod 8) octets - each with value 8-(||M|| mod 8). The padding string PS will - satisfy one of the following statements: - - PS = 01, if ||M|| mod 8 = 7 ; - PS = 02 02, if ||M|| mod 8 = 6 ; - ... - PS = 08 08 08 08 08 08 08 08, if ||M|| mod 8 = 0. - - - - -Kaliski Informational [Page 12] - -RFC 2898 Password-Based Cryptography September 2000 - - - The length in octets of the encoded message will be a multiple - of eight and it will be possible to recover the message M - unambiguously from the encoded message. (This padding rule is - taken from RFC 1423 [3].) - - 5. Encrypt the encoded message EM with the underlying block cipher - (DES or RC2) in cipher block chaining mode under the encryption - key K with initialization vector IV to produce the ciphertext - C. For DES, the key K shall be considered as a 64-bit encoding - of a 56-bit DES key with parity bits ignored (see [9]). For - RC2, the "effective key bits" shall be 64 bits. - - 6. Output the ciphertext C. - - The salt S and the iteration count c may be conveyed to the party - performing decryption in an AlgorithmIdentifier value (see Appendix - A.3). - -6.1.2 Decryption Operation - - The decryption operation for PBES1 consists of the following steps, - which decrypt a ciphertext C under a password P to recover a message - M: - - 1. Obtain the eight-octet salt S and the iteration count c. - - 2. Apply the PBKDF1 key derivation function (Section 5.1) to the - password P, the salt S, and the iteration count c to produce a - derived key DK of length 16 octets: - - DK = PBKDF1 (P, S, c, 16) - - 3. Separate the derived key DK into an encryption key K consisting - of the first eight octets of DK and an initialization vector IV - consisting of the next eight octets: - - K = DK<0..7> , - IV = DK<8..15> . - - 4. Decrypt the ciphertext C with the underlying block cipher (DES - or RC2) in cipher block chaining mode under the encryption key - K with initialization vector IV to recover an encoded message - EM. If the length in octets of the ciphertext C is not a - multiple of eight, output "decryption error" and stop. - - 5. Separate the encoded message EM into a message M and a padding - string PS: - - - - -Kaliski Informational [Page 13] - -RFC 2898 Password-Based Cryptography September 2000 - - - EM = M || PS , - - where the padding string PS consists of some number psLen - octets each with value psLen, where psLen is between 1 and 8. - If it is not possible to separate the encoded message EM in - this manner, output "decryption error" and stop. - - 6. Output the recovered message M. - -6.2 PBES2 - - PBES2 combines a password-based key derivation function, which shall - be PBKDF2 (Section 5.2) for this version of PKCS #5, with an - underlying encryption scheme (see Appendix B.2 for examples). The key - length and any other parameters for the underlying encryption scheme - depend on the scheme. - - PBES2 is recommended for new applications. - -6.2.1 Encryption Operation - - The encryption operation for PBES2 consists of the following steps, - which encrypt a message M under a password P to produce a ciphertext - C, applying a selected key derivation function KDF and a selected - underlying encryption scheme: - - 1. Select a salt S and an iteration count c, as outlined in - Section 4. - - 2. Select the length in octets, dkLen, for the derived key for the - underlying encryption scheme. - - 3. Apply the selected key derivation function to the password P, - the salt S, and the iteration count c to produce a derived key - DK of length dkLen octets: - - DK = KDF (P, S, c, dkLen) . - - 4. Encrypt the message M with the underlying encryption scheme - under the derived key DK to produce a ciphertext C. (This step - may involve selection of parameters such as an initialization - vector and padding, depending on the underlying scheme.) - - 5. Output the ciphertext C. - - - - - - - -Kaliski Informational [Page 14] - -RFC 2898 Password-Based Cryptography September 2000 - - - The salt S, the iteration count c, the key length dkLen, and - identifiers for the key derivation function and the underlying - encryption scheme may be conveyed to the party performing decryption - in an AlgorithmIdentifier value (see Appendix A.4). - -6.2.2 Decryption Operation - - The decryption operation for PBES2 consists of the following steps, - which decrypt a ciphertext C under a password P to recover a message - M: - - 1. Obtain the salt S for the operation. - - 2. Obtain the iteration count c for the key derivation function. - - 3. Obtain the key length in octets, dkLen, for the derived key for - the underlying encryption scheme. - - 4. Apply the selected key derivation function to the password P, - the salt S, and the iteration count c to produce a derived key - DK of length dkLen octets: - - DK = KDF (P, S, c, dkLen) . - - 5. Decrypt the ciphertext C with the underlying encryption scheme - under the derived key DK to recover a message M. If the - decryption function outputs "decryption error," then output - "decryption error" and stop. - - 6. Output the recovered message M. - -7. Message Authentication Schemes - - A message authentication scheme consists of a MAC (message - authentication code) generation operation and a MAC verification - operation, where the MAC generation operation produces a message - authentication code from a message under a key, and the MAC - verification operation verifies the message authentication code under - the same key. In a password-based message authentication scheme, the - key is a password. - - One scheme is specified in this section: PBMAC1. - - - - - - - - - -Kaliski Informational [Page 15] - -RFC 2898 Password-Based Cryptography September 2000 - - -7.1 PBMAC1 - - PBMAC1 combines a password-based key derivation function, which shall - be PBKDF2 (Section 5.2) for this version of PKCS #5, with an - underlying message authentication scheme (see Appendix B.3 for an - example). The key length and any other parameters for the underlying - message authentication scheme depend on the scheme. - -7.1.1 MAC Generation - - The MAC generation operation for PBMAC1 consists of the following - steps, which process a message M under a password P to generate a - message authentication code T, applying a selected key derivation - function KDF and a selected underlying message authentication scheme: - - 1. Select a salt S and an iteration count c, as outlined in - Section 4. - - 2. Select a key length in octets, dkLen, for the derived key for - the underlying message authentication function. - - 3. Apply the selected key derivation function to the password P, - the salt S, and the iteration count c to produce a derived key - DK of length dkLen octets: - - DK = KDF (P, S, c, dkLen) . - - 4. Process the message M with the underlying message - authentication scheme under the derived key DK to generate a - message authentication code T. - - 5. Output the message authentication code T. - - The salt S, the iteration count c, the key length dkLen, and - identifiers for the key derivation function and underlying message - authentication scheme may be conveyed to the party performing - verification in an AlgorithmIdentifier value (see Appendix A.5). - -7.1.2 MAC Verification - - The MAC verification operation for PBMAC1 consists of the following - steps, which process a message M under a password P to verify a - message authentication code T: - - 1. Obtain the salt S and the iteration count c. - - 2. Obtain the key length in octets, dkLen, for the derived key for - the underlying message authentication scheme. - - - -Kaliski Informational [Page 16] - -RFC 2898 Password-Based Cryptography September 2000 - - - 3. Apply the selected key derivation function to the password P, - the salt S, and the iteration count c to produce a derived key - DK of length dkLen octets: - - DK = KDF (P, S, c, dkLen) . - - 4. Process the message M with the underlying message - authentication scheme under the derived key DK to verify the - message authentication code T. - - 5. If the message authentication code verifies, output "correct"; - else output "incorrect." - -8. Security Considerations - - Password-based cryptography is generally limited in the security that - it can provide, particularly for methods such as those defined in - this document where off-line password search is possible. While the - use of salt and iteration count can increase the complexity of attack - (see Section 4 for recommendations), it is essential that passwords - are selected well, and relevant guidelines (e.g., [17]) should be - taken into account. It is also important that passwords be protected - well if stored. - - In general, different keys should be derived from a password for - different uses to minimize the possibility of unintended - interactions. For password-based encryption with a single algorithm, - a random salt is sufficient to ensure that different keys will be - produced. In certain other situations, as outlined in Section 4, a - structured salt is necessary. The recommendations in Section 4 should - thus be taken into account when selecting the salt value. - -9. Author's Address - - Burt Kaliski - RSA Laboratories - 20 Crosby Drive - Bedford, MA 01730 USA - - EMail: bkaliski@rsasecurity.com - - - - - - - - - - - -Kaliski Informational [Page 17] - -RFC 2898 Password-Based Cryptography September 2000 - - -APPENDICES - -A. ASN.1 Syntax - - This section defines ASN.1 syntax for the key derivation functions, - the encryption schemes, the message authentication scheme, and - supporting techniques. The intended application of these definitions - includes PKCS #8 and other syntax for key management, encrypted data, - and integrity-protected data. (Various aspects of ASN.1 are specified - in several ISO/IEC standards [9][10][11][12][13][14].) - - The object identifier pkcs-5 identifies the arc of the OID tree from - which the PKCS #5-specific OIDs in this section are derived: - - rsadsi OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 113549} - pkcs OBJECT IDENTIFIER ::= {rsadsi 1} - pkcs-5 OBJECT IDENTIFIER ::= {pkcs 5} - -A.1 PBKDF1 - - No object identifier is given for PBKDF1, as the object identifiers - for PBES1 are sufficient for existing applications and PBKDF2 is - recommended for new applications. - -A.2 PBKDF2 - - The object identifier id-PBKDF2 identifies the PBKDF2 key derivation - function (Section 5.2). - - id-PBKDF2 OBJECT IDENTIFIER ::= {pkcs-5 12} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type PBKDF2-params: - - PBKDF2-params ::= SEQUENCE { - salt CHOICE { - specified OCTET STRING, - otherSource AlgorithmIdentifier {{PBKDF2-SaltSources}} - }, - iterationCount INTEGER (1..MAX), - keyLength INTEGER (1..MAX) OPTIONAL, - prf AlgorithmIdentifier {{PBKDF2-PRFs}} DEFAULT - algid-hmacWithSHA1 } - - The fields of type PKDF2-params have the following meanings: - - - - - - -Kaliski Informational [Page 18] - -RFC 2898 Password-Based Cryptography September 2000 - - - - salt specifies the salt value, or the source of the salt value. - It shall either be an octet string or an algorithm ID with an OID - in the set PBKDF2-SaltSources, which is reserved for future - versions of PKCS #5. - - The salt-source approach is intended to indicate how the salt - value is to be generated as a function of parameters in the - algorithm ID, application data, or both. For instance, it may - indicate that the salt value is produced from the encoding of a - structure that specifies detailed information about the derived - key as suggested in Section 4.1. Some of the information may be - carried elsewhere, e.g., in the encryption algorithm ID. However, - such facilities are deferred to a future version of PKCS #5. - - In this version, an application may achieve the benefits mentioned - in Section 4.1 by choosing a particular interpretation of the salt - value in the specified alternative. - - PBKDF2-SaltSources ALGORITHM-IDENTIFIER ::= { ... } - - - iterationCount specifies the iteration count. The maximum - iteration count allowed depends on the implementation. It is - expected that implementation profiles may further constrain the - bounds. - - - keyLength, an optional field, is the length in octets of the - derived key. The maximum key length allowed depends on the - implementation; it is expected that implementation profiles may - further constrain the bounds. The field is provided for - convenience only; the key length is not cryptographically - protected. If there is concern about interaction between - operations with different key lengths for a given salt (see - Section 4.1), the salt should distinguish among the different key - lengths. - - - prf identifies the underlying pseudorandom function. It shall be - an algorithm ID with an OID in the set PBKDF2-PRFs, which for this - version of PKCS #5 shall consist of id-hmacWithSHA1 (see Appendix - B.1.1) and any other OIDs defined by the application. - - PBKDF2-PRFs ALGORITHM-IDENTIFIER ::= - { {NULL IDENTIFIED BY id-hmacWithSHA1}, ... } - - The default pseudorandom function is HMAC-SHA-1: - - algid-hmacWithSHA1 AlgorithmIdentifier {{PBKDF2-PRFs}} ::= - {algorithm id-hmacWithSHA1, parameters NULL : NULL} - - - - -Kaliski Informational [Page 19] - -RFC 2898 Password-Based Cryptography September 2000 - - -A.3 PBES1 - - Different object identifiers identify the PBES1 encryption scheme - (Section 6.1) according to the underlying hash function in the key - derivation function and the underlying block cipher, as summarized in - the following table: - - Hash Function Block Cipher OID - MD2 DES pkcs-5.1 - MD2 RC2 pkcs-5.4 - MD5 DES pkcs-5.3 - MD5 RC2 pkcs-5.6 - SHA-1 DES pkcs-5.10 - SHA-1 RC2 pkcs-5.11 - - pbeWithMD2AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 1} - pbeWithMD2AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 4} - pbeWithMD5AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 3} - pbeWithMD5AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 6} - pbeWithSHA1AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 10} - pbeWithSHA1AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 11} - - For each OID, the parameters field associated with the OID in an - AlgorithmIdentifier shall have type PBEParameter: - - PBEParameter ::= SEQUENCE { - salt OCTET STRING (SIZE(8)), - iterationCount INTEGER } - - The fields of type PBEParameter have the following meanings: - - - salt specifies the salt value, an eight-octet string. - - - iterationCount specifies the iteration count. - -A.4 PBES2 - - The object identifier id-PBES2 identifies the PBES2 encryption scheme - (Section 6.2). - - id-PBES2 OBJECT IDENTIFIER ::= {pkcs-5 13} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type PBES2-params: - - PBES2-params ::= SEQUENCE { - keyDerivationFunc AlgorithmIdentifier {{PBES2-KDFs}}, - encryptionScheme AlgorithmIdentifier {{PBES2-Encs}} } - - - -Kaliski Informational [Page 20] - -RFC 2898 Password-Based Cryptography September 2000 - - - The fields of type PBES2-params have the following meanings: - - - keyDerivationFunc identifies the underlying key derivation - function. It shall be an algorithm ID with an OID in the set - PBES2-KDFs, which for this version of PKCS #5 shall consist of - id-PBKDF2 (Appendix A.2). - - PBES2-KDFs ALGORITHM-IDENTIFIER ::= - { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } - - - encryptionScheme identifies the underlying encryption scheme. It - shall be an algorithm ID with an OID in the set PBES2-Encs, whose - definition is left to the application. Example underlying - encryption schemes are given in Appendix B.2. - - PBES2-Encs ALGORITHM-IDENTIFIER ::= { ... } - -A.5 PBMAC1 - - The object identifier id-PBMAC1 identifies the PBMAC1 message - authentication scheme (Section 7.1). - - id-PBMAC1 OBJECT IDENTIFIER ::= {pkcs-5 14} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type PBMAC1-params: - - PBMAC1-params ::= SEQUENCE { - keyDerivationFunc AlgorithmIdentifier {{PBMAC1-KDFs}}, - messageAuthScheme AlgorithmIdentifier {{PBMAC1-MACs}} } - - The keyDerivationFunc field has the same meaning as the corresponding - field of PBES2-params (Appendix A.4) except that the set of OIDs is - PBMAC1-KDFs. - - PBMAC1-KDFs ALGORITHM-IDENTIFIER ::= - { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } - - The messageAuthScheme field identifies the underlying message - authentication scheme. It shall be an algorithm ID with an OID in the - set PBMAC1-MACs, whose definition is left to the application. Example - underlying encryption schemes are given in Appendix B.3. - - PBMAC1-MACs ALGORITHM-IDENTIFIER ::= { ... } - - - - - - - -Kaliski Informational [Page 21] - -RFC 2898 Password-Based Cryptography September 2000 - - -B. Supporting Techniques - - This section gives several examples of underlying functions and - schemes supporting the password-based schemes in Sections 5, 6 and 7. - - While these supporting techniques are appropriate for applications to - implement, none of them is required to be implemented. It is - expected, however, that profiles for PKCS #5 will be developed that - specify particular supporting techniques. - - This section also gives object identifiers for the supporting - techniques. The object identifiers digestAlgorithm and - encryptionAlgorithm identify the arcs from which certain algorithm - OIDs referenced in this section are derived: - - digestAlgorithm OBJECT IDENTIFIER ::= {rsadsi 2} - encryptionAlgorithm OBJECT IDENTIFIER ::= {rsadsi 3} - -B.1 Pseudorandom functions - - An example pseudorandom function for PBKDF2 (Section 5.2) is HMAC- - SHA-1. - -B.1.1 HMAC-SHA-1 - - HMAC-SHA-1 is the pseudorandom function corresponding to the HMAC - message authentication code [7] based on the SHA-1 hash function - [18]. The pseudorandom function is the same function by which the - message authentication code is computed, with a full-length output. - (The first argument to the pseudorandom function PRF serves as HMAC's - "key," and the second serves as HMAC's "text." In the case of PBKDF2, - the "key" is thus the password and the "text" is the salt.) HMAC- - SHA-1 has a variable key length and a 20-octet (160-bit) output - value. - - Although the length of the key to HMAC-SHA-1 is essentially - unbounded, the effective search space for pseudorandom function - outputs may be limited by the structure of the function. In - particular, when the key is longer than 512 bits, HMAC-SHA-1 will - first hash it to 160 bits. Thus, even if a long derived key - consisting of several pseudorandom function outputs is produced from - a key, the effective search space for the derived key will be at most - 160 bits. Although the specific limitation for other key sizes - depends on details of the HMAC construction, one should assume, to be - conservative, that the effective search space is limited to 160 bits - for other key sizes as well. - - - - - -Kaliski Informational [Page 22] - -RFC 2898 Password-Based Cryptography September 2000 - - - (The 160-bit limitation should not generally pose a practical - limitation in the case of password-based cryptography, since the - search space for a password is unlikely to be greater than 160 bits.) - - The object identifier id-hmacWithSHA1 identifies the HMAC-SHA-1 - pseudorandom function: - - id-hmacWithSHA1 OBJECT IDENTIFIER ::= {digestAlgorithm 7} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type NULL. This object identifier is - employed in the object set PBKDF2-PRFs (Appendix A.2). - - Note. Although HMAC-SHA-1 was designed as a message authentication - code, its proof of security is readily modified to accommodate - requirements for a pseudorandom function, under stronger assumptions. - - A hash function may also meet the requirements of a pseudorandom - function under certain assumptions. For instance, the direct - application of a hash function to to the concatenation of the "key" - and the "text" may be appropriate, provided that "text" has - appropriate structure to prevent certain attacks. HMAC-SHA-1 is - preferable, however, because it treats "key" and "text" as separate - arguments and does not require "text" to have any structure. - -B.2 Encryption Schemes - - Example pseudorandom functions for PBES2 (Section 6.2) are DES-CBC- - Pad, DES-EDE2-CBC-Pad, RC2-CBC-Pad, and RC5-CBC-Pad. - - The object identifiers given in this section are intended to be - employed in the object set PBES2-Encs (Appendix A.4). - -B.2.1 DES-CBC-Pad - - DES-CBC-Pad is single-key DES [15] in CBC mode [16] with the RFC 1423 - padding operation (see Section 6.1.1). DES-CBC-Pad has an eight-octet - encryption key and an eight-octet initialization vector. The key is - considered as a 64-bit encoding of a 56-bit DES key with parity bits - ignored. - - The object identifier desCBC (defined in the NIST/OSI Implementors' - Workshop agreements) identifies the DES-CBC-Pad encryption scheme: - - desCBC OBJECT IDENTIFIER ::= - {iso(1) identified-organization(3) oiw(14) secsig(3) - algorithms(2) 7} - - - - -Kaliski Informational [Page 23] - -RFC 2898 Password-Based Cryptography September 2000 - - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type OCTET STRING (SIZE(8)), - specifying the initialization vector for CBC mode. - -B.2.2 DES-EDE3-CBC-Pad - - DES-EDE3-CBC-Pad is three-key triple-DES in CBC mode [1] with the RFC - 1423 padding operation. DES-EDE3-CBC-Pad has a 24-octet encryption - key and an eight-octet initialization vector. The key is considered - as the concatenation of three eight-octet keys, each of which is a - 64-bit encoding of a 56-bit DES key with parity bits ignored. - - The object identifier des-EDE3-CBC identifies the DES-EDE3-CBC-Pad - encryption scheme: - - des-EDE3-CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 7} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type OCTET STRING (SIZE(8)), - specifying the initialization vector for CBC mode. - - Note. An OID for DES-EDE3-CBC without padding is given in ANSI X9.52 - [1]; the one given here is preferred since it specifies padding. - -B.2.3 RC2-CBC-Pad - - RC2-CBC-Pad is the RC2(tm) encryption algorithm [21] in CBC mode with - the RFC 1423 padding operation. RC2-CBC-Pad has a variable key - length, from one to 128 octets, a separate "effective key bits" - parameter from one to 1024 bits that limits the effective search - space independent of the key length, and an eight-octet - initialization vector. - - The object identifier rc2CBC identifies the RC2-CBC-Pad encryption - scheme: - - rc2CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 2} - - The parameters field associated with OID in an AlgorithmIdentifier - shall have type RC2-CBC-Parameter: - - RC2-CBC-Parameter ::= SEQUENCE { - rc2ParameterVersion INTEGER OPTIONAL, - iv OCTET STRING (SIZE(8)) } - - - - - - - -Kaliski Informational [Page 24] - -RFC 2898 Password-Based Cryptography September 2000 - - - The fields of type RC2-CBCParameter have the following meanings: - - - rc2ParameterVersion is a proprietary RSA Security Inc. encoding of - the "effective key bits" for RC2. The following encodings are - defined: - - Effective Key Bits Encoding - 40 160 - 64 120 - 128 58 - b >= 256 b - - If the rc2ParameterVersion field is omitted, the "effective key bits" - defaults to 32. (This is for backward compatibility with certain very - old implementations.) - - - iv is the eight-octet initialization vector. - -B.2.4 RC5-CBC-Pad - - RC5-CBC-Pad is the RC5(tm) encryption algorithm [20] in CBC mode with - a generalization of the RFC 1423 padding operation. This scheme is - fully specified in [2]. RC5-CBC-Pad has a variable key length, from 0 - to 256 octets, and supports both a 64-bit block size and a 128-bit - block size. For the former, it has an eight-octet initialization - vector, and for the latter, a 16-octet initialization vector. - RC5-CBC-Pad also has a variable number of "rounds" in the encryption - operation, from 8 to 127. - - Note: The generalization of the padding operation is as follows. For - RC5 with a 64-bit block size, the padding string is as defined in RFC - 1423. For RC5 with a 128-bit block size, the padding string consists - of 16-(||M|| mod 16) octets each with value 16-(||M|| mod 16). - - The object identifier rc5-CBC-PAD [2] identifies RC5-CBC-Pad - encryption scheme: - - rc5-CBC-PAD OBJECT IDENTIFIER ::= {encryptionAlgorithm 9} - - The parameters field associated with this OID in an - AlgorithmIdentifier shall have type RC5-CBC-Parameters: - - RC5-CBC-Parameters ::= SEQUENCE { - version INTEGER {v1-0(16)} (v1-0), - rounds INTEGER (8..127), - blockSizeInBits INTEGER (64 | 128), - iv OCTET STRING OPTIONAL } - - - - -Kaliski Informational [Page 25] - -RFC 2898 Password-Based Cryptography September 2000 - - - The fields of type RC5-CBC-Parameters have the following meanings: - - - version is the version of the algorithm, which shall be v1-0. - - - rounds is the number of rounds in the encryption operation, which - shall be between 8 and 127. - - - blockSizeInBits is the block size in bits, which shall be 64 or - 128. - - - iv is the initialization vector, an eight-octet string for 64-bit - RC5 and a 16-octet string for 128-bit RC5. The default is a string - of the appropriate length consisting of zero octets. - -B.3 Message Authentication Schemes - - An example message authentication scheme for PBMAC1 (Section 7.1) is - HMAC-SHA-1. - -B.3.1 HMAC-SHA-1 - - HMAC-SHA-1 is the HMAC message authentication scheme [7] based on the - SHA-1 hash function [18]. HMAC-SHA-1 has a variable key length and a - 20-octet (160-bit) message authentication code. - - The object identifier id-hmacWithSHA1 (see Appendix B.1.1) identifies - the HMAC-SHA-1 message authentication scheme. (The object identifier - is the same for both the pseudorandom function and the message - authentication scheme; the distinction is to be understood by - context.) This object identifier is intended to be employed in the - object set PBMAC1-Macs (Appendix A.5). - -C. ASN.1 Module - - For reference purposes, the ASN.1 syntax in the preceding sections is - presented as an ASN.1 module here. - - -- PKCS #5 v2.0 ASN.1 Module - -- Revised March 25, 1999 - - -- This module has been checked for conformance with the - -- ASN.1 standard by the OSS ASN.1 Tools - - PKCS5v2-0 {iso(1) member-body(2) us(840) rsadsi(113549) - pkcs(1) pkcs-5(5) modules(16) pkcs5v2-0(1)} - - DEFINITIONS ::= BEGIN - - - - -Kaliski Informational [Page 26] - -RFC 2898 Password-Based Cryptography September 2000 - - - -- Basic object identifiers - - rsadsi OBJECT IDENTIFIER ::= {iso(1) member-body(2) us(840) 113549} - pkcs OBJECT IDENTIFIER ::= {rsadsi 1} - - pkcs-5 OBJECT IDENTIFIER ::= {pkcs 5} - - -- Basic types and classes - - AlgorithmIdentifier { ALGORITHM-IDENTIFIER:InfoObjectSet } ::= - SEQUENCE { - algorithm ALGORITHM-IDENTIFIER.&id({InfoObjectSet}), - parameters ALGORITHM-IDENTIFIER.&Type({InfoObjectSet} - {@algorithm}) OPTIONAL - } - - ALGORITHM-IDENTIFIER ::= TYPE-IDENTIFIER - - -- PBKDF2 - - PBKDF2Algorithms ALGORITHM-IDENTIFIER ::= - { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ...} - - id-PBKDF2 OBJECT IDENTIFIER ::= {pkcs-5 12} - - algid-hmacWithSHA1 AlgorithmIdentifier {{PBKDF2-PRFs}} ::= - {algorithm id-hmacWithSHA1, parameters NULL : NULL} - - PBKDF2-params ::= SEQUENCE { - salt CHOICE { - specified OCTET STRING, - otherSource AlgorithmIdentifier {{PBKDF2-SaltSources}} - }, - iterationCount INTEGER (1..MAX), - keyLength INTEGER (1..MAX) OPTIONAL, - prf AlgorithmIdentifier {{PBKDF2-PRFs}} DEFAULT - algid-hmacWithSHA1 - } - - PBKDF2-SaltSources ALGORITHM-IDENTIFIER ::= { ... } - - PBKDF2-PRFs ALGORITHM-IDENTIFIER ::= - { {NULL IDENTIFIED BY id-hmacWithSHA1}, ... } - - -- PBES1 - - - PBES1Algorithms ALGORITHM-IDENTIFIER ::= { - - - -Kaliski Informational [Page 27] - -RFC 2898 Password-Based Cryptography September 2000 - - - {PBEParameter IDENTIFIED BY pbeWithMD2AndDES-CBC} | - {PBEParameter IDENTIFIED BY pbeWithMD2AndRC2-CBC} | - {PBEParameter IDENTIFIED BY pbeWithMD5AndDES-CBC} | - {PBEParameter IDENTIFIED BY pbeWithMD5AndRC2-CBC} | - {PBEParameter IDENTIFIED BY pbeWithSHA1AndDES-CBC} | - {PBEParameter IDENTIFIED BY pbeWithSHA1AndRC2-CBC}, - ... - } - - pbeWithMD2AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 1} - pbeWithMD2AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 4} - pbeWithMD5AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 3} - pbeWithMD5AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 6} - pbeWithSHA1AndDES-CBC OBJECT IDENTIFIER ::= {pkcs-5 10} - pbeWithSHA1AndRC2-CBC OBJECT IDENTIFIER ::= {pkcs-5 11} - - PBEParameter ::= SEQUENCE { - salt OCTET STRING (SIZE(8)), - iterationCount INTEGER - } - - -- PBES2 - - PBES2Algorithms ALGORITHM-IDENTIFIER ::= - { {PBES2-params IDENTIFIED BY id-PBES2}, ...} - - id-PBES2 OBJECT IDENTIFIER ::= {pkcs-5 13} - - PBES2-params ::= SEQUENCE { - keyDerivationFunc AlgorithmIdentifier {{PBES2-KDFs}}, - encryptionScheme AlgorithmIdentifier {{PBES2-Encs}} - } - - PBES2-KDFs ALGORITHM-IDENTIFIER ::= - { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } - - PBES2-Encs ALGORITHM-IDENTIFIER ::= { ... } - - -- PBMAC1 - - PBMAC1Algorithms ALGORITHM-IDENTIFIER ::= - { {PBMAC1-params IDENTIFIED BY id-PBMAC1}, ...} - - id-PBMAC1 OBJECT IDENTIFIER ::= {pkcs-5 14} - - PBMAC1-params ::= SEQUENCE { - keyDerivationFunc AlgorithmIdentifier {{PBMAC1-KDFs}}, - messageAuthScheme AlgorithmIdentifier {{PBMAC1-MACs}} - - - -Kaliski Informational [Page 28] - -RFC 2898 Password-Based Cryptography September 2000 - - - } - - PBMAC1-KDFs ALGORITHM-IDENTIFIER ::= - { {PBKDF2-params IDENTIFIED BY id-PBKDF2}, ... } - - PBMAC1-MACs ALGORITHM-IDENTIFIER ::= { ... } - - -- Supporting techniques - - digestAlgorithm OBJECT IDENTIFIER ::= {rsadsi 2} - encryptionAlgorithm OBJECT IDENTIFIER ::= {rsadsi 3} - - SupportingAlgorithms ALGORITHM-IDENTIFIER ::= { - {NULL IDENTIFIED BY id-hmacWithSHA1} | - {OCTET STRING (SIZE(8)) IDENTIFIED BY desCBC} | - {OCTET STRING (SIZE(8)) IDENTIFIED BY des-EDE3-CBC} | - {RC2-CBC-Parameter IDENTIFIED BY rc2CBC} | - {RC5-CBC-Parameters IDENTIFIED BY rc5-CBC-PAD}, - ... - } - - id-hmacWithSHA1 OBJECT IDENTIFIER ::= {digestAlgorithm 7} - - desCBC OBJECT IDENTIFIER ::= - {iso(1) identified-organization(3) oiw(14) secsig(3) - algorithms(2) 7} -- from OIW - - des-EDE3-CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 7} - - rc2CBC OBJECT IDENTIFIER ::= {encryptionAlgorithm 2} - - RC2-CBC-Parameter ::= SEQUENCE { - rc2ParameterVersion INTEGER OPTIONAL, - iv OCTET STRING (SIZE(8)) - } - - rc5-CBC-PAD OBJECT IDENTIFIER ::= {encryptionAlgorithm 9} - - RC5-CBC-Parameters ::= SEQUENCE { - version INTEGER {v1-0(16)} (v1-0), - rounds INTEGER (8..127), - blockSizeInBits INTEGER (64 | 128), - iv OCTET STRING OPTIONAL - } - - END - - - - - -Kaliski Informational [Page 29] - -RFC 2898 Password-Based Cryptography September 2000 - - -Intellectual Property Considerations - - RSA Security makes no patent claims on the general constructions - described in this document, although specific underlying techniques - may be covered. Among the underlying techniques, the RC5 encryption - algorithm (Appendix B.2.4) is protected by U.S. Patents 5,724,428 - [22] and 5,835,600 [23]. - - RC2 and RC5 are trademarks of RSA Security. - - License to copy this document is granted provided that it is - identified as RSA Security Inc. Public-Key Cryptography Standards - (PKCS) in all material mentioning or referencing this document. - - RSA Security makes no representations regarding intellectual property - claims by other parties. Such determination is the responsibility of - the user. - -Revision history - - Versions 1.0-1.3 - - Versions 1.0-1.3 were distributed to participants in RSA Data - Security Inc.'s Public-Key Cryptography Standards meetings in - February and March 1991. - - Version 1.4 - - Version 1.4 was part of the June 3, 1991 initial public release of - PKCS. Version 1.4 was published as NIST/OSI Implementors' Workshop - document SEC-SIG-91-20. - - Version 1.5 - - Version 1.5 incorporated several editorial changes, including - updates to the references and the addition of a revision history. - - Version 2.0 - - Version 2.0 incorporates major editorial changes in terms of the - document structure, and introduces the PBES2 encryption scheme, - the PBMAC1 message authentication scheme, and independent - password-based key derivation functions. This version continues to - support the encryption process in version 1.5. - - - - - - - -Kaliski Informational [Page 30] - -RFC 2898 Password-Based Cryptography September 2000 - - -References - - [1] American National Standard X9.52 - 1998, Triple Data Encryption - Algorithm Modes of Operation. Working draft, Accredited - Standards Committee X9, July 27, 1998. - - [2] Baldwin, R. and R. Rivest, "The RC5, RC5-CBC, RC5-CBC-Pad, and - RC5-CTS Algorithms", RFC 2040, October 1996. - - [3] Balenson, D., "Privacy Enhancement for Internet Electronic Mail: - Part III: Algorithms, Modes, and Identifiers", RFC 1423, - February 1993. - - [4] S.M. Bellovin and M. Merritt. Encrypted key exchange: - Password-based protocols secure against dictionary attacks. In - Proceedings of the 1992 IEEE Computer Society Conference on - Research in Security and Privacy, pages 72-84, IEEE Computer - Society, 1992. - - [5] D. Jablon. Strong password-only authenticated key exchange. ACM - Computer Communications Review, October 1996. - - [6] Kaliski, B., "The MD2 Message-Digest Algorithm", RFC 1319, April - 1992. - - [7] Krawczyk, H., Bellare, M. and R. Canetti, "HMAC: Keyed-Hashing - for Message Authentication", RFC 2104, February 1997. - - [8] Robert Morris and Ken Thompson. Password security: A case - history. Communications of the ACM, 22(11):594-597, November - 1979. - - [9] ISO/IEC 8824-1:1995: Information technology - Abstract Syntax - Notation One (ASN.1) - Specification of basic notation. 1995. - - [10] ISO/IEC 8824-1:1995/Amd.1:1995 Information technology - Abstract - Syntax Notation One (ASN.1) - Specification of basic notation - - Amendment 1 - Rules of extensibility. 1995. - - [11] ISO/IEC 8824-2:1995 Information technology - Abstract Syntax - Notation One (ASN.1) - Information object specification. 1995. - - [12] ISO/IEC 8824-2:1995/Amd.1:1995 Information technology - Abstract - Syntax Notation One (ASN.1) - Information object specification - - Amendment 1 - Rules of extensibility. 1995. - - [13] ISO/IEC 8824-3:1995 Information technology - Abstract Syntax - Notation One (ASN.1) - Constraint specification. 1995. - - - -Kaliski Informational [Page 31] - -RFC 2898 Password-Based Cryptography September 2000 - - - [14] ISO/IEC 8824-4:1995 Information technology - Abstract Syntax - Notation One (ASN.1) - Parameterization of ASN.1 specifications. - 1995. - - [15] National Institute of Standards and Technology (NIST). FIPS PUB - 46-2: Data Encryption Standard. December 30, 1993. - - [16] National Institute of Standards and Technology (NIST). FIPS PUB - 81: DES Modes of Operation. December 2, 1980. - - [17] National Institute of Standards and Technology (NIST). FIPS PUB - 112: Password Usage. May 30, 1985. - - [18] National Institute of Standards and Technology (NIST). FIPS PUB - 180-1: Secure Hash Standard. April 1994. - - [19] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April - 1992. - - [20] R.L. Rivest. The RC5 encryption algorithm. In Proceedings of the - Second International Workshop on Fast Software Encryption, pages - 86-96, Springer-Verlag, 1994. - - [21] Rivest, R., "A Description of the RC2(r) Encryption Algorithm", - RFC 2268, March 1998. - - [22] R.L. Rivest. Block-Encryption Algorithm with Data-Dependent - Rotations. U.S. Patent No. 5,724,428, March 3, 1998. - - [23] R.L. Rivest. Block Encryption Algorithm with Data-Dependent - Rotations. U.S. Patent No. 5,835,600, November 10, 1998. - - [24] RSA Laboratories. PKCS #5: Password-Based Encryption Standard. - Version 1.5, November 1993. - - [25] RSA Laboratories. PKCS #8: Private-Key Information Syntax - Standard. Version 1.2, November 1993. - - [26] T. Wu. The Secure Remote Password protocol. In Proceedings of - the 1998 Internet Society Network and Distributed System - Security Symposium, pages 97-111, Internet Society, 1998. - - [27] Yergeau, F., "UTF-8, a transformation format of ISO 10646", RFC - 2279, January 1998. - - - - - - - -Kaliski Informational [Page 32] - -RFC 2898 Password-Based Cryptography September 2000 - - -Contact Information & About PKCS - - The Public-Key Cryptography Standards are specifications produced by - RSA Laboratories in cooperation with secure systems developers - worldwide for the purpose of accelerating the deployment of public- - key cryptography. First published in 1991 as a result of meetings - with a small group of early adopters of public-key technology, the - PKCS documents have become widely referenced and implemented. - Contributions from the PKCS series have become part of many formal - and de facto standards, including ANSI X9 documents, PKIX, SET, - S/MIME, and SSL. - - Further development of PKCS occurs through mailing list discussions - and occasional workshops, and suggestions for improvement are - welcome. For more information, contact: - - PKCS Editor - RSA Laboratories - 20 Crosby Drive - Bedford, MA 01730 USA - pkcs-editor@rsasecurity.com - http://www.rsalabs.com/pkcs/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Kaliski Informational [Page 33] - -RFC 2898 Password-Based Cryptography September 2000 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2000). 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. - - - - - - - - - - - - - - - - - - - -Kaliski Informational [Page 34] - diff --git a/docs/[rfc4616] PLAIN/rfc4616.txt b/docs/[rfc4616] PLAIN/rfc4616.txt deleted file mode 100755 index 991189d5..00000000 --- a/docs/[rfc4616] PLAIN/rfc4616.txt +++ /dev/null @@ -1,619 +0,0 @@ - - - - - - -Network Working Group K. Zeilenga, Ed. -Request for Comments: 4616 OpenLDAP Foundation -Updates: 2595 August 2006 -Category: Standards Track - - - The PLAIN Simple Authentication and Security Layer (SASL) Mechanism - -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 (2006). - -Abstract - - This document defines a simple clear-text user/password Simple - Authentication and Security Layer (SASL) mechanism called the PLAIN - mechanism. The PLAIN mechanism is intended to be used, in - combination with data confidentiality services provided by a lower - layer, in protocols that lack a simple password authentication - command. - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 1] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -1. Introduction - - Clear-text, multiple-use passwords are simple, interoperate with - almost all existing operating system authentication databases, and - are useful for a smooth transition to a more secure password-based - authentication mechanism. The drawback is that they are unacceptable - for use over network connections where data confidentiality is not - ensured. - - This document defines the PLAIN Simple Authentication and Security - Layer ([SASL]) mechanism for use in protocols with no clear-text - login command (e.g., [ACAP] or [SMTP-AUTH]). This document updates - RFC 2595, replacing Section 6. Changes since RFC 2595 are detailed - in Appendix A. - - The name associated with this mechanism is "PLAIN". - - The PLAIN SASL mechanism does not provide a security layer. - - The PLAIN mechanism should not be used without adequate data security - protection as this mechanism affords no integrity or confidentiality - protections itself. The mechanism is intended to be used with data - security protections provided by application-layer protocol, - generally through its use of Transport Layer Security ([TLS]) - services. - - By default, implementations SHOULD advertise and make use of the - PLAIN mechanism only when adequate data security services are in - place. Specifications for IETF protocols that indicate that this - mechanism is an applicable authentication mechanism MUST mandate that - implementations support an strong data security service, such as TLS. - - 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 [Keywords]. - -2. PLAIN SASL Mechanism - - The mechanism consists of a single message, a string of [UTF-8] - encoded [Unicode] characters, from the client to the server. The - client presents the authorization identity (identity to act as), - followed by a NUL (U+0000) character, followed by the authentication - identity (identity whose password will be used), followed by a NUL - (U+0000) character, followed by the clear-text password. As with - other SASL mechanisms, the client does not provide an authorization - identity when it wishes the server to derive an identity from the - credentials and use that as the authorization identity. - - - - -Zeilenga Standards Track [Page 2] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - The formal grammar for the client message using Augmented BNF [ABNF] - follows. - - message = [authzid] UTF8NUL authcid UTF8NUL passwd - authcid = 1*SAFE ; MUST accept up to 255 octets - authzid = 1*SAFE ; MUST accept up to 255 octets - passwd = 1*SAFE ; MUST accept up to 255 octets - UTF8NUL = %x00 ; UTF-8 encoded NUL character - - SAFE = UTF1 / UTF2 / UTF3 / UTF4 - ;; any UTF-8 encoded Unicode character except NUL - - UTF1 = %x01-7F ;; except NUL - UTF2 = %xC2-DF UTF0 - UTF3 = %xE0 %xA0-BF UTF0 / %xE1-EC 2(UTF0) / - %xED %x80-9F UTF0 / %xEE-EF 2(UTF0) - UTF4 = %xF0 %x90-BF 2(UTF0) / %xF1-F3 3(UTF0) / - %xF4 %x80-8F 2(UTF0) - UTF0 = %x80-BF - - The authorization identity (authzid), authentication identity - (authcid), password (passwd), and NUL character deliminators SHALL be - transferred as [UTF-8] encoded strings of [Unicode] characters. As - the NUL (U+0000) character is used as a deliminator, the NUL (U+0000) - character MUST NOT appear in authzid, authcid, or passwd productions. - - The form of the authzid production is specific to the application- - level protocol's SASL profile [SASL]. The authcid and passwd - productions are form-free. Use of non-visible characters or - characters that a user may be unable to enter on some keyboards is - discouraged. - - Servers MUST be capable of accepting authzid, authcid, and passwd - productions up to and including 255 octets. It is noted that the - UTF-8 encoding of a Unicode character may be as long as 4 octets. - - Upon receipt of the message, the server will verify the presented (in - the message) authentication identity (authcid) and password (passwd) - with the system authentication database, and it will verify that the - authentication credentials permit the client to act as the (presented - or derived) authorization identity (authzid). If both steps succeed, - the user is authenticated. - - The presented authentication identity and password strings, as well - as the database authentication identity and password strings, are to - be prepared before being used in the verification process. The - [SASLPrep] profile of the [StringPrep] algorithm is the RECOMMENDED - preparation algorithm. The SASLprep preparation algorithm is - - - -Zeilenga Standards Track [Page 3] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - recommended to improve the likelihood that comparisons behave in an - expected manner. The SASLprep preparation algorithm is not mandatory - so as to allow the server to employ other preparation algorithms - (including none) when appropriate. For instance, use of a different - preparation algorithm may be necessary for the server to interoperate - with an external system. - - When preparing the presented strings using [SASLPrep], the presented - strings are to be treated as "query" strings (Section 7 of - [StringPrep]) and hence unassigned code points are allowed to appear - in their prepared output. When preparing the database strings using - [SASLPrep], the database strings are to be treated as "stored" - strings (Section 7 of [StringPrep]) and hence unassigned code points - are prohibited from appearing in their prepared output. - - Regardless of the preparation algorithm used, if the output of a - non-invertible function (e.g., hash) of the expected string is - stored, the string MUST be prepared before input to that function. - - Regardless of the preparation algorithm used, if preparation fails or - results in an empty string, verification SHALL fail. - - When no authorization identity is provided, the server derives an - authorization identity from the prepared representation of the - provided authentication identity string. This ensures that the - derivation of different representations of the authentication - identity produces the same authorization identity. - - The server MAY use the credentials to initialize any new - authentication database, such as one suitable for [CRAM-MD5] or - [DIGEST-MD5]. - -3. Pseudo-Code - - This section provides pseudo-code illustrating the verification - process (using hashed passwords and the SASLprep preparation - function) discussed above. This section is not definitive. - - boolean Verify(string authzid, string authcid, string passwd) { - string pAuthcid = SASLprep(authcid, true); # prepare authcid - string pPasswd = SASLprep(passwd, true); # prepare passwd - if (pAuthcid == NULL || pPasswd == NULL) { - return false; # preparation failed - } - if (pAuthcid == "" || pPasswd == "") { - return false; # empty prepared string - } - - - - -Zeilenga Standards Track [Page 4] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - storedHash = FetchPasswordHash(pAuthcid); - if (storedHash == NULL || storedHash == "") { - return false; # error or unknown authcid - } - - if (!Compare(storedHash, Hash(pPasswd))) { - return false; # incorrect password - } - - if (authzid == NULL ) { - authzid = DeriveAuthzid(pAuthcid); - if (authzid == NULL || authzid == "") { - return false; # could not derive authzid - } - } - - if (!Authorize(pAuthcid, authzid)) { - return false; # not authorized - } - - return true; - } - - The second parameter of the SASLprep function, when true, indicates - that unassigned code points are allowed in the input. When the - SASLprep function is called to prepare the password prior to - computing the stored hash, the second parameter would be false. - - The second parameter provided to the Authorize function is not - prepared by this code. The application-level SASL profile should be - consulted to determine what, if any, preparation is necessary. - - Note that the DeriveAuthzid and Authorize functions (whether - implemented as one function or two, whether designed in a manner in - which these functions or whether the mechanism implementation can be - reused elsewhere) require knowledge and understanding of mechanism - and the application-level protocol specification and/or - implementation details to implement. - - Note that the Authorize function outcome is clearly dependent on - details of the local authorization model and policy. Both functions - may be dependent on other factors as well. - - - - - - - - - -Zeilenga Standards Track [Page 5] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -4. Examples - - This section provides examples of PLAIN authentication exchanges. - The examples are intended to help the readers understand the above - text. The examples are not definitive. - - "C:" and "S:" indicate lines sent by the client and server, - respectively. "<NUL>" represents a single NUL (U+0000) character. - The Application Configuration Access Protocol ([ACAP]) is used in the - examples. - - The first example shows how the PLAIN mechanism might be used for - user authentication. - - S: * ACAP (SASL "CRAM-MD5") (STARTTLS) - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - S: * ACAP (SASL "CRAM-MD5" "PLAIN") - C: a002 AUTHENTICATE "PLAIN" - S: + "" - C: {21} - C: <NUL>tim<NUL>tanstaaftanstaaf - S: a002 OK "Authenticated" - - The second example shows how the PLAIN mechanism might be used to - attempt to assume the identity of another user. In this example, the - server rejects the request. Also, this example makes use of the - protocol optional initial response capability to eliminate a round- - trip. - - S: * ACAP (SASL "CRAM-MD5") (STARTTLS) - C: a001 STARTTLS - S: a001 OK "Begin TLS negotiation now" - <TLS negotiation, further commands are under TLS layer> - S: * ACAP (SASL "CRAM-MD5" "PLAIN") - C: a002 AUTHENTICATE "PLAIN" {20+} - C: Ursel<NUL>Kurt<NUL>xipj3plmq - S: a002 NO "Not authorized to requested authorization identity" - -5. Security Considerations - - As the PLAIN mechanism itself provided no integrity or - confidentiality protections, it should not be used without adequate - external data security protection, such as TLS services provided by - many application-layer protocols. By default, implementations SHOULD - NOT advertise and SHOULD NOT make use of the PLAIN mechanism unless - adequate data security services are in place. - - - -Zeilenga Standards Track [Page 6] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - When the PLAIN mechanism is used, the server gains the ability to - impersonate the user to all services with the same password - regardless of any encryption provided by TLS or other confidentiality - protection mechanisms. Whereas many other authentication mechanisms - have similar weaknesses, stronger SASL mechanisms address this issue. - Clients are encouraged to have an operational mode where all - mechanisms that are likely to reveal the user's password to the - server are disabled. - - General [SASL] security considerations apply to this mechanism. - - Unicode, [UTF-8], and [StringPrep] security considerations also - apply. - -6. IANA Considerations - - The SASL Mechanism registry [IANA-SASL] entry for the PLAIN mechanism - has been updated by the IANA to reflect that this document now - provides its technical specification. - - To: iana@iana.org - Subject: Updated Registration of SASL mechanism PLAIN - - SASL mechanism name: PLAIN - Security considerations: See RFC 4616. - Published specification (optional, recommended): RFC 4616 - Person & email address to contact for further information: - Kurt Zeilenga <kurt@openldap.org> - IETF SASL WG <ietf-sasl@imc.org> - Intended usage: COMMON - Author/Change controller: IESG <iesg@ietf.org> - Note: Updates existing entry for PLAIN - -7. Acknowledgements - - This document is a revision of RFC 2595 by Chris Newman. Portions of - the grammar defined in Section 2 were borrowed from [UTF-8] by - Francois Yergeau. - - This document is a product of the IETF Simple Authentication and - Security Layer (SASL) Working Group. - - - - - - - - - - -Zeilenga Standards Track [Page 7] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -8. Normative References - - [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 4234, October 2005. - - [Keywords] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [SASL] Melnikov, A., Ed., and K. Zeilenga, Ed., "Simple - Authentication and Security Layer (SASL)", RFC 4422, - June 2006. - - [SASLPrep] Zeilenga, K., "SASLprep: Stringprep Profile for User - Names and Passwords", RFC 4013, February 2005. - - [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [Unicode] The Unicode Consortium, "The Unicode Standard, Version - 3.2.0" is defined by "The Unicode Standard, Version - 3.0" (Reading, MA, Addison-Wesley, 2000. ISBN 0-201- - 61633-5), as amended by the "Unicode Standard Annex - #27: Unicode 3.1" - (http://www.unicode.org/reports/tr27/) and by the - "Unicode Standard Annex #28: Unicode 3.2" - (http://www.unicode.org/reports/tr28/). - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [TLS] Dierks, T. and E. Rescorla, "The Transport Layer - Security (TLS) Protocol Version 1.1", RFC 4346, April - 2006. - -9. Informative References - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November - 1997. - - [CRAM-MD5] Nerenberg, L., Ed., "The CRAM-MD5 SASL Mechanism", Work - in Progress, June 2006. - - [DIGEST-MD5] Melnikov, A., Ed., "Using Digest Authentication as a - SASL Mechanism", Work in Progress, June 2006. - - - - - -Zeilenga Standards Track [Page 8] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - - [IANA-SASL] IANA, "SIMPLE AUTHENTICATION AND SECURITY LAYER (SASL) - MECHANISMS", - <http://www.iana.org/assignments/sasl-mechanisms>. - - [SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication", - RFC 2554, March 1999. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 9] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -Appendix A. Changes since RFC 2595 - - This appendix is non-normative. - - This document replaces Section 6 of RFC 2595. - - The specification details how the server is to compare client- - provided character strings with stored character strings. - - The ABNF grammar was updated. In particular, the grammar now allows - LINE FEED (U+000A) and CARRIAGE RETURN (U+000D) characters in the - authzid, authcid, passwd productions. However, whether these control - characters may be used depends on the string preparation rules - applicable to the production. For passwd and authcid productions, - control characters are prohibited. For authzid, one must consult the - application-level SASL profile. This change allows PLAIN to carry - all possible authorization identity strings allowed in SASL. - - Pseudo-code was added. - - The example section was expanded to illustrate more features of the - PLAIN mechanism. - -Editor's Address - - Kurt D. Zeilenga - OpenLDAP Foundation - - EMail: Kurt@OpenLDAP.org - - - - - - - - - - - - - - - - - - - - - - -Zeilenga Standards Track [Page 10] - -RFC 4616 The PLAIN SASL Mechanism August 2006 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2006). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA). - - - - - - - -Zeilenga Standards Track [Page 11] - diff --git a/docs/[rfc5228] Sieve/obsolete/rfc3028 - sievescripts.txt b/docs/[rfc5228] Sieve/obsolete/rfc3028 - sievescripts.txt deleted file mode 100755 index c5a57c46..00000000 --- a/docs/[rfc5228] Sieve/obsolete/rfc3028 - sievescripts.txt +++ /dev/null @@ -1,276 +0,0 @@ -This Sievecode is extracted from the sieve spec. - -_Comments_______________________________________________________________________ - -if size :over 100K { # this is a comment - discard; -} - ---- - -if size :over 100K { /* this is a comment - this is still a comment */ discard /* this is a comment - */ ; -} - -_Test Lists_____________________________________________________________________ - -if anyof (not exists ["From", "Date"], - header :contains "from" "fool@example.edu") { - discard; -} - -_Comparators____________________________________________________________________ - -if header :contains :comparator "i;octet" "Subject" - "MAKE MONEY FAST" { - discard; -} - -_Implicit Keep__________________________________________________________________ - -if size :over 500K { discard; } - -_Control Structure If´__________________________________________________________ - -require "fileinto"; -if header :contains "from" "coyote" { - discard; -} elsif header :contains ["subject"] ["$$$"] { - discard; -} else { - fileinto "INBOX"; -} - ---- - -if header :contains ["From"] ["coyote"] { - redirect "acm@example.edu"; -} elsif header :contains "Subject" "$$$" { - redirect "postmaster@example.edu"; -} else { - redirect "field@example.edu"; -} - -_Control Structure Require______________________________________________________ - -require ["fileinto", "reject"]; - ---- - -require "fileinto"; -require "vacation"; - -_Action reject__________________________________________________________________ - -if header :contains "from" "coyote@desert.example.org" { - reject "I am not taking mail from you, and I don't want - your birdseed, either!"; -} - -_Action fileinto________________________________________________________________ - -require "fileinto"; -if header :contains ["from"] "coyote" { - fileinto "INBOX.harassment"; -} - -_Action redirect________________________________________________________________ - -redirect "bart@example.edu"; - -_Action keep____________________________________________________________________ - -if size :under 1M { keep; } else { discard; } - --- - -if not size :under 1M { discard; } - -_Action discard_________________________________________________________________ - -if header :contains ["from"] ["idiot@example.edu"] { - discard; -} - -_Test Address___________________________________________________________________ - -if address :is :all "from" "tim@example.com" { - discard; -} - -_Envelope Test__________________________________________________________________ - -require "envelope"; -if envelope :all :is "from" "tim@example.com" { - discard; -} - -_Test exists____________________________________________________________________ - -if not exists ["From","Date"] { - discard; - } - -_Extended Example_______________________________________________________________ - -# -# 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; - } -# -# 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"; - } - - - -=IMAPFLAGS====================================================================== - -_Setflag Action_________________________________________________________________ - -if size :over 500K { - setflag "\\Deleted"; - } - ---- - -if header :contains "from" "boss@frobnitzm.edu" { - setflag "\\Flagged"; - fileinto "INBOX.From Boss"; -} - -_Addflag Action_________________________________________________________________ - -addflag "\\Deleted"; -addflag "\\Answered"; -addflag ["\\Deleted", "\\Answered"]; - -_Removeflag Action______________________________________________________________ - -if header :contains "Disposition-Notification-To" "mel@example.com" { - addflag "$MDNRequired"; -} -if header :contains "from" "imap@cac.washington.edu" { - removeflag "$MDNRequired"; - fileinto "INBOX.imap-list"; -} - -_Extended example_______________________________________________________________ - - # - # Example Sieve Filter - # Declare any optional features or extension used by the script - # - require ["fileinto", "reject", "imapflags"]; - - # - # Reject any large messages - # - if size :over 1M - { - if header :is "From" "boss@company.com" - { - addflag "\\Flagged $Big"; - # The message will be marked as "\Flagged $Big" when filed into - # mailbox "Big messages" - } - fileinto "Big messages"; - } - - if header :is "From" "grandma@example.net" - { - addflag ["\\Answered", "$MDNSent"]; - # If the message is bigger than 1Mb it will be marked as "\Flagged - # $Big \Answered $MDNSent" - # when filed into mailbox "grandma". If the message is shorter than - # 1Mb it will be marked as "\Answered $MDNSent" - fileinto "GrandMa"; # move to "GrandMa" folder - } - - # - # 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" - { - setflag "\\Flagged"; - # Message will always have just "\Flagged" flag - keep; - } - - # - # Keep all messages to or from people in my company - # - elsif anyof address :domain :is ["From", "To"] "company.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@company.com", - header :matches "subject" - ["*make*money*fast*", "*university*dipl*mas*"]) - { - removeflag "\\Flagged"; - # 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"; - } diff --git a/docs/[rfc5228] Sieve/obsolete/rfc3028.txt b/docs/[rfc5228] Sieve/obsolete/rfc3028.txt deleted file mode 100755 index d909a542..00000000 --- a/docs/[rfc5228] Sieve/obsolete/rfc3028.txt +++ /dev/null @@ -1,2019 +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 "<key: string>" 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" <comparator-name: string> - - 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 <test1: test> <block1: block> - - Syntax: elsif <test2: test> <block2: block> - - Syntax: else <block> - - 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 <capabilities: string-list> - - 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 <reason: string> - - 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 <folder: string> - - 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 <address: string> - - 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] - <header-list: string-list> <key-list: string-list> - - 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 <tests: test-list> - - 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 <tests: test-list> - - 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] - <envelope-part: string-list> <key-list: string-list> - - 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 <header-names: string-list> - - 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] - <header-names: string-list> <key-list: string-list> - - 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 <test> - - 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"> <limit: number> - - 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 <folder: string> - 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 <reason: string> - 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] - <envelope-part: string-list> <key-list: string-list> - 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/docs/[rfc5228] Sieve/rfc5228.txt b/docs/[rfc5228] Sieve/rfc5228.txt deleted file mode 100755 index e5a02c6d..00000000 --- a/docs/[rfc5228] Sieve/rfc5228.txt +++ /dev/null @@ -1,2355 +0,0 @@ - - - - - - -Network Working Group P. Guenther, Ed. -Request for Comments: 5228 Sendmail, Inc. -Obsoletes: 3028 T. Showalter, Ed. -Category: Standards Track January 2008 - - - Sieve: An Email 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. - -Abstract - - This document describes a language for filtering email 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 the base language - has no variables, loops, or ability to shell out to external - programs. - - - - - - - - - - - - - - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 1] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -Table of Contents - - 1. Introduction ....................................................4 - 1.1. Conventions Used in This Document ..........................4 - 1.2. Example Mail Messages ......................................5 - 2. Design ..........................................................6 - 2.1. Form of the Language .......................................6 - 2.2. Whitespace .................................................7 - 2.3. Comments ...................................................7 - 2.4. Literal Data ...............................................7 - 2.4.1. Numbers .............................................7 - 2.4.2. Strings .............................................8 - 2.4.2.1. String Lists ...............................9 - 2.4.2.2. Headers ....................................9 - 2.4.2.3. Addresses .................................10 - 2.4.2.4. Encoding Characters Using - "encoded-character" .......................10 - 2.5. Tests .....................................................11 - 2.5.1. Test Lists .........................................12 - 2.6. Arguments .................................................12 - 2.6.1. Positional Arguments ...............................12 - 2.6.2. Tagged Arguments ...................................12 - 2.6.3. Optional Arguments .................................13 - 2.6.4. Types of Arguments .................................13 - 2.7. String Comparison .........................................13 - 2.7.1. Match Type .........................................14 - 2.7.2. Comparisons across Character Sets ..................15 - 2.7.3. Comparators ........................................15 - 2.7.4. Comparisons against Addresses ......................16 - 2.8. Blocks ....................................................17 - 2.9. Commands ..................................................17 - 2.10. Evaluation ...............................................18 - 2.10.1. Action Interaction ................................18 - 2.10.2. Implicit Keep .....................................18 - 2.10.3. Message Uniqueness in a Mailbox ...................19 - 2.10.4. Limits on Numbers of Actions ......................19 - 2.10.5. Extensions and Optional Features ..................19 - 2.10.6. Errors ............................................20 - 2.10.7. Limits on Execution ...............................20 - 3. Control Commands ...............................................21 - 3.1. Control if ................................................21 - 3.2. Control require ...........................................22 - 3.3. Control stop ..............................................22 - 4. Action Commands ................................................23 - 4.1. Action fileinto ...........................................23 - 4.2. Action redirect ...........................................23 - 4.3. Action keep ...............................................24 - 4.4. Action discard ............................................25 - - - -Guenther & Showalter Standards Track [Page 2] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 5. Test Commands ..................................................26 - 5.1. Test address ..............................................26 - 5.2. Test allof ................................................27 - 5.3. Test anyof ................................................27 - 5.4. Test envelope .............................................27 - 5.5. Test exists ...............................................28 - 5.6. Test false ................................................28 - 5.7. Test header ...............................................29 - 5.8. Test not ..................................................29 - 5.9. Test size .................................................29 - 5.10. Test true ................................................30 - 6. Extensibility ..................................................30 - 6.1. Capability String .........................................31 - 6.2. IANA Considerations .......................................31 - 6.2.1. Template for Capability Registrations ..............32 - 6.2.2. Handling of Existing Capability Registrations ......32 - 6.2.3. Initial Capability Registrations ...................32 - 6.3. Capability Transport ......................................33 - 7. Transmission ...................................................33 - 8. Parsing ........................................................34 - 8.1. Lexical Tokens ............................................34 - 8.2. Grammar ...................................................36 - 8.3. Statement Elements ........................................36 - 9. Extended Example ...............................................37 - 10. Security Considerations .......................................38 - 11. Acknowledgments ...............................................39 - 12. Normative References ..........................................39 - 13. Informative References ........................................40 - 14. Changes from RFC 3028 .........................................41 - - - - - - - - - - - - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 3] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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 graphical user interfaces (GUIs) for filter creation and - manipulation. The base language was not designed to be Turing- - complete: it does not have a loop control structure or functions. - - Scripts written in Sieve are executed during final delivery, when the - message is moved to the user-accessible mailbox. In systems where - the Mail Transfer Agent (MTA) does final delivery, such as - traditional Unix mail, it is reasonable to filter 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 - email, 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. - -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", "REQUIRED", "SHALL", "SHALL NOT", - "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this - document are to be interpreted as described in [KEYWORDS]. - - - -Guenther & Showalter Standards Track [Page 4] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Each section on a command (test, action, or control) has a line - labeled "Usage:". This line describes the usage 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 "<key: string>" represents an argument called "key" that - is a string. Literal strings are represented with double-quoted - strings. Alternatives are separated with slashes, and parentheses - are used for grouping, similar to [ABNF]. - - In the "Usage:" 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 is defined in section 8 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, or 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 - 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 - ----------------------------------------------------------- - - - - - - - - -Guenther & Showalter Standards Track [Page 5] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Message B - ----------------------------------------------------------- - From: youcouldberich!@reply-by-postal-mail.invalid - Sender: b1ff@de.res.example.com - To: rube@landru.example.com - 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. - - With the exceptions of strings and comments, the language is limited - to US-ASCII characters. Strings and comments may contain octets - outside the US-ASCII range. Specifically, they will normally be in - UTF-8, as specified in [UTF-8]. NUL (US-ASCII 0) is never permitted - in scripts, while CR and LF can only appear as the CRLF line ending. - - Note: While this specification permits arbitrary octets to appear - in Sieve scripts inside strings and comments, this has made it - difficult to robustly handle Sieve scripts in programs that are - sensitive to the encodings used. The "encoded-character" - capability (section 2.4.2.4) provides an alternative means of - representing such octets in strings using just US-ASCII - characters. As such, the use of non-UTF-8 text in scripts should - be considered a deprecated feature that may be abandoned. - - Tokens other than strings are considered case-insensitive. - - - - - - - - -Guenther & Showalter Standards Track [Page 6] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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. - -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, strings, and string lists. - -2.4.1. Numbers - - Numbers are given as ordinary decimal numbers. As a shorthand for - expressing larger values, such as message sizes, a suffix of "K", - "M", or "G" MAY be 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 gibi-, or - 1,073,741,824 (2^30) times the value of the number [BINARY-SI]. - - - - - - -Guenther & Showalter Standards Track [Page 7] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Implementations MUST support integer values in the inclusive range - zero to 2,147,483,647 (2^31 - 1), but MAY support larger values. - - Only non-negative integers are permitted by this specification. - -2.4.2. Strings - - Scripts involve large numbers of string values 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, US-ASCII 34). A backslash ("\", US-ASCII 92) inside of a - quoted string is followed by either another backslash or a double - quote. These two-character sequences represent a single backslash or - double quote within the value, respectively. - - Scripts SHOULD NOT escape other characters with a 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"), though that may be changed by - extensions. - - Non-printing characters such as tabs, CRLF, and control characters - are permitted in quoted strings. Quoted strings MAY span multiple - lines. An unencoded NUL (US-ASCII 0) is not allowed in strings; see - section 2.4.2.4 for how it can be encoded. - - As message header data is converted to [UTF-8] for comparison (see - section 2.7.2), most string values will use the UTF-8 encoding. - However, implementations MUST accept all strings that match the - grammar in section 8. The ability to use non-UTF-8 encoded strings - matches existing practice and has proven to be useful both in tests - for invalid data and in arguments containing raw MIME parts for - extension actions that generate outgoing messages. - - 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. The CRLF before the final period is - considered part of the value. 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 - that 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 as dot-stuffed; - - - -Guenther & Showalter Standards Track [Page 8] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 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. - - For instance, the test 'header :contains ["To", "Cc"] - ["me@example.com", "me00@landru.example.com"]' is true if either a To - header or Cc header of the input message contains either of the email - addresses "me@example.com" or "me00@landru.example.com". - - 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], 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. - - Similarly, no header will match a syntactically invalid header name. - An implementation MUST NOT cause an error for syntactically invalid - header names in tests. - - Header lines are unfolded as described in [IMAIL] section 2.2.3. - Interpretation of header data SHOULD be done according to [MIME3] - section 6.2 (see section 2.7.2 below for details). - - - - - - - -Guenther & Showalter Standards Track [Page 9] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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 within this document. Using the symbols defined in - [IMAIL], section 3, 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 - permitted. - - It is an error for a script to execute an action with a value for use - as an outbound address that doesn't match the "sieve-address" syntax. - -2.4.2.4. Encoding Characters Using "encoded-character" - - When the "encoded-character" extension is in effect, certain - character sequences in strings are replaced by their decoded value. - This happens after escape sequences are interpreted and dot- - unstuffing has been done. Implementations SHOULD support "encoded- - character". - - Arbitrary octets can be embedded in strings by using the syntax - encoded-arb-octets. The sequence is replaced by the octets with the - hexadecimal values given by each hex-pair. - - blank = WSP / CRLF - encoded-arb-octets = "${hex:" hex-pair-seq "}" - hex-pair-seq = *blank hex-pair *(1*blank hex-pair) *blank - hex-pair = 1*2HEXDIG - - Where WSP and HEXDIG non-terminals are defined in Appendix B.1 of - [ABNF]. - - It may be inconvenient or undesirable to enter Unicode characters - verbatim, and for these cases the syntax encoded-unicode-char can be - used. The sequence is replaced by the UTF-8 encoding of the - specified Unicode characters, which are identified by the hexadecimal - value of unicode-hex. - - encoded-unicode-char = "${unicode:" unicode-hex-seq "}" - unicode-hex-seq = *blank unicode-hex - *(1*blank unicode-hex) *blank - unicode-hex = 1*HEXDIG - - - -Guenther & Showalter Standards Track [Page 10] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - It is an error for a script to use a hexadecimal value that isn't in - either the range 0 to D7FF or the range E000 to 10FFFF. (The range - D800 to DFFF is excluded as those character numbers are only used as - part of the UTF-16 encoding form and are not applicable to the UTF-8 - encoding that the syntax here represents.) - - Note: Implementations MUST NOT raise an error for an out-of-range - Unicode value unless the sequence containing it is well-formed - according to the grammar. - - The capability string for use with the require command is "encoded- - character". - - In the following script, message B is discarded, since the specified - test string is equivalent to "$$$". - - Example: require "encoded-character"; - if header :contains "Subject" "$${hex:24 24}" { - discard; - } - The following examples demonstrate valid and invalid encodings and - how they are handled: - - "$${hex:40}" -> "$@" - "${hex: 40 }" -> "@" - "${HEX: 40}" -> "@" - "${hex:40" -> "${hex:40" - "${hex:400}" -> "${hex:400}" - "${hex:4${hex:30}}" -> "${hex:40}" - "${unicode:40}" -> "@" - "${ unicode:40}" -> "${ unicode:40}" - "${UNICODE:40}" -> "@" - "${UnICoDE:0000040}" -> "@" - "${Unicode:40}" -> "@" - "${Unicode:Cool}" -> "${Unicode:Cool}" - "${unicode:200000}" -> error - "${Unicode:DF01} -> error - -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 to decide - which block of code is run. - - - - - - - - -Guenther & Showalter Standards Track [Page 11] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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 as a comma-separated list in parentheses. - - Example: if anyof (not exists ["From", "Date"], - header :contains "from" "fool@example.com") { - 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. - - It is an error for a script, on a single command, to use conflicting - arguments or to use a tagged or optional argument more than once. - -2.6.1. Positional Arguments - - Positional arguments are given to a command that 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. - -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 literal data, 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 - - - - - -Guenther & Showalter Standards Track [Page 12] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - with commands, but they still may be reordered arbitrarily provided - they appear before positional arguments. Tagged arguments may be - mixed with optional arguments. - - 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 comparator [COLLATION] will be used - to compare two strings, since different languages may impose - different orderings on UTF-8 [UTF-8] strings. - -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 8.2 presents a parsable version of this: - Arguments are string lists (string-lists), numbers, and tags, which - may be followed by a test or a test list (test-list), which may be - followed by a block of commands. No more than one test or test list, - or more than one block of commands, may be used, and commands that - end with a block 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 uses the comparators defined in the Internet - Application Protocol Collation Registry [COLLATION]. - - - - - - - -Guenther & Showalter Standards Track [Page 13] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 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 - - Commands that perform string comparisons may have an optional match - type argument. The three match types in this specification are - ":contains", ":is", and ":matches". - - 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 empty 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 empty key ("") only ":is" matches with the empty - value. - - The ":matches" match type specifies a wildcard match using the - characters "*" and "?"; the entire value must be matched. "*" - matches zero or more characters in the value and "?" matches a single - character in the value, where the comparator that is used (see - section 2.7.3) defines what a character is. For example, the - comparators "i;octet" and "i;ascii-casemap" define a character to be - a single octet, so "?" will always match exactly one octet when one - of those comparators is in use. In contrast, a Unicode-based - comparator would define a character to be any UTF-8 octet sequence - encoding one Unicode character and thus "?" may match more than one - octet. "?" 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. - - In order to specify what type of match is supposed to happen, - commands that support matching take optional arguments ":matches", - ":is", and ":contains". Commands default to using ":is" matching if - no match type argument is supplied. Note that these modifiers - interact with comparators; in particular, only comparators that - support the "substring match" operation are 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. - - - - -Guenther & Showalter Standards Track [Page 14] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 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 - - Messages may involve a number of character sets. In order for - comparisons to work across character sets, implementations SHOULD - implement the following behavior: - - Comparisons are performed on octets. Implementations convert text - from header fields in all charsets [MIME3] to Unicode, encoded as - UTF-8, as input to the comparator (see section 2.7.3). - Implementations MUST be capable of converting US-ASCII, ISO-8859- - 1, the US-ASCII subset of ISO-8859-* character sets, and UTF-8. - Text that the implementation cannot convert to Unicode for any - reason MAY be treated as plain US-ASCII (including any [MIME3] - syntax) or processed according to local conventions. An encoded - NUL octet (character zero) SHOULD NOT cause early termination of - the header content being compared against. - - 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. The Internet - Application Protocol Collation Registry [COLLATION] provides the - framework for describing and naming comparators. - - 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 US-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 to use a - comparator with ":matches" or ":contains" that is not compatible with - it. - - - - -Guenther & Showalter Standards Track [Page 15] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Sieve treats a comparator result of "undefined" the same as a result - of "no-match". That is, this base specification does not provide any - means to directly detect invalid comparator input. - - 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" <comparator-name: string> - - 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 section 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 - 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. - - - - -Guenther & Showalter Standards Track [Page 16] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - If an address is not syntactically valid, then it will not be matched - by tests specifying ":localpart" or ":domain". - - 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 and supplied - as the final argument to a command. Such a command is a control - structure: when executed it has control over the number of times the - commands in the block are executed. - - 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. - -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. - The actions referenced in this document are: - - - keep, to save the message in the default location - - fileinto, to save the message in a specific mailbox - - redirect, to forward the message to another address - - discard, to silently throw away the message - - - - - - -Guenther & Showalter Standards Track [Page 17] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - A control command is a command that affects the parsing or the flow - of execution of the Sieve script in some way. A control structure is - a control command that 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 section 4.3) 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 may. - - 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. - - - - - - - - -Guenther & Showalter Standards Track [Page 18] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -2.10.3. Message Uniqueness in a Mailbox - - Implementations SHOULD NOT deliver a message to the same mailbox more - than once, even if a script explicitly asks for a message to be - written to a mailbox twice. - - 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 the number 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 allow at least one keep or one fileinto. If - fileinto is not implemented, implementations MUST allow at least one - keep. - -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. This protects scripts - from having their behavior altered by extensions that the script - author might not have even been aware of. - - Implementations MUST NOT execute any Sieve script test or command - subsequent to "require" if one of the required extensions is - unavailable. - - 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. - - Extensions that define actions MUST state how they interact with - actions discussed in the base specification. - - - - - - - -Guenther & Showalter Standards Track [Page 19] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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 MUST perform syntactic, semantic, and run-time checks - on code that is actually executed. Implementations MAY perform those - checks or any part of them on code that is not reached during - execution. - - When an error happens, implementations MUST notify the user that an - error occurred and 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. - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 20] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -3. Control Commands - - Control structures are needed to allow for multiple and conditional - actions. - -3.1. Control 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 or else MUST only follow an if or elsif. An error occurs if - these conditions are not met. - - Usage: if <test1: test> <block1: block> - - Usage: elsif <test2: test> <block2: block> - - Usage: else <block3: block> - - The semantics are similar to those of any of the many other - programming languages these control structures 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's block. - - This provides a way of performing exactly one of the blocks in the - chain. - - In the following example, both messages A and B are dropped. - - Example: require "fileinto"; - if header :contains "from" "coyote" { - discard; - } elsif header :contains ["subject"] ["$$$"] { - discard; - } else { - fileinto "INBOX"; - } - - - - - - -Guenther & Showalter Standards Track [Page 21] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - When the script below is run over message A, it redirects the message - to acm@example.com; message B, to postmaster@example.com; any other - message is redirected to field@example.com. - - Example: if header :contains ["From"] ["coyote"] { - redirect "acm@example.com"; - } elsif header :contains "Subject" "$$$" { - redirect "postmaster@example.com"; - } else { - redirect "field@example.com"; - } - - 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 require - - Usage: require <capabilities: string-list> - - 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 stop - - Usage: stop - - The "stop" action ends all processing. If the implicit keep has not - been cancelled, then it is taken. - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 22] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -4. Action Commands - - This document supplies four actions that may be taken on a message: - keep, fileinto, redirect, and discard. - - Implementations MUST support the "keep", "discard", and "redirect" - actions. - - Implementations SHOULD support "fileinto". - - Implementations MAY limit the number of certain actions taken (see - section 2.10.4). - -4.1. Action fileinto - - Usage: fileinto <mailbox: string> - - The "fileinto" action delivers the message into the specified - mailbox. Implementations SHOULD support fileinto, but in some - environments this may be impossible. Implementations MAY place - restrictions on mailbox names; use of an invalid mailbox name MAY be - treated as an error or result in delivery to an implementation- - defined mailbox. If the specified mailbox doesn't exist, the - implementation MAY treat it as an error, create the mailbox, or - deliver the message to an implementation-defined mailbox. If the - implementation uses a different encoding scheme than UTF-8 for - mailbox names, it SHOULD reencode the mailbox name from UTF-8 to its - encoding scheme. For example, the Internet Message Access Protocol - [IMAP] uses modified UTF-7, such that a mailbox argument of "odds & - ends" would appear in IMAP as "odds &- ends". - - The capability string for use with the require command is "fileinto". - - In the following script, message A is filed into mailbox - "INBOX.harassment". - - Example: require "fileinto"; - if header :contains ["from"] "coyote" { - fileinto "INBOX.harassment"; - } - -4.2. Action redirect - - Usage: redirect <address: string> - - 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 - - - -Guenther & Showalter Standards Track [Page 23] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - headers, but it may add new headers. In particular, existing - Received headers MUST be preserved and the count of Received headers - in the outgoing message MUST be larger than the same count on the - message as received by the implementation. (An implementation that - adds a Received header before processing the message does not need to - add another when redirecting.) - - The message is sent back out with the address from the redirect - command as an envelope recipient. Implementations MAY combine - separate redirects for a given message into a single submission with - multiple envelope recipients. (This is not a Mail User Agent (MUA)- - style forward, which creates a new message with a different sender - and message ID, wrapping the old message in a new one.) - - The envelope sender address on the outgoing message is chosen by the - sieve implementation. It MAY be copied from the message being - processed. However, if the message being processed has an empty - envelope sender address the outgoing message MUST also have an empty - envelope sender address. This last requirement is imposed to prevent - loops in the case where a message is redirected to an invalid address - when then returns a delivery status notification that also ends up - being redirected to the same invalid address. - - A simple script can be used for redirecting all mail: - - Example: redirect "bart@example.com"; - - Implementations MUST take measures to implement loop control, - possibly including adding headers to the message or counting Received - headers as specified in section 6.2 of [SMTP]. If an implementation - detects a loop, it causes an error. - - Implementations MUST provide means of limiting the number of - redirects a Sieve script can perform. See section 10 for more - details. - - Implementations MAY ignore a redirect action silently due to policy - reasons. For example, an implementation MAY choose not to redirect - to an address that is known to be undeliverable. Any ignored - redirect MUST NOT cancel the implicit keep. - -4.3. Action keep - - Usage: 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 - - - -Guenther & Showalter Standards Track [Page 24] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 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. - - 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.4. Action discard - - Usage: 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.com" is thrown - out. - - Example: if header :contains ["from"] ["idiot@example.com"] { - 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. - - - - - - - - - - -Guenther & Showalter Standards Track [Page 25] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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. - -5.1. Test address - - Usage: address [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] - <header-list: string-list> <key-list: string-list> - - 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. Whether there are other addresses - present in the header doesn't affect this test; this test does not - provide any way to determine whether an address is the only address - in a header. - - Like envelope and header, this test returns true if any combination - of the header-list and key-list arguments match and returns false - otherwise. - - 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 or 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, and Resent-To, and it SHOULD include any other - header that utilizes an "address-list" structured header body. - - Example: if address :is :all "from" "tim@example.com" { - discard; - } - - - - -Guenther & Showalter Standards Track [Page 26] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -5.2. Test allof - - Usage: allof <tests: test-list> - - 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. - -5.3. Test anyof - - Usage: anyof <tests: test-list> - - 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 - - Usage: envelope [COMPARATOR] [ADDRESS-PART] [MATCH-TYPE] - <envelope-part: string-list> <key-list: string-list> - - The "envelope" test is true if the specified part of the [SMTP] (or - equivalent) envelope matches the specified key. This specification - defines the interpretation of the (case insensitive) "from" and "to" - envelope-parts. Additional envelope-parts may be defined by other - extensions; implementations SHOULD consider unknown envelope parts an - error. - - If one of the envelope-part strings is (case insensitive) "from", - then matching occurs against the FROM address used in the SMTP MAIL - command. The null reverse-path is matched against as the empty - string, regardless of the ADDRESS-PART argument specified. - - 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. - - - -Guenther & Showalter Standards Track [Page 27] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Like address and header, this test returns true if any combination of - the envelope-part list and key-list arguments match and returns false - otherwise. - - 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. The - capability string for use with the require command is "envelope". - - Example: require "envelope"; - if envelope :all :is "from" "tim@example.com" { - discard; - } - -5.5. Test exists - - Usage: exists <header-names: string-list> - - 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 - - Usage: false - - The "false" test always evaluates to false. - - - - - - - - - -Guenther & Showalter Standards Track [Page 28] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -5.7. Test header - - Usage: header [COMPARATOR] [MATCH-TYPE] - <header-names: string-list> <key-list: string-list> - - The "header" test evaluates to true if the value of any of the named - headers, ignoring leading and trailing whitespace, 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 header-names list and key-list arguments match and returns - false otherwise. - - If a header listed in the header-names argument exists, it contains - the empty key (""). However, if the named header is not present, it - does not match any key, including the empty key. So if a message - contained the header - - X-Caffeine: C8H10N4O2 - - these tests on that header evaluate as follows: - - header :is ["X-Caffeine"] [""] => false - header :contains ["X-Caffeine"] [""] => true - - Testing whether a given header is either absent or doesn't contain - any non-whitespace characters can be done using a negated "header" - test: - - not header :matches "Cc" "?*" - -5.8. Test not - - Usage: not <test1: test> - - 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 - - Usage: size <":over" / ":under"> <limit: number> - - 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. - - - - -Guenther & Showalter Standards Track [Page 29] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - 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 in the - [IMAIL] representation of the message. - - Note that for a message that is exactly 4,000 octets, the message is - neither ":over" nor ":under" 4000 octets. - -5.10. Test true - - Usage: true - - The "true" test always evaluates to true. - -6. Extensibility - - New control commands, 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. - - Any extensions to this language MUST define a capability string that - uniquely identifies that extension. Capability string are case- - sensitive; for example, "foo" and "FOO" are different capabilities. - If a new version of an extension changes the functionality of a - previously defined extension, it MUST use a different name. - Extensions may register a set of related capabilities by registering - just a unique prefix for them. The "comparator-" prefix is an - example of this. The prefix MUST end with a "-" and MUST NOT overlap - any existing registrations. - - In a situation where there is a script 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. Extensions MUST - NOT change the behavior of the "require" control command or alter the - interpretation of the argument to the "require" control. - - - -Guenther & Showalter Standards Track [Page 30] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Extensions that can submit new email messages or otherwise generate - new protocol requests MUST consider loop suppression, at least to - document any security considerations. - -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: - - encoded-character The string "encoded-character" indicates that the - implementation supports the interpretation of - "${hex:...}" and "${unicode:...}" in strings. - - envelope The string "envelope" indicates that the implementation - supports the "envelope" command. - - fileinto The string "fileinto" indicates that the implementation - supports the "fileinto" 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. - -6.2. IANA Considerations - - In order to provide a standard set of extensions, a registry is - maintained by IANA. This registry contains both vendor-controlled - capability names (beginning with "vnd.") and IETF-controlled - capability names. Vendor-controlled capability names may be - registered on a first-come, first-served basis, by applying to IANA - with the form in the following section. Registration of capability - prefixes that do not begin with "vnd." REQUIRES a standards track or - IESG-approved experimental RFC. - - Extensions designed for interoperable use SHOULD use IETF-controlled - capability names. - - - - -Guenther & Showalter Standards Track [Page 31] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -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: [the string for use in the 'require' statement] - Description: [a brief description of what the extension adds - or changes] - RFC number: [for extensions published as RFCs] - Contact address: [email and/or physical address to contact for - additional information] - -6.2.2. Handling of Existing Capability Registrations - - In order to bring the existing capability registrations in line with - the new template, IANA has modified each as follows: - - 1. The "capability name" and "capability arguments" fields have been - eliminated - 2. The "capability keyword" field have been renamed to "Capability - name" - 3. An empty "Description" field has been added - 4. The "Standards Track/IESG-approved experimental RFC number" field - has been renamed to "RFC number" - 5. The "Person and email address to contact for further information" - field should be renamed to "Contact address" - -6.2.3. Initial Capability Registrations - - This RFC updates the following entries in the IANA registry for Sieve - extensions. - - Capability name: encoded-character - Description: changes the interpretation of strings to allow - arbitrary octets and Unicode characters to be - represented using US-ASCII - RFC number: RFC 5228 (Sieve base spec) - Contact address: The Sieve discussion list <ietf-mta-filters@imc.org> - - Capability name: fileinto - Description: adds the 'fileinto' action for delivering to a - mailbox other than the default - RFC number: RFC 5228 (Sieve base spec) - Contact address: The Sieve discussion list <ietf-mta-filters@imc.org> - - - - -Guenther & Showalter Standards Track [Page 32] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Capability name: envelope - Description: adds the 'envelope' test for testing the message - transport sender and recipient address - RFC number: RFC 5228 (Sieve base spec) - Contact address: The Sieve discussion list <ietf-mta-filters@imc.org> - - Capability name: comparator-* (anything starting with "comparator-") - Description: adds the indicated comparator for use with the - :comparator argument - RFC number: RFC 5228 (Sieve base spec) and [COLLATION] - Contact address: The Sieve discussion list <ietf-mta-filters@imc.org> - -6.3. Capability Transport - - 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 the 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 updated 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. - Security considerations: Discussed in section 10 of this RFC. - Interoperability considerations: Discussed in section 2.10.5 - of this RFC. - Published specification: this RFC. - Applications that use this media type: sieve-enabled mail - servers and clients - Additional information: - Magic number(s): - File extension(s): .siv .sieve - Macintosh File Type Code(s): - - - - -Guenther & Showalter Standards Track [Page 33] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - Person & email address to contact for further information: - See the discussion list at ietf-mta-filters@imc.org. - Intended usage: - COMMON - Author/Change controller: - The SIEVE WG, delegated by the IESG. - -8. Parsing - - The Sieve grammar is separated into tokens and a separate grammar as - most programming languages are. Additional rules are supplied here - for common arguments to various language facilities. - -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 US-ASCII. - - The following are tokens in Sieve: - - - identifiers - - tags - - numbers - - quoted strings - - multi-line strings - - other separators - - Identifiers, tags, and numbers are case-insensitive, while quoted - strings and multi-line strings are case-sensitive. - - Blanks, horizontal tabs, CRLFs, and comments ("whitespace") are - ignored except as they separate tokens. Some whitespace is required - to separate otherwise adjacent tokens and in specific places in the - multi-line strings. CR and LF can only appear in CRLF pairs. - - The other separators are single individual characters and are - mentioned explicitly in the grammar. - - The lexical structure of sieve is defined in the following grammar - (as described in [ABNF]): - - bracket-comment = "/*" *not-star 1*STAR - *(not-star-slash *not-star 1*STAR) "/" - ; 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.) - - - - -Guenther & Showalter Standards Track [Page 34] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - comment = bracket-comment / hash-comment - - hash-comment = "#" *octet-not-crlf CRLF - - identifier = (ALPHA / "_") *(ALPHA / DIGIT / "_") - - multi-line = "text:" *(SP / HTAB) (hash-comment / CRLF) - *(multiline-literal / multiline-dotstart) - "." CRLF - - multiline-literal = [ octet-not-period *octet-not-crlf ] CRLF - - multiline-dotstart = "." 1*octet-not-crlf CRLF - ; A line containing only "." ends the - ; multi-line. Remove a leading '.' if - ; followed by another '.'. - - not-star = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-FF - ; either a CRLF pair, OR a single octet - ; other than NUL, CR, LF, or star - - not-star-slash = CRLF / %x01-09 / %x0B-0C / %x0E-29 / %x2B-2E / - %x30-FF - ; either a CRLF pair, OR a single octet - ; other than NUL, CR, LF, star, or slash - - number = 1*DIGIT [ QUANTIFIER ] - - octet-not-crlf = %x01-09 / %x0B-0C / %x0E-FF - ; a single octet other than NUL, CR, or LF - - octet-not-period = %x01-09 / %x0B-0C / %x0E-2D / %x2F-FF - ; a single octet other than NUL, - ; CR, LF, or period - - octet-not-qspecial = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-FF - ; a single octet other than NUL, - ; CR, LF, double-quote, or backslash - - QUANTIFIER = "K" / "M" / "G" - - quoted-other = "\" octet-not-qspecial - ; represents just the octet-no-qspecial - ; character. SHOULD NOT be used - - quoted-safe = CRLF / octet-not-qspecial - ; either a CRLF pair, OR a single octet other - ; than NUL, CR, LF, double-quote, or backslash - - - -Guenther & Showalter Standards Track [Page 35] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - quoted-special = "\" (DQUOTE / "\") - ; represents just a double-quote or backslash - - quoted-string = DQUOTE quoted-text DQUOTE - - quoted-text = *(quoted-safe / quoted-special / quoted-other) - - STAR = "*" - - tag = ":" identifier - - white-space = 1*(SP / CRLF / HTAB) / comment - -8.2. Grammar - - The following is the grammar of Sieve after it has been lexically - interpreted. No whitespace or comments appear below. The start - symbol is "start". - - 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) ")" - -8.3. Statement Elements - - These elements are collected from the "Syntax" sections elsewhere in - this document, and are provided here in [ABNF] syntax so that they - can be modified by extensions. - - ADDRESS-PART = ":localpart" / ":domain" / ":all" - - - -Guenther & Showalter Standards Track [Page 36] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - COMPARATOR = ":comparator" string - - MATCH-TYPE = ":is" / ":contains" / ":matches" - -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"]; - - # - # Handle messages from known mailing lists - # Move messages from IETF filter discussion list to filter mailbox - # - if header :is "Sender" "owner-ietf-mta-filters@imc.org" - { - fileinto "filter"; # move to "filter" mailbox - } - # - # Keep all messages to or from people in my company - # - elsif address :DOMAIN :is ["From", "To"] "example.com" - { - keep; # keep in "In" mailbox - } - - # - # 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*"]) - { - fileinto "spam"; # move to "spam" mailbox - } - else - { - # Move all other (non-company) mail to "personal" - # mailbox. - fileinto "personal"; - } - - - -Guenther & Showalter Standards Track [Page 37] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -10. Security Considerations - - Users must get their mail. It is imperative that whatever - implementations use to store the user-defined filtering scripts - protect them from unauthorized modification, to preserve the - integrity of the mail system. An attacker who can modify a script - can cause mail to be discarded, rejected, or forwarded to an - unauthorized recipient. In addition, it's possible that Sieve - scripts might expose private information, such as mailbox names, or - email addresses of favored (or disfavored) correspondents. Because - of that, scripts SHOULD also be protected from unauthorized - retrieval. - - Several commands, such as "discard", "redirect", and "fileinto", - allow for actions to be taken that are potentially very dangerous. - - Use of the "redirect" command to generate notifications may easily - overwhelm the target address, especially if it was not designed to - handle large messages. - - Allowing a single script to redirect to multiple destinations can be - used as a means of amplifying the number of messages in an attack. - Moreover, if loop detection is not properly implemented, it may be - possible to set up exponentially growing message loops. Accordingly, - Sieve implementations: - - (1) MUST implement facilities to detect and break message loops. See - section 6.2 of [SMTP] for additional information on basic loop - detection strategies. - - (2) MUST provide the means for administrators to limit the ability of - users to abuse redirect. In particular, it MUST be possible to - limit the number of redirects a script can perform. - Additionally, if no use cases exist for using redirect to - multiple destinations, this limit SHOULD be set to 1. Additional - limits, such as the ability to restrict redirect to local users, - MAY also be implemented. - - (3) MUST provide facilities to log use of redirect in order to - facilitate tracking down abuse. - - (4) MAY use script analysis to determine whether or not a given - script can be executed safely. While the Sieve language is - sufficiently complex that full analysis of all possible scripts - is computationally infeasible, the majority of real-world scripts - are amenable to analysis. For example, an implementation might - - - - - -Guenther & Showalter Standards Track [Page 38] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - allow scripts that it has determined are safe to run unhindered, - block scripts that are potentially problematic, and subject - unclassifiable scripts to additional auditing and logging. - - Allowing redirects at all may not be appropriate in situations where - email accounts are freely available and/or not trackable to a human - who can be held accountable for creating message bombs or other - abuse. - - As with any filter on a message stream, if the Sieve implementation - and the mail agents 'behind' Sieve in the message stream differ in - their interpretation of the messages, it may be possible for an - attacker to subvert the filter. Of particular note are differences - in the interpretation of malformed messages (e.g., missing or extra - syntax characters) or those that exhibit corner cases (e.g., NUL - octets encoded via [MIME3]). - -11. Acknowledgments - - This document has been revised in part based on comments and - discussions that took place on and off the SIEVE mailing list. - Thanks to Sharon Chisholm, Cyrus Daboo, Ned Freed, Arnt Gulbrandsen, - Michael Haardt, Kjetil Torgrim Homme, Barry Leiba, Mark E. Mallett, - Alexey Melnikov, Eric Rescorla, Rob Siemborski, and Nigel Swinson for - reviews and suggestions. - -12. Normative References - - [ABNF] Crocker, D., Ed., and P. Overell, "Augmented BNF for - Syntax Specifications: ABNF", RFC 4234, October 2005. - - [COLLATION] Newman, C., Duerst, M., and A. Gulbrandsen, "Internet - Application Protocol Collation Registry", RFC 4790, March - 2007. - - [IMAIL] Resnick, P., Ed., "Internet Message Format", RFC 2822, - April 2001. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [MIME] Freed, N. and N. Borenstein, "Multipurpose Internet Mail - Extensions (MIME) Part One: Format of Internet Message - Bodies", RFC 2045, November 1996. - - [MIME3] Moore, K., "MIME (Multipurpose Internet Mail Extensions) - Part Three: Message Header Extensions for Non-ASCII - Text", RFC 2047, November 1996. - - - -Guenther & Showalter Standards Track [Page 39] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - - [SMTP] Klensin, J., Ed., "Simple Mail Transfer Protocol", RFC - 2821, April 2001. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - -13. Informative References - - [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 3464, January - 2003. - - [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. - - [IMAP] Crispin, M., "Internet Message Access Protocol - version - 4rev1", RFC 3501, March 2003. - - [MDN] Hansen, T., Ed., and G. Vaudreuil, Ed., "Message - Disposition Notification", RFC 3798, May 2004. - - [RFC3028] Showalter, T., "Sieve: A Mail Filtering Language", RFC - 3028, January 2001. - - - - - - - - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 40] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -14. Changes from RFC 3028 - - This following list is a summary of the changes that have been made - in the Sieve language base specification from [RFC3028]. - - 1. Removed ban on tests having side-effects - 2. Removed reject extension (will be specified in a separate RFC) - 3. Clarified description of comparators to match [COLLATION], the - new base specification for them - 4. Require stripping of leading and trailing whitespace in "header" - test - 5. Clarified or tightened handling of many minor items, including: - - invalid [MIME3] encoding - - invalid addresses in headers - - invalid header field names in tests - - 'undefined' comparator result - - unknown envelope parts - - null return-path in "envelope" test - 6. Capability strings are case-sensitive - 7. Clarified that fileinto should reencode non-ASCII mailbox - names to match the mailstore's conventions - 8. Errors in the ABNF were corrected - 9. The references were updated and split into normative and - informative - 10. Added encoded-character capability and deprecated (but did not - remove) use of arbitrary binary octets in Sieve scripts. - 11. Updated IANA registration template, and added IANA - considerations to permit capability prefix registrations. - 12. Added .sieve as a valid extension for Sieve scripts. - -Editors' Addresses - - Philip Guenther - Sendmail, Inc. - 6425 Christie St. Ste 400 - Emeryville, CA 94608 - EMail: guenther@sendmail.com - - Tim Showalter - EMail: tjs@psaux.com - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 41] - -RFC 5228 Sieve: An Email Filtering Language January 2008 - - -Full Copyright Statement - - Copyright (C) The IETF Trust (2008). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND - THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - - - - - - - - - - - -Guenther & Showalter Standards Track [Page 42] - diff --git a/docs/[rfc5802] SCRAM/rfc5802.pdf b/docs/[rfc5802] SCRAM/rfc5802.pdf Binary files differdeleted file mode 100755 index a9381d3e..00000000 --- a/docs/[rfc5802] SCRAM/rfc5802.pdf +++ /dev/null diff --git a/docs/[rfc5802] SCRAM/rfc5802.txt b/docs/[rfc5802] SCRAM/rfc5802.txt deleted file mode 100755 index 971003a7..00000000 --- a/docs/[rfc5802] SCRAM/rfc5802.txt +++ /dev/null @@ -1,1571 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) C. Newman -Request for Comments: 5802 Oracle -Category: Standards Track A. Menon-Sen -ISSN: 2070-1721 Oryx Mail Systems GmbH - A. Melnikov - Isode, Ltd. - N. Williams - Oracle - July 2010 - - - Salted Challenge Response Authentication Mechanism (SCRAM) - SASL and GSS-API Mechanisms - -Abstract - - The secure authentication mechanism most widely deployed and used by - Internet application protocols is the transmission of clear-text - passwords over a channel protected by Transport Layer Security (TLS). - There are some significant security concerns with that mechanism, - which could be addressed by the use of a challenge response - authentication mechanism protected by TLS. Unfortunately, the - challenge response mechanisms presently on the standards track all - fail to meet requirements necessary for widespread deployment, and - have had success only in limited use. - - This specification describes a family of Simple Authentication and - Security Layer (SASL; RFC 4422) authentication mechanisms called the - Salted Challenge Response Authentication Mechanism (SCRAM), which - addresses the security concerns and meets the deployability - requirements. When used in combination with TLS or an equivalent - security layer, a mechanism from this family could improve the status - quo for application protocol authentication and provide a suitable - choice for a mandatory-to-implement mechanism for future application - protocol standards. - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 1] - -RFC 5802 SCRAM July 2010 - - -Status of This Memo - - This is an Internet Standards Track document. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Further information on - Internet Standards is available in Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc5802. - -Copyright Notice - - Copyright (c) 2010 IETF Trust and the persons identified as the - document authors. All rights reserved. - - This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (http://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with respect - to this document. Code Components extracted from this document must - include Simplified BSD License text as described in Section 4.e of - the Trust Legal Provisions and are provided without warranty as - described in the Simplified BSD License. - - - - - - - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 2] - -RFC 5802 SCRAM July 2010 - - -Table of Contents - - 1. Introduction ....................................................4 - 2. Conventions Used in This Document ...............................5 - 2.1. Terminology ................................................5 - 2.2. Notation ...................................................6 - 3. SCRAM Algorithm Overview ........................................7 - 4. SCRAM Mechanism Names ...........................................8 - 5. SCRAM Authentication Exchange ...................................9 - 5.1. SCRAM Attributes ..........................................10 - 5.2. Compliance with SASL Mechanism Requirements ...............13 - 6. Channel Binding ................................................14 - 6.1. Default Channel Binding ...................................15 - 7. Formal Syntax ..................................................15 - 8. SCRAM as a GSS-API Mechanism ...................................19 - 8.1. GSS-API Principal Name Types for SCRAM ....................19 - 8.2. GSS-API Per-Message Tokens for SCRAM ......................20 - 8.3. GSS_Pseudo_random() for SCRAM .............................20 - 9. Security Considerations ........................................20 - 10. IANA Considerations ...........................................22 - 11. Acknowledgements ..............................................23 - 12. References ....................................................24 - 12.1. Normative References .....................................24 - 12.2. Normative References for GSS-API Implementors ............24 - 12.3. Informative References ...................................25 - Appendix A. Other Authentication Mechanisms .......................27 - Appendix B. Design Motivations ....................................27 - - - - - - - - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 3] - -RFC 5802 SCRAM July 2010 - - -1. Introduction - - This specification describes a family of authentication mechanisms - called the Salted Challenge Response Authentication Mechanism (SCRAM) - which addresses the requirements necessary to deploy a challenge- - response mechanism more widely than past attempts (see Appendix A and - Appendix B). When used in combination with Transport Layer Security - (TLS; see [RFC5246]) or an equivalent security layer, a mechanism - from this family could improve the status quo for application - protocol authentication and provide a suitable choice for a - mandatory-to-implement mechanism for future application protocol - standards. - - For simplicity, this family of mechanisms does not presently include - negotiation of a security layer [RFC4422]. It is intended to be used - with an external security layer such as that provided by TLS or SSH, - with optional channel binding [RFC5056] to the external security - layer. - - SCRAM is specified herein as a pure Simple Authentication and - Security Layer (SASL) [RFC4422] mechanism, but it conforms to the new - bridge between SASL and the Generic Security Service Application - Program Interface (GSS-API) called "GS2" [RFC5801]. This means that - this document defines both, a SASL mechanism and a GSS-API mechanism. - - SCRAM provides the following protocol features: - - o The authentication information stored in the authentication - database is not sufficient by itself to impersonate the client. - The information is salted to prevent a pre-stored dictionary - attack if the database is stolen. - - o The server does not gain the ability to impersonate the client to - other servers (with an exception for server-authorized proxies). - - o The mechanism permits the use of a server-authorized proxy without - requiring that proxy to have super-user rights with the back-end - server. - - o Mutual authentication is supported, but only the client is named - (i.e., the server has no name). - - o When used as a SASL mechanism, SCRAM is capable of transporting - authorization identities (see [RFC4422], Section 2) from the - client to the server. - - - - - - -Newman, et al. Standards Track [Page 4] - -RFC 5802 SCRAM July 2010 - - - A separate document defines a standard LDAPv3 [RFC4510] attribute - that enables storage of the SCRAM authentication information in LDAP. - See [RFC5803]. - - For an in-depth discussion of why other challenge response mechanisms - are not considered sufficient, see Appendix A. For more information - about the motivations behind the design of this mechanism, see - Appendix B. - -2. Conventions Used in This Document - - 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 [RFC2119]. - - Formal syntax is defined by [RFC5234] including the core rules - defined in Appendix B of [RFC5234]. - - Example lines prefaced by "C:" are sent by the client and ones - prefaced by "S:" by the server. If a single "C:" or "S:" label - applies to multiple lines, then the line breaks between those lines - are for editorial clarity only, and are not part of the actual - protocol exchange. - -2.1. Terminology - - This document uses several terms defined in [RFC4949] ("Internet - Security Glossary") including the following: authentication, - authentication exchange, authentication information, brute force, - challenge-response, cryptographic hash function, dictionary attack, - eavesdropping, hash result, keyed hash, man-in-the-middle, nonce, - one-way encryption function, password, replay attack, and salt. - Readers not familiar with these terms should use that glossary as a - reference. - - Some clarifications and additional definitions follow: - - o Authentication information: Information used to verify an identity - claimed by a SCRAM client. The authentication information for a - SCRAM identity consists of salt, iteration count, "StoredKey" and - "ServerKey" (as defined in the algorithm overview) for each - supported cryptographic hash function. - - o Authentication database: The database used to look up the - authentication information associated with a particular identity. - For application protocols, LDAPv3 (see [RFC4510]) is frequently - - - - - -Newman, et al. Standards Track [Page 5] - -RFC 5802 SCRAM July 2010 - - - used as the authentication database. For network-level protocols - such as PPP or 802.11x, the use of RADIUS [RFC2865] is more - common. - - o Base64: An encoding mechanism defined in [RFC4648] that converts - an octet string input to a textual output string that can be - easily displayed to a human. The use of base64 in SCRAM is - restricted to the canonical form with no whitespace. - - o Octet: An 8-bit byte. - - o Octet string: A sequence of 8-bit bytes. - - o Salt: A random octet string that is combined with a password - before applying a one-way encryption function. This value is used - to protect passwords that are stored in an authentication - database. - -2.2. Notation - - The pseudocode description of the algorithm uses the following - notations: - - o ":=": The variable on the left-hand side represents the octet - string resulting from the expression on the right-hand side. - - o "+": Octet string concatenation. - - o "[ ]": A portion of an expression enclosed in "[" and "]" may not - be included in the result under some circumstances. See the - associated text for a description of those circumstances. - - o Normalize(str): Apply the SASLprep profile [RFC4013] of the - "stringprep" algorithm [RFC3454] as the normalization algorithm to - a UTF-8 [RFC3629] encoded "str". The resulting string is also in - UTF-8. When applying SASLprep, "str" is treated as a "stored - strings", which means that unassigned Unicode codepoints are - prohibited (see Section 7 of [RFC3454]). Note that - implementations MUST either implement SASLprep or disallow use of - non US-ASCII Unicode codepoints in "str". - - o HMAC(key, str): Apply the HMAC keyed hash algorithm (defined in - [RFC2104]) using the octet string represented by "key" as the key - and the octet string "str" as the input string. The size of the - result is the hash result size for the hash function in use. For - example, it is 20 octets for SHA-1 (see [RFC3174]). - - - - - -Newman, et al. Standards Track [Page 6] - -RFC 5802 SCRAM July 2010 - - - o H(str): Apply the cryptographic hash function to the octet string - "str", producing an octet string as a result. The size of the - result depends on the hash result size for the hash function in - use. - - o XOR: Apply the exclusive-or operation to combine the octet string - on the left of this operator with the octet string on the right of - this operator. The length of the output and each of the two - inputs will be the same for this use. - - o Hi(str, salt, i): - - U1 := HMAC(str, salt + INT(1)) - U2 := HMAC(str, U1) - ... - Ui-1 := HMAC(str, Ui-2) - Ui := HMAC(str, Ui-1) - - Hi := U1 XOR U2 XOR ... XOR Ui - - where "i" is the iteration count, "+" is the string concatenation - operator, and INT(g) is a 4-octet encoding of the integer g, most - significant octet first. - - Hi() is, essentially, PBKDF2 [RFC2898] with HMAC() as the - pseudorandom function (PRF) and with dkLen == output length of - HMAC() == output length of H(). - -3. SCRAM Algorithm Overview - - The following is a description of a full, uncompressed SASL SCRAM - authentication exchange. Nothing in SCRAM prevents either sending - the client-first message with the SASL authentication request defined - by an application protocol ("initial client response"), or sending - the server-final message as additional data of the SASL outcome of - authentication exchange defined by an application protocol. See - [RFC4422] for more details. - - Note that this section omits some details, such as client and server - nonces. See Section 5 for more details. - - To begin with, the SCRAM client is in possession of a username and - password (*) (or a ClientKey/ServerKey, or SaltedPassword). It sends - the username to the server, which retrieves the corresponding - authentication information, i.e., a salt, StoredKey, ServerKey, and - the iteration count i. (Note that a server implementation may choose - - - - - -Newman, et al. Standards Track [Page 7] - -RFC 5802 SCRAM July 2010 - - - to use the same iteration count for all accounts.) The server sends - the salt and the iteration count to the client, which then computes - the following values and sends a ClientProof to the server: - - (*) Note that both the username and the password MUST be encoded in - UTF-8 [RFC3629]. - - Informative Note: Implementors are encouraged to create test cases - that use both usernames and passwords with non-ASCII codepoints. In - particular, it's useful to test codepoints whose "Unicode - Normalization Form C" and "Unicode Normalization Form KC" are - different. Some examples of such codepoints include Vulgar Fraction - One Half (U+00BD) and Acute Accent (U+00B4). - - SaltedPassword := Hi(Normalize(password), salt, i) - ClientKey := HMAC(SaltedPassword, "Client Key") - StoredKey := H(ClientKey) - AuthMessage := client-first-message-bare + "," + - server-first-message + "," + - client-final-message-without-proof - ClientSignature := HMAC(StoredKey, AuthMessage) - ClientProof := ClientKey XOR ClientSignature - ServerKey := HMAC(SaltedPassword, "Server Key") - ServerSignature := HMAC(ServerKey, AuthMessage) - - The server authenticates the client by computing the ClientSignature, - exclusive-ORing that with the ClientProof to recover the ClientKey - and verifying the correctness of the ClientKey by applying the hash - function and comparing the result to the StoredKey. If the ClientKey - is correct, this proves that the client has access to the user's - password. - - Similarly, the client authenticates the server by computing the - ServerSignature and comparing it to the value sent by the server. If - the two are equal, it proves that the server had access to the user's - ServerKey. - - The AuthMessage is computed by concatenating messages from the - authentication exchange. The format of these messages is defined in - Section 7. - -4. SCRAM Mechanism Names - - A SCRAM mechanism name is a string "SCRAM-" followed by the - uppercased name of the underlying hash function taken from the IANA - "Hash Function Textual Names" registry (see http://www.iana.org), - optionally followed by the suffix "-PLUS" (see below). Note that - SASL mechanism names are limited to 20 octets, which means that only - - - -Newman, et al. Standards Track [Page 8] - -RFC 5802 SCRAM July 2010 - - - hash function names with lengths shorter or equal to 9 octets - (20-length("SCRAM-")-length("-PLUS") can be used. For cases when the - underlying hash function name is longer than 9 octets, an alternative - 9-octet (or shorter) name can be used to construct the corresponding - SCRAM mechanism name, as long as this alternative name doesn't - conflict with any other hash function name from the IANA "Hash - Function Textual Names" registry. In order to prevent future - conflict, such alternative names SHOULD be registered in the IANA - "Hash Function Textual Names" registry. - - For interoperability, all SCRAM clients and servers MUST implement - the SCRAM-SHA-1 authentication mechanism, i.e., an authentication - mechanism from the SCRAM family that uses the SHA-1 hash function as - defined in [RFC3174]. - - The "-PLUS" suffix is used only when the server supports channel - binding to the external channel. If the server supports channel - binding, it will advertise both the "bare" and "plus" versions of - whatever mechanisms it supports (e.g., if the server supports only - SCRAM with SHA-1, then it will advertise support for both SCRAM-SHA-1 - and SCRAM-SHA-1-PLUS). If the server does not support channel - binding, then it will advertise only the "bare" version of the - mechanism (e.g., only SCRAM-SHA-1). The "-PLUS" exists to allow - negotiation of the use of channel binding. See Section 6. - -5. SCRAM Authentication Exchange - - SCRAM is a SASL mechanism whose client response and server challenge - messages are text-based messages containing one or more attribute- - value pairs separated by commas. Each attribute has a one-letter - name. The messages and their attributes are described in - Section 5.1, and defined in Section 7. - - SCRAM is a client-first SASL mechanism (see [RFC4422], Section 5, - item 2a), and returns additional data together with a server's - indication of a successful outcome. - - This is a simple example of a SCRAM-SHA-1 authentication exchange - when the client doesn't support channel bindings (username 'user' and - password 'pencil' are used): - - C: n,,n=user,r=fyko+d2lbbFgONRv9qkxdawL - S: r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j,s=QSXCR+Q6sek8bf92, - i=4096 - C: c=biws,r=fyko+d2lbbFgONRv9qkxdawL3rfcNHYJY1ZVvWVs7j, - p=v0X8v3Bz2T0CJGbJQyF0X+HI4Ts= - S: v=rmF9pqV8S7suAoZWja4dJRkFsKQ= - - - - -Newman, et al. Standards Track [Page 9] - -RFC 5802 SCRAM July 2010 - - - First, the client sends the "client-first-message" containing: - - o a GS2 header consisting of a flag indicating whether channel - binding is supported-but-not-used, not supported, or used, and an - optional SASL authorization identity; - - o SCRAM username and a random, unique nonce attributes. - - Note that the client's first message will always start with "n", "y", - or "p"; otherwise, the message is invalid and authentication MUST - fail. This is important, as it allows for GS2 extensibility (e.g., - to add support for security layers). - - In response, the server sends a "server-first-message" containing the - user's iteration count i and the user's salt, and appends its own - nonce to the client-specified one. - - The client then responds by sending a "client-final-message" with the - same nonce and a ClientProof computed using the selected hash - function as explained earlier. - - The server verifies the nonce and the proof, verifies that the - authorization identity (if supplied by the client in the first - message) is authorized to act as the authentication identity, and, - finally, it responds with a "server-final-message", concluding the - authentication exchange. - - The client then authenticates the server by computing the - ServerSignature and comparing it to the value sent by the server. If - the two are different, the client MUST consider the authentication - exchange to be unsuccessful, and it might have to drop the - connection. - -5.1. SCRAM Attributes - - This section describes the permissible attributes, their use, and the - format of their values. All attribute names are single US-ASCII - letters and are case-sensitive. - - Note that the order of attributes in client or server messages is - fixed, with the exception of extension attributes (described by the - "extensions" ABNF production), which can appear in any order in the - designated positions. See Section 7 for authoritative reference. - - o a: This is an optional attribute, and is part of the GS2 [RFC5801] - bridge between the GSS-API and SASL. This attribute specifies an - authorization identity. A client may include it in its first - message to the server if it wants to authenticate as one user, but - - - -Newman, et al. Standards Track [Page 10] - -RFC 5802 SCRAM July 2010 - - - subsequently act as a different user. This is typically used by - an administrator to perform some management task on behalf of - another user, or by a proxy in some situations. - - Upon the receipt of this value the server verifies its - correctness according to the used SASL protocol profile. - Failed verification results in failed authentication exchange. - - If this attribute is omitted (as it normally would be), the - authorization identity is assumed to be derived from the - username specified with the (required) "n" attribute. - - The server always authenticates the user specified by the "n" - attribute. If the "a" attribute specifies a different user, - the server associates that identity with the connection after - successful authentication and authorization checks. - - The syntax of this field is the same as that of the "n" field - with respect to quoting of '=' and ','. - - o n: This attribute specifies the name of the user whose password is - used for authentication (a.k.a. "authentication identity" - [RFC4422]). A client MUST include it in its first message to the - server. If the "a" attribute is not specified (which would - normally be the case), this username is also the identity that - will be associated with the connection subsequent to - authentication and authorization. - - Before sending the username to the server, the client SHOULD - prepare the username using the "SASLprep" profile [RFC4013] of - the "stringprep" algorithm [RFC3454] treating it as a query - string (i.e., unassigned Unicode code points are allowed). If - the preparation of the username fails or results in an empty - string, the client SHOULD abort the authentication exchange - (*). - - (*) An interactive client can request a repeated entry of the - username value. - - Upon receipt of the username by the server, the server MUST - either prepare it using the "SASLprep" profile [RFC4013] of the - "stringprep" algorithm [RFC3454] treating it as a query string - (i.e., unassigned Unicode codepoints are allowed) or otherwise - be prepared to do SASLprep-aware string comparisons and/or - index lookups. If the preparation of the username fails or - results in an empty string, the server SHOULD abort the - - - - - -Newman, et al. Standards Track [Page 11] - -RFC 5802 SCRAM July 2010 - - - authentication exchange. Whether or not the server prepares - the username using "SASLprep", it MUST use it as received in - hash calculations. - - The characters ',' or '=' in usernames are sent as '=2C' and - '=3D' respectively. If the server receives a username that - contains '=' not followed by either '2C' or '3D', then the - server MUST fail the authentication. - - o m: This attribute is reserved for future extensibility. In this - version of SCRAM, its presence in a client or a server message - MUST cause authentication failure when the attribute is parsed by - the other end. - - o r: This attribute specifies a sequence of random printable ASCII - characters excluding ',' (which forms the nonce used as input to - the hash function). No quoting is applied to this string. As - described earlier, the client supplies an initial value in its - first message, and the server augments that value with its own - nonce in its first response. It is important that this value be - different for each authentication (see [RFC4086] for more details - on how to achieve this). The client MUST verify that the initial - part of the nonce used in subsequent messages is the same as the - nonce it initially specified. The server MUST verify that the - nonce sent by the client in the second message is the same as the - one sent by the server in its first message. - - o c: This REQUIRED attribute specifies the base64-encoded GS2 header - and channel binding data. It is sent by the client in its second - authentication message. The attribute data consist of: - - * the GS2 header from the client's first message (recall that the - GS2 header contains a channel binding flag and an optional - authzid). This header is going to include channel binding type - prefix (see [RFC5056]), if and only if the client is using - channel binding; - - * followed by the external channel's channel binding data, if and - only if the client is using channel binding. - - o s: This attribute specifies the base64-encoded salt used by the - server for this user. It is sent by the server in its first - message to the client. - - o i: This attribute specifies an iteration count for the selected - hash function and user, and MUST be sent by the server along with - the user's salt. - - - - -Newman, et al. Standards Track [Page 12] - -RFC 5802 SCRAM July 2010 - - - For the SCRAM-SHA-1/SCRAM-SHA-1-PLUS SASL mechanism, servers - SHOULD announce a hash iteration-count of at least 4096. Note - that a client implementation MAY cache ClientKey&ServerKey (or - just SaltedPassword) for later reauthentication to the same - service, as it is likely that the server is going to advertise - the same salt value upon reauthentication. This might be - useful for mobile clients where CPU usage is a concern. - - o p: This attribute specifies a base64-encoded ClientProof. The - client computes this value as described in the overview and sends - it to the server. - - o v: This attribute specifies a base64-encoded ServerSignature. It - is sent by the server in its final message, and is used by the - client to verify that the server has access to the user's - authentication information. This value is computed as explained - in the overview. - - o e: This attribute specifies an error that occurred during - authentication exchange. It is sent by the server in its final - message and can help diagnose the reason for the authentication - exchange failure. On failed authentication, the entire server- - final-message is OPTIONAL; specifically, a server implementation - MAY conclude the SASL exchange with a failure without sending the - server-final-message. This results in an application-level error - response without an extra round-trip. If the server-final-message - is sent on authentication failure, then the "e" attribute MUST be - included. - - o As-yet unspecified mandatory and optional extensions. Mandatory - extensions are encoded as values of the 'm' attribute (see ABNF - for reserved-mext in section 7). Optional extensions use as-yet - unassigned attribute names. - - Mandatory extensions sent by one peer but not understood by the - other MUST cause authentication failure (the server SHOULD send - the "extensions-not-supported" server-error-value). - - Unknown optional extensions MUST be ignored upon receipt. - -5.2. Compliance with SASL Mechanism Requirements - - This section describes compliance with SASL mechanism requirements - specified in Section 5 of [RFC4422]. - - 1) "SCRAM-SHA-1" and "SCRAM-SHA-1-PLUS". - - 2a) SCRAM is a client-first mechanism. - - - -Newman, et al. Standards Track [Page 13] - -RFC 5802 SCRAM July 2010 - - - 2b) SCRAM sends additional data with success. - - 3) SCRAM is capable of transferring authorization identities from - the client to the server. - - 4) SCRAM does not offer any security layers (SCRAM offers channel - binding instead). - - 5) SCRAM has a hash protecting the authorization identity. - -6. Channel Binding - - SCRAM supports channel binding to external secure channels, such as - TLS. Clients and servers may or may not support channel binding, - therefore the use of channel binding is negotiable. SCRAM does not - provide security layers, however, therefore it is imperative that - SCRAM provide integrity protection for the negotiation of channel - binding. - - Use of channel binding is negotiated as follows: - - o Servers that support the use of channel binding SHOULD advertise - both the non-PLUS (SCRAM-<hash-function>) and PLUS-variant (SCRAM- - <hash-function>-PLUS) mechanism name. If the server cannot - support channel binding, it SHOULD advertise only the non-PLUS- - variant. If the server would never succeed in the authentication - of the non-PLUS-variant due to policy reasons, it MUST advertise - only the PLUS-variant. - - o If the client supports channel binding and the server does not - appear to (i.e., the client did not see the -PLUS name advertised - by the server), then the client MUST NOT use an "n" gs2-cbind- - flag. - - o Clients that support mechanism negotiation and channel binding - MUST use a "p" gs2-cbind-flag when the server offers the PLUS- - variant of the desired GS2 mechanism. - - o If the client does not support channel binding, then it MUST use - an "n" gs2-cbind-flag. Conversely, if the client requires the use - of channel binding then it MUST use a "p" gs2-cbind-flag. Clients - that do not support mechanism negotiation never use a "y" gs2- - cbind-flag, they use either "p" or "n" according to whether they - require and support the use of channel binding or whether they do - not, respectively. - - o Upon receipt of the client-first message, the server checks the - channel binding flag (gs2-cbind-flag). - - - -Newman, et al. Standards Track [Page 14] - -RFC 5802 SCRAM July 2010 - - - * If the flag is set to "y" and the server supports channel - binding, the server MUST fail authentication. This is because - if the client sets the channel binding flag to "y", then the - client must have believed that the server did not support - channel binding -- if the server did in fact support channel - binding, then this is an indication that there has been a - downgrade attack (e.g., an attacker changed the server's - mechanism list to exclude the -PLUS suffixed SCRAM mechanism - name(s)). - - * If the channel binding flag was "p" and the server does not - support the indicated channel binding type, then the server - MUST fail authentication. - - The server MUST always validate the client's "c=" field. The server - does this by constructing the value of the "c=" attribute and then - checking that it matches the client's c= attribute value. - - For more discussions of channel bindings, and the syntax of channel - binding data for various security protocols, see [RFC5056]. - -6.1. Default Channel Binding - - A default channel binding type agreement process for all SASL - application protocols that do not provide their own channel binding - type agreement is provided as follows. - - 'tls-unique' is the default channel binding type for any application - that doesn't specify one. - - Servers MUST implement the "tls-unique" [RFC5929] channel binding - type, if they implement any channel binding. Clients SHOULD - implement the "tls-unique" [RFC5929] channel binding type, if they - implement any channel binding. Clients and servers SHOULD choose the - highest-layer/innermost end-to-end TLS channel as the channel to - which to bind. - - Servers MUST choose the channel binding type indicated by the client, - or fail authentication if they don't support it. - -7. Formal Syntax - - The following syntax specification uses the Augmented Backus-Naur - form (ABNF) notation as specified in [RFC5234]. "UTF8-2", "UTF8-3", - and "UTF8-4" non-terminal are defined in [RFC3629]. - - - - - - -Newman, et al. Standards Track [Page 15] - -RFC 5802 SCRAM July 2010 - - - ALPHA = <as defined in RFC 5234 appendix B.1> - DIGIT = <as defined in RFC 5234 appendix B.1> - UTF8-2 = <as defined in RFC 3629 (STD 63)> - UTF8-3 = <as defined in RFC 3629 (STD 63)> - UTF8-4 = <as defined in RFC 3629 (STD 63)> - - attr-val = ALPHA "=" value - ;; Generic syntax of any attribute sent - ;; by server or client - - value = 1*value-char - - value-safe-char = %x01-2B / %x2D-3C / %x3E-7F / - UTF8-2 / UTF8-3 / UTF8-4 - ;; UTF8-char except NUL, "=", and ",". - - value-char = value-safe-char / "=" - - printable = %x21-2B / %x2D-7E - ;; Printable ASCII except ",". - ;; Note that any "printable" is also - ;; a valid "value". - - base64-char = ALPHA / DIGIT / "/" / "+" - - base64-4 = 4base64-char - - base64-3 = 3base64-char "=" - - base64-2 = 2base64-char "==" - - base64 = *base64-4 [base64-3 / base64-2] - - posit-number = %x31-39 *DIGIT - ;; A positive number. - - saslname = 1*(value-safe-char / "=2C" / "=3D") - ;; Conforms to <value>. - - authzid = "a=" saslname - ;; Protocol specific. - - cb-name = 1*(ALPHA / DIGIT / "." / "-") - ;; See RFC 5056, Section 7. - ;; E.g., "tls-server-end-point" or - ;; "tls-unique". - - - - - -Newman, et al. Standards Track [Page 16] - -RFC 5802 SCRAM July 2010 - - - gs2-cbind-flag = ("p=" cb-name) / "n" / "y" - ;; "n" -> client doesn't support channel binding. - ;; "y" -> client does support channel binding - ;; but thinks the server does not. - ;; "p" -> client requires channel binding. - ;; The selected channel binding follows "p=". - - gs2-header = gs2-cbind-flag "," [ authzid ] "," - ;; GS2 header for SCRAM - ;; (the actual GS2 header includes an optional - ;; flag to indicate that the GSS mechanism is not - ;; "standard", but since SCRAM is "standard", we - ;; don't include that flag). - - username = "n=" saslname - ;; Usernames are prepared using SASLprep. - - reserved-mext = "m=" 1*(value-char) - ;; Reserved for signaling mandatory extensions. - ;; The exact syntax will be defined in - ;; the future. - - channel-binding = "c=" base64 - ;; base64 encoding of cbind-input. - - proof = "p=" base64 - - nonce = "r=" c-nonce [s-nonce] - ;; Second part provided by server. - - c-nonce = printable - - s-nonce = printable - - salt = "s=" base64 - - verifier = "v=" base64 - ;; base-64 encoded ServerSignature. - - iteration-count = "i=" posit-number - ;; A positive number. - - client-first-message-bare = - [reserved-mext ","] - username "," nonce ["," extensions] - - client-first-message = - gs2-header client-first-message-bare - - - -Newman, et al. Standards Track [Page 17] - -RFC 5802 SCRAM July 2010 - - - server-first-message = - [reserved-mext ","] nonce "," salt "," - iteration-count ["," extensions] - - client-final-message-without-proof = - channel-binding "," nonce ["," - extensions] - - client-final-message = - client-final-message-without-proof "," proof - - server-error = "e=" server-error-value - - server-error-value = "invalid-encoding" / - "extensions-not-supported" / ; unrecognized 'm' value - "invalid-proof" / - "channel-bindings-dont-match" / - "server-does-support-channel-binding" / - ; server does not support channel binding - "channel-binding-not-supported" / - "unsupported-channel-binding-type" / - "unknown-user" / - "invalid-username-encoding" / - ; invalid username encoding (invalid UTF-8 or - ; SASLprep failed) - "no-resources" / - "other-error" / - server-error-value-ext - ; Unrecognized errors should be treated as "other-error". - ; In order to prevent information disclosure, the server - ; may substitute the real reason with "other-error". - - server-error-value-ext = value - ; Additional error reasons added by extensions - ; to this document. - - server-final-message = (server-error / verifier) - ["," extensions] - - extensions = attr-val *("," attr-val) - ;; All extensions are optional, - ;; i.e., unrecognized attributes - ;; not defined in this document - ;; MUST be ignored. - - cbind-data = 1*OCTET - - - - - -Newman, et al. Standards Track [Page 18] - -RFC 5802 SCRAM July 2010 - - - cbind-input = gs2-header [ cbind-data ] - ;; cbind-data MUST be present for - ;; gs2-cbind-flag of "p" and MUST be absent - ;; for "y" or "n". - -8. SCRAM as a GSS-API Mechanism - - This section and its sub-sections and all normative references of it - not referenced elsewhere in this document are INFORMATIONAL for SASL - implementors, but they are NORMATIVE for GSS-API implementors. - - SCRAM is actually also a GSS-API mechanism. The messages are the - same, but a) the GS2 header on the client's first message and channel - binding data is excluded when SCRAM is used as a GSS-API mechanism, - and b) the RFC2743 section 3.1 initial context token header is - prefixed to the client's first authentication message (context - token). - - The GSS-API mechanism OID for SCRAM-SHA-1 is 1.3.6.1.5.5.14 (see - Section 10). - - SCRAM security contexts always have the mutual_state flag - (GSS_C_MUTUAL_FLAG) set to TRUE. SCRAM does not support credential - delegation, therefore SCRAM security contexts alway have the - deleg_state flag (GSS_C_DELEG_FLAG) set to FALSE. - -8.1. GSS-API Principal Name Types for SCRAM - - SCRAM does not explicitly name acceptor principals. However, the use - of acceptor principal names to find or prompt for passwords is - useful. Therefore, SCRAM supports standard generic name syntaxes for - acceptors such as GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], Section - 4.1). Implementations should use the target name passed to - GSS_Init_sec_context(), if any, to help retrieve or prompt for SCRAM - passwords. - - SCRAM supports only a single name type for initiators: - GSS_C_NT_USER_NAME. GSS_C_NT_USER_NAME is the default name type for - SCRAM. - - There is no name canonicalization procedure for SCRAM beyond applying - SASLprep as described in Section 5.1. - - The query, display, and exported name syntaxes for SCRAM principal - names are all the same. There are no SCRAM-specific name syntaxes - (SCRAM initiator principal names are free-form); -- applications - should use generic GSS-API name types such as GSS_C_NT_USER_NAME and - - - - -Newman, et al. Standards Track [Page 19] - -RFC 5802 SCRAM July 2010 - - - GSS_C_NT_HOSTBASED_SERVICE (see [RFC2743], Section 4). The exported - name token does, of course, conform to [RFC2743], Section 3.2, but - the "NAME" part of the token is just a SCRAM user name. - -8.2. GSS-API Per-Message Tokens for SCRAM - - The per-message tokens for SCRAM as a GSS-API mechanism SHALL be the - same as those for the Kerberos V GSS-API mechanism [RFC4121] (see - Section 4.2 and sub-sections), using the Kerberos V "aes128-cts-hmac- - sha1-96" enctype [RFC3962]. - - The replay_det_state (GSS_C_REPLAY_FLAG), sequence_state - (GSS_C_SEQUENCE_FLAG), conf_avail (GSS_C_CONF_FLAG) and integ_avail - (GSS_C_CONF_FLAG) security context flags are always set to TRUE. - - The 128-bit session "protocol key" SHALL be derived by using the - least significant (right-most) 128 bits of HMAC(StoredKey, "GSS-API - session key" || ClientKey || AuthMessage). "Specific keys" are then - derived as usual as described in Section 2 of [RFC4121], [RFC3961], - and [RFC3962]. - - The terms "protocol key" and "specific key" are Kerberos V5 terms - [RFC3961]. - - SCRAM does support PROT_READY, and is PROT_READY on the initiator - side first upon receipt of the server's reply to the initial security - context token. - -8.3. GSS_Pseudo_random() for SCRAM - - The GSS_Pseudo_random() [RFC4401] for SCRAM SHALL be the same as for - the Kerberos V GSS-API mechanism [RFC4402]. There is no acceptor- - asserted sub-session key for SCRAM, thus GSS_C_PRF_KEY_FULL and - GSS_C_PRF_KEY_PARTIAL are equivalent for SCRAM's GSS_Pseudo_random(). - The protocol key to be used for the GSS_Pseudo_random() SHALL be the - same as the key defined in Section 8.2. - -9. Security Considerations - - If the authentication exchange is performed without a strong security - layer (such as TLS with data confidentiality), then a passive - eavesdropper can gain sufficient information to mount an offline - dictionary or brute-force attack that can be used to recover the - user's password. The amount of time necessary for this attack - depends on the cryptographic hash function selected, the strength of - the password, and the iteration count supplied by the server. An - external security layer with strong encryption will prevent this - attack. - - - -Newman, et al. Standards Track [Page 20] - -RFC 5802 SCRAM July 2010 - - - If the external security layer used to protect the SCRAM exchange - uses an anonymous key exchange, then the SCRAM channel binding - mechanism can be used to detect a man-in-the-middle attack on the - security layer and cause the authentication to fail as a result. - However, the man-in-the-middle attacker will have gained sufficient - information to mount an offline dictionary or brute-force attack. - For this reason, SCRAM allows to increase the iteration count over - time. (Note that a server that is only in possession of "StoredKey" - and "ServerKey" can't automatically increase the iteration count upon - successful authentication. Such an increase would require resetting - the user's password.) - - If the authentication information is stolen from the authentication - database, then an offline dictionary or brute-force attack can be - used to recover the user's password. The use of salt mitigates this - attack somewhat by requiring a separate attack on each password. - Authentication mechanisms that protect against this attack are - available (e.g., the EKE class of mechanisms). RFC 2945 [RFC2945] is - an example of such technology. The WG elected not to use EKE like - mechanisms as a basis for SCRAM. - - If an attacker obtains the authentication information from the - authentication repository and either eavesdrops on one authentication - exchange or impersonates a server, the attacker gains the ability to - impersonate that user to all servers providing SCRAM access using the - same hash function, password, iteration count, and salt. For this - reason, it is important to use randomly generated salt values. - - SCRAM does not negotiate a hash function to use. Hash function - negotiation is left to the SASL mechanism negotiation. It is - important that clients be able to sort a locally available list of - mechanisms by preference so that the client may pick the appropriate - mechanism to use from a server's advertised mechanism list. This - preference order is not specified here as it is a local matter. The - preference order should include objective and subjective notions of - mechanism cryptographic strength (e.g., SCRAM with a successor to - SHA-1 may be preferred over SCRAM with SHA-1). - - Note that to protect the SASL mechanism negotiation applications - normally must list the server mechanisms twice: once before and once - after authentication, the latter using security layers. Since SCRAM - does not provide security layers, the only ways to protect the - mechanism negotiation are a) use channel binding to an external - channel, or b) use an external channel that authenticates a user- - provided server name. - - - - - - -Newman, et al. Standards Track [Page 21] - -RFC 5802 SCRAM July 2010 - - - SCRAM does not protect against downgrade attacks of channel binding - types. The complexities of negotiating a channel binding type, and - handling down-grade attacks in that negotiation, were intentionally - left out of scope for this document. - - A hostile server can perform a computational denial-of-service attack - on clients by sending a big iteration count value. - - See [RFC4086] for more information about generating randomness. - -10. IANA Considerations - - IANA has added the following family of SASL mechanisms to the SASL - Mechanism registry established by [RFC4422]: - - To: iana@iana.org - Subject: Registration of a new SASL family SCRAM - - SASL mechanism name (or prefix for the family): SCRAM-* - Security considerations: Section 7 of [RFC5802] - Published specification (optional, recommended): [RFC5802] - Person & email address to contact for further information: - IETF SASL WG <sasl@ietf.org> - Intended usage: COMMON - Owner/Change controller: IESG <iesg@ietf.org> - Note: Members of this family MUST be explicitly registered - using the "IETF Review" [RFC5226] registration procedure. - Reviews MUST be requested on the SASL mailing list - <sasl@ietf.org> (or a successor designated by the responsible - Security AD). - - Note to future SCRAM-mechanism designers: each new SCRAM-SASL - mechanism MUST be explicitly registered with IANA and MUST comply - with SCRAM-mechanism naming convention defined in Section 4 of this - document. - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 22] - -RFC 5802 SCRAM July 2010 - - - IANA has added the following entries to the SASL Mechanism registry - established by [RFC4422]: - - To: iana@iana.org - Subject: Registration of a new SASL mechanism SCRAM-SHA-1 - - SASL mechanism name (or prefix for the family): SCRAM-SHA-1 - Security considerations: Section 7 of [RFC5802] - Published specification (optional, recommended): [RFC5802] - Person & email address to contact for further information: - IETF SASL WG <sasl@ietf.org> - Intended usage: COMMON - Owner/Change controller: IESG <iesg@ietf.org> - Note: - - To: iana@iana.org - Subject: Registration of a new SASL mechanism SCRAM-SHA-1-PLUS - - SASL mechanism name (or prefix for the family): SCRAM-SHA-1-PLUS - Security considerations: Section 7 of [RFC5802] - Published specification (optional, recommended): [RFC5802] - Person & email address to contact for further information: - IETF SASL WG <sasl@ietf.org> - Intended usage: COMMON - Owner/Change controller: IESG <iesg@ietf.org> - Note: - - Per this document, IANA has assigned a GSS-API mechanism OID for - SCRAM-SHA-1 from the iso.org.dod.internet.security.mechanisms prefix - (see "SMI Security for Mechanism Codes" registry). - -11. Acknowledgements - - This document benefited from discussions on the SASL WG mailing list. - The authors would like to specially thank Dave Cridland, Simon - Josefsson, Jeffrey Hutzelman, Kurt Zeilenga, Pasi Eronen, Ben - Campbell, Peter Saint-Andre, and Tobias Markmann for their - contributions to this document. A special thank you to Simon - Josefsson for shepherding this document and for doing one of the - first implementations of this specification. - - - - - - - - - - - -Newman, et al. Standards Track [Page 23] - -RFC 5802 SCRAM July 2010 - - -12. References - -12.1. Normative References - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, - February 1997. - - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [RFC3174] Eastlake, D. and P. Jones, "US Secure Hash Algorithm 1 - (SHA1)", RFC 3174, September 2001. - - [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [RFC4013] Zeilenga, K., "SASLprep: Stringprep Profile for User Names - and Passwords", RFC 4013, February 2005. - - [RFC4422] Melnikov, A. and K. Zeilenga, "Simple Authentication and - Security Layer (SASL)", RFC 4422, June 2006. - - [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. - - [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure - Channels", RFC 5056, November 2007. - - [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. - - [RFC5929] Altman, J., Williams, N., and L. Zhu, "Channel Bindings - for TLS", RFC 5929, July 2010. - -12.2. Normative References for GSS-API Implementors - - [RFC2743] Linn, J., "Generic Security Service Application Program - Interface Version 2, Update 1", RFC 2743, January 2000. - - [RFC3961] Raeburn, K., "Encryption and Checksum Specifications for - Kerberos 5", RFC 3961, February 2005. - - - - - -Newman, et al. Standards Track [Page 24] - -RFC 5802 SCRAM July 2010 - - - [RFC3962] Raeburn, K., "Advanced Encryption Standard (AES) - Encryption for Kerberos 5", RFC 3962, February 2005. - - [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos - Version 5 Generic Security Service Application Program - Interface (GSS-API) Mechanism: Version 2", RFC 4121, - July 2005. - - [RFC4401] Williams, N., "A Pseudo-Random Function (PRF) API - Extension for the Generic Security Service Application - Program Interface (GSS-API)", RFC 4401, February 2006. - - [RFC4402] Williams, N., "A Pseudo-Random Function (PRF) for the - Kerberos V Generic Security Service Application Program - Interface (GSS-API) Mechanism", RFC 4402, February 2006. - - [RFC5801] Josefsson, S. and N. Williams, "Using Generic Security - Service Application Program Interface (GSS-API) Mechanisms - in Simple Authentication and Security Layer (SASL): The - GS2 Mechanism Family", RFC 5801, July 2010. - -12.3. Informative References - - [CRAMHISTORIC] - Zeilenga, K., "CRAM-MD5 to Historic", Work in Progress, - November 2008. - - [DIGESTHISTORIC] - Melnikov, A., "Moving DIGEST-MD5 to Historic", Work - in Progress, July 2008. - - [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, - "Remote Authentication Dial In User Service (RADIUS)", - RFC 2865, June 2000. - - [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography - Specification Version 2.0", RFC 2898, September 2000. - - [RFC2945] Wu, T., "The SRP Authentication and Key Exchange System", - RFC 2945, September 2000. - - [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness - Requirements for Security", BCP 106, RFC 4086, June 2005. - - [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol - (LDAP): Technical Specification Road Map", RFC 4510, - June 2006. - - - - -Newman, et al. Standards Track [Page 25] - -RFC 5802 SCRAM July 2010 - - - [RFC4616] Zeilenga, K., "The PLAIN Simple Authentication and - Security Layer (SASL) Mechanism", RFC 4616, August 2006. - - [RFC4949] Shirey, R., "Internet Security Glossary, Version 2", - RFC 4949, August 2007. - - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an - IANA Considerations Section in RFCs", BCP 26, RFC 5226, - May 2008. - - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.2", RFC 5246, August 2008. - - [RFC5803] Melnikov, A., "Lightweight Directory Access Protocol - (LDAP) Schema for Storing Salted Challenge Response - Authentication Mechanism (SCRAM) Secrets", RFC 5803, - July 2010. - - [tls-server-end-point] - IANA, "Registration of TLS server end-point channel - bindings", available from http://www.iana.org, June 2008. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 26] - -RFC 5802 SCRAM July 2010 - - -Appendix A. Other Authentication Mechanisms - - The DIGEST-MD5 [DIGESTHISTORIC] mechanism has proved to be too - complex to implement and test, and thus has poor interoperability. - The security layer is often not implemented, and almost never used; - everyone uses TLS instead. For a more complete list of problems with - DIGEST-MD5 that led to the creation of SCRAM, see [DIGESTHISTORIC]. - - The CRAM-MD5 SASL mechanism, while widely deployed, also has some - problems. In particular, it is missing some modern SASL features - such as support for internationalized usernames and passwords, - support for passing of authorization identity, and support for - channel bindings. It also doesn't support server authentication. - For a more complete list of problems with CRAM-MD5, see - [CRAMHISTORIC]. - - The PLAIN [RFC4616] SASL mechanism allows a malicious server or - eavesdropper to impersonate the authenticating user to any other - server for which the user has the same password. It also sends the - password in the clear over the network, unless TLS is used. Server - authentication is not supported. - -Appendix B. Design Motivations - - The following design goals shaped this document. Note that some of - the goals have changed since the initial version of the document. - - o The SASL mechanism has all modern SASL features: support for - internationalized usernames and passwords, support for passing of - authorization identity, and support for channel bindings. - - o The protocol supports mutual authentication. - - o The authentication information stored in the authentication - database is not sufficient by itself to impersonate the client. - - o The server does not gain the ability to impersonate the client to - other servers (with an exception for server-authorized proxies), - unless such other servers allow SCRAM authentication and use the - same salt and iteration count for the user. - - o The mechanism is extensible, but (hopefully) not over-engineered - in this respect. - - o The mechanism is easier to implement than DIGEST-MD5 in both - clients and servers. - - - - - -Newman, et al. Standards Track [Page 27] - -RFC 5802 SCRAM July 2010 - - -Authors' Addresses - - Chris Newman - Oracle - 800 Royal Oaks - Monrovia, CA 91016 - USA - - EMail: chris.newman@oracle.com - - - Abhijit Menon-Sen - Oryx Mail Systems GmbH - - EMail: ams@toroid.org - - - Alexey Melnikov - Isode, Ltd. - - EMail: Alexey.Melnikov@isode.com - - - Nicolas Williams - Oracle - 5300 Riata Trace Ct - Austin, TX 78727 - USA - - EMail: Nicolas.Williams@oracle.com - - - - - - - - - - - - - - - - - - - - - -Newman, et al. Standards Track [Page 28] - diff --git a/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-06.txt b/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-06.txt deleted file mode 100755 index 6deab9c1..00000000 --- a/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-06.txt +++ /dev/null @@ -1,1237 +0,0 @@ -Network Working Group Tim Martin -Document: draft-martin-managesieve-06.txt Mirapoint Inc. -Expires: August 2006 Alexey Melnikov - Isode Limited - February 2006 - - - A Protocol for Remotely Managing Sieve Scripts - - <draft-martin-managesieve-06.txt> - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - - -Abstract - - Sieve scripts allow users to filter incoming email. Message stores - are commonly sealed servers so users cannot log into them, yet users - must be able to update their scripts on them. This document - describes a protocol "sieve" for securely managing Sieve scripts on - a remote server. This protocol allows a user to have multiple - scripts, and also alerts a user to syntactically flawed scripts. - - - Table of Contents - - - -Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . . 1 -Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 -1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 -1.1. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 -1.2. Conventions Used in the Document . . . . . . . . . . . . . . 4 -1.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 -1.4. Response Codes . . . . . . . . . . . . . . . . . . . . . . . 5 -1.5. Active Script . . . . . . . . . . . . . . . . . . . . . . . . 6 -1.6. Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 -1.7. Script Names . . . . . . . . . . . . . . . . . . . . . . . . 7 -1.8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 7 -2. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 8 -2.1. AUTHENTICATE Command . . . . . . . . . . . . . . . . . . . . 8 -2.2. STARTTLS Command . . . . . . . . . . . . . . . . . . . . . . 10 -2.3. LOGOUT Command . . . . . . . . . . . . . . . . . . . . . . . 10 -2.4. CAPABILITY Command . . . . . . . . . . . . . . . . . . . . . 11 -2.5. HAVESPACE Command . . . . . . . . . . . . . . . . . . . . . . 11 -2.6. PUTSCRIPT Command . . . . . . . . . . . . . . . . . . . . . . 11 -2.7. LISTSCRIPTS Command . . . . . . . . . . . . . . . . . . . . . 13 -2.8. SETACTIVE Command . . . . . . . . . . . . . . . . . . . . . . 13 -2.9. GETSCRIPT Command . . . . . . . . . . . . . . . . . . . . . . 13 -2.10. DELETESCRIPT Command . . . . . . . . . . . . . . . . . . . . 14 -3. Sieve URL Scheme . . . . . . . . . . . . . . . . . . . . . . 14 -4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 -5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 -7. References . . . . . . . . . . . . . . . . . . . . . . . . . -7.1. Normative References . . . . . . . . . . . . . . . . . . . . -7.2. Informative References . . . . . . . . . . . . . . . . . . . -8. Author's Address . . . . . . . . . . . . . . . . . . . . . . - - -1. Introduction - - - -1.1. Changes - - [[Note to RFC editor: please delete this section before publication]] - - Changes since 05 - - -More ABNF fixes - - -Added IANA considerations - - -Added/fixed text about AUTHENTICATE. - - -Updated the text om Sieve URLs. - - -Updated and added new examples. - - Changes since 04 - - -Updated boilerplate and some references. Added Alexey as co-editor. - - -Minor ABNF fixes - - -Cleaned up terminology (for example, made more consistent with SASL) - - -Added more examples, fixed some existing examples - - -Clarified that STARTTLS command is optional - - -Clarified that disabling an active script when there is no script active - is not an error. - - Changes since 03 - - -Add referals and Sieve URLs - - -Lots of spelling/grammer fixes - - -Don't give capabilities after successful STARTTLS. This is because - it isn't consistant with AUTHENTICATE. There is language specifying - that a client should re-issue a CAPABILITY command after - AUTHENTICATE/STARTTLS. - - -Putting a script of length 0 doesn't remove the script. If this - functionality is desired, the DELETESCRIPT command should be used. - - Changes since 02 - - -add BYE response - - -typo on line 588 - - -allow ANONYMOUS access for sieve script verification - - -updated SIEVE spec reference - - Changes since 01 - - -changed contact info - - Changes since 00 - - -added response codes (from ACAP) - - -removed special-ok response from authenticate command (response - codes obsolete it) - - -changed service name to "sieve" - - -ABNF fixes - - -Alexey's wording changes - - -Eliminated lame PLAIN paragraph - - Changes since PRE - - -dropped synchronized literals. added HAVESPACE command - - -changed capability response syntax. added CAPABILITY command - - -allowed pipelining - - - "sieve" -> "Sieve". Other minor fixes - - -made script names more flexible - - -added starttls support - - -1.2. Conventions Used in the Document - - 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 [KEYWORDS]. - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. Line breaks that do not start a new "C:" or - "S:" exist for editorial reasons. - - -1.3. Syntax - - This a line oriented protocol much like [IMAP4rev1] or [ACAP]. There - are three types: ATOMS, numbers and strings. Strings may be quoted - or literal. See [ACAP] for detailed descriptions of these types. - - Each command consists of an atom followed by zero or more strings - and numbers terminated by a newline. - - All client queries are replied to with either an OK, NO, or BYE - response. Each response may be followed by a response code (see - response codes section) and by a string consisting of human readable - text in the local language. The contents of the string SHOULD be - shown to the user and implementations MUST NOT attempt to parse the - message for meaning. - - The BYE response may be used if the server wishes to close the - connection. A server may wish to do this because the client was idle - for too long or there were too many failed authentication attempts. This - response can be issued at any time and should be immediately followed - by a server hang-up of the connection. If a server has a inactivity - timeout resulting in client autologout it MUST be no less than 30 - minutes. - - <<IANA registration is pending. Current implementations generally use - port number 2000.>> - - -1.4. Response Codes - - An OK, NO, 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: - - AUTH-TOO-WEAK - - This response code is returned in the NO response 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 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. - - QUOTA - - The command would have placed the user above the site-defined quota - constraints. - - REFERRAL - - This response code may be returned with a BYE result from any - command, and includes a mandatory parameter that indicates what - server to access to manage this user's sieve scripts. The server - will be specified by a Sieve URL (see "Sieve URL Scheme" section). - The scriptname portion of the URL MUST NOT be specified. The client - should authenticate to the specified server and use it for all - further commands in the current session. - - SASL - - This response code can occur in the OK response to a successful - AUTHENTICATE command and includes the optional final server response - data from the server as specified by [SASL]. - - TRANSITION-NEEDED - - This response code occurs in a NO response of 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 is typically done - by establishing a secure channel using TLS, followed by authenticating - once using the [PLAIN] authentication mechanism. The selected - mechanism SHOULD then work for authentications in subsequent sessions. - - This condition 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. - - Client implementations MUST tolerate response codes that they do not - recognize. - - -1.5. Active Script - - A user may have multiple Sieve scripts on the server, yet only one - script may be used for filtering of incoming messages. This is the - active script. Users may have zero or one active scripts and MUST - use the SETACTIVE command described below for changing the active - script or disabling Sieve processing. For example, a user may have - an everyday script they normally use and a special script they use - when they go on vacation. Users can change which script is being - used without having to download and upload a script stored somewhere - else. - - -1.6. Quotas - - Servers SHOULD impose quotas to prevent malicious users from - overflowing available storage. If a command would place a user over - a quota setting, servers MUST reply with a NO response. Client - implementations MUST be able to handle commands failing because of - quota restrictions. - - -1.7. Script Names - - Sieve script names may contain any valid UTF-8 characters, but names - must be at least one octet long. Zero octets script name - has special meaning (see SETACTIVE command section). Servers MUST - allow names of up to 128 UTF-8 octets <<(do we really want to specify - length in UTF-8 octets, as opposed to Unicode characters?)>> - in length, and may allow longer - names. - - -1.8. Capabilities - - Server capabilities are sent by the server upon a client connection. - Clients may request the capabilities at a later time by issuing the - CAPABILITY command described later. The capabilities consist of a - series of lines each with one or two strings. The first string is - the name of the capability, which is case-insensitive. The second - optional string is the value associated with that capability. - Order of capabilities is arbitrary, but each capability name can - appear at most once. - - The following capabilities are defined in this document: - - IMPLEMENTATION - Name of implementation and version - - SASL - List of SASL mechanisms supported by the server, each - separated by a space - - SIEVE - List of space separated Sieve extensions supported - - STARTTLS - If TLS [TLS] is supported by this implementation - - A server implementation MUST return SIEVE and IMPLEMENTATION - capabilities. - - A client implementation MUST ignore any other capabilities given - that it does not understand. - - Example: - - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "FILEINTO VACATION" - S: "STARTTLS" - S: OK - - <<Add RENAMESCRIPT>> - - -2. Commands - - The following commands are valid. Prior to successful authentication - only the AUTHENTICATE, CAPABILITY, STARTTLS, and LOGOUT commands are - valid. Servers MUST reject all other commands with a NO response. - Clients may pipeline commands (send more than one command at a time - without waiting for completion of the first command ). However, a - group of commands sent together MUST NOT have an AUTHENTICATE, - a STARTTLS or a HAVESPACE command anywhere but the last command in - the list. - - -2.1. AUTHENTICATE Command - - Arguments: - String - mechanism - String - initial data (optional) - - 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 identify and authenticate 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 the NO response. - - The authentication protocol exchange consists of a series of server - challenges and client responses that are specific to the selected - authentication mechanism. A server challenge consists of a string - (quoted or literal) followed by a CRLF. The contents of the string is - a base-64 encoding of the SASL data. A client response consists of - a string (quoted or literal) with the base-64 encoding of the SASL - data followed by a CRLF. If the client wishes to cancel the - authentication exchange, it issues a string containing a single "*". - If the server receives such a response, it MUST reject the - AUTHENTICATE command by sending an NO reply. - - Note that an empty challenge/response is sent as an empty string. - If the mechanism dictates that the final response is sent by the - server this data MAY be placed within the data portion of the SASL - response code to save a round trip. - - 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 the NO response. - - The service name specified by this protocol's profile of SASL is - "sieve". - - Reauthentication is not supported by ManageSieve protocol's profile - of SASL. I.e. after a successfully completed AUTHENTICATE command, - no more AUTHENTICATE commands may be issued in the same session. - After a successful AUTHENTICATE command completes, a server MUST - reject any further AUTHENTICATE commands with a NO reply. - - 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 OK response for the server. - - When a security layer takes effect, the ManageSieve protocol is reset - to the initial state (the state in ManageSieve after a client - has connected to the server). The server MUST discard any - knowledge obtained from the client which was not obtained from - the SASL (or TLS) negotiation itself. - Likewise, the client MUST discard any knowledge obtained from - the server, such as the list of ManageSieve extensions, which - was not obtained from the SASL (or TLS) negotiation itself. - (Note that a client MAY compare the advertised SASL mechanisms before and - after authentication in order to detect an active down-negotiation attack. - See below.) - - Once a SASL security layer is established, the server MUST re-issue the - capability results, followed by an OK response. This is necessary to - protect against man-in-the-middle attacks which alter the capabilities - list prior to SASL negotiation. - The capability results MUST include all SASL mechanisms. This is done in - order to allow client to detect active down-negotiation attack. - - When both [TLS] and SASL security layers are in effect, the - TLS encoding MUST be applied (when sending data) after the SASL encoding, - regardless of the order in which the layers were negotiated. - - Server implementations SHOULD support SASL proxy authentication so - that an administrator can administer a user's scripts. Proxy - authentication is when a user authenticates as herself/himself but - requests the server to act (authorize) as another user. - - <<The authorization identity generated by this [SASL] exchange - is a simple username, and both client and server MUST use the - [SASLprep] profile of the [StringPrep] algorithm to prepare - these names for transmission or comparison. If preparation of - the authorization identity fails or results in an empty string - (unless it was transmitted as the empty string), the server - MUST fail the authentication.>> - - 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. - - Note that a failed NO response to the AUTHENTICATE command may contain - one of the following response codes: AUTH-TOO-WEAK, ENCRYPT-NEEDED or - TRANSITION-NEEDED. See section 1.4 for detailed description of the - relevant conditions. - - To ensure interoperability, client and server implementations - of this extension MUST implement the [DIGEST-MD5] SASL - mechanism. <<What is the IESG policy on this?>> - - - Implementations MAY advertise the ANONYMOUS SASL mechanism [SASL-ANON]. - This indicates that the server supports ANONYMOUS SIEVE - script syntax verification. Only the CAPABILITY, PUTSCRIPT and - LOGOUT commands are available to the anonymous user. All other - commands MUST give NO responses. Furthermore the PUTSCRIPT command - SHOULD NOT <<MUST NOT?>> store any data. In this mode a positive - response to the PUTSCRIPT command indicates that the given script - does not have any syntax errors. - - Examples (Note that long lines are folded for readability and are - not part of protocol exchange): - - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "FILEINTO VACATION" - S: "STARTTLS" - S: OK - C: Authenticate "DIGEST-MD5" - S: "cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA==" - C: "Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg=" - S: OK (SASL "cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA==") - - A slightly different variant of the same authentication exchange: - - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "FILEINTO VACATION" - S: "STARTTLS" - S: OK - C: Authenticate "DIGEST-MD5" - S: {128+} - S: cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA== - C: {276+} - C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg=" - S: {56+} - S: cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== - C: "" - S: OK - - Another example demostrating use of SASL PLAIN mechanism under TLS: - - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "" -<<Is this allowed?>> - S: "SIEVE" "FILEINTO VACATION" - S: "STARTTLS" - S: OK - C: STARTTLS - S: OK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "PLAIN" - S: "SIEVE" "FILEINTO VACATION" - S: OK - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xu" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xz" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xy" - S: BYE "Too many failed authentication attempts" - <Server closes connection> - - -2.2. STARTTLS Command - - Support for STARTTLS command in servers is optional. Its availability - is advertised with "STARTTLS" capability as described in section - 1.8. - - The STARTTLS command requests commencement of a TLS negotiation. - The negotiation begins immediately after the CRLF in the OK - response. After a client issues a STARTTLS command, it MUST NOT - issue further commands until a server response is seen and the TLS - negotiation is complete. - - The STARTTLS command is only valid in non-authenticated state. The - server remains in non-authenticated state, even if client - credentials are supplied during the TLS negotiation. The SASL [SASL] - EXTERNAL mechanism MAY be used to authenticate once TLS client - credentials are successfully exchanged, but servers supporting the - STARTTLS command are not required to support the EXTERNAL mechanism. - - After the TLS layer is established, the server MUST re-issue the - capability results, followed by an OK response. This is necessary to - protect against man-in-the-middle attacks which alter the capabilities - list prior to STARTTLS. - - The capability result MUST NOT include the STARTTLS capability. - - The client MUST discard cached capability information and replace it - with the new information. The server MAY advertise different - capabilities after STARTTLS. - - Example: - - C: STARTTLS - S: OK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "PLAIN DIGEST-MD5 GSSAPI" - S: "SIEVE" "FILEINTO VACATION" - S: OK - - -2.3. LOGOUT Command - - The client sends the LOGOUT command when it is finished with a - connection and wishes to terminate it. The server MUST reply with an - OK response and terminate the connection. The server MUST ignore - commands issued by the client after the LOGOUT command. - - Example: - - C: Logout - S: OK - <connection terminated> - - -2.4. CAPABILITY Command - - The CAPABILITY command requests the server capabilities as described - earlier in this document. While the capabilities are sent upon - connection, they may change during authentication. The client SHOULD - issue a CAPABILITY command after successful authentication or after - negotiating a security layer using STARTTLS. - - - Example: - - C: CAPABILITY - S: "IMPLEMENTATION" "CMU Cyrus Sieved v001" - S: "SASL" "PLAIN KERBEROS_V4 GSSAPI" - S: "SIEVE" "FILEINTO VACATION" - S: "STARTTLS" - S: OK - - -2.5. HAVESPACE Command - - Arguments: - String - name - Number - size - - The HAVESPACE command is used to query the server for available - space. Clients specify the name they wish to save the script as and - it's size in octets. Servers respond with an NO if storing a script - with that name and size would fail or OK otherwise. Clients should - issue this command before attempting to place a script on the - server. - - Example: - - C: HAVESPACE "myscript" 999999 - S: NO (QUOTA) "Quota exceeded" - - C: HAVESPACE "foobar" 435 - S: OK - - -2.6. PUTSCRIPT Command - - Arguments: - String - Script name - String - Script content - - The PUTSCRIPT command is used by the client to submit a Sieve script - to the server. - - If the script already exists upon success the old script will be - overwritten. The old script MUST NOT be overwritten if PUTSCRIPT - fails in any way. A script of zero length SHOULD be disallowed. - - This command places the script on the server. It does not affect - whether the script is processed on incoming mail. The SETACTIVE - command is used to mark a script as active. - - When submitting large scripts clients SHOULD use the HAVESPACE - command beforehand to query if the server is willing to accept a - script of that size. - - The server MUST check the submitted script for syntactic validity. - If the script fails this test the server MUST reply with a NO - response. Any script that fails the validity test MUST NOT be stored - on the server. The message given with a NO response MUST be human - readable and SHOULD contain a specific error message giving line - number of the first error. Implementors should strive to produce - helpful error messages similar to those given by programming - language compilers. Client implementations should note that this may - be a multiline literal string with more than one error message - separated by newlines. - - Example: - - C: Putscript "foo" {31+} - C: #comment - C: InvalidSieveCommand - C: - S: NO "line 2: Syntax error" - - C: Putscript "mysievescript" {110+} - C: require ["fileinto"]; - C: - C: if envelope :contains "to" "tmartin+sent" { - C: fileinto "INBOX.sent"; - C: } - S: OK - - -2.7. LISTSCRIPTS Command - - This command lists the scripts the user has on the server. Upon - success a list of linebreak separated script names is returned - followed by an OK response. If there exists an active script the - atom ACTIVE is appended to the line of that script. The ACTIVE - string MUST NOT appear on more than one response line. - - Example: - - C: Listscripts - S: "summer_script" - S: "vacation_script" - S: "main_script" ACTIVE - S: OK - - -2.8. SETACTIVE Command - - Arguments: - String - script name - - This command sets a script active. If the script name is the empty - string (i.e. "") then any active script is disabled. Disabling an active script - when there is no script active is not an error and MUST result in OK reply. - - If the script does not exist on the server then the server MUST reply with a NO - response. - - Examples: - - C: Setactive "vacationscript" - S: Ok - - C: Setactive "" - S: Ok - - C: Setactive "baz" - S: No "There is no script by that name" - - -2.9. GETSCRIPT Command - - Arguments: - String - Script name - - This command gets the contents of the specified script. If the - script does not exist the server MUST reply with a NO response. Upon - success a string with the contents of the script is returned - followed by a OK response. - - Example: - - C: Getscript "myscript" - S: {48+} - S: #this is my wonderful script - S: reject "I reject all"; - S: - S: OK - - -2.10. DELETESCRIPT Command - - Parameters: - sieve-name - Script name - - This command is used to delete a user's Sieve script. Servers MUST - reply with a NO response if the script does not exist. The server - MUST NOT allow the client to delete an active script and reply with - a NO response if attempted. If a client wishes to delete an active - script it should use the SETACTIVE command to disable the script - first. - - Example: - - C: Deletescript "foo" - S: Ok - - C: Deletescript "baz" - S: No "You may not delete an active script" - - -3. Sieve URL Scheme - - URI scheme name: sieve - - Status: permanent - - URI scheme syntax: - - Described using ABNF [ABNF] and ABNF entities from [URI-GEN]. - - sieveurl = sieveurl-server / sieveurl-script - - sieveurl-server = "sieve://" authority - - sieveurl-script = "sieve://" [ authority ] "/" scriptname - - scriptname = *pchar - - URI scheme semantics: - - A Sieve URL identifies a Sieve server or a Sieve - script on a Sieve server. <<The latter form is associated with - application/sieve MIME type.>> - <<There is no MIME type associated with this URI.>> - - The server form is used in the REFERRAL response code in order - to designate another server where the client should perform - its operations. - - The script form allows to retrieve (GETSCRIPT), update (PUTSCRIPT), - delete (DELETESCRIPT) or activate (SETACTIVE) the named script, - however the most typical action would be to retrieve the script. - If the script name is empty, the URI requests that the client - lists available scripts using LISTSCRIPTS command. - - Encoding considerations: The script name, if present, - is in UTF-8. Non-US-ASCII UTF-8 octets MUST be percent-encoded as - described in [URI-GEN]. - - The user name (in the "authority" part), if present, - is in UTF-8. Non-US-ASCII UTF-8 octets MUST be percent-encoded as - described in [URI-GEN]. - - Applications/protocols that use this URI scheme name: - <<The protocol is described in this document.>> - - Interoperability considerations: None. - - Security considerations: <<None>>. - - Contact: Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - References: This document and <<RFC 3028>>. - - -4. 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. - - - SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / %x5D-7F - ;; any TEXT-CHAR except QUOTED-SPECIALS - - QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS - - QUOTED-SPECIALS = <"> / "\" - - SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / - UTF8-5 / UTF8-6 - - 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 - - auth-type = <"> auth-type-name <"> - - auth-type-name = iana-token - ;; as defined in SASL [SASL] - - command = command-authenticate / command-logout / - command-getscript / command-setactive / - command-listscripts / command-deletescript / - command-putscript / command-capability / - command-havespace / command-starttls - - command-authenticate = "AUTHENTICATE" SP auth-type [SP string] - *(CRLF string) CRLF - - command-capability = "CAPABILITY" CRLF - - command-deletescript = "DELETESCRIPT" SP sieve-name CRLF - - command-getscript = "GETSCRIPT" SP sieve-name CRLF - - command-havespace = "HAVESPACE" SP sieve-name SP number CRLF - - command-listscripts = "LISTSCRIPTS" CRLF - - command-logout = "LOGOUT" CRLF - - command-putscript = "PUTSCRIPT" SP sieve-name SP string CRLF - - command-setactive = "SETACTIVE" SP sieve-name CRLF - - command-starttls = "STARTTLS" CRLF - - literal = "{" number "+}" CRLF *OCTET - ;; The number represents the number of octets. - ;; Sieve scripts MUST be sent as literal-utf8. - ;; <<literal-utf8>> is defined in ACAP. - - number = 1*DIGIT - ;; A 32-bit unsigned number. - ;; (0 <= n < 4,294,967,296) - - quoted = <"> *1024QUOTED-CHAR <"> - ;; limited to 1024 octets between the <">s - - resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / - "QUOTA" / resp-code-sasl / resp-code-referral - "TRANSITION-NEEDED" / "TRYLATER" / - resp-code-ext - - resp-code-referral = "REFERRAL" SP sieveurl - - resp-code-sasl = "SASL" SP string - - resp-code-ext = iana-token [SP extension-data] - ;; unknown codes MUST be tolerated by the client - - response = response-authenticate / response-logout / - response-getscript / response-setactive / - response-listscripts / response-deletescript / - response-putscript / response-capability / - response-havespace / response-starttls - - response-authenticate = *(string CRLF) (response-oknobye) - - response-capability = *(single-capability) response-oknobye - - single-capability = capability-name [SP string] CRLF - - capability-name = string - <<Note that literals are allowed!>> - - initial-capabilities = <"> "IMPLEMENTATION" <"> SP string / - <"> "SASL" <"> SP sasl-mechs / - <"> "SIEVE" <"> SP sieve-extensions / - <"> "STARTTLS" <"> - ;; Each capability conforms to - ;; the syntax for single-capability. - ;; Also note that the capability name - ;; can be returned as either literal - ;; or quoted, even though only "quoted" - ;; string is shown above. - - sasl-mechs = string - ; space separated list of SASL mechanisms, - ; can be empty - - sieve-extensions = string - ; space separated list of supported SIEVE extensions, - ; can be empty - - response-deletescript = response-oknobye - - response-getscript = [string CRLF] response-oknobye - - response-havespace = response-oknobye - - response-listscripts = *(sieve-name [SP "ACTIVE"] CRLF) response-oknobye - ;; ACTIVE may only occur with one sieve-name - - response-logout = response-oknobye - - response-oknobye = ("OK" / "NO" / "BYE") [SP "(" resp-code ")"] - [SP string] CRLF - - response-putscript = response-oknobye - - response-setactive = response-oknobye - - response-starttls = response-oknobye - - sieve-name = string - - string = quoted / literal - - -5. Security Considerations - - The AUTHENTICATE command uses SASL [SASL] and possibly TLS [TLS] to provide - basic authentication, authorization, integrity and privacy services. - When a SASL mechanism is used the security considerations for that - mechanism apply. - - This 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. - - -6. IANA Considerations - - IANA is requested to reserve TCP port number 2000 for use with - the Manage Sieve protocol described in this document. - - IANA is requested to create a new registry for Manage Sieve - capabilities. The registration template for Manage Sieve capabilities - is specified in the next section. - Manage Sieve protocol capabilities MUST be specified in a standards - track or IESG approved experimental RFC. - - <<Add a new registry for response codes, as per ABNF comments.>> - - <<Reference to SIEVE URL registration.>> - - -6.1. Manage Sieve Capability Registration Template - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: - - Description: - - Relevant publications: - - Person & email address to contact for further information: - - Author/Change controller: - - -6.2. Registration of Initial Manage Sieve capabilities. - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: IMPLEMENTATION - - Description: Its value contains name of server - implementation and its version. - - Relevant publications: this RFC, section 1.8. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: SASL - - Description: Its value contains a space separated - list of SASL mechanisms supported by server. - - Relevant publications: this RFC, sections 1.8 and 2.1. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: SIEVE - - Description: Its value contains a space separated - list of supported SIEVE extensions - - Relevant publications: this RFC, section 1.8. - <<Also [SIEVE]>> - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: STARTTLS - - Description: This capability is returned if server - supports TLS (STARTTLS command). - - Relevant publications: this RFC, sections 1.8 and 2.2. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - -7. References - -7.1. Normative References - - [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997 - <ftp://ftp.isi.edu/in-notes/rfc2119.txt> - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [ACAP] Newman, Myers, "ACAP -- Application Configuration Access Proto- - col", RFC 2244, Innosoft, Netscape, November 1997. - - [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and Security - Layer (SASL)", work in progress, draft-ietf-sasl-rfc2222bis-*.txt. - - [SASLprep] Zeilega, K., "SASLprep: Stringprep profile for user names - and passwords", work in progress, draft-ietf-sasl-saslprep-*.txt. - - [StringPrep] Hoffman, P. and Blanchet, M., "Preparation of - Internationalized Strings ("stringprep")", work in progress, - draft-hoffman-rfc3454bis-*.txt. - - [SASL-ANON] K. Zeilenga (Ed.), "The Anonymous SASL Mechanism", - work in progress, draft-ietf-sasl-anon-XX.txt (Obsoletes RFC 2245). - - [SIEVE] Guenther, P. and Showalter, T., "Sieve: An Email Filtering - Language", work in Progress, draft-ietf-sieve-3028bis-XX.txt - - [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, - January 1999. <<Needs updating>> - - [URI-GEN] Berners-Lee, T., Fielding, R. and L. Masinter, - "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, - January 2005. - - -7.2. Informative References - - [IMAP4rev1] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [PLAIN] K. Zeilenga, "The Plain SASL Mechanism", - work in progress, draft-ietf-sasl-plain-XX.txt (Updates RFC 2595). - - -8. Author's Address - - Tim Martin - Mirapoint Inc. - 909 Hermosa Court - Sunnyvale, CA 94085 - Phone: (408) 720-3835 - EMail: timmartin@alumni.cmu.edu - - Alexey Melnikov - Isode Ltd. - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex, TW12 2BX, GB - Email: alexey.melnikov@isode.com - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - The IETF has been notified of intellectual property rights claimed in - regard to some or all of the specification contained in this - document. For more information consult the online list of claimed - rights. - - -Disclaimer of Validity - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Copyright Statement - - Copyright (C) The Internet Society (2006). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - -Appendix A. Acknowledgments - - Thanks to Simon Josefsson, Larry Greenfield, Allen Johnson, Chris - Newman, Lyndon Nerenberg, Tim Showalter, Sarah Robeson, and Walter - Wong for help with this document. diff --git a/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-08.txt b/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-08.txt deleted file mode 100755 index 59bb20f9..00000000 --- a/docs/[rfc5804] Managing Sieve/draft-martin-managesieve-08.txt +++ /dev/null @@ -1,1359 +0,0 @@ -Network Working Group Tim Martin -INTERNET-DRAFT BeThereBeSquare Inc. -Intended status: Standards Track Alexey Melnikov -Expires: February 2008 Isode Limited - August 14, 2007 - - - - A Protocol for Remotely Managing Sieve Scripts - <draft-martin-managesieve-08.txt> - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - Internet-Drafts are working documents of the Internet - Engineering Task Force (IETF), its areas, and its - working groups. Note that other groups may also distribute - working documents as Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of - six months and may be updated, replaced, or obsoleted by - other documents at any time. It is inappropriate to use - Internet-Drafts as reference material or to cite them other - than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/1id-abstracts.html - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html - - Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The IETF Trust (2007). - - -Abstract - - Sieve scripts allow users to filter incoming email. Message stores - are commonly sealed servers so users cannot log into them, yet users - must be able to update their scripts on them. This document - describes a protocol "sieve" for securely managing Sieve scripts on - a remote server. This protocol allows a user to have multiple - scripts, and also alerts a user to syntactically flawed scripts. - - - Table of Contents - - - -Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . . 1 -Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 -1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 -1.1. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 -1.2. Conventions Used in the Document . . . . . . . . . . . . . . 4 -1.3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 -1.4. Response Codes . . . . . . . . . . . . . . . . . . . . . . . 5 -1.5. Active Script . . . . . . . . . . . . . . . . . . . . . . . . 6 -1.6. Quotas . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 -1.7. Script Names . . . . . . . . . . . . . . . . . . . . . . . . 7 -1.8. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 7 -2. Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 8 -2.1. AUTHENTICATE Command . . . . . . . . . . . . . . . . . . . . 8 -2.2. STARTTLS Command . . . . . . . . . . . . . . . . . . . . . . 10 -2.3. LOGOUT Command . . . . . . . . . . . . . . . . . . . . . . . 10 -2.4. CAPABILITY Command . . . . . . . . . . . . . . . . . . . . . 11 -2.5. HAVESPACE Command . . . . . . . . . . . . . . . . . . . . . . 11 -2.6. PUTSCRIPT Command . . . . . . . . . . . . . . . . . . . . . . 11 -2.7. LISTSCRIPTS Command . . . . . . . . . . . . . . . . . . . . . 13 -2.8. SETACTIVE Command . . . . . . . . . . . . . . . . . . . . . . 13 -2.9. GETSCRIPT Command . . . . . . . . . . . . . . . . . . . . . . 13 -2.10. DELETESCRIPT Command . . . . . . . . . . . . . . . . . . . . 14 -3. Sieve URL Scheme . . . . . . . . . . . . . . . . . . . . . . 14 -4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 -5. Security Considerations . . . . . . . . . . . . . . . . . . . 18 -7. References . . . . . . . . . . . . . . . . . . . . . . . . . -7.1. Normative References . . . . . . . . . . . . . . . . . . . . -7.2. Informative References . . . . . . . . . . . . . . . . . . . -8. Author's Address . . . . . . . . . . . . . . . . . . . . . . - - -1. Introduction - - - -1.1. Changes - - [[Note to RFC editor: please delete this section before - publication]] - - Changes since 07 - - -Fixed examples to match 3028bis - capability names are case - sensitive, so examples should show "fileinto" instead of - "FILEINTO", etc. - - -Minor editorial changes - - Changes since 06 - - -Clarified meaning of the QUOTA response code - - -Clarified which characters are not allowed in script names - and the maximum script name length - - -Clarified that the empty list of SASL mechanisms is allowed - - -Clarified that PUTSCRIPT must not store data after anonymous - authentication - - -Move text about NOTIFY capability into this document - - -Additional examples - - -Updated ABNF, References, Contact information - - Changes since 05 - - -More ABNF fixes - - -Added IANA considerations - - -Added/fixed text about AUTHENTICATE. - - -Updated the text om Sieve URLs. - - -Updated and added new examples. - - Changes since 04 - - -Updated boilerplate and some references. Added Alexey as co-editor. - - -Minor ABNF fixes - - -Cleaned up terminology (for example, made more consistent with - SASL) - - -Added more examples, fixed some existing examples - - -Clarified that STARTTLS command is optional - - -Clarified that disabling an active script when there is no script - active is not an error. - - Changes since 03 - - -Add referals and Sieve URLs - - -Lots of spelling/grammer fixes - - -Don't give capabilities after successful STARTTLS. This is because - it isn't consistant with AUTHENTICATE. There is language specifying - that a client should re-issue a CAPABILITY command after - AUTHENTICATE/STARTTLS. - - -Putting a script of length 0 doesn't remove the script. If this - functionality is desired, the DELETESCRIPT command should be used. - - Changes since 02 - - -add BYE response - - -typo on line 588 - - -allow ANONYMOUS access for sieve script verification - - -updated SIEVE spec reference - - Changes since 01 - - -changed contact info - - Changes since 00 - - -added response codes (from ACAP) - - -removed special-ok response from authenticate command (response - codes obsolete it) - - -changed service name to "sieve" - - -ABNF fixes - - -Alexey's wording changes - - -Eliminated lame PLAIN paragraph - - Changes since PRE - - -dropped synchronized literals. added HAVESPACE command - - -changed capability response syntax. added CAPABILITY command - - -allowed pipelining - - - "sieve" -> "Sieve". Other minor fixes - - -made script names more flexible - - -added starttls support - - -1.2. Conventions Used in the Document - - 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 [KEYWORDS]. - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. Line breaks that do not start a new "C:" or - "S:" exist for editorial reasons. - - -1.3. Syntax - - This a line oriented protocol much like [IMAP4rev1] or [ACAP]. There - are three types: ATOMS, numbers and strings. Strings may be quoted - or literal. See [ACAP] for detailed descriptions of these types. - <<Clarify that the CRLF after the literal size is not "end of the - line">> - - Each command consists of an atom followed by zero or more strings - and numbers terminated by a newline. - - All client queries are replied to with either an OK, NO, or BYE - response. Each response may be followed by a response code (see - response codes section) and by a string consisting of human readable - text in the local language. The contents of the string SHOULD be - shown to the user and implementations MUST NOT attempt to parse the - message for meaning. - - The BYE response may be used if the server wishes to close the - connection. A server may wish to do this because the client was idle - for too long or there were too many failed authentication attempts. - This response can be issued at any time and should be immediately - followed by a server hang-up of the connection. If a server has a - inactivity timeout resulting in client autologout it MUST be no less - than 30 minutes. - - <<IANA registration is pending. Current implementations generally - use port number 2000.>> - - -1.4. Response Codes - - An OK, NO, 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: - - AUTH-TOO-WEAK - - This response code is returned in the NO response 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 in the NO response 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. - - QUOTA - - If this response code is returned in the NO/BYE response, it means - that the command would have placed the user above the site-defined - quota constraints. If this response code is returned in the OK - response, it can mean that the user is near its quota or that the - user exceeded its quota, but the server supports soft quotas. - - REFERRAL - - This response code may be returned with a BYE result from any - command, and includes a mandatory parameter that indicates what - server to access to manage this user's sieve scripts. The server - will be specified by a Sieve URL (see "Sieve URL Scheme" section). - The scriptname portion of the URL MUST NOT be specified. The client - should authenticate to the specified server and use it for all - further commands in the current session. - - SASL - - This response code can occur in the OK response to a successful - AUTHENTICATE command and includes the optional final server response - data from the server as specified by [SASL]. - - TRANSITION-NEEDED - - This response code occurs in a NO response of 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 is typically done - by establishing a secure channel using TLS, followed by - authenticating once using the [PLAIN] authentication mechanism. - The selected mechanism SHOULD then work for authentications in - subsequent sessions. - - This condition 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. This - response code only make sense when returned in a NO/BYE response. - - - Client implementations MUST tolerate response codes that they do not - recognize. - - -1.5. Active Script - - A user may have multiple Sieve scripts on the server, yet only one - script may be used for filtering of incoming messages. This is the - active script. Users may have zero or one active scripts and MUST - use the SETACTIVE command described below for changing the active - script or disabling Sieve processing. For example, a user may have - an everyday script they normally use and a special script they use - when they go on vacation. Users can change which script is being - used without having to download and upload a script stored somewhere - else. - - -1.6. Quotas - - Servers SHOULD impose quotas to prevent malicious users from - overflowing available storage. If a command would place a user over - a quota setting, servers that impose such quotas MUST reply with a - NO response. Client implementations MUST be able to handle commands - failing because of quota restrictions. - - -1.7. Script Names - - Sieve script names may contain any valid UTF-8 characters, except - for NUL, CR or LF. Names MUST be at least one octet long. Zero - octets script name has special meaning (see SETACTIVE command - section). Servers MUST allow names of up to 128 Unicode characters - in length, and MAY allow longer names. - - -1.8. Capabilities - - Server capabilities are sent by the server upon a client connection. - Clients may request the capabilities at a later time by issuing the - CAPABILITY command described later. The capabilities consist of a - series of lines each with one or two strings. The first string is - the name of the capability, which is case-insensitive. The second - optional string is the value associated with that capability. - Order of capabilities is arbitrary, but each capability name can - appear at most once. - - The following capabilities are defined in this document: - - IMPLEMENTATION - Name of implementation and version - - SASL - List of SASL mechanisms supported by the server, each - separated by a space. This list can be empty if and only if - STARTTLS is also advertised. This means that the client must - negotiate TLS encryption with STARTTLS first, at which point - the SASL capability will list a non empty list of SASL mechanisms. - <<But STARTTLS is optional!>> - - SIEVE - List of space separated Sieve extensions (as listed - in Sieve "require" action [SIEVE]) supported by the Sieve engine - - STARTTLS - If TLS [TLS] is supported by this implementation - - NOTIFY - A space separated list of URI schema parts for supported - notification methods. This capability MUST be specified if the - Sieve implementation supports the "enotify" extension - [NOTIFY]. - - A server implementation MUST return SIEVE and IMPLEMENTATION - capabilities. - - A client implementation MUST ignore any listed capabilities - that it does not understand. - - Example: - - S: "IMPlemENTATION" "Example1 ManageSieved v001" - S: "SASl" "DIGEST-MD5 GSSAPI" - S: "SIeVE" "fileinto vacation" - S: "StaRTTLS" - S: "NOTIFY" "xmpp mailto" - S: OK - - <<Add RENAMESCRIPT>> - - -2. Commands - - The following commands are valid. Prior to successful authentication - only the AUTHENTICATE, CAPABILITY, STARTTLS, and LOGOUT commands are - valid. Servers MUST reject all other commands with a NO response. - Clients may pipeline commands (send more than one command at a time - without waiting for completion of the first command ). However, a - group of commands sent together MUST NOT have an AUTHENTICATE, - a STARTTLS or a HAVESPACE command anywhere but the last command in - the list. - - -2.1. AUTHENTICATE Command - - Arguments: - String - mechanism - String - initial data (optional) - - 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 identify and authenticate 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 the NO response. - - The authentication protocol exchange consists of a series of server - challenges and client responses that are specific to the selected - authentication mechanism. A server challenge consists of a string - (quoted or literal) followed by a CRLF. The contents of the string - is a base-64 encoding [BASE64] of the SASL data. A client response - consists of a string (quoted or literal) with the base-64 encoding - of the SASL data followed by a CRLF. If the client wishes to cancel - the authentication exchange, it issues a string containing a single - "*". If the server receives such a response, it MUST reject the - AUTHENTICATE command by sending an NO reply. - - Note that an empty challenge/response is sent as an empty string. - If the mechanism dictates that the final response is sent by the - server this data MAY be placed within the data portion of the SASL - response code to save a round trip. - - 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 the NO response. - - The service name specified by this protocol's profile of SASL is - "sieve". - - Reauthentication is not supported by ManageSieve protocol's profile - of SASL. I.e. after a successfully completed AUTHENTICATE command, - no more AUTHENTICATE commands may be issued in the same session. - After a successful AUTHENTICATE command completes, a server MUST - reject any further AUTHENTICATE commands with a NO reply. - - 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 OK response for the server. - - When a security layer takes effect, the ManageSieve protocol is - reset to the initial state (the state in ManageSieve after a client - has connected to the server). The server MUST discard any - knowledge obtained from the client which was not obtained from - the SASL (or TLS) negotiation itself. - Likewise, the client MUST discard any knowledge obtained from - the server, such as the list of ManageSieve extensions, which - was not obtained from the SASL (or TLS) negotiation itself. - (Note that a client MAY compare the advertised SASL mechanisms - before and after authentication in order to detect an active - down-negotiation attack. See below.) - - Once a SASL security layer is established, the server MUST re-issue - the capability results, followed by an OK response. This is - necessary to protect against man-in-the-middle attacks which alter - the capabilities list prior to SASL negotiation. - The capability results MUST include all SASL mechanisms. This is - done in order to allow client to detect active down-negotiation - attack. - - When both [TLS] and SASL security layers are in effect, the - TLS encoding MUST be applied (when sending data) after the SASL - encoding, regardless of the order in which the layers were - negotiated. - - Server implementations SHOULD support SASL proxy authentication so - that an administrator can administer a user's scripts. Proxy - authentication is when a user authenticates as herself/himself but - requests the server to act (authorize) as another user. - - <<The authorization identity generated by this [SASL] exchange - is a simple username, and both client and server MUST use the - [SASLprep] profile of the [StringPrep] algorithm to prepare - these names for transmission or comparison. If preparation of - the authorization identity fails or results in an empty string - (unless it was transmitted as the empty string), the server - MUST fail the authentication.>> - - 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. - - Note that a failed NO response to the AUTHENTICATE command may - contain one of the following response codes: AUTH-TOO-WEAK, - ENCRYPT-NEEDED or TRANSITION-NEEDED. See section 1.4 for detailed - description of the relevant conditions. - - To ensure interoperability, client and server implementations - of this extension MUST implement the [DIGEST-MD5] SASL - mechanism. <<What is the IESG policy on this?>> - - - Implementations MAY advertise the ANONYMOUS SASL mechanism - [SASL-ANON]. This indicates that the server supports ANONYMOUS SIEVE - script syntax verification. Only the CAPABILITY, PUTSCRIPT and - LOGOUT commands are available to the anonymous user. All other - commands MUST give NO responses. Furthermore the PUTSCRIPT command - MUST NOT persistently store any data. In this mode a positive - response to the PUTSCRIPT command indicates that the given script - does not have any syntax errors. - - Examples (Note that long lines are folded for readability and are - not part of protocol exchange): - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - C: Authenticate "DIGEST-MD5" - S: "cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA==" - C: "Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg=" - S: OK (SASL "cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZ - mZmZA==") - - A slightly different variant of the same authentication exchange: - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - C: Authenticate "DIGEST-MD5" - S: {128+} - S: cmVhbG09ImVsd29vZC5pbm5vc29mdC5jb20iLG5vbmNlPSJPQTZNRzl0 - RVFHbTJoaCIscW9wPSJhdXRoIixhbGdvcml0aG09bWQ1LXNlc3MsY2hh - cnNldD11dGYtOA== - C: {276+} - C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuY29tIixub25jZT0iT0E2TUc5dEVRR20yaGgiLG5jPTAw - MDAwMDAxLGNub25jZT0iT0E2TUhYaDZWcVRyUmsiLGRpZ2VzdC11cmk9Im - ltYXAvZWx3b29kLmlubm9zb2Z0LmNvbSIscmVzcG9uc2U9ZDM4OGRhZDkw - ZDRiYmQ3NjBhMTUyMzIxZjIxNDNhZjcscW9wPWF1dGg=" - S: {56+} - S: cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== - C: "" - S: OK - - Another example demostrating use of SASL PLAIN mechanism under TLS. - This example also demonstrate use of SASL "initial response" - (the second parameter to the Authenticate command): - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - C: STARTTLS - S: OK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "PLAIN" - S: "SIEVE" "fileinto vacation" - S: OK - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xu" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xz" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xy" - S: BYE "Too many failed authentication attempts" - <Server closes connection> - - The following example demonstrate use of SASL "initial response". - It also demonstrates that an empty response can be sent as a - literal: - - C: AUTHENTICATE "GSSAPI" {1488+} - C: YIIE[...1480 octets here ...]dA== - S: {208+} - S: YIGZBgkqhkiG9xIBAgICAG+BiTCBhqADAgEFoQMCAQ+iejB4oAMCARKic - [...114 octets here ...] - /yzpAy9p+Y0LanLskOTvMc0MnjgAa4YEr3eJ6 - C: {0+} - C: - S: {44+} - S: BQQF/wAMAAwAAAAAYRGFAo6W0vIHti8i1UXODgEAEAA= - C: {44+} - C: BQQE/wAMAAwAAAAAIsT1iv9UkZApw471iXt6cwEAAAE= - S: OK - - -2.2. STARTTLS Command - - Support for STARTTLS command in servers is optional. Its - availability is advertised with "STARTTLS" capability as described - in section 1.8. - - The STARTTLS command requests commencement of a TLS negotiation. - The negotiation begins immediately after the CRLF in the OK - response. After a client issues a STARTTLS command, it MUST NOT - issue further commands until a server response is seen and the TLS - negotiation is complete. - - The STARTTLS command is only valid in non-authenticated state. The - server remains in non-authenticated state, even if client - credentials are supplied during the TLS negotiation. The SASL [SASL] - EXTERNAL mechanism MAY be used to authenticate once TLS client - credentials are successfully exchanged, but servers supporting the - STARTTLS command are not required to support the EXTERNAL mechanism. - - After the TLS layer is established, the server MUST re-issue the - capability results, followed by an OK response. This is necessary to - protect against man-in-the-middle attacks which alter the - capabilities list prior to STARTTLS. This capability result MUST NOT - include the STARTTLS capability. - - The client MUST discard cached capability information and replace it - with the new information. The server MAY advertise different - capabilities after STARTTLS. - - Example: - - C: StartTls - S: oK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "PLAIN DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: ok - - -2.3. LOGOUT Command - - The client sends the LOGOUT command when it is finished with a - connection and wishes to terminate it. The server MUST reply with an - OK response and terminate the connection. The server MUST ignore - commands issued by the client after the LOGOUT command. - - Example: - - C: Logout - S: Ok - <connection terminated> - - -2.4. CAPABILITY Command - - The CAPABILITY command requests the server capabilities as described - earlier in this document. While the capabilities are sent upon - connection, they may change during authentication. The client SHOULD - issue a CAPABILITY command after successful authentication or after - negotiating a security layer using STARTTLS. - - - Example: - - C: CAPABILITY - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "PLAIN KERBEROS_V4 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - - -2.5. HAVESPACE Command - - Arguments: - String - name - Number - size - - The HAVESPACE command is used to query the server for available - space. Clients specify the name they wish to save the script as and - its size in octets. Servers respond with an NO if storing a script - with that name and size would fail or OK otherwise. Clients SHOULD - issue this command before attempting to place a script on the - server. - - Example: - - C: HAVESPACE "myscript" 999999 - S: NO (QUOTA) "Quota exceeded" - - C: HAVESPACE "foobar" 435 - S: OK - - -2.6. PUTSCRIPT Command - - Arguments: - String - Script name - String - Script content - - The PUTSCRIPT command is used by the client to submit a Sieve script - to the server. - - If the script already exists, upon success the old script will be - overwritten. The old script MUST NOT be overwritten if PUTSCRIPT - fails in any way. A script of zero length SHOULD be disallowed. - - This command places the script on the server. It does not affect - whether the script is processed on incoming mail, unless it replaces - the script which is already active. The SETACTIVE - command is used to mark a script as active. - - When submitting large scripts clients SHOULD use the HAVESPACE - command beforehand to query if the server is willing to accept a - script of that size. - - The server MUST check the submitted script for syntactic validity. - If the script fails this test the server MUST reply with a NO - response. Any script that fails the validity test MUST NOT be stored - on the server. The message given with a NO response MUST be human - readable and SHOULD contain a specific error message giving the line - number of the first error. Implementors should strive to produce - helpful error messages similar to those given by programming - language compilers. Client implementations should note that this may - be a multiline literal string with more than one error message - separated by newlines. - - Example: - - C: Putscript "foo" {31+} - C: #comment - C: InvalidSieveCommand - C: - S: NO "line 2: Syntax error" - - C: Putscript "mysievescript" {110+} - C: require ["fileinto"]; - C: - C: if envelope :contains "to" "tmartin+sent" { - C: fileinto "INBOX.sent"; - C: } - S: OK - - -2.7. LISTSCRIPTS Command - - This command lists the scripts the user has on the server. Upon - success a list of CRLF separated script names (each represented - as a quoted or literal string) is returned followed by an OK - response. If there exists an active script the atom ACTIVE is - appended to the corresponding script name. The atom ACTIVE - MUST NOT appear on more than one response line. - - Example: - - C: Listscripts - S: "summer_script" - S: "vacation_script" - S: {13+} - S: clever"script - S: "main_script" ACTIVE - S: OK - - C: listscripts - S: "summer_script" - S: "main_script" active - S: OK - - -2.8. SETACTIVE Command - - Arguments: - String - script name - - This command sets a script active. If the script name is the empty - string (i.e. "") then any active script is disabled. Disabling an - active script when there is no script active is not an error and - MUST result in OK reply. - - If the script does not exist on the server then the server MUST - reply with a NO response. - - Examples: - - C: Setactive "vacationscript" - S: Ok - - C: Setactive "" - S: Ok - - C: Setactive "baz" - S: No "There is no script by that name" - - C: Setactive "baz" - S: No {31+} - S: There is no script by that name - - -2.9. GETSCRIPT Command - - Arguments: - String - Script name - - This command gets the contents of the specified script. If the - script does not exist the server MUST reply with a NO response. Upon - success a string with the contents of the script is returned - followed by a OK response. - - Example: - - C: Getscript "myscript" - S: {54+} - S: #this is my wonderful script - S: reject "I reject all"; - S: - S: OK - - -2.10. DELETESCRIPT Command - - Parameters: - sieve-name - Script name - - This command is used to delete a user's Sieve script. Servers MUST - reply with a NO response if the script does not exist. The server - MUST NOT allow the client to delete an active script, so the server - MUST reply with a NO response if attempted. If a client wishes to - delete an active script it should use the SETACTIVE command to - disable the script first. - - Example: - - C: Deletescript "foo" - S: Ok - - C: Deletescript "baz" - S: No "You may not delete an active script" - - -3. Sieve URL Scheme - - URI scheme name: sieve - - Status: permanent - - URI scheme syntax: - - Described using ABNF [ABNF] and ABNF entities from [URI-GEN]. - - sieveurl = sieveurl-server / sieveurl-script - - sieveurl-server = "sieve://" authority - - sieveurl-script = "sieve://" [ authority ] "/" scriptname - - scriptname = *pchar - - URI scheme semantics: - - A Sieve URL identifies a Sieve server or a Sieve - script on a Sieve server. <<The latter form is associated with - application/sieve MIME type.>> - <<There is no MIME type associated with this URI.>> - - The server form is used in the REFERRAL response code in order - to designate another server where the client should perform - its operations. - - The script form allows to retrieve (GETSCRIPT), update - (PUTSCRIPT), delete (DELETESCRIPT) or activate (SETACTIVE) - the named script, however the most typical action would be to - retrieve the script. If the script name is empty, the URI - requests that the client lists available scripts using - the LISTSCRIPTS command. - - Encoding considerations: The script name, if present, - is in UTF-8. Non-US-ASCII UTF-8 octets MUST be percent-encoded as - described in [URI-GEN]. - - The user name (in the "authority" part), if present, - is in UTF-8. Non-US-ASCII UTF-8 octets MUST be percent-encoded as - described in [URI-GEN]. - - Applications/protocols that use this URI scheme name: - ManageSieve [RFC XXXX] clients and servers. - Clients that can store user preferences in protocols such as - LDAP or ACAP. <<Add ref>> - - Interoperability considerations: None. - - Security considerations: <<None>>. - - Contact: Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - References: This document and <<RFC 3028>> [SIEVE]. - - -4. 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. - - - SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / - %x5D-7F - ;; any TEXT-CHAR except QUOTED-SPECIALS - - QUOTED-CHAR = SAFE-UTF8-CHAR / DQUOTE QUOTED-SPECIALS - - QUOTED-SPECIALS = DQUOTE / "\" - - SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 / - UTF8-5 / UTF8-6 - - 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 - - auth-type = DQUOTE auth-type-name DQUOTE - - auth-type-name = iana-token - ;; as defined in SASL [SASL] - - command = command-authenticate / command-logout / - command-getscript / command-setactive / - command-listscripts / command-deletescript / - command-putscript / command-capability / - command-havespace / command-starttls - - command-authenticate = "AUTHENTICATE" SP auth-type [SP string] - *(CRLF string) CRLF - - command-capability = "CAPABILITY" CRLF - - command-deletescript = "DELETESCRIPT" SP sieve-name CRLF - - command-getscript = "GETSCRIPT" SP sieve-name CRLF - - command-havespace = "HAVESPACE" SP sieve-name SP number CRLF - - command-listscripts = "LISTSCRIPTS" CRLF - - command-logout = "LOGOUT" CRLF - - command-putscript = "PUTSCRIPT" SP sieve-name SP string CRLF - - command-setactive = "SETACTIVE" SP sieve-name CRLF - - command-starttls = "STARTTLS" CRLF - - literal = "{" number "+}" CRLF *OCTET - ;; The number represents the number of - ;; octets. -<<Need to make "+" only allowed from clients to server, to match - IMAP LITERAL+). Also need to also update the examples to match.>> - - number = 1*DIGIT - ;; A 32-bit unsigned number. - ;; (0 <= n < 4,294,967,296) - - quoted = DQUOTE *1024QUOTED-CHAR DQUOTE - ;; limited to 1024 octets between the <">s - - resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / - "QUOTA" / resp-code-sasl / - resp-code-referral / - "TRANSITION-NEEDED" / "TRYLATER" / - resp-code-ext - - resp-code-referral = "REFERRAL" SP sieveurl - - resp-code-sasl = "SASL" SP string - - resp-code-ext = iana-token [SP extension-data] - ;; unknown response codes MUST be tolerated - ;; by the client. <<"iana-token" and - ;; "extension-data" are defined in ACAP>> - - response = response-authenticate / - response-logout / - response-getscript / - response-setactive / - response-listscripts / - response-deletescript / - response-putscript / - response-capability / - response-havespace / - response-starttls - - response-authenticate = *(string CRLF) (response-oknobye) - - response-capability = *(single-capability) response-oknobye - - single-capability = capability-name [SP string] CRLF - - capability-name = string - <<Note that literals are allowed!>> - - initial-capabilities = DQUOTE "IMPLEMENTATION" DQUOTE SP string / - DQUOTE "SASL" DQUOTE SP sasl-mechs / - DQUOTE "SIEVE" DQUOTE SP sieve-extensions / - DQUOTE "STARTTLS" DQUOTE - ;; Each capability conforms to - ;; the syntax for single-capability. - ;; Also note that the capability name - ;; can be returned as either literal - ;; or quoted, even though only "quoted" - ;; string is shown above. - - sasl-mechs = string - ; space separated list of SASL mechanisms, - ; can be empty - - sieve-extensions = string - ; space separated list of supported SIEVE extensions, - ; can be empty - - response-deletescript = response-oknobye - - response-getscript = [string CRLF] response-oknobye - <<Need to rewrite ABNF to make it clear that - script content is required with OK response - and must not be sent with the NO (and - possibly BYE) response.>> - - response-havespace = response-oknobye - - response-listscripts = *(sieve-name [SP "ACTIVE"] CRLF) - response-oknobye - ;; ACTIVE may only occur with one sieve-name - - response-logout = response-oknobye - - response-oknobye = ("OK" / "NO" / "BYE") [SP "(" resp-code ")"] - [SP string] CRLF - - response-putscript = response-oknobye - - response-setactive = response-oknobye - - response-starttls = response-oknobye - - sieve-name = string - ;; MUST NOT contain NUL, CR or LF - - string = quoted / literal - - -5. Security Considerations - - The AUTHENTICATE command uses SASL [SASL] to provide authentication - and authorization services. - Integrity and privacy services can be provided by [SASL] and/or - [TLS]. When a SASL mechanism is used the security considerations for - that mechanism apply. - - This protocol's 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 SASL (via the AUTHENTICATE - command) and/or [TLS] (via the STARTTLS 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. - - -6. IANA Considerations - - IANA is requested to reserve TCP port number 2000 for use with - the Manage Sieve protocol described in this document. - - IANA is requested to create a new registry for Manage Sieve - capabilities. The registration template for Manage Sieve - capabilities is specified in the next section. - Manage Sieve protocol capabilities MUST be specified in a standards - track or IESG approved experimental RFC. - - <<Add a new registry for response codes, as per ABNF comments.>> - - <<Reference to SIEVE URL registration.>> - - -6.1. Manage Sieve Capability Registration Template - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: - - Description: - - Relevant publications: - - Person & email address to contact for further information: - - Author/Change controller: - - -6.2. Registration of Initial Manage Sieve capabilities. - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: IMPLEMENTATION - - Description: Its value contains name of server - implementation and its version. - - Relevant publications: this RFC, section 1.8. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: SASL - - Description: Its value contains a space separated - list of SASL mechanisms supported by server. - - Relevant publications: this RFC, sections 1.8 and 2.1. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: SIEVE - - Description: Its value contains a space separated - list of supported SIEVE extensions - - Relevant publications: this RFC, section 1.8. - <<Also [SIEVE]>> - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: STARTTLS - - Description: This capability is returned if server - supports TLS (STARTTLS command). - - Relevant publications: this RFC, sections 1.8 and 2.2. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - - To: iana@iana.org - Subject: Manage Sieve Capability Registration - - Please register the following Manage Sieve Capability: - - Capability name: NOTIFY - - Description: This capability is returned if server - supports 'enotify' Sieve extension. - - Relevant publications: this RFC, section 1.8. - - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - -7. References - -7.1. Normative References - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [ACAP] Newman, Myers, "ACAP -- Application Configuration Access - Protocol", RFC 2244, Innosoft, Netscape, November 1997. - - [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication and - Security Layer (SASL)", RFC 4422, June 2006. - - [SASLprep] Zeilega, K., "SASLprep: Stringprep profile for User Names - and Passwords", RFC 4013, February 2005. - - [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, December 2002. - - [SASL-ANON] K. Zeilenga (Ed.), "Anonymous Simple Authentication and - Security Layer (SASL) Mechanism", RFC 4505, June 2006. - - [SIEVE] Guenther, P. and Showalter, T., "Sieve: An Email Filtering - Language", work in Progress, draft-ietf-sieve-3028bis-XX.txt - - [TLS] Dierks, T. and E. Rescorla, "The Transport Layer Security - (TLS) Protocol Version 1.1", RFC 4346, April 2006. - - [URI-GEN] Berners-Lee, T., Fielding, R. and L. Masinter, - "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, - January 2005. - - [BASE64] - Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. - - [NOTIFY] Melnikov, A. (Ed.), Leiba, B. (Ed.), Segmuller, W. and - T. Martin, "Sieve Extension: Notifications", work in progress, - draft-ietf-sieve-notify-XX.txt. - - -7.2. Informative References - - [IMAP4rev1] Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 3501, March 2003. - - [PLAIN] K. Zeilenga, "The PLAIN Simple Authentication and Security - Layer (SASL) Mechanism", RFC 4616, August 2006. - - [DIGEST-MD5] Melnikov, A. (Ed.), "Using Digest Authentication as - a SASL Mechanism", work in progress, - draft-ietf-sasl-rfc2831bis-XX.txt. - - -8. Author's Address - - Tim Martin - BeThereBeSquare Inc. - 672 Haight st. - San Francisco, CA 94117 - Phone: (510) 260-4175 - EMail: timmartin@alumni.cmu.edu - - Alexey Melnikov - Isode Ltd. - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex, TW12 2BX, GB - Email: alexey.melnikov@isode.com - - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed - to pertain to the implementation or use of the technology described - in this document or the extent to which any license under such - rights might or might not be available; nor does it represent that - it has made any independent effort to identify any such rights. - Information on the procedures with respect to rights in RFC - documents can be found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use - of such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository - at http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - - -18. Full Copyright Statement - - Copyright (C) The IETF Trust (2007). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on - an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE - REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE - IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM 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. - - -Appendix A. Acknowledgments - - Thanks to Simon Josefsson, Larry Greenfield, Allen Johnson, Chris - Newman, Lyndon Nerenberg, Tim Showalter, Sarah Robeson, Walter - Wong, Barry Leiba, Arnt Gulbrandsen, Stephan Bosch for help with - this document. diff --git a/docs/[rfc5804] Managing Sieve/rfc5804.txt b/docs/[rfc5804] Managing Sieve/rfc5804.txt deleted file mode 100755 index d6deaa89..00000000 --- a/docs/[rfc5804] Managing Sieve/rfc5804.txt +++ /dev/null @@ -1,2747 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) A. Melnikov, Ed. -Request for Comments: 5804 Isode Limited -Category: Standards Track T. Martin -ISSN: 2070-1721 BeThereBeSquare, Inc. - July 2010 - - - A Protocol for Remotely Managing Sieve Scripts - -Abstract - - Sieve scripts allow users to filter incoming email. Message stores - are commonly sealed servers so users cannot log into them, yet users - must be able to update their scripts on them. This document - describes a protocol "ManageSieve" for securely managing Sieve - scripts on a remote server. This protocol allows a user to have - multiple scripts, and also alerts a user to syntactically flawed - scripts. - -Status of This Memo - - This is an Internet Standards Track document. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Further information on - Internet Standards is available in Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc5804. - -Copyright Notice - - Copyright (c) 2010 IETF Trust and the persons identified as the - document authors. All rights reserved. - - This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (http://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with respect - to this document. Code Components extracted from this document must - include Simplified BSD License text as described in Section 4.e of - the Trust Legal Provisions and are provided without warranty as - described in the Simplified BSD License. - - - - -Melnikov & Martin Standards Track [Page 1] - -RFC 5804 ManageSieve July 2010 - - -Table of Contents - - 1. Introduction ....................................................3 - 1.1. Commands and Responses .....................................3 - 1.2. Syntax .....................................................3 - 1.3. Response Codes .............................................3 - 1.4. Active Script ..............................................6 - 1.5. Quotas .....................................................6 - 1.6. Script Names ...............................................6 - 1.7. Capabilities ...............................................7 - 1.8. Transport ..................................................9 - 1.9. Conventions Used in This Document .........................10 - 2. Commands .......................................................10 - 2.1. AUTHENTICATE Command ......................................11 - 2.1.1. Use of SASL PLAIN Mechanism over TLS ...............16 - 2.2. STARTTLS Command ..........................................16 - 2.2.1. Server Identity Check ..............................17 - 2.3. LOGOUT Command ............................................20 - 2.4. CAPABILITY Command ........................................20 - 2.5. HAVESPACE Command .........................................20 - 2.6. PUTSCRIPT Command .........................................21 - 2.7. LISTSCRIPTS Command .......................................23 - 2.8. SETACTIVE Command .........................................24 - 2.9. GETSCRIPT Command .........................................25 - 2.10. DELETESCRIPT Command .....................................25 - 2.11. RENAMESCRIPT Command .....................................26 - 2.12. CHECKSCRIPT Command ......................................27 - 2.13. NOOP Command .............................................28 - 2.14. Recommended Extensions ...................................28 - 2.14.1. UNAUTHENTICATE Command ............................28 - 3. Sieve URL Scheme ...............................................29 - 4. Formal Syntax ..................................................31 - 5. Security Considerations ........................................37 - 6. IANA Considerations ............................................38 - 6.1. ManageSieve Capability Registration Template ..............39 - 6.2. Registration of Initial ManageSieve Capabilities ..........39 - 6.3. ManageSieve Response Code Registration Template ...........41 - 6.4. Registration of Initial ManageSieve Response Codes ........41 - 7. Internationalization Considerations ............................46 - 8. Acknowledgements ...............................................46 - 9. References .....................................................47 - 9.1. Normative References ......................................47 - 9.2. Informative References ....................................48 - - - - - - - - -Melnikov & Martin Standards Track [Page 2] - -RFC 5804 ManageSieve July 2010 - - -1. Introduction - -1.1. Commands and Responses - - A ManageSieve connection consists of the establishment of a client/ - server network 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 - response. - - All interactions transmitted by client and server are in the form of - lines, that is, strings that end with a CRLF. The protocol receiver - of a ManageSieve client or server is either reading a line or reading - a sequence of octets with a known count followed by a line. - -1.2. Syntax - - ManageSieve is a line-oriented protocol much like [IMAP] or [ACAP], - which runs over TCP. There are three data types: atoms, numbers and - strings. Strings may be quoted or literal. See [ACAP] for detailed - descriptions of these types. - - Each command consists of an atom (the command name) followed by zero - or more strings and numbers terminated by CRLF. - - All client queries are replied to with either an OK, NO, or BYE - response. Each response may be followed by a response code (see - Section 1.3) and by a string consisting of human-readable text in the - local language (as returned by the LANGUAGE capability; see - Section 1.7), encoded in UTF-8 [UTF-8]. The contents of the string - SHOULD be shown to the user ,and implementations MUST NOT attempt to - parse the message for meaning. - - The BYE response SHOULD be used if the server wishes to close the - connection. A server may wish to do this because the client was idle - for too long or there were too many failed authentication attempts. - This response can be issued at any time and should be immediately - followed by a server hang-up of the connection. If a server has an - inactivity timeout resulting in client autologout, it MUST be no less - than 30 minutes after successful authentication. The inactivity - timeout MAY be less before authentication. - -1.3. Response Codes - - An OK, NO, 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. - - - -Melnikov & Martin Standards Track [Page 3] - -RFC 5804 ManageSieve July 2010 - - - 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 (Solidus, %x2F) hierarchy with each level of - hierarchy representing increasing detail about the error. Response - codes MUST NOT start with the Solidus character. Clients MUST - tolerate additional hierarchical response code detail that they don't - understand. For example, if the client supports the "QUOTA" response - code, but doesn't understand the "QUOTA/MAXSCRIPTS" response code, it - should treat "QUOTA/MAXSCRIPTS" as "QUOTA". - - Client implementations MUST tolerate (ignore) response codes that - they do not recognize. - - The currently defined response codes are the following: - - AUTH-TOO-WEAK - - This response code is returned in the NO or BYE response 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 in the NO or BYE response 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. - - QUOTA - - If this response code is returned in the NO/BYE response, it means - that the command would have placed the user above the site-defined - quota constraints. If this response code is returned in the OK - response, it can mean that the user's storage is near its quota, or - it can mean that the account exceeded its quota but that the - condition is being allowed by the server (the server supports - so-called soft quotas). The QUOTA response code has two more - detailed variants: "QUOTA/MAXSCRIPTS" (the maximum number of per-user - scripts) and "QUOTA/MAXSIZE" (the maximum script size). - - REFERRAL - - This response code may be returned with a BYE result from any - command, and includes a mandatory parameter that indicates what - server to access to manage this user's Sieve scripts. The server - will be specified by a Sieve URL (see Section 3). The scriptname - - - -Melnikov & Martin Standards Track [Page 4] - -RFC 5804 ManageSieve July 2010 - - - portion of the URL MUST NOT be specified. The client should - authenticate to the specified server and use it for all further - commands in the current session. - - SASL - - This response code can occur in the OK response to a successful - AUTHENTICATE command and includes the optional final server response - data from the server as specified by [SASL]. - - TRANSITION-NEEDED - - This response code occurs in a NO response of 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 is typically done - by establishing a secure channel using TLS, verifying server identity - as specified in Section 2.2.1, and finally authenticating once using - the [PLAIN] authentication mechanism. The selected mechanism SHOULD - then work for authentications in subsequent sessions. - - This condition 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. This - response code only makes sense when returned in a NO/BYE response. - - ACTIVE - - A command failed because it is not allowed on the active script, for - example, DELETESCRIPT on the active script. This response code only - makes sense when returned in a NO/BYE response. - - NONEXISTENT - - A command failed because the referenced script name doesn't exist. - This response code only makes sense when returned in a NO/BYE - response. - - ALREADYEXISTS - - A command failed because the referenced script name already exists. - This response code only makes sense when returned in a NO/BYE - response. - - - -Melnikov & Martin Standards Track [Page 5] - -RFC 5804 ManageSieve July 2010 - - - TAG - - This response code name is followed by a string specified in the - command. See Section 2.13 for a possible use case. - - WARNINGS - - This response code MAY be returned by the server in the OK response - (but it might be returned with the NO/BYE response as well) and - signals the client that even though the script is syntactically - valid, it might contain errors not intended by the script writer. - This response code is typically returned in response to PUTSCRIPT - and/or CHECKSCRIPT commands. A client seeing such response code - SHOULD present the returned warning text to the user. - -1.4. Active Script - - A user may have multiple Sieve scripts on the server, yet only one - script may be used for filtering of incoming messages. This is the - active script. Users may have zero or one active script and MUST use - the SETACTIVE command described below for changing the active script - or disabling Sieve processing. For example, users may have an - everyday script they normally use and a special script they use when - they go on vacation. Users can change which script is being used - without having to download and upload a script stored somewhere else. - -1.5. Quotas - - Servers SHOULD impose quotas to prevent malicious users from - overflowing available storage. If a command would place a user over - a quota setting, servers that impose such quotas MUST reply with a NO - response containing the QUOTA response code. Client implementations - MUST be able to handle commands failing because of quota - restrictions. - -1.6. Script Names - - A Sieve script name is a sequence of Unicode characters encoded in - UTF-8 [UTF-8]. A script name MUST comply with Net-Unicode Definition - (Section 2 of [NET-UNICODE]), with the additional restriction of - prohibiting the following Unicode characters: - - o 0000-001F; [CONTROL CHARACTERS] - - o 007F; DELETE - - o 0080-009F; [CONTROL CHARACTERS] - - - - -Melnikov & Martin Standards Track [Page 6] - -RFC 5804 ManageSieve July 2010 - - - o 2028; LINE SEPARATOR - - o 2029; PARAGRAPH SEPARATOR - - Sieve script names MUST be at least one octet (and hence Unicode - character) long. Zero octets script name has a special meaning (see - Section 2.8). Servers MUST allow names of up to 128 Unicode - characters in length (which can take up to 512 bytes when encoded in - UTF-8, not counting the terminating NUL), and MAY allow longer names. - A server that receives a script name longer than its internal limit - MUST reject the corresponding operation, in particular it MUST NOT - truncate the script name. - -1.7. Capabilities - - Server capabilities are sent automatically by the server upon a - client connection, or after successful STARTTLS and AUTHENTICATE - (which establishes a Simple Authentication and Security Layer (SASL)) - commands. Capabilities may change immediately after a successfully - completed STARTTLS command, and/or immediately after a successfully - completed AUTHENTICATE command, and/or after a successfully completed - UNAUTHENTICATE command (see Section 2.14.1). Capabilities MUST - remain static at all other times. - - Clients MAY request the capabilities at a later time by issuing the - CAPABILITY command described later. The capabilities consist of a - series of lines each with one or two strings. The first string is - the name of the capability, which is case-insensitive. The second - optional string is the value associated with that capability. Order - of capabilities is arbitrary, but each capability name can appear at - most once. - - The following capabilities are defined in this document: - - IMPLEMENTATION - Name of implementation and version. This capability - MUST always be returned by the server. - - SASL - List of SASL mechanisms supported by the server, each - separated by a space. This list can be empty if and only if STARTTLS - is also advertised. This means that the client must negotiate TLS - encryption with STARTTLS first, at which point the SASL capability - will list a non-empty list of SASL mechanisms. - - SIEVE - List of space-separated Sieve extensions (as listed in Sieve - "require" action [SIEVE]) supported by the Sieve engine. This - capability MUST always be returned by the server. - - - - - -Melnikov & Martin Standards Track [Page 7] - -RFC 5804 ManageSieve July 2010 - - - STARTTLS - If TLS [TLS] is supported by this implementation. Before - advertising this capability a server MUST verify to the best of its - ability that TLS can be successfully negotiated by a client with - common cipher suites. Specifically, a server should verify that a - server certificate has been installed and that the TLS subsystem has - successfully initialized. This capability SHOULD NOT be advertised - once STARTTLS or AUTHENTICATE command completes successfully. Client - and server implementations MUST implement the STARTTLS extension. - - MAXREDIRECTS - Specifies the limit on the number of Sieve "redirect" - actions a script can perform during a single evaluation. Note that - this is different from the total number of "redirect" actions a - script can contain. The value is a non-negative number represented - as a ManageSieve string. - - NOTIFY - A space-separated list of URI schema parts for supported - notification methods. This capability MUST be specified if the Sieve - implementation supports the "enotify" extension [NOTIFY]. - - LANGUAGE - The language (<Language-Tag> from [RFC5646]) currently - used for human-readable error messages. If this capability is not - returned, the "i-default" [RFC2277] language is assumed. Note that - the current language MAY be per-user configurable (i.e., it MAY - change after authentication). - - OWNER - The canonical name of the logged-in user (SASL "authorization - identity") encoded in UTF-8. This capability MUST NOT be returned in - unauthenticated state and SHOULD be returned once the AUTHENTICATE - command succeeds. - - VERSION - This capability MUST be returned by servers compliant with - this document or its successor. For servers compliant with this - document, the capability value is the string "1.0". Lack of this - capability means that the server predates this specification and thus - doesn't support the following commands: RENAMESCRIPT, CHECKSCRIPT, - and NOOP. - - Section 2.14 defines some additional ManageSieve extensions and their - respective capabilities. - - A server implementation MUST return SIEVE, IMPLEMENTATION, and - VERSION capabilities. - - A client implementation MUST ignore any listed capabilities that it - does not understand. - - - - - - -Melnikov & Martin Standards Track [Page 8] - -RFC 5804 ManageSieve July 2010 - - - Example: - - S: "IMPlemENTATION" "Example1 ManageSieved v001" - S: "SASl" "DIGEST-MD5 GSSAPI" - S: "SIeVE" "fileinto vacation" - S: "StaRTTLS" - S: "NOTIFY" "xmpp mailto" - S: "MAXREdIRECTS" "5" - S: "VERSION" "1.0" - S: OK - - After successful authentication, this might look like this: - - Example: - - S: "IMPlemENTATION" "Example1 ManageSieved v001" - S: "SASl" "DIGEST-MD5 GSSAPI" - S: "SIeVE" "fileinto vacation" - S: "NOTIFY" "xmpp mailto" - S: "OWNER" "alexey@example.com" - S: "MAXREdIRECTS" "5" - S: "VERSION" "1.0" - S: OK - -1.8. Transport - - The ManageSieve protocol assumes a reliable data stream such as that - provided by TCP. When TCP is used, a ManageSieve server typically - listens on port 4190. - - Before opening the TCP connection, the ManageSieve client first MUST - resolve the Domain Name System (DNS) hostname associated with the - receiving entity and determine the appropriate TCP port for - communication with the receiving entity. The process is as follows: - - 1. Attempt to resolve the hostname using a [DNS-SRV] Service of - "sieve" and a Proto of "tcp" for the target domain (e.g., - "example.net"), resulting in resource records such as - "_sieve._tcp.example.net.". The result of the SRV lookup, if - successful, will be one or more combinations of a port and - hostname; the ManageSieve client MUST resolve the returned - hostnames to IPv4/IPv6 addresses according to returned SRV record - weight. IP addresses from the first successfully resolved - hostname (with the corresponding port number returned by SRV - lookup) are used to connect to the server. If connection using - one of the IP addresses fails, the next resolved IP address is - - - - - -Melnikov & Martin Standards Track [Page 9] - -RFC 5804 ManageSieve July 2010 - - - used to connect. If connection to all resolved IP addresses - fails, then the resolution/connect is repeated for the next - hostname returned by SRV lookup. - - 2. If the SRV lookup fails, the fallback SHOULD be a normal IPv4 or - IPv6 address record resolution to determine the IP address, where - the port used is the default ManageSieve port of 4190. - -1.9. Conventions Used in This Document - - 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 [KEYWORDS]. - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. Line breaks that do not start a new "C:" or - "S:" exist for editorial reasons. - - Examples of authentication in this document are using DIGEST-MD5 - [DIGEST-MD5] and GSSAPI [GSSAPI] SASL mechanisms. - -2. Commands - - This section and its subsections describe valid ManageSieve commands. - Upon initial connection to the server, the client's session is in - non-authenticated state. Prior to successful authentication, only - the AUTHENTICATE, CAPABILITY, STARTTLS, LOGOUT, and NOOP (see Section - 2.13) commands are valid. ManageSieve extensions MAY define other - commands that are valid in non-authenticated state. Servers MUST - reject all other commands with a NO response. Clients may pipeline - commands (send more than one command at a time without waiting for - completion of the first command). However, a group of commands sent - together MUST NOT have an AUTHENTICATE (*), a STARTTLS, or a - HAVESPACE command anywhere but the last command in the list. - - (*) - The only exception to this rule is when the AUTHENTICATE - command contains an initial response for a SASL mechanism that allows - clients to send data first, the mechanism is known to complete in one - round trip, and the mechanism doesn't negotiate a SASL security - layer. Two examples of such SASL mechanisms are PLAIN [PLAIN] and - EXTERNAL [SASL]. - - - - - - - - - - -Melnikov & Martin Standards Track [Page 10] - -RFC 5804 ManageSieve July 2010 - - -2.1. AUTHENTICATE Command - - Arguments: String - mechanism - String - initial data (optional) - - 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 identify and authenticate 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 the NO response. - - The authentication protocol exchange consists of a series of server - challenges and client responses that are specific to the selected - authentication mechanism. A server challenge consists of a string - (quoted or literal) followed by a CRLF. The contents of the string - is a base-64 encoding [BASE64] of the SASL data. A client response - consists of a string (quoted or literal) with the base-64 encoding of - the SASL data followed by a CRLF. If the client wishes to cancel the - authentication exchange, it issues a string containing a single "*". - If the server receives such a response, it MUST reject the - AUTHENTICATE command by sending a NO reply. - - Note that an empty challenge/response is sent as an empty string. If - the mechanism dictates that the final response is sent by the server, - this data MAY be placed within the data portion of the SASL response - code to save a round trip. - - 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 MUST reject the AUTHENTICATE command by - sending the NO response. - - The service name specified by this protocol's profile of SASL is - "sieve". - - Reauthentication is not supported by ManageSieve protocol's profile - of SASL. That is, after a successfully completed AUTHENTICATE - command, no more AUTHENTICATE commands may be issued in the same - session. After a successful AUTHENTICATE command completes, a server - MUST reject any further AUTHENTICATE commands with a NO reply. - - - -Melnikov & Martin Standards Track [Page 11] - -RFC 5804 ManageSieve July 2010 - - - However, note that a server may implement the UNAUTHENTICATE - extension described in Section 2.14.1. - - If a security layer is negotiated through the SASL authentication - exchange, it takes effect immediately following the CRLF that - concludes the successful authentication exchange for the client, and - the CRLF of the OK response for the server. - - When a security layer takes effect, the ManageSieve protocol is reset - to the initial state (the state in ManageSieve after a client has - connected to the server). The server MUST discard any knowledge - obtained from the client that was not obtained from the SASL (or TLS) - negotiation itself. Likewise, the client MUST discard any knowledge - obtained from the server, such as the list of ManageSieve extensions, - that was not obtained from the SASL (and/or TLS) negotiation itself. - (Note that a client MAY compare the advertised SASL mechanisms before - and after authentication in order to detect an active down- - negotiation attack. See below.) - - Once a SASL security layer is established, the server MUST re-issue - the capability results, followed by an OK response. This is - necessary to protect against man-in-the-middle attacks that alter the - capabilities list prior to SASL negotiation. The capability results - MUST include all SASL mechanisms the server was capable of - negotiating with that client. This is done in order to allow the - client to detect an active down-negotiation attack. If a user- - oriented client detects such a down-negotiation attack, it SHOULD - either notify the user (it MAY give the user the opportunity to - continue with the ManageSieve session in this case) or close the - transport connection and indicate that a down-negotiation attack - might be in progress. If an automated client detects a down- - negotiation attack, it SHOULD return or log an error indicating that - a possible attack might be in progress and/or SHOULD close the - transport connection. - - When both [TLS] and SASL security layers are in effect, the TLS - encoding MUST be applied (when sending data) after the SASL encoding. - - Server implementations SHOULD support SASL proxy authentication so - that an administrator can administer a user's scripts. Proxy - authentication is when a user authenticates as herself/himself but - requests the server to act (authorize) as another user. - - The authorization identity generated by this [SASL] exchange is a - "simple username" (in the sense defined in [SASLprep]), and both - client and server MUST use the [SASLprep] profile of the [StringPrep] - algorithm to prepare these names for transmission or comparison. If - preparation of the authorization identity fails or results in an - - - -Melnikov & Martin Standards Track [Page 12] - -RFC 5804 ManageSieve July 2010 - - - empty string (unless it was transmitted as the empty string), the - server MUST fail the authentication. - - 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. - - Note that a failed (NO) response to the AUTHENTICATE command may - contain one of the following response codes: AUTH-TOO-WEAK, ENCRYPT- - NEEDED, or TRANSITION-NEEDED. See Section 1.3 for detailed - description of the relevant conditions. - - To ensure interoperability, both client and server implementations of - the ManageSieve protocol MUST implement the SCRAM-SHA-1 [SCRAM] SASL - mechanism, as well as [PLAIN] over [TLS]. - - Note: use of PLAIN over TLS reflects current use of PLAIN over TLS in - other email-related protocols; however, a longer-term goal is to - migrate email-related protocols from using PLAIN over TLS to SCRAM- - SHA-1 mechanism. - - Examples (Note that long lines are folded for readability and are not - part of protocol exchange): - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: "VERSION" "1.0" - S: OK - C: Authenticate "DIGEST-MD5" - S: "cmVhbG09ImVsd29vZC5pbm5vc29mdC5leGFtcGxlLmNvbSIsbm9uY2U9Ik - 9BNk1HOXRFUUdtMmhoIixxb3A9ImF1dGgiLGFsZ29yaXRobT1tZDUtc2Vz - cyxjaGFyc2V0PXV0Zi04" - C: "Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuZXhhbXBsZS5jb20iLG5vbmNlPSJPQTZNRzl0RVFHbTJo - aCIsbmM9MDAwMDAwMDEsY25vbmNlPSJPQTZNSFhoNlZxVHJSayIsZGlnZX - N0LXVyaT0ic2lldmUvZWx3b29kLmlubm9zb2Z0LmV4YW1wbGUuY29tIixy - ZXNwb25zZT1kMzg4ZGFkOTBkNGJiZDc2MGExNTIzMjFmMjE0M2FmNyxxb3 - A9YXV0aA==" - S: OK (SASL "cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZ - mZmZA==") - - - - - - - - -Melnikov & Martin Standards Track [Page 13] - -RFC 5804 ManageSieve July 2010 - - - A slightly different variant of the same authentication exchange is: - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "VERSION" "1.0" - S: "STARTTLS" - S: OK - C: Authenticate "DIGEST-MD5" - S: {136} - S: cmVhbG09ImVsd29vZC5pbm5vc29mdC5leGFtcGxlLmNvbSIsbm9uY2U9Ik - 9BNk1HOXRFUUdtMmhoIixxb3A9ImF1dGgiLGFsZ29yaXRobT1tZDUtc2Vz - cyxjaGFyc2V0PXV0Zi04 - C: {300+} - C: Y2hhcnNldD11dGYtOCx1c2VybmFtZT0iY2hyaXMiLHJlYWxtPSJlbHdvb2 - QuaW5ub3NvZnQuZXhhbXBsZS5jb20iLG5vbmNlPSJPQTZNRzl0RVFHbTJo - aCIsbmM9MDAwMDAwMDEsY25vbmNlPSJPQTZNSFhoNlZxVHJSayIsZGlnZX - N0LXVyaT0ic2lldmUvZWx3b29kLmlubm9zb2Z0LmV4YW1wbGUuY29tIixy - ZXNwb25zZT1kMzg4ZGFkOTBkNGJiZDc2MGExNTIzMjFmMjE0M2FmNyxxb3 - A9YXV0aA== - S: {56} - S: cnNwYXV0aD1lYTQwZjYwMzM1YzQyN2I1NTI3Yjg0ZGJhYmNkZmZmZA== - C: "" - S: OK - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Martin Standards Track [Page 14] - -RFC 5804 ManageSieve July 2010 - - - Another example demonstrating use of SASL PLAIN mechanism under TLS - follows. This example also demonstrate use of SASL "initial - response" (the second parameter to the Authenticate command): - - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "VERSION" "1.0" - S: "SASL" "" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - C: STARTTLS - S: OK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "VERSION" "1.0" - S: "SASL" "PLAIN" - S: "SIEVE" "fileinto vacation" - S: OK - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xu" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xz" - S: NO - C: Authenticate "PLAIN" "QJIrweAPyo6Q1T9xy" - S: BYE "Too many failed authentication attempts" - <Server closes connection> - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Martin Standards Track [Page 15] - -RFC 5804 ManageSieve July 2010 - - - The following example demonstrates use of SASL "initial response". - It also demonstrates that an empty response can be sent as a literal - and that negotiating a SASL security layer results in the server - re-issuing server capabilities: - - C: AUTHENTICATE "GSSAPI" {1488+} - C: YIIE[...1480 octets here ...]dA== - S: {208} - S: YIGZBgkqhkiG9xIBAgICAG+BiTCBhqADAgEFoQMCAQ+iejB4oAMCARKic - [...114 octets here ...] - /yzpAy9p+Y0LanLskOTvMc0MnjgAa4YEr3eJ6 - C: {0+} - C: - S: {44} - S: BQQF/wAMAAwAAAAAYRGFAo6W0vIHti8i1UXODgEAEAA= - C: {44+} - C: BQQE/wAMAAwAAAAAIsT1iv9UkZApw471iXt6cwEAAAE= - S: OK - <Further commands/responses are under SASL security layer> - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "VERSION" "1.0" - S: "SASL" "PLAIN DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "LANGUAGE" "ru" - S: "MAXREDIRECTS" "3" - S: ok - -2.1.1. Use of SASL PLAIN Mechanism over TLS - - This section is normative for ManageSieve client implementations that - support SASL [PLAIN] over [TLS]. - - If a ManageSieve client is willing to use SASL PLAIN over TLS to - authenticate to the ManageSieve server, the client MUST verify the - server identity (see Section 2.2.1). If the server identity can't be - verified (e.g., the server has not provided any certificate, or if - the certificate verification fails), the client MUST NOT attempt to - authenticate using the SASL PLAIN mechanism. - -2.2. STARTTLS Command - - Support for STARTTLS command in servers is optional. Its - availability is advertised with "STARTTLS" capability as described in - Section 1.7. - - The STARTTLS command requests commencement of a TLS [TLS] - negotiation. The negotiation begins immediately after the CRLF in - the OK response. After a client issues a STARTTLS command, it MUST - - - -Melnikov & Martin Standards Track [Page 16] - -RFC 5804 ManageSieve July 2010 - - - NOT issue further commands until a server response is seen and the - TLS negotiation is complete. - - The STARTTLS command is only valid in non-authenticated state. The - server remains in non-authenticated state, even if client credentials - are supplied during the TLS negotiation. The SASL [SASL] EXTERNAL - mechanism MAY be used to authenticate once TLS client credentials are - successfully exchanged, but servers supporting the STARTTLS command - are not required to support the EXTERNAL mechanism. - - After the TLS layer is established, the server MUST re-issue the - capability results, followed by an OK response. This is necessary to - protect against man-in-the-middle attacks that alter the capabilities - list prior to STARTTLS. This capability result MUST NOT include the - STARTTLS capability. - - The client MUST discard cached capability information and replace it - with the new information. The server MAY advertise different - capabilities after STARTTLS. - - Example: - - C: StartTls - S: oK - <TLS negotiation, further commands are under TLS layer> - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "SASL" "PLAIN DIGEST-MD5 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "VERSION" "1.0" - S: "LANGUAGE" "fr" - S: ok - -2.2.1. Server Identity Check - - During the TLS negotiation, the ManageSieve client MUST check its - understanding of the server hostname/IP address against the server's - identity as presented in the server Certificate message, in order to - prevent man-in-the-middle attacks. In this section, the client's - understanding of the server's identity is called the "reference - identity". - - Checking is performed according to the following rules: - - o If the reference identity is a hostname: - - 1. If a subjectAltName extension of the SRVName [X509-SRV], - dNSName [X509] (in that order of preference) type is present - in the server's certificate, then it SHOULD be used as the - - - -Melnikov & Martin Standards Track [Page 17] - -RFC 5804 ManageSieve July 2010 - - - source of the server's identity. Matching is performed as - described in Section 2.2.1.1, with the exception that no - wildcard matching is allowed for SRVName type. If the - certificate contains multiple names (e.g., more than one - dNSName field), then a match with any one of the fields is - considered acceptable. - - 2. The client MAY use other types of subjectAltName for - performing comparison. - - 3. The server's identity MAY also be verified by comparing the - reference identity to the Common Name (CN) [RFC4519] value in - the leaf Relative Distinguished Name (RDN) of the subjectName - field of the server's certificate. This comparison is - performed using the rules for comparison of DNS names in - Section 2.2.1.1, below. Although the use of the Common Name - value is existing practice, it is deprecated, and - Certification Authorities are encouraged to provide - subjectAltName values instead. Note that the TLS - implementation may represent DNs in certificates according to - X.500 or other conventions. For example, some X.500 - implementations order the RDNs in a DN using a left-to-right - (most significant to least significant) convention instead of - LDAP's right-to-left convention. - - o When the reference identity is an IP address, the iPAddress - subjectAltName SHOULD be used by the client for comparison. The - comparison is performed as described in Section 2.2.1.2. - - If the server identity check fails, user-oriented clients SHOULD - either notify the user (clients MAY give the user the opportunity to - continue with the ManageSieve session in this case) or close the - transport connection and indicate that the server's identity is - suspect. Automated clients SHOULD return or log an error indicating - that the server's identity is suspect and/or SHOULD close the - transport connection. Automated clients MAY provide a configuration - setting that disables this check, but MUST provide a setting that - enables it. - - Beyond the server identity check described in this section, clients - should be prepared to do further checking to ensure that the server - is authorized to provide the service it is requested to provide. The - client may need to make use of local policy information in making - this determination. - - - - - - - -Melnikov & Martin Standards Track [Page 18] - -RFC 5804 ManageSieve July 2010 - - -2.2.1.1. Comparison of DNS Names - - If the reference identity is an internationalized domain name, - conforming implementations MUST convert it to the ASCII Compatible - Encoding (ACE) format as specified in Section 4 of RFC 3490 [RFC3490] - before comparison with subjectAltName values of type dNSName. - Specifically, conforming implementations MUST perform the conversion - operation specified in Section 4 of [RFC3490] as follows: - - o in step 1, the domain name SHALL be considered a "stored string"; - - o in step 3, set the flag called "UseSTD3ASCIIRules"; - - o in step 4, process each label with the "ToASCII" operation; and - - o in step 5, change all label separators to U+002E (full stop). - - After performing the "to-ASCII" conversion, the DNS labels and names - MUST be compared for equality according to the rules specified in - Section 3 of [RFC3490]; i.e., once all label separators are replaced - with U+002E (dot) they are compared in the case-insensitive manner. - - The '*' (ASCII 42) wildcard character is allowed in subjectAltName - values of type dNSName, and then only as the left-most (least - significant) DNS label in that value. This wildcard matches any - left-most DNS label in the server name. That is, the subject - *.example.com matches the server names a.example.com and - b.example.com, but does not match example.com or a.b.example.com. - -2.2.1.2. Comparison of IP Addresses - - When the reference identity is an IP address, the identity MUST be - converted to the "network byte order" octet string representation - [RFC791][RFC2460]. For IP Version 4, as specified in RFC 791, the - octet string will contain exactly four octets. For IP Version 6, as - specified in RFC 2460, the octet string will contain exactly sixteen - octets. This octet string is then compared against subjectAltName - values of type iPAddress. A match occurs if the reference identity - octet string and value octet strings are identical. - -2.2.1.3. Comparison of Other subjectName Types - - Client implementations MAY support matching against subjectAltName - values of other types as described in other documents. - - - - - - - -Melnikov & Martin Standards Track [Page 19] - -RFC 5804 ManageSieve July 2010 - - -2.3. LOGOUT Command - - The client sends the LOGOUT command when it is finished with a - connection and wishes to terminate it. The server MUST reply with an - OK response. The server MUST ignore commands issued by the client - after the LOGOUT command. - - The client SHOULD wait for the OK response before closing the - connection. This avoids the TCP connection going into the TIME_WAIT - state on the server. In order to avoid going into the TIME_WAIT TCP - state, the server MAY wait for a short while for the client to close - the TCP connection first. Whether or not the server waits for the - client to close the connection, it MUST then close the connection - itself. - - Example: - - C: Logout - S: Ok - <connection is terminated> - -2.4. CAPABILITY Command - - The CAPABILITY command requests the server capabilities as described - earlier in this document. It has no parameters. - - Example: - - C: CAPABILITY - S: "IMPLEMENTATION" "Example1 ManageSieved v001" - S: "VERSION" "1.0" - S: "SASL" "PLAIN SCRAM-SHA-1 GSSAPI" - S: "SIEVE" "fileinto vacation" - S: "STARTTLS" - S: OK - -2.5. HAVESPACE Command - - Arguments: String - name - Number - script size - - The HAVESPACE command is used to query the server for available - space. Clients specify the name they wish to save the script as and - its size in octets. Both parameters can be used by the server to see - if the script with the specified name and size is within a user's - quota(s). For example, the server MAY use the script name to check - if a script would be replaced or a new one would be created. Servers - respond with a NO if storing a script with that name and size would - - - -Melnikov & Martin Standards Track [Page 20] - -RFC 5804 ManageSieve July 2010 - - - fail or OK otherwise. Clients SHOULD issue this command before - attempting to place a script on the server. - - Note that the OK response from the HAVESPACE command does not - constitute a guarantee of success as server disk space conditions - could change between the client issuing the HAVESPACE and the client - issuing the PUTSCRIPT commands. A QUOTA response code (see - Section 1.3) remains a possible (albeit unlikely) response to a - subsequent PUTSCRIPT with the same name and size. - - Example: - - C: HAVESPACE "myscript" 999999 - S: NO (QUOTA/MAXSIZE) "Quota exceeded" - - C: HAVESPACE "foobar" 435 - S: OK - -2.6. PUTSCRIPT Command - - Arguments: String - Script name - String - Script content - - The PUTSCRIPT command is used by the client to submit a Sieve script - to the server. - - If the script already exists, upon success the old script will be - overwritten. The old script MUST NOT be overwritten if PUTSCRIPT - fails in any way. A script of zero length SHOULD be disallowed. - - This command places the script on the server. It does not affect - whether the script is processed on incoming mail, unless it replaces - the script that is already active. The SETACTIVE command is used to - mark a script as active. - - When submitting large scripts, clients SHOULD use the HAVESPACE - command beforehand to query if the server is willing to accept a - script of that size. - - The server MUST check the submitted script for validity, which - includes checking that the script complies with the Sieve grammar - [SIEVE] and that all Sieve extensions mentioned in the script's - "require" statement(s) are supported by the Sieve interpreter. (Note - that if the Sieve interpreter supports the Sieve "ihave" extension - [I-HAVE], any unrecognized/unsupported extension mentioned in the - "ihave" test MUST NOT cause the validation failure.) Other checks - such as validating the supplied command arguments for each command - MAY be performed. Essentially, the performed validation SHOULD be - - - -Melnikov & Martin Standards Track [Page 21] - -RFC 5804 ManageSieve July 2010 - - - the same as performed when compiling the script for execution. - Implementations that use a binary representation to store compiled - scripts can extend the validation to a full compilation, in order to - avoid validating uploaded scripts multiple times. - - If the script fails the validation, the server MUST reply with a NO - response. Any script that fails the validity test MUST NOT be stored - on the server. The message given with a NO response MUST be human - readable and SHOULD contain a specific error message giving the line - number of the first error. Implementors should strive to produce - helpful error messages similar to those given by programming language - compilers. Client implementations should note that this may be a - multiline literal string with more than one error message separated - by CRLFs. The human-readable message is in the language returned in - the latest LANGUAGE capability (or in "i-default"; see Section 1.7), - encoded in UTF-8 [UTF-8]. - - An OK response MAY contain the WARNINGS response code. In such a - case the human-readable message that follows the OK response SHOULD - contain a specific warning message (or messages) giving the line - number(s) in the script that might contain errors not intended by the - script writer. The human-readable message is in the language - returned in the latest LANGUAGE capability (or in "i-default"; see - Section 1.7), encoded in UTF-8 [UTF-8]. A client seeing such a - response code SHOULD present the message to the user. - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov & Martin Standards Track [Page 22] - -RFC 5804 ManageSieve July 2010 - - - Examples: - - C: Putscript "foo" {31+} - C: #comment - C: InvalidSieveCommand - C: - S: NO "line 2: Syntax error" - - C: Putscript "mysievescript" {110+} - C: require ["fileinto"]; - C: - C: if envelope :contains "to" "tmartin+sent" { - C: fileinto "INBOX.sent"; - C: } - S: OK - - C: Putscript "myforwards" {190+} - C: redirect "111@example.net"; - C: - C: if size :under 10k { - C: redirect "mobile@cell.example.com"; - C: } - C: - C: if envelope :contains "to" "tmartin+lists" { - C: redirect "lists@groups.example.com"; - C: } - S: OK (WARNINGS) "line 8: server redirect action - limit is 2, this redirect might be ignored" - -2.7. LISTSCRIPTS Command - - This command lists the scripts the user has on the server. Upon - success, a list of CRLF-separated script names (each represented as a - quoted or literal string) is returned followed by an OK response. If - there exists an active script, the atom ACTIVE is appended to the - corresponding script name. The atom ACTIVE MUST NOT appear on more - than one response line. - - - - - - - - - - - - - - -Melnikov & Martin Standards Track [Page 23] - -RFC 5804 ManageSieve July 2010 - - - Example: - - C: Listscripts - S: "summer_script" - S: "vacation_script" - S: {13} - S: clever"script - S: "main_script" ACTIVE - S: OK - - C: listscripts - S: "summer_script" - S: "main_script" active - S: OK - -2.8. SETACTIVE Command - - Arguments: String - script name - - This command sets a script active. If the script name is the empty - string (i.e., ""), then any active script is disabled. Disabling an - active script when there is no script active is not an error and MUST - result in an OK reply. - - If the script does not exist on the server, then the server MUST - reply with a NO response. Such a reply SHOULD contain the - NONEXISTENT response code. - - Examples: - - C: Setactive "vacationscript" - S: Ok - - C: Setactive "" - S: Ok - - C: Setactive "baz" - S: No (NONEXISTENT) "There is no script by that name" - - C: Setactive "baz" - S: No (NONEXISTENT) {31} - S: There is no script by that name - - - - - - - - - -Melnikov & Martin Standards Track [Page 24] - -RFC 5804 ManageSieve July 2010 - - -2.9. GETSCRIPT Command - - Arguments: String - script name - - This command gets the contents of the specified script. If the - script does not exist, the server MUST reply with a NO response. - Such a reply SHOULD contain the NONEXISTENT response code. - - Upon success, a string with the contents of the script is returned - followed by an OK response. - - Example: - - C: Getscript "myscript" - S: {54} - S: #this is my wonderful script - S: reject "I reject all"; - S: - S: OK - -2.10. DELETESCRIPT Command - - Arguments: String - script name - - This command is used to delete a user's Sieve script. Servers MUST - reply with a NO response if the script does not exist. Such - responses SHOULD include the NONEXISTENT response code. - - The server MUST NOT allow the client to delete an active script, so - the server MUST reply with a NO response if attempted. Such a - response SHOULD contain the ACTIVE response code. If a client wishes - to delete an active script, it should use the SETACTIVE command to - disable the script first. - - Example: - - C: Deletescript "foo" - S: Ok - - C: Deletescript "baz" - S: No (ACTIVE) "You may not delete an active script" - - - - - - - - - - -Melnikov & Martin Standards Track [Page 25] - -RFC 5804 ManageSieve July 2010 - - -2.11. RENAMESCRIPT Command - - Arguments: String - Old Script name - String - New Script name - - This command is used to rename a user's Sieve script. Servers MUST - reply with a NO response if the old script does not exist (in which - case the NONEXISTENT response code SHOULD be included), or a script - with the new name already exists (in which case the ALREADYEXISTS - response code SHOULD be included). Renaming the active script is - allowed; the renamed script remains active. - - Example: - - C: Renamescript "foo" "bar" - S: Ok - - C: Renamescript "baz" "bar" - S: No "bar already exists" - - If the server doesn't support the RENAMESCRIPT command, the client - can emulate it by performing the following steps: - - 1. List available scripts with LISTSCRIPTS. If the script with the - new script name exists, then the client should ask the user - whether to abort the operation, to replace the script (by issuing - the DELETESCRIPT <newname> after that), or to choose a different - name. - - 2. Download the old script with GETSCRIPT <oldname>. - - 3. Upload the old script with the new name: PUTSCRIPT <newname>. - - 4. If the old script was active (as reported by LISTSCRIPTS in step - 1), then make the new script active: SETACTIVE <newname>. - - 5. Delete the old script: DELETESCRIPT <oldname>. - - Note that these steps don't describe how to handle various other - error conditions (for example, NO response containing QUOTA response - code in step 3). Error handling is left as an exercise for the - reader. - - - - - - - - - -Melnikov & Martin Standards Track [Page 26] - -RFC 5804 ManageSieve July 2010 - - -2.12. CHECKSCRIPT Command - - Arguments: String - Script content - - The CHECKSCRIPT command is used by the client to verify Sieve script - validity without storing the script on the server. - - The server MUST check the submitted script for syntactic validity, - which includes checking that all Sieve extensions mentioned in Sieve - script "require" statement(s) are supported by the Sieve interpreter. - (Note that if the Sieve interpreter supports the Sieve "ihave" - extension [I-HAVE], any unrecognized/unsupported extension mentioned - in the "ihave" test MUST NOT cause the syntactic validation failure.) - If the script fails this test, the server MUST reply with a NO - response. The message given with a NO response MUST be human - readable and SHOULD contain a specific error message giving the line - number of the first error. Implementors should strive to produce - helpful error messages similar to those given by programming language - compilers. Client implementations should note that this may be a - multiline literal string with more than one error message separated - by CRLFs. The human-readable message is in the language returned in - the latest LANGUAGE capability (or in "i-default"; see Section 1.7), - encoded in UTF-8 [UTF-8]. - - Examples: - - C: CheckScript {31+} - C: #comment - C: InvalidSieveCommand - C: - S: NO "line 2: Syntax error" - - A ManageSieve server supporting this command MUST NOT check if the - script will put the current user over its quota limit. - - An OK response MAY contain the WARNINGS response code. In such a - case, the human-readable message that follows the OK response SHOULD - contain a specific warning message (or messages) giving the line - number(s) in the script that might contain errors not intended by the - script writer. The human-readable message is in the language - returned in the latest LANGUAGE capability (or in "i-default"; see - Section 1.7), encoded in UTF-8 [UTF-8]. A client seeing such a - response code SHOULD present the message to the user. - - - - - - - - -Melnikov & Martin Standards Track [Page 27] - -RFC 5804 ManageSieve July 2010 - - -2.13. NOOP Command - - Arguments: String - tag to echo back (optional) - - The NOOP command does nothing, beyond returning a response to the - client. It may be used by clients for protocol re-synchronization or - to reset any inactivity auto-logout timer on the server. - - The response to the NOOP command is always OK, followed by the TAG - response code together with the supplied string. If no string was - supplied in the NOOP command, the TAG response code MUST NOT be - included. - - Examples: - - C: NOOP - S: OK "NOOP completed" - - C: NOOP "STARTTLS-SYNC-42" - S: OK (TAG {16} - S: STARTTLS-SYNC-42) "Done" - -2.14. Recommended Extensions - - The UNAUTHENTICATE extension (advertised as the "UNAUTHENTICATE" - capability with no parameters) defines a new UNAUTHENTICATE command, - which allows a client to return the server to non-authenticated - state. Support for this extension is RECOMMENDED. - -2.14.1. UNAUTHENTICATE Command - - The UNAUTHENTICATE command returns the server to the - non-authenticated state. It doesn't affect any previously - established TLS [TLS] or SASL (Section 2.1) security layer. - - The UNAUTHENTICATE command is only valid in authenticated state. If - issued in a wrong state, the server MUST reject it with a NO - response. - - The UNAUTHENTICATE command has no parameters. - - When issued in the authenticated state, the UNAUTHENTICATE command - MUST NOT fail (i.e., it must never return anything other than OK or - BYE). - - - - - - - -Melnikov & Martin Standards Track [Page 28] - -RFC 5804 ManageSieve July 2010 - - -3. Sieve URL Scheme - - URI scheme name: sieve - - Status: permanent - - URI scheme syntax: Described using ABNF [ABNF]. Some ABNF - productions not defined below are from [URI-GEN]. - - sieveurl = sieveurl-server / sieveurl-list-scripts / - sieveurl-script - - sieveurl-server = "sieve://" authority - - sieveurl-list-scripts = "sieve://" authority ["/"] - - sieveurl-script = "sieve://" authority "/" - [owner "/"] scriptname - - authority = <defined in [URI-GEN]> - - owner = *ochar - ;; %-encoded version of [SASL] authorization - ;; identity (script owner) or "userid". - ;; - ;; Empty owner is used to reference - ;; global scripts. - ;; - ;; Note that ASCII characters such as " ", ";", - ;; "&", "=", "/" and "?" must be %-encoded - ;; as per rule specified in [URI-GEN]. - - scriptname = 1*ochar - ;; %-encoded version of UTF-8 representation - ;; of the script name. - ;; Note that ASCII characters such as " ", ";", - ;; "&", "=", "/" and "?" must be %-encoded - ;; as per rule specified in [URI-GEN]. - - ochar = unreserved / pct-encoded / sub-delims-sh / - ":" / "@" - ;; Same as [URI-GEN] 'pchar', - ;; but without ";", "&" and "=". - - unreserved = <defined in [URI-GEN]> - - pct-encoded = <defined in [URI-GEN]> - - - - -Melnikov & Martin Standards Track [Page 29] - -RFC 5804 ManageSieve July 2010 - - - sub-delims-sh = "!" / "$" / "'" / "(" / ")" / - "*" / "+" / "," - ;; Same as [URI-GEN] sub-delims, - ;; but without ";", "&" and "=". - - URI scheme semantics: - - A Sieve URL identifies a Sieve server or a Sieve script on a Sieve - server. The latter form is associated with the application/sieve - MIME type defined in [SIEVE]. There is no MIME type associated - with the former form of Sieve URI. - - The server form is used in the REFERRAL response code (see Section - 1.3) in order to designate another server where the client should - perform its operations. - - The script form allows to retrieve (GETSCRIPT), update - (PUTSCRIPT), delete (DELETESCRIPT), or activate (SETACTIVE) the - named script; however, the most typical action would be to - retrieve the script. If the script name is empty (omitted), the - URI requests that the client lists available scripts using the - LISTSCRIPTS command. - - Encoding considerations: - - The script name and/or the owner, if present, is in UTF-8. Non-- - US-ASCII UTF-8 octets MUST be percent-encoded as described in - [URI-GEN]. US-ASCII characters such as " " (space), ";", "&", - "=", "/" and "?" MUST be %-encoded as described in [URI-GEN]. - Note that "&" and "?" are in this list in order to allow for - future extensions. - - Note that the empty owner (e.g., sieve://example.com//script) is - different from the missing owner (e.g., - sieve://example.com/script) and is reserved for referencing global - scripts. - - The user name (in the "authority" part), if present, is in UTF-8. - Non-US-ASCII UTF-8 octets MUST be percent-encoded as described in - [URI-GEN]. - - Applications/protocols that use this URI scheme name: - ManageSieve [RFC5804] clients and servers. Clients that can store - user preferences in protocols such as [LDAP] or [ACAP]. - - Interoperability considerations: None. - - - - - -Melnikov & Martin Standards Track [Page 30] - -RFC 5804 ManageSieve July 2010 - - - Security considerations: - The <scriptname> part of a ManageSieve URL might potentially disclose - some confidential information about the author of the script or, - depending on a ManageSieve implementation, about configuration of the - mail system. The latter might be used to prepare for a more complex - attack on the mail system. - - Clients resolving ManageSieve URLs that wish to achieve data - confidentiality and/or integrity SHOULD use the STARTTLS command (if - supported by the server) before starting authentication, or use a - SASL mechanism, such as GSSAPI, that provides a confidentiality - security layer. - - Contact: Alexey Melnikov <alexey.melnikov@isode.com> - - Author/Change controller: IESG. - - References: This document and RFC 5228 [SIEVE]. - -4. 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]. - "UTF8-2", "UTF8-3", and "UTF8-4" non-terminal are defined in [UTF-8]. - - Except as noted otherwise, all alphabetic characters are case- - insensitive. The use of upper- or lowercase characters to define - token strings is for editorial clarity only. Implementations MUST - accept these strings in a case-insensitive fashion. - - SAFE-CHAR = %x01-09 / %x0B-0C / %x0E-21 / %x23-5B / - %x5D-7F - ;; any TEXT-CHAR except QUOTED-SPECIALS - - QUOTED-CHAR = SAFE-UTF8-CHAR / "\" QUOTED-SPECIALS - - QUOTED-SPECIALS = DQUOTE / "\" - - SAFE-UTF8-CHAR = SAFE-CHAR / UTF8-2 / UTF8-3 / UTF8-4 - ;; <UTF8-2>, <UTF8-3>, and <UTF8-4> - ;; are defined in [UTF-8]. - - ATOM-CHAR = "!" / %x23-27 / %x2A-5B / %x5D-7A / %x7C-7E - ;; Any CHAR except ATOM-SPECIALS - - ATOM-SPECIALS = "(" / ")" / "{" / SP / CTL / QUOTED-SPECIALS - - - - -Melnikov & Martin Standards Track [Page 31] - -RFC 5804 ManageSieve July 2010 - - - NZDIGIT = %x31-39 - ;; 1-9 - - atom = 1*1024ATOM-CHAR - - iana-token = atom - ;; MUST be registered with IANA - - auth-type = DQUOTE auth-type-name DQUOTE - - auth-type-name = iana-token - ;; as defined in SASL [SASL] - - command = (command-any / command-auth / - command-nonauth) CRLF - ;; Modal based on state - - command-any = command-capability / command-logout / - command-noop - ;; Valid in all states - - command-auth = command-getscript / command-setactive / - command-listscripts / command-deletescript / - command-putscript / command-checkscript / - command-havespace / - command-renamescript / - command-unauthenticate - ;; Valid only in Authenticated state - - command-nonauth = command-authenticate / command-starttls - ;; Valid only when in Non-Authenticated - ;; state - - command-authenticate = "AUTHENTICATE" SP auth-type [SP string] - *(CRLF string) - - command-capability = "CAPABILITY" - - command-deletescript = "DELETESCRIPT" SP sieve-name - - command-getscript = "GETSCRIPT" SP sieve-name - - command-havespace = "HAVESPACE" SP sieve-name SP number - - command-listscripts = "LISTSCRIPTS" - - command-noop = "NOOP" [SP string] - - - - -Melnikov & Martin Standards Track [Page 32] - -RFC 5804 ManageSieve July 2010 - - - command-logout = "LOGOUT" - - command-putscript = "PUTSCRIPT" SP sieve-name SP sieve-script - - command-checkscript = "CHECKSCRIPT" SP sieve-script - - sieve-script = string - - command-renamescript = "RENAMESCRIPT" SP old-sieve-name SP - new-sieve-name - - old-sieve-name = sieve-name - - new-sieve-name = sieve-name - - command-setactive = "SETACTIVE" SP active-sieve-name - - command-starttls = "STARTTLS" - - command-unauthenticate= "UNAUTHENTICATE" - - 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] ")" - - literal-c2s = "{" number "+}" CRLF *OCTET - ;; The number represents the number of - ;; octets. - ;; This type of literal can only be sent - ;; from the client to the server. - - literal-s2c = "{" number "}" CRLF *OCTET - ;; Almost identical to literal-c2s, - ;; but with no '+' character. - ;; The number represents the number of - ;; octets. - ;; This type of literal can only be sent - ;; from the server to the client. - - - - - - - -Melnikov & Martin Standards Track [Page 33] - -RFC 5804 ManageSieve July 2010 - - - number = (NZDIGIT *DIGIT) / "0" - ;; A 32-bit unsigned number - ;; with no extra leading zeros. - ;; (0 <= n < 4,294,967,296) - - number-str = string - ;; <number> encoded as a <string>. - - quoted = DQUOTE *1024QUOTED-CHAR DQUOTE - ;; limited to 1024 octets between the <">s - - resp-code = "AUTH-TOO-WEAK" / "ENCRYPT-NEEDED" / "QUOTA" - ["/" ("MAXSCRIPTS" / "MAXSIZE")] / - resp-code-sasl / - resp-code-referral / - "TRANSITION-NEEDED" / "TRYLATER" / - "ACTIVE" / "NONEXISTENT" / - "ALREADYEXISTS" / "WARNINGS" / - "TAG" SP string / - resp-code-ext - - resp-code-referral = "REFERRAL" SP sieveurl - - resp-code-sasl = "SASL" SP string - - resp-code-name = iana-token - ;; The response code name is hierarchical, - ;; separated by '/'. - ;; The response code name MUST NOT start - ;; with '/'. - - resp-code-ext = resp-code-name [SP extension-data] - ;; unknown response codes MUST be tolerated - ;; by the client. - - response = response-authenticate / - response-logout / - response-getscript / - response-setactive / - response-listscripts / - response-deletescript / - response-putscript / - response-checkscript / - response-capability / - response-havespace / - response-starttls / - response-renamescript / - response-noop / - - - -Melnikov & Martin Standards Track [Page 34] - -RFC 5804 ManageSieve July 2010 - - - response-unauthenticate - - response-authenticate = *(string CRLF) - ((response-ok [response-capability]) / - response-nobye) - ;; <response-capability> is REQUIRED if a - ;; SASL security layer was negotiated and - ;; MUST be omitted otherwise. - - response-capability = *(single-capability) response-oknobye - - single-capability = capability-name [SP string] CRLF - - capability-name = string - - ;; Note that literal-s2c is allowed. - - initial-capabilities = DQUOTE "IMPLEMENTATION" DQUOTE SP string / - DQUOTE "SASL" DQUOTE SP sasl-mechs / - DQUOTE "SIEVE" DQUOTE SP sieve-extensions / - DQUOTE "MAXREDIRECTS" DQUOTE SP number-str / - DQUOTE "NOTIFY" DQUOTE SP notify-mechs / - DQUOTE "STARTTLS" DQUOTE / - DQUOTE "LANGUAGE" DQUOTE SP language / - DQUOTE "VERSION" DQUOTE SP version / - DQUOTE "OWNER" DQUOTE SP string - ;; Each capability conforms to - ;; the syntax for single-capability. - ;; Also, note that the capability name - ;; can be returned as either literal-s2c - ;; or quoted, even though only "quoted" - ;; string is shown above. - - version = ( DQUOTE "1.0" DQUOTE ) / version-ext - - version-ext = DQUOTE ver-major "." ver-minor DQUOTE - ; Future versions specified in updates - ; to this document. An increment to - ; the ver-major means a backward-incompatible - ; change to the protocol, e.g., "3.5" (ver-major "3") - ; is not backward-compatible with any "2.X" version. - ; Any version "Z.W" MUST be backward compatible - ; with any version "Z.Q", where Q < W. - ; For example, version "2.4" is backward compatible - ; with version "2.0", "2.1", "2.2", and "2.3". - - ver-major = number - - - - -Melnikov & Martin Standards Track [Page 35] - -RFC 5804 ManageSieve July 2010 - - - ver-minor = number - - sasl-mechs = string - ; Space-separated list of SASL mechanisms, - ; each SASL mechanism name complies with rules - ; specified in [SASL]. - ; Can be empty. - - sieve-extensions = string - ; Space-separated list of supported SIEVE extensions. - ; Can be empty. - - language = string - ; Contains <Language-Tag> from [RFC5646]. - - - notify-mechs = string - ; Space-separated list of URI schema parts - ; for supported notification [NOTIFY] methods. - ; MUST NOT be empty. - - response-deletescript = response-oknobye - - response-getscript = (sieve-script CRLF response-ok) / - response-nobye - - response-havespace = response-oknobye - - response-listscripts = *(sieve-name [SP "ACTIVE"] CRLF) - response-oknobye - ;; ACTIVE may only occur with one sieve-name - - response-logout = response-oknobye - - response-unauthenticate= response-oknobye - ;; "NO" response can only be returned when - ;; the command is issued in a wrong state - ;; or has a wrong number of parameters - - response-ok = "OK" [SP "(" resp-code ")"] - [SP string] CRLF - ;; The string contains human-readable text - ;; encoded as UTF-8. - - response-nobye = ("NO" / "BYE") [SP "(" resp-code ")"] - [SP string] CRLF - ;; The string contains human-readable text - ;; encoded as UTF-8. - - - -Melnikov & Martin Standards Track [Page 36] - -RFC 5804 ManageSieve July 2010 - - - response-oknobye = response-ok / response-nobye - - response-noop = response-ok - - response-putscript = response-oknobye - - response-checkscript = response-oknobye - - response-renamescript = response-oknobye - - response-setactive = response-oknobye - - response-starttls = (response-ok response-capability) / - response-nobye - - sieve-name = string - ;; See Section 1.6 for the full list of - ;; prohibited characters. - ;; Empty string is not allowed. - - active-sieve-name = string - ;; See Section 1.6 for the full list of - ;; prohibited characters. - ;; This is similar to <sieve-name>, but - ;; empty string is allowed and has a special - ;; meaning. - - string = quoted / literal-c2s / literal-s2c - ;; literal-c2s is only allowed when sent - ;; from the client to the server. - ;; literal-s2c is only allowed when sent - ;; from the server to the client. - ;; quoted is allowed in either direction. - -5. Security Considerations - - The AUTHENTICATE command uses SASL [SASL] to provide authentication - and authorization services. Integrity and privacy services can be - provided by [SASL] and/or [TLS]. When a SASL mechanism is used, the - security considerations for that mechanism apply. - - This protocol's transactions are susceptible to passive observers or - man-in-the-middle attacks that alter the data, unless the optional - encryption and integrity services of the SASL (via the AUTHENTICATE - command) and/or [TLS] (via the STARTTLS 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. - - - -Melnikov & Martin Standards Track [Page 37] - -RFC 5804 ManageSieve July 2010 - - - If an implementation supports SASL mechanisms that are vulnerable to - passive eavesdropping attacks (such as [PLAIN]), then the - implementation MUST support at least one configuration where these - SASL mechanisms are not advertised or used without the presence of an - external security layer such as [TLS]. - - Some response codes returned on failed AUTHENTICATE command may - disclose whether or not the username is valid (e.g., TRANSITION- - NEEDED), so server implementations SHOULD provide the ability to - disable these features (or make them not conditional on a per-user - basis) for sites concerned about such disclosure. In the case of - ENCRYPT-NEEDED, if it is applied to all identities then no extra - information is disclosed, but if it is applied on a per-user basis it - can disclose information. - - A compromised or malicious server can use the TRANSITION-NEEDED - response code to force the client that is configured to use a - mechanism that does not disclose the user's password to the server - (e.g., Kerberos), to send the bare password to the server. Clients - SHOULD have the ability to disable the password transition feature, - or disclose that risk to the user and offer the user an option of how - to proceed. - -6. IANA Considerations - - IANA has reserved TCP port number 4190 for use with the ManageSieve - protocol described in this document. - - IANA has registered the "sieve" URI scheme defined in Section 3 of - this document. - - IANA has registered "sieve" in the "GSSAPI/Kerberos/SASL Service - Names" registry. - - IANA has created a new registry for ManageSieve capabilities. The - registration template for ManageSieve capabilities is specified in - Section 6.1. ManageSieve protocol capabilities MUST be specified in - a Standards-Track or IESG-approved Experimental RFC. - - IANA has created a new registry for ManageSieve response codes. The - registration template for ManageSieve response codes is specified in - Section 6.3. ManageSieve protocol response codes MUST be specified - in a Standards-Track or IESG-approved Experimental RFC. - - - - - - - - -Melnikov & Martin Standards Track [Page 38] - -RFC 5804 ManageSieve July 2010 - - -6.1. ManageSieve Capability Registration Template - - To: iana@iana.org - Subject: ManageSieve Capability Registration - - Please register the following ManageSieve capability: - - Capability name: - Description: - Relevant publications: - Person & email address to contact for further information: - Author/Change controller: - -6.2. Registration of Initial ManageSieve Capabilities - - To: iana@iana.org - Subject: ManageSieve Capability Registration - - Please register the following ManageSieve capabilities: - - Capability name: IMPLEMENTATION - Description: Its value contains the name of the server - implementation and its version. - Relevant publications: this RFC, Section 1.7. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: SASL - Description: Its value contains a space-separated list of SASL - mechanisms supported by the server. - Relevant publications: this RFC, Sections 1.7 and 2.1. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: SIEVE - Description: Its value contains a space-separated list of supported - SIEVE extensions. - Relevant publications: this RFC, Section 1.7. Also [SIEVE]. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - -Melnikov & Martin Standards Track [Page 39] - -RFC 5804 ManageSieve July 2010 - - - Capability name: STARTTLS - Description: This capability is returned if the server supports TLS - (STARTTLS command). - Relevant publications: this RFC, Sections 1.7 and 2.2. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: NOTIFY - Description: This capability is returned if the server supports the - 'enotify' [NOTIFY] Sieve extension. - Relevant publications: this RFC, Section 1.7. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: MAXREDIRECTS - Description: This capability returns the limit on the number of - Sieve "redirect" actions a script can perform during a - single evaluation. The value is a non-negative number - represented as a ManageSieve string. - Relevant publications: this RFC, Section 1.7. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: LANGUAGE - Description: The language (<Language-Tag> from [RFC5646]) currently - used for human-readable error messages. - Relevant publications: this RFC, Section 1.7. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Capability name: OWNER - Description: Its value contains the UTF-8-encoded name of the - currently logged-in user ("authorization identity" - according to RFC 4422). - Relevant publications: this RFC, Section 1.7. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - - -Melnikov & Martin Standards Track [Page 40] - -RFC 5804 ManageSieve July 2010 - - - Capability name: VERSION - Description: This capability is returned if the server is compliant - with RFC 5804; i.e., that it supports RENAMESCRIPT, - CHECKSCRIPT, and NOOP commands. - Relevant publications: this RFC, Sections 2.11, 2.12, and 2.13. - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - -6.3. ManageSieve Response Code Registration Template - - To: iana@iana.org - Subject: ManageSieve Response Code Registration - - Please register the following ManageSieve response code: - - Response Code: - Arguments (use ABNF to specify syntax, or the word NONE if none - can be specified): - Purpose: - Published Specification(s): - Person & email address to contact for further information: - Author/Change controller: - -6.4. Registration of Initial ManageSieve Response Codes - - To: iana@iana.org - Subject: ManageSieve Response Code Registration - - Please register the following ManageSieve response codes: - - Response Code: AUTH-TOO-WEAK - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: This response code is returned in the NO response from - an AUTHENTICATE command. It indicates that site - security policy forbids the use of the requested - mechanism for the specified authentication identity. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - - -Melnikov & Martin Standards Track [Page 41] - -RFC 5804 ManageSieve July 2010 - - - Response Code: ENCRYPT-NEEDED - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: This response code is returned in the NO response 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. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: QUOTA - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: If this response code is returned in the NO/BYE - response, it means that the command would have placed - the user above the site-defined quota constraints. If - this response code is returned in the OK response, it - can mean that the user is near its quota or that the - user exceeded its quota, but the server supports soft - quotas. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: QUOTA/MAXSCRIPTS - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: If this response code is returned in the NO/BYE - response, it means that the command would have placed - the user above the site-defined limit on the number of - Sieve scripts. If this response code is returned in - the OK response, it can mean that the user is near its - quota or that the user exceeded its quota, but the - server supports soft quotas. This response code is a - more specific version of the QUOTA response code. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - -Melnikov & Martin Standards Track [Page 42] - -RFC 5804 ManageSieve July 2010 - - - Response Code: QUOTA/MAXSIZE - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: If this response code is returned in the NO/BYE - response, it means that the command would have placed - the user above the site-defined maximum script size. - If this response code is returned in the OK response, - it can mean that the user is near its quota or that - the user exceeded its quota, but the server supports - soft quotas. This response code is a more specific - version of the QUOTA response code. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: REFERRAL - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): <sieveurl> - Purpose: This response code may be returned with a BYE result - from any command, and includes a mandatory parameter - that indicates what server to access to manage this - user's Sieve scripts. The server will be specified by - a Sieve URL (see Section 3). The scriptname portion - of the URL MUST NOT be specified. The client should - authenticate to the specified server and use it for - all further commands in the current session. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: SASL - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): <string> - Purpose: This response code can occur in the OK response to a - successful AUTHENTICATE command and includes the - optional final server response data from the server as - specified by [SASL]. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - -Melnikov & Martin Standards Track [Page 43] - -RFC 5804 ManageSieve July 2010 - - - Response Code: TRANSITION-NEEDED - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: This response code occurs in a NO response of 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 is typically done - by establishing a secure channel using TLS, followed - by authenticating once using the [PLAIN] - authentication mechanism. The selected mechanism - SHOULD then work for authentications in subsequent - sessions. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: TRYLATER - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: A command failed due to a temporary server failure. - The client MAY continue using local information and - try the command later. This response code only make - sense when returned in a NO/BYE response. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: ACTIVE - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: A command failed because it is not allowed on the - active script, for example, DELETESCRIPT on the active - script. This response code only makes sense when - returned in a NO/BYE response. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - - - - - -Melnikov & Martin Standards Track [Page 44] - -RFC 5804 ManageSieve July 2010 - - - Response Code: NONEXISTENT - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: A command failed because the referenced script name - doesn't exist. This response code only makes sense - when returned in a NO/BYE response. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: ALREADYEXISTS - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: A command failed because the referenced script name - already exists. This response code only makes sense - when returned in a NO/BYE response. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: WARNINGS - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): NONE - Purpose: This response code MAY be returned by the server in - the OK response (but it might be returned with the NO/ - BYE response as well) and signals the client that even - though the script is syntactically valid, it might - contain errors not intended by the script writer. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - Response Code: TAG - Arguments (use ABNF to specify syntax, or the word NONE if none can - be specified): string - Purpose: This response code name is followed by a string - specified in the command that caused this response. - It is typically used for client state synchronization. - Published Specification(s): [RFC5804] - Person & email address to contact for further information: - Alexey Melnikov <alexey.melnikov@isode.com> - Author/Change controller: IESG. - - - - - - -Melnikov & Martin Standards Track [Page 45] - -RFC 5804 ManageSieve July 2010 - - -7. Internationalization Considerations - - The LANGUAGE capability (see Section 1.7) allows a client to discover - the current language used in all human-readable responses that might - be returned at the end of any OK/NO/BYE response. Human-readable - text in OK responses typically doesn't need to be shown to the user, - unless it is returned in response to a PUTSCRIPT or CHECKSCRIPT - command that also contains the WARNINGS response code (Section 1.3). - Human-readable text from NO/BYE responses is intended be shown to the - user, unless the client can automatically handle failure of the - command that caused such a response. Clients SHOULD use response - codes (Section 1.3) for automatic error handling. Response codes MAY - also be used by the client to present error messages in a language - understood by the user, for example, if the LANGUAGE capability - doesn't return a language understood by the user. - - Note that the human-readable text from OK (WARNINGS) or NO/BYE - responses for PUTSCRIPT/CHECKSCRIPT commands is intended for advanced - users that understand Sieve language. Such advanced users are often - sophisticated enough to be able to handle whatever language the - server is using, even if it is not their preferred language, and will - want to see error/warning text no matter what language the server - puts it in. - - A client that generates Sieve script automatically, for example, if - the script is generated without user intervention or from a UI that - presents an abstract list of conditions and corresponding actions, - SHOULD NOT present warning/error messages to the user, because the - user might not even be aware that the client is using Sieve - underneath. However, if the client has a debugging mode, such - warnings/errors SHOULD be available in the debugging mode. - - Note that this document doesn't provide a way to modify the currently - used language. It is expected that a future extension will address - that. - -8. Acknowledgements - - Thanks to Simon Josefsson, Larry Greenfield, Allen Johnson, Chris - Newman, Lyndon Nerenberg, Tim Showalter, Sarah Robeson, Walter Wong, - Barry Leiba, Arnt Gulbrandsen, Stephan Bosch, Ken Murchison, Phil - Pennock, Ned Freed, Jeffrey Hutzelman, Mark E. Mallett, Dilyan - Palauzov, Dave Cridland, Aaron Stone, Robert Burrell Donkin, Patrick - Ben Koetter, Bjoern Hoehrmann, Martin Duerst, Pasi Eronen, Magnus - Westerlund, Tim Polk, and Julien Coloos for help with this document. - Special thank you to Phil Pennock for providing text for the NOOP - command, as well as finding various bugs in the document. - - - - -Melnikov & Martin Standards Track [Page 46] - -RFC 5804 ManageSieve July 2010 - - -9. References - -9.1. Normative References - - [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", STD 68, RFC 5234, January 2008. - - [ACAP] Newman, C. and J. Myers, "ACAP -- Application - Configuration Access Protocol", RFC 2244, November - 1997. - - [BASE64] Josefsson, S., "The Base16, Base32, and Base64 Data - Encodings", RFC 4648, October 2006. - - [DNS-SRV] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR - for specifying the location of services (DNS SRV)", - RFC 2782, February 2000. - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", BCP 14, RFC 2119, March 1997. - - [NET-UNICODE] Klensin, J. and M. Padlipsky, "Unicode Format for - Network Interchange", RFC 5198, March 2008. - - [NOTIFY] Melnikov, A., Leiba, B., Segmuller, W., and T. Martin, - "Sieve Email Filtering: Extension for Notifications", - RFC 5435, January 2009. - - [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and - Languages", BCP 18, RFC 2277, January 1998. - - [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version - 6 (IPv6) Specification", RFC 2460, December 1998. - - [RFC3490] Faltstrom, P., Hoffman, P., and A. Costello, - "Internationalizing Domain Names in Applications - (IDNA)", RFC 3490, March 2003. - - [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol - (LDAP): Schema for User Applications", RFC 4519, June - 2006. - - [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying - Languages", BCP 47, RFC 5646, September 2009. - - [RFC791] Postel, J., "Internet Protocol", STD 5, RFC 791, - September 1981. - - - - -Melnikov & Martin Standards Track [Page 47] - -RFC 5804 ManageSieve July 2010 - - - [SASL] Melnikov, A. and K. Zeilenga, "Simple Authentication - and Security Layer (SASL)", RFC 4422, June 2006. - - [SASLprep] Zeilenga, K., "SASLprep: Stringprep Profile for User - Names and Passwords", RFC 4013, February 2005. - - [SCRAM] Menon-Sen, A., Melnikov, A., Newman, C., and N. - Williams, "Salted Challenge Response Authentication - Mechanism (SCRAM) SASL and GSS-API Mechanisms", RFC - 5802, July 2010. - - [SIEVE] Guenther, P. and T. Showalter, "Sieve: An Email - Filtering Language", RFC 5228, January 2008. - - [StringPrep] Hoffman, P. and M. Blanchet, "Preparation of - Internationalized Strings ("stringprep")", RFC 3454, - December 2002. - - [TLS] Dierks, T. and E. Rescorla, "The Transport Layer - Security (TLS) Protocol Version 1.2", RFC 5246, August - 2008. - - [URI-GEN] Berners-Lee, T., Fielding, R., and L. Masinter, - "Uniform Resource Identifier (URI): Generic Syntax", - STD 66, RFC 3986, January 2005. - - [UTF-8] Yergeau, F., "UTF-8, a transformation format of ISO - 10646", STD 63, RFC 3629, November 2003. - - [X509] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., - Housley, R., and W. Polk, "Internet X.509 Public Key - Infrastructure Certificate and Certificate Revocation - List (CRL) Profile", RFC 5280, May 2008. - - [X509-SRV] Santesson, S., "Internet X.509 Public Key - Infrastructure Subject Alternative Name for Expression - of Service Name", RFC 4985, August 2007. - -9.2. Informative References - - [DIGEST-MD5] Leach, P. and C. Newman, "Using Digest Authentication - as a SASL Mechanism", RFC 2831, May 2000. - - [GSSAPI] Melnikov, A., "The Kerberos V5 ("GSSAPI") Simple - Authentication and Security Layer (SASL) Mechanism", - RFC 4752, November 2006. - - - - - -Melnikov & Martin Standards Track [Page 48] - -RFC 5804 ManageSieve July 2010 - - - [I-HAVE] Freed, N., "Sieve Email Filtering: Ihave Extension", - RFC 5463, March 2009. - - [IMAP] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - - VERSION 4rev1", RFC 3501, March 2003. - - [LDAP] Zeilenga, K., "Lightweight Directory Access Protocol - (LDAP): Technical Specification Road Map", RFC 4510, - June 2006. - - [PLAIN] Zeilenga, K., "The PLAIN Simple Authentication and - Security Layer (SASL) Mechanism", RFC 4616, August - 2006. - -Authors' Addresses - - Alexey Melnikov (editor) - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex TW12 2BX - UK - - EMail: Alexey.Melnikov@isode.com - - - Tim Martin - BeThereBeSquare, Inc. - 672 Haight st. - San Francisco, CA 94117 - USA - - Phone: +1 510 260-4175 - EMail: timmartin@alumni.cmu.edu - - - - - - - - - - - - - - - - - -Melnikov & Martin Standards Track [Page 49] - diff --git a/docs/[rfc6070] PBKDF2 Test Vectors/rfc6070.txt b/docs/[rfc6070] PBKDF2 Test Vectors/rfc6070.txt deleted file mode 100755 index 67cd340b..00000000 --- a/docs/[rfc6070] PBKDF2 Test Vectors/rfc6070.txt +++ /dev/null @@ -1,283 +0,0 @@ - - - - - - -Internet Engineering Task Force (IETF) S. Josefsson -Request for Comments: 6070 SJD AB -Category: Informational January 2011 -ISSN: 2070-1721 - - - PKCS #5: Password-Based Key Derivation Function 2 (PBKDF2) - Test Vectors - -Abstract - - This document contains test vectors for the Public-Key Cryptography - Standards (PKCS) #5 Password-Based Key Derivation Function 2 (PBKDF2) - with the Hash-based Message Authentication Code (HMAC) Secure Hash - Algorithm (SHA-1) pseudorandom function. - -Status of This Memo - - This document is not an Internet Standards Track specification; it is - published for informational purposes. - - This document is a product of the Internet Engineering Task Force - (IETF). It represents the consensus of the IETF community. It has - received public review and has been approved for publication by the - Internet Engineering Steering Group (IESG). Not all documents - approved by the IESG are a candidate for any level of Internet - Standard; see Section 2 of RFC 5741. - - Information about the current status of this document, any errata, - and how to provide feedback on it may be obtained at - http://www.rfc-editor.org/info/rfc6070. - -Copyright Notice - - Copyright (c) 2011 IETF Trust and the persons identified as the - document authors. All rights reserved. - - This document is subject to BCP 78 and the IETF Trust's Legal - Provisions Relating to IETF Documents - (http://trustee.ietf.org/license-info) in effect on the date of - publication of this document. Please review these documents - carefully, as they describe your rights and restrictions with respect - to this document. Code Components extracted from this document must - include Simplified BSD License text as described in Section 4.e of - the Trust Legal Provisions and are provided without warranty as - described in the Simplified BSD License. - - - - - -Josefsson Informational [Page 1] - -RFC 6070 PKCS #5 PBKDF2 Test Vectors January 2011 - - -Table of Contents - - 1. Introduction ....................................................2 - 2. PBKDF2 HMAC-SHA1 Test Vectors ...................................2 - 3. Acknowledgements ................................................4 - 4. Copying Conditions ..............................................4 - 5. Security Considerations .........................................4 - 6. References ......................................................4 - 6.1. Normative References .......................................4 - 6.2. Informative References .....................................5 - -1. Introduction - - The Public-Key Cryptography Standards (PKCS) #5 [RFC2898] Password- - Based Key Derivation Function 2 (PBKDF2) is used by several protocols - to derive encryption keys from a password. - - For example, Salted Challenge Response Authentication Mechanism - (SCRAM) [RFC5802] uses PBKDF2 with Hash-based Message Authentication - Code (HMAC) [RFC2104] and Secure Hash Algorithm (SHA-1) - [FIPS.180-1.1995]. - - Test vectors for the algorithm were not included in the original - specification, but are often useful for implementers. This document - addresses the shortcoming. - -2. PBKDF2 HMAC-SHA1 Test Vectors - - The input strings below are encoded using ASCII [ANSI.X3-4.1986]. - The sequence "\0" (without quotation marks) means a literal ASCII NUL - value (1 octet). "DK" refers to the Derived Key. - - Input: - P = "password" (8 octets) - S = "salt" (4 octets) - c = 1 - dkLen = 20 - - Output: - DK = 0c 60 c8 0f 96 1f 0e 71 - f3 a9 b5 24 af 60 12 06 - 2f e0 37 a6 (20 octets) - - - - - - - - - -Josefsson Informational [Page 2] - -RFC 6070 PKCS #5 PBKDF2 Test Vectors January 2011 - - - Input: - P = "password" (8 octets) - S = "salt" (4 octets) - c = 2 - dkLen = 20 - - Output: - DK = ea 6c 01 4d c7 2d 6f 8c - cd 1e d9 2a ce 1d 41 f0 - d8 de 89 57 (20 octets) - - - Input: - P = "password" (8 octets) - S = "salt" (4 octets) - c = 4096 - dkLen = 20 - - Output: - DK = 4b 00 79 01 b7 65 48 9a - be ad 49 d9 26 f7 21 d0 - 65 a4 29 c1 (20 octets) - - - Input: - P = "password" (8 octets) - S = "salt" (4 octets) - c = 16777216 - dkLen = 20 - - Output: - DK = ee fe 3d 61 cd 4d a4 e4 - e9 94 5b 3d 6b a2 15 8c - 26 34 e9 84 (20 octets) - - - Input: - P = "passwordPASSWORDpassword" (24 octets) - S = "saltSALTsaltSALTsaltSALTsaltSALTsalt" (36 octets) - c = 4096 - dkLen = 25 - - Output: - DK = 3d 2e ec 4f e4 1c 84 9b - 80 c8 d8 36 62 c0 e4 4a - 8b 29 1a 96 4c f2 f0 70 - 38 (25 octets) - - - - -Josefsson Informational [Page 3] - -RFC 6070 PKCS #5 PBKDF2 Test Vectors January 2011 - - - Input: - P = "pass\0word" (9 octets) - S = "sa\0lt" (5 octets) - c = 4096 - dkLen = 16 - - Output: - DK = 56 fa 6a a7 55 48 09 9d - cc 37 d7 f0 34 25 e0 c3 (16 octets) - -3. Acknowledgements - - Barry Brachman and Love Hornquist Astrand confirmed the test vectors - (using independent implementations) and pointed out a mistake in the - salt octet length count. - -4. Copying Conditions - - This document should be considered a Code Component and is thus - available under the BSD license. - -5. Security Considerations - - The security considerations in [RFC2898] apply. This document does - not introduce any new security considerations. - -6. References - -6.1. Normative References - - [ANSI.X3-4.1986] - American National Standards Institute, "Coded Character - Set - 7-bit American Standard Code for Information - Interchange", ANSI X3.4, 1986. - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- - Hashing for Message Authentication", RFC 2104, - February 1997. - - [RFC2898] Kaliski, B., "PKCS #5: Password-Based Cryptography - Specification Version 2.0", RFC 2898, September 2000. - - [FIPS.180-1.1995] - National Institute of Standards and Technology, "Secure - Hash Standard", FIPS PUB 180-1, April 1995, - <http://www.itl.nist.gov/fipspubs/fip180-1.htm>. - - - - - -Josefsson Informational [Page 4] - -RFC 6070 PKCS #5 PBKDF2 Test Vectors January 2011 - - -6.2. Informative References - - [RFC5802] Newman, C., Menon-Sen, A., Melnikov, A., and N. Williams, - "Salted Challenge Response Authentication Mechanism - (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, - July 2010. - -Author's Address - - Simon Josefsson - SJD AB - Hagagatan 24 - Stockholm 113 47 - SE - - EMail: simon@josefsson.org - URI: http://josefsson.org/ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Josefsson Informational [Page 5] - diff --git a/docs/draft-ietf-sieve-notify-03.txt b/docs/draft-ietf-sieve-notify-03.txt deleted file mode 100755 index 2a778515..00000000 --- a/docs/draft-ietf-sieve-notify-03.txt +++ /dev/null @@ -1,842 +0,0 @@ - - - - -Sieve Working Group A. Melnikov, Ed. -Internet-Draft Isode Limited -Expires: December 25, 2006 B. Leiba, Ed. - W. Segmuller - IBM T.J. Watson Research Center - T. Martin - Mirapoint Inc. - June 23, 2006 - - - Sieve Extension: Notifications - draft-ietf-sieve-notify-03 - -Status of this Memo - - By submitting this Internet-Draft, each author represents that any - applicable patent or other IPR claims of which he or she is aware - have been or will be disclosed, and any of which he or she becomes - aware will be disclosed, in accordance with Section 6 of BCP 79. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on December 25, 2006. - -Copyright Notice - - Copyright (C) The Internet Society (2006). - -Abstract - - Users go to great lengths to be notified as quickly as possible that - they have received new mail. Most of these methods involve polling - to check for new messages periodically. A push method handled by the - final delivery agent gives users quicker notifications and saves - - - -Melnikov, et al. Expires December 25, 2006 [Page 1] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - server resources. This document does not specify the notification - method but is expected that using existing instant messaging - infrastructure such as Zephyr, Jabber, or SMS messages will be - popular. This draft describes an extension to the Sieve mail - filtering language that allows users to give specific rules for how - and when notifications should be sent. - -ToDo - - o Change tagged :method to the positional parameter? - - -Changes since draft-ietf-sieve-notify-02 - - o Added :from tagged argument. - - o Added Extract_text action, which allows to extract content of the - first text/* part. - - o Added back the ":options" parameter to the notify action. - - o Added new section talking about requirements on notification - method specs. - - o Added more examples. - - -Changes since draft-ietf-sieve-notify-00 - - o Updated references, etc. - - o Added IANA considerations section. - - o Removed denotify action. - - o Updated examples to use the variables extension. - - o Replaced notification method with URI. - - o Removed text suggesting that this extension can be used to track - all Sieve actions taken. - - o Changed priority to be a string. - - o Added text about URI verification. - - o Clarified that a notification method is allowed to perform - adaptation of notification context (e.g. truncation, charset - - - -Melnikov, et al. Expires December 25, 2006 [Page 2] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - conversion, etc.). These adaptations must be documented in a - document describing the notification method. - - o Clarified that notify is compatible with all existing actions. - - o Removed the :id parameter to the notify action. - - o Added valid_notif_method test that allows to test if an - notification method (URI) is supported. - - o Added a new capability response to ManageSieve that allows to - report supported notification types. - - -Table of Contents - - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 - 1.1. Conventions used in this document . . . . . . . . . . . . . 5 - - 2. Capability Identifier . . . . . . . . . . . . . . . . . . . 5 - - 3. Notify Action . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.1. Notify Action Syntax and Semantics . . . . . . . . . . . . . 5 - 3.2. Notify tag ":method" . . . . . . . . . . . . . . . . . . . . 5 - 3.3. Notify tag ":from" . . . . . . . . . . . . . . . . . . . . . 6 - 3.4. Notify tag ":priority" . . . . . . . . . . . . . . . . . . . 6 - 3.5. Notify tag ":options" . . . . . . . . . . . . . . . . . . . 7 - 3.6. Notify tag ":message" . . . . . . . . . . . . . . . . . . . 7 - 3.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 3.8. Requirements on notification methods specifications . . . . 9 - - 4. Extract_text Action . . . . . . . . . . . . . . . . . . . . 10 - - 5. Test valid_notif_method . . . . . . . . . . . . . . . . . . 11 - - 6. Interactions with Other Sieve Actions . . . . . . . . . . . 11 - - 7. Security Considerations . . . . . . . . . . . . . . . . . . 11 - - 8. Extensions to ManageSieve protocol . . . . . . . . . . . . . 12 - - 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 12 - - 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 - - 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 - 11.1. Normative References . . . . . . . . . . . . . . . . . . . . 12 - 11.2. Informative References . . . . . . . . . . . . . . . . . . . 13 - - - -Melnikov, et al. Expires December 25, 2006 [Page 3] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 14 - Intellectual Property and Copyright Statements . . . . . . . 15 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov, et al. Expires December 25, 2006 [Page 4] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -1. Introduction - - This is an extension to the Sieve language defined by [Sieve] for - providing instant notifications. It defines the new action "notify". - - This document does not dictate the notification method used. - Examples of possible notification methods are Zephyr and Jabber. The - available methods shall be site-defined. - -1.1. Conventions used in this document - - Conventions for notations are as in [Sieve] section 1.1, including - the use of [ABNF]. - - 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 [Kwds]. - - -2. Capability Identifier - - The capability string associated with the extension defined in this - document is "notify". - - -3. Notify Action - -3.1. Notify Action Syntax and Semantics - - Usage: notify [":method" string] - [":from" string] - [":priority" <"1" / "2" / "3">] - [":options" 1*(string-list / number)] - [":message" string] - - The Notify action specifies that a notification should be sent to the - user. The format of the notification is implementation-defined and - is also affected by the notification method used (see Section 3.2). - However, all content specified in the :message parameter SHOULD be - included. - -3.2. Notify tag ":method" - - The :method tag identifies the notification method that will be used; - it is a URI. For example, the notification method can be an SMS URI - [SMS-URI] containing a phone number, or an XMPP [XMPP] URI containing - a Jabber identifier [XMPP-URI]. If the :method tag is not specified, - a default implementation-defined notification method is used, and if - - - -Melnikov, et al. Expires December 25, 2006 [Page 5] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - there is no default method defined, the notification is ignored. - Implementations MUST NOT generate an error condition for lack of a - default notification method, and execution of the script MUST - continue. - - The supported URI values will be site-specific. If an URI schema is - specified that the implementation does not support, the notification - MUST cause an error condition. Sieve scripts can check the supported - methods using the "valid_notif_method" test to be sure that they only - use supported ones, to avoid such error conditions. If the :method - tag contains a supported URI schema, then the URI MUST be checked for - syntactic validity. An invalid URI syntax or an unsupported URI - extension MUST cause an error. An implementation MAY enforce other - semantic restrictions on URIs -- for example an SMS URI can only - contain phone numbers in a particular geographical region. Violation - of such semantic restrictions MUST be treated as an error. - [[Barry 1: "MUST" seems silly here, since the whole sentence is a - "MAY".]] - -3.3. Notify tag ":from" - - A ":from" parameter may be used to specify a notification method - specific author of the notification. Implementations SHOULD check - the syntax according to the notification method specification and - generate an error when a syntactically invalid ":from" parameter is - specified. - -3.4. Notify tag ":priority" - - The :priority tag specifies the importance of the notification. The - :priority tag is followed by a numeric value represented as a string: - "1" (high importance), "2" (normal importance), and "3" (low - importance). If no priority is given, a default priority of "2" - SHOULD be assumed. Some notification methods allow users to specify - their state of activity (for example "busy" or "away from keyboard"). - If the notification method provides this information it SHOULD be - used to selectively send notifications. If, for example, the user - marks herself as "busy", a notification method can require that a - notification with a priority of "3" is not to be sent, however the - user should be notified of a higher priority notifications. If the - notification method allows users to filter messages based upon - certain parameters in the message, users SHOULD be able to filter - based upon priority. If the notification method does not support - priority, then this parameter MUST be ignored. - [[Alexey 1: Should we keep using "high", "normal" and "low" instead? - Numbers are easier to compare with comparators.]] - [[Barry 3.5: Why do we call this "priority", and then explain it as - "importance"? Shouldn't we just call it "importance"?]] - - - -Melnikov, et al. Expires December 25, 2006 [Page 6] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -3.5. Notify tag ":options" - - The :options tag is used to send additional parameters to the - notification method. Interpretation of :options is method-specific. - [[Alexey 2: Do we need IANA registry for this?]] - -3.6. Notify tag ":message" - - The :message tag specifies the message data to be included in the - notification. The entirety of the string SHOULD be sent but - implementations MAY shorten the message for technical or aesthetic - reasons. If the message parameter is absent, a default message - containing the value of the From header field [[Alexey 3: Align with - usage of :from]] and the value of the Subject header field will be - used. Note that the notification method (the ":method" tag) may - affect how this information is formatted. - - The implementation of a notification method MAY modify the final - notification text -- for example, truncating it if it exceeds a - length limit, or modifying characters that can not be represented in - the target character set. Allowed modifications should be documented - in a standards-track or informational document. - - In order to construct more complex messages the notify extension can - be used together with the Sieve variables extension [Variables], as - shown in the examples below. - -3.7. Examples - - - - - - - - - - - - - - - - - - - - - - - -Melnikov, et al. Expires December 25, 2006 [Page 7] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - Example 1: - require ["notify", "fileinto", "variables"]; - - if header :contains "from" "boss@example.org" { - notify :priority "1" - :message "This is probably very important"; - # Don't send any further notifications - stop; - } - - if header :contains "to" "sievemailinglist@example.org" { - # :matches is used to get the value of the Subject header - if header :matches "Subject" "*" { - set "subject" "${1}"; - } - - # :matches is used to get the value of the From header - if header :matches "From" "*" { - set "from" "${1}"; - } - - notify :priority "3" - :message "[SIEVE] ${from}: ${subject}"; - fileinto "INBOX.sieve"; - } - - - Example 2: - require ["notify", "fileinto", "variables", "envelope"]; - - if header :matches "from" "*@*.example.org" { - # :matches is used to get the MAIL FROM address - if envelope :all :matches "from" "*" { - set "env_from" " [really: ${1}]"; - } - - # :matches is used to get the value of the Subject header - if header :matches "Subject" "*" { - set "subject" "${1}"; - } - - # :matches is used to get the address from the From header - if address :matches :all "from" "*" { - set "from_addr" "${1}"; - } - - notify :message "${from_addr}${env_from}: ${subject}"; - } - - - -Melnikov, et al. Expires December 25, 2006 [Page 8] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - Example 3: - require ["notify", "variables"]; - - set "notif_method" - "xmpp:tim@example.com?You%20got%20mail&subject=SIEVE"; - - if header :contains "subject" "Your dog" { - set "notif_method" "sms:+14085551212"; - } - - if header :contains "to" "sievemailinglist@example.org" { - set "notif_method" ""; - } - - if not string :is "${notif_method}" "" { - notify :method "${notif_method}"; - } - - if header :contains "from" "boss@example.org" { - # :matches is used to get the value of the Subject header - if header :matches "Subject" "*" { - set "subject" "${1}"; - } - - # don't need high priority notification for - # a 'for your information' - if not header :contains "subject" "FYI:" { - notify :method "sms:+14085551212" - :priority "1" :message "BOSS: ${subject}"; - } - } - - [[anchor2: Make sure that the XMPP notification syntax is correct.]] - -3.8. Requirements on notification methods specifications - - This section describes requirements on a document describing a Sieve - notification method. [[Alexey 4: The whole section is very raw and - needs more work.]] - - A notification method MAY ignore parameters specified in the Notify - action. - - It is RECOMMENDED that a timestamp be included in the notification. - - Implementations SHOULD NOT include extraneous information. - - If there are errors sending the notification, the Sieve interpreter - - - -Melnikov, et al. Expires December 25, 2006 [Page 9] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - SHOULD ignore the notification and not retry indefinitely. - - -4. Extract_text Action - - Usage: extract_text [MODIFIER] [":first" number] - <varname: string> - - The Extract_text action stores at most :first bytes of the first - text/* part in the variable identified by varname. If the :first - parameter is not present, the whole content of the first text/* part - is stored. If the message being processed doesn't contain any text/* - part, the action will set the variable identified by varname to empty - string. [[Alexey 5: Do we need to be more specific about what "the - first text part" means?]] - - Modifiers are applied on the extracted text before it is stored in - the variable. See [Variables] for details. - - Note that this action is only available when the Sieve script - specifies both "variables" [Variables] and "notify" capabilities in - the require statements. - - - - Example 4: - require ["notify", "variables"]; - - if header :contains "from" "boss@example.org" { - # :matches is used to get the value of the Subject header - if header :matches "Subject" "*" { - set "subject" "${1}"; - } - - # extract the first 100 bytes of the first text/* part - extract_text :first 100 "msgcontent"; - - # don't need high priority notification for - # a 'for your information' - if not header :contains "subject" "FYI:" { - notify :method "sms:+14085551212" - :priority "1" :message - "BOSS: ${subject}; ${msgcontent}"; - } - } - - - - - - -Melnikov, et al. Expires December 25, 2006 [Page 10] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -5. Test valid_notif_method - - Usage: valid_notif_method <notification-uris: string-list> - - The "valid_notif_method" test is true if the notification methods - listed in the notification-uris argument are supported and they are - syntactically and semantically (including implementation-specific - semantic restrictions) valid. This test MUST perform exactly the - same validation as would be performed on the ":method" parameter of - the "notify" action. - - All of the listed notification methods must be supported and valid or - the test is false. - - - - Example 5: - if not valid_notif_method ["mailto:", - "http://gw.example.net/notify?test"] { - stop; - } - - -6. Interactions with Other Sieve Actions - - The notify action is compatible with all other actions, and does not - affect the operation of other actions. In particular, the notify - action MUST NOT cancel the implicit keep. - - Multiple executed notify actions are allowed. - - -7. Security Considerations - - Security considerations are discussed in [Sieve]. Additionally, - implementations must be careful to follow the security considerations - of the specific notification methods. - - The notify action is potentially very dangerous. The path the - notification takes through the network may not be secure. An error - in the options string may cause the message to be transmitted to - someone it was not intended for, or may expose information to - eavesdroppers. - - Just because a notification is received doesn't mean it was sent by - the Sieve implementation. It might be possible to forge - notifications with some notification methods. - - - - -Melnikov, et al. Expires December 25, 2006 [Page 11] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -8. Extensions to ManageSieve protocol - - A ManageSieve [ManageSieve] server that supports the "notify" - extension MUST advertise the NOTIFY capability, that has a single - mandatory parameter. The parameter is a string containing space - separated list of URI schema parts for supported nofication methods. - - Example: - S: "NOTIFY" "xmpp mailto" - - -9. IANA Considerations - - The following template specifies the IANA registration of the notify - Sieve extension specified in this document: - - To: iana@iana.org - Subject: Registration of new Sieve extension - Capability name: notify - Capability keyword: notify - Capability arguments: N/A - Standards Track/IESG-approved experimental RFC number: this RFC - Person and email address to contact for further information: - Alexey Melnikov <Alexey.Melnikov@isode.com> - - This information should be added to the list of sieve extensions - given on http://www.iana.org/assignments/sieve-extensions. - - -10. Acknowledgements - - Thanks to Larry Greenfield, Sarah Robeson, Tim Showalter, Cyrus - Daboo, Nigel Swinson, Kjetil Torgrim Homme, Michael Haardt, Mark E. - Mallett and Ned Freed for help with this document. - - -11. References - -11.1. Normative References - - [ABNF] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax - Specifications: ABNF", RFC 4234, October 2005. - - [Kwds] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - [ManageSieve] - Martin, T. and A. Melnikov, "A Protocol for Remotely - - - -Melnikov, et al. Expires December 25, 2006 [Page 12] - -Internet-Draft Sieve Extension: Notifications June 2006 - - - Managing Sieve Scripts", work in - progress, draft-martin-managesieve, February 2006. - - [Sieve] Guenther, P. and T. Showalter, "Sieve: An Email Filtering - Language", work in progress, draft-ietf-sieve-3028bis, - July 2005. - - [Variables] - Homme, K., "Sieve Extension: Variables", work in - progress, draft-ietf-sieve-variables, October 2005. - -11.2. Informative References - - [SMS-URI] Wilde, E. and A. Vaha-Sipila, "URI scheme for GSM Short - Message Service", work in progress, draft-wilde-sms-uri, - August 2005. - - [XMPP] Saint-Andre, Ed., P., "Extensible Messaging and Presence - Protocol (XMPP): Core", RFC 3920, October 2004. - - [XMPP-URI] - Saint-Andre, P., "Internationalized Resource Identifiers - (IRIs) and Uniform Resource Identifiers (URIs) for the - Extensible Messaging and Presence Protocol (XMPP)", work - in progress, draft-saintandre-xmpp-iri, September 2005. - - - - - - - - - - - - - - - - - - - - - - - - - - -Melnikov, et al. Expires December 25, 2006 [Page 13] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -Authors' Addresses - - Alexey Melnikov (editor) - Isode Limited - 5 Castle Business Village - 36 Station Road - Hampton, Middlesex TW12 2BX - UK - - Email: Alexey.Melnikov@isode.com - - - Barry Leiba (editor) - IBM T.J. Watson Research Center - 19 Skyline Drive - Hawthorne, NY 10532 - US - - Phone: +1 914 784 7941 - Email: leiba@watson.ibm.com - - - Wolfgang Segmuller - IBM T.J. Watson Research Center - 19 Skyline Drive - Hawthorne, NY 10532 - US - - Phone: +1 914 784 7408 - Email: werewolf@us.ibm.com - - - Tim Martin - Mirapoint Inc. - 909 Hermosa Court - Sunnyvale, CA 94085 - US - - Phone: +1 409 720 3835 - Email: tmartin@mirapoint.com - - - - - - - - - - - -Melnikov, et al. Expires December 25, 2006 [Page 14] - -Internet-Draft Sieve Extension: Notifications June 2006 - - -Intellectual Property Statement - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - - -Disclaimer of Validity - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - - -Copyright Statement - - Copyright (C) The Internet Society (2006). This document is subject - to the rights, licenses and restrictions contained in BCP 78, and - except as set forth therein, the authors retain all their rights. - - -Acknowledgment - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - -Melnikov, et al. Expires December 25, 2006 [Page 15] - - diff --git a/docs/draft-murchison-sasl-login-00.txt b/docs/draft-murchison-sasl-login-00.txt deleted file mode 100755 index e6ffc297..00000000 --- a/docs/draft-murchison-sasl-login-00.txt +++ /dev/null @@ -1,396 +0,0 @@ - - - - - - - -Internet Draft K. Murchison -Category: Informational M. Crispin -Expires: March 2, 2004 28 August 2003 - - - The LOGIN SASL Mechanism - - <draft-murchison-sasl-login-00.txt> - - -Status of this Memo - - This document is an Internet-Draft and is subject to all provisions - of Section 10 of RFC2026. - - Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as - Internet-Drafts. - - Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress." - - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/1id-abstracts.html - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html - - -Copyright Notice - - Copyright (C) The Internet Society 2003. All Rights Reserved. - - -Abstract - - This document documents the obsolete clear-text user/password Simple - Authentication and Security Layer (SASL) mechanism called the LOGIN - mechanism. The LOGIN mechanism was intended to be used, in - combination with data confidentiality services provided by a lower - layer, in protocols which lack a simple password authentication - command. - - - - - - -Expires: March 2, 2004 Murchison [Page 1] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - - -Conventions Used in the Document - - 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 [KEYWORDS]. - - -1. Background and Intended Usage - - This document documents the obsolete LOGIN Simple Authentication and - Security Layer ([SASL]) mechanism which was in use in protocols with - no clear-text login command (e.g., [SMTP-AUTH]). - - Note: The LOGIN SASL mechanism is obsoleted in favor of the PLAIN - SASL mechanism ([PLAIN]). The LOGIN mechanism is documented here - only for the purpose of backwards compatibility with legacy software. - Clients SHOULD implement the PLAIN SASL mechanism and use it whenever - offered by a server. The LOGIN SASL mechanism SHOULD NOT be used by - a client when other plaintext mechanisms are offered by a server. - - The name associated with this mechanism is "LOGIN". - - The LOGIN SASL mechanism does not provide a security layer. This - mechanism MUST NOT be used without adequate security protection as - the mechanism affords no integrity nor confidentiality protection - itself. The LOGIN SASL mechanism MUST NOT be advertised or used in - any configuration that prohibits the PLAIN mechanism or plaintext - LOGIN (or USER/PASS) command that sends passwords in the clear. - - -2. LOGIN SASL Mechanism - - The authorization identity is the same string as the "username" in - the traditional (non-SASL) LOGIN or USER commands; the authorization - authenticator is the same string as the traditional "password". The - authentication identity is the same as the authorization identity in - this mechanism. - - Only US-ASCII printable characters SHOULD be used in the username and - password to permit maximal interoperability. If non-US-ASCII - characters are used in a username, they MUST use UTF-8. Passwords - MAY contain arbitrary binary data excluding NUL, CR and LF - characters. However, if a password is supplied to the client as a - sequence of characters (e.g., a password dialog box), those - characters MUST be encoded as UTF-8. - - The username MUST be less than 64 characters in length. - - - -Expires: March 2, 2004 Murchison [Page 2] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - -2.1. Client side of authentication protocol exchange - - The client expects the server to issue a challenge. The client then - responds with the authorization identity. The client then expects - the server to issue a second challenge. The client then responds - with the authorization authenticator. The contents of both - challenges SHOULD be ignored. - - -2.2. Server side of authentication protocol exchange - - The server issues the string "User Name" in challenge, and receives a - client response. This response is recorded as the authorization - identity. The server then issues the string "Password" in challenge, - and receives a client response. This response is recorded as the - authorization authenticator. The server must verify that the - authorization authenticator permits login as the authorization - identity. - - Note: There is at least one widely deployed client which requires - that the challenge strings transmitted by the server be "Username:" - and "Password:" respectively. For this reason, server - implementations MAY send these challenge strings instead of those - listed above. - - -2.3. Example - - This example shows the use of the LOGIN mechanism with the SMTP AUTH - command [SMTP-AUTH] under the protection of SMTP STARTTLS [SMTP-TLS]. - The user name is "tim" and the password is "tanstaaftanstaaf". The - base64 encoding of the challenges and responses is part of the SMTP - AUTH command, not part of the LOGIN specification itself. "C:" and - "S:" indicate lines sent by the client and server respectively. - - S: 220 smtp.example.com ESMTP server ready - C: EHLO test.example.com - S: 250-smtp.example.com - S: 250-STARTTLS - S: 250 AUTH CRAM-MD5 - C: STARTTLS - S: 220 Ready to start TLS - <TLS negotiation, further commands are under TLS layer> - C: EHLO test.example.com - S: 250-smtp.example.com - S: 250 AUTH LOGIN CRAM-MD5 - C: AUTH LOGIN - S: 334 VXNlciBOYW1lAA== - - - -Expires: March 2, 2004 Murchison [Page 3] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - - C: dGlt - S: 334 UGFzc3dvcmQA - C: dGFuc3RhYWZ0YW5zdGFhZg== - S: 235 Authentication successful. - - -3. - Security Considerations - - The LOGIN mechanism relies upon an underlying encryption layer or - other secure channel for security. When used without an encryption - layer or secure channel, it is vulnerable to a common network - eavesdropping attack. Therefore the LOGIN mechanism MUST NOT be - advertised or used in any configuration that prohibits the PLAIN - mechanism or a plaintext LOGIN (or USER/PASS) command that sends - passwords in the clear. - - -4. - IANA Considerations - - The registration for the LOGIN SASL mechanism follows: - - SASL mechanism name: LOGIN - Security Considerations: See section 3 of this memo - Published specification: this memo - Person & email address to contact for futher information: - See section 7 of this memo - Intended usage: OBSOLETE - Owner/Change controller: See section 7 of this memo - - -5. - References - - -5.1. - Normative References - - - [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", Harvard University, RFC 2119, March 1997. - - - [SASL] Melnikov, A., Ed., "Simple Authentication and Security Layer - (SASL)", Isode, draft-ietf-sasl-rfc2222bis-xx.txt, Work In - Progress. - - - - -Expires: March 2, 2004 Murchison [Page 4] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - -5.2. Informative References - - - [PLAIN] Zeilenga, Kurt D., Ed., "The Plain SASL Mechanism", - OpenLDAP Foundation, draft-ietf-sasl-plain-xx.txt, Work In - Progress. - - - [SMTP-AUTH] Myers, J., "SMTP Service Extension for Authentication", - Netscape Communications, RFC 2554, March 1999. - - - [SMTP-TLS] Hoffman, P., "SMTP Service Extension for Secure SMTP - over Transport Layer Security", Internet Mail Consortium, RFC - 3207, February 2002. - - - -6. Acknowledgments - - Thanks to Rob Siemborski for his input and feedback on this document. - - -7. - Author's Address - - Kenneth Murchison - Oceana Matrix Ltd. - 21 Princeton Place - Orchard Park, NY 14127 - - Phone: (716) 662-8973 - - EMail: ken@oceana.com - - - - - Mark R. Crispin - Networks and Distributed Computing - University of Washington - 4545 15th Avenue NE - Seattle, WA 98105-4527 - - Phone: (206) 543-5762 - - EMail: MRC@CAC.Washington.EDU - - - - -Expires: March 2, 2004 Murchison [Page 5] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - -8. - Intellectual Property Considerations - - The IETF takes no position regarding the validity or scope of any - intellectual property or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; neither does it represent that it has - made any effort to identify any such rights. Information on the - IETF's procedures with respect to rights in standards-track and - standards-related documentation can be found in BCP-11. Copies of - claims of rights made available for publication and any assurances of - licenses to be made available, or the result of an attempt made to - obtain a general license or permission for the use of such proprietary - rights by implementors or users of this specification can be obtained - from the IETF Secretariat. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights which may cover technology that may be required to practice - this standard. Please address the information to the IETF Executive - Director. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Expires: March 2, 2004 Murchison [Page 6] - -Internet Draft LOGIN SASL Mechanism August 28, 2004 - - -9. - Full Copyright Statement - - Copyright (C) The Internet Society 2003. 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. - - - - - - - - - - - - - - - - - - - - - - - - -Expires: March 2, 2004 Murchison [Page 7] - diff --git a/docs/rfc2221.txt b/docs/rfc2221.txt deleted file mode 100755 index 78f73c90..00000000 --- a/docs/rfc2221.txt +++ /dev/null @@ -1,284 +0,0 @@ - - - - - -Network Working Group M. Gahrns -Request for Comments: 2221 Microsoft -Category: Standards Track October 1997 - - - IMAP4 Login Referrals - -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. - -1. Abstract - - When dealing with large amounts of users and many IMAP4 [RFC-2060] - servers, it is often necessary to move users from one IMAP4 server to - another. For example, hardware failures or organizational changes - may dictate such a move. - - Login referrals allow clients to transparently connect to an - alternate IMAP4 server, if their home IMAP4 server has changed. - - A referral mechanism can provide efficiencies over the alternative - 'proxy method', in which the local IMAP4 server contacts the remote - server on behalf of the client, and then transfers the data from the - remote server to itself, and then on to the client. The referral - mechanism's direct client connection to the remote server is often a - more efficient use of bandwidth, and does not require the local - server to impersonate the client when authenticating to the remote - server. - -2. Conventions used in this document - - In examples, "C:" and "S:" indicate lines sent by the client and - server respectively. - - A home server, is an IMAP4 server that contains the user's inbox. - - A remote server is a server that contains remote mailboxes. - - - - - -Gahrns Standards Track [Page 1] - -RFC 2221 IMAP4 Login Referrals October 1997 - - - 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]. - -3. Introduction and Overview - - IMAP4 servers that support this extension MUST list the keyword - LOGIN-REFERRALS in their CAPABILITY response. No client action is - needed to invoke the LOGIN-REFERRALS capability in a server. - - A LOGIN-REFERRALS capable IMAP4 server SHOULD NOT return a referral - to a server that will return a referral. A client MUST NOT follow - more than 10 levels of referral without consulting the user. - - A LOGIN-REFERRALS response code MUST contain as an argument a valid - IMAP server URL as defined in [IMAP-URL]. - - A home server referral consists of either a tagged NO or OK, or an - untagged BYE response that contains a LOGIN-REFERRALS response code. - - Example: A001 NO [REFERRAL IMAP://user;AUTH=*@SERVER2/] Remote Server - - NOTE: user;AUTH=* is specified as required by [IMAP-URL] to avoid a - client falling back to anonymous login. - -4. Home Server Referrals - - A home server referral may be returned in response to an AUTHENTICATE - or LOGIN command, or it may appear in the connection startup banner. - If a server returns a home server referral in a tagged NO response, - that server does not contain any mailboxes that are accessible to the - user. If a server returns a home server referral in a tagged OK - response, it indicates that the user's personal mailboxes are - elsewhere, but the server contains public mailboxes which are - readable by the user. After receiving a home server referral, the - client can not make any assumptions as to whether this was a - permanent or temporary move of the user. - -4.1. LOGIN and AUTHENTICATE Referrals - - An IMAP4 server MAY respond to a LOGIN or AUTHENTICATE command with a - home server referral if it wishes to direct the user to another IMAP4 - server. - - Example: C: A001 LOGIN MIKE PASSWORD - S: A001 NO [REFERRAL IMAP://MIKE@SERVER2/] Specified user - is invalid on this server. Try SERVER2. - - - - -Gahrns Standards Track [Page 2] - -RFC 2221 IMAP4 Login Referrals October 1997 - - - Example: C: A001 LOGIN MATTHEW PASSWORD - S: A001 OK [REFERRAL IMAP://MATTHEW@SERVER2/] Specified - user's personal mailboxes located on Server2, but - public mailboxes are available. - - Example: C: A001 AUTHENTICATE GSSAPI - <authentication exchange> - S: A001 NO [REFERRAL IMAP://user;AUTH=GSSAPI@SERVER2/] - Specified user is invalid on this server. Try - SERVER2. - -4.2. BYE at connection startup referral - - An IMAP4 server MAY respond with an untagged BYE and a REFERRAL - response code that contains an IMAP URL to a home server if it is not - willing to accept connections and wishes to direct the client to - another IMAP4 server. - - Example: S: * BYE [REFERRAL IMAP://user;AUTH=*@SERVER2/] Server not - accepting connections. Try SERVER2 - -5. Formal Syntax - - The following syntax specification uses the augmented Backus-Naur - Form (BNF) as described in [ABNF]. - - This amends the "resp_text_code" element of the IMAP4 grammar - described in [RFC-2060] - - resp_text_code =/ "REFERRAL" SPACE <imapurl> - ; See [IMAP-URL] for definition of <imapurl> - ; See [RFC-2060] for base definition of resp_text_code - -6. Security Considerations - - The IMAP4 login referral mechanism makes use of IMAP URLs, and as - such, have the same security considerations as general internet URLs - [RFC-1738], and in particular IMAP URLs [IMAP-URL]. - - A server MUST NOT give a login referral if authentication for that - user fails. This is to avoid revealing information about the user's - account to an unauthorized user. - - With the LOGIN-REFERRALS capability, it is potentially easier to - write a rogue 'password catching' server that collects login data and - then refers the client to their actual IMAP4 server. Although - referrals reduce the effort to write such a server, the referral - response makes detection of the intrusion easier. - - - -Gahrns Standards Track [Page 3] - -RFC 2221 IMAP4 Login Referrals October 1997 - - -7. References - - [RFC-2060], Crispin, M., "Internet Message Access Protocol - Version - 4rev1", RFC 2060, December 1996. - - [IMAP-URL], Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, - September 1997. - - [RFC-1738], Berners-Lee, T., Masinter, L. and M. McCahill, "Uniform - Resource Locators (URL)", RFC 1738, December 1994. - - [RFC-2119], Bradner, S., "Key words for use in RFCs to Indicate - Requirement Levels", RFC 2119, March 1997. - - [ABNF], DRUMS working group, Dave Crocker Editor, "Augmented BNF for - Syntax Specifications: ABNF", Work in Progress. - -8. Acknowledgments - - Many valuable suggestions were received from private discussions and - the IMAP4 mailing list. In particular, Raymond Cheng, Mark Crispin, - Mark Keasling Chris Newman and Larry Osterman made significant - contributions to this document. - -9. Author's Address - - Mike Gahrns - Microsoft - One Microsoft Way - Redmond, WA, 98072 - - Phone: (206) 936-9833 - EMail: mikega@microsoft.com - - - - - - - - - - - - - - - - - - -Gahrns Standards Track [Page 4] - -RFC 2221 IMAP4 Login Referrals October 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 implmentation may be prepared, copied, published - andand 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." - - - - - - - - - - - - - - - - - - - - - - - - -Gahrns Standards Track [Page 5] - - - diff --git a/docs/rfc2298.txt b/docs/rfc2298.txt deleted file mode 100755 index 62836512..00000000 --- a/docs/rfc2298.txt +++ /dev/null @@ -1,1571 +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 <Joe_Recipient@mega.edu> - Message-Id: <199509200019.12345@mega.edu> - Subject: Disposition notification - To: Jane Sender <Jane_Sender@huge.com> - 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 <Joe_Recipient@mega.edu> 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 <IANA@IANA.ORG>. - -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/docs/rfc4086.txt b/docs/rfc4086.txt deleted file mode 100755 index 91041845..00000000 --- a/docs/rfc4086.txt +++ /dev/null @@ -1,2691 +0,0 @@ - - - - - - -Network Working Group D. Eastlake, 3rd -Request for Comments: 4086 Motorola Laboratories -BCP: 106 J. Schiller -Obsoletes: 1750 MIT -Category: Best Current Practice S. Crocker - June 2005 - - Randomness Requirements for Security - -Status of This Memo - - This document specifies an Internet Best Current Practices for the - Internet Community, and requests discussion and suggestions for - improvements. Distribution of this memo is unlimited. - -Copyright Notice - - Copyright (C) The Internet Society (2005). - -Abstract - - Security systems are built on strong cryptographic algorithms that - foil pattern analysis attempts. However, the security of these - systems is dependent on generating secret quantities for passwords, - cryptographic keys, and similar quantities. The use of pseudo-random - processes to generate secret quantities can result in pseudo- - security. A sophisticated attacker may find it easier to reproduce - the environment that produced the secret quantities and to search the - resulting small set of possibilities than to locate the quantities in - the whole of the potential number space. - - Choosing random quantities to foil a resourceful and motivated - adversary is surprisingly difficult. This document points out many - pitfalls in using poor entropy sources or traditional pseudo-random - number generation techniques for generating such quantities. It - recommends the use of truly random hardware techniques and shows that - the existing hardware on many systems can be used for this purpose. - It provides suggestions to ameliorate the problem when a hardware - solution is not available, and it gives examples of how large such - quantities need to be for some applications. - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 1] - -RFC 4086 Randomness Requirements for Security June 2005 - - -Table of Contents - - 1. Introduction and Overview .......................................3 - 2. General Requirements ............................................4 - 3. Entropy Sources .................................................7 - 3.1. Volume Required ............................................7 - 3.2. Existing Hardware Can Be Used For Randomness ...............8 - 3.2.1. Using Existing Sound/Video Input ....................8 - 3.2.2. Using Existing Disk Drives ..........................8 - 3.3. Ring Oscillator Sources ....................................9 - 3.4. Problems with Clocks and Serial Numbers ...................10 - 3.5. Timing and Value of External Events .......................11 - 3.6. Non-hardware Sources of Randomness ........................12 - 4. De-skewing .....................................................12 - 4.1. Using Stream Parity to De-Skew ............................13 - 4.2. Using Transition Mappings to De-Skew ......................14 - 4.3. Using FFT to De-Skew ......................................15 - 4.4. Using Compression to De-Skew ..............................15 - 5. Mixing .........................................................16 - 5.1. A Trivial Mixing Function .................................17 - 5.2. Stronger Mixing Functions .................................18 - 5.3. Using S-Boxes for Mixing ..................................19 - 5.4. Diffie-Hellman as a Mixing Function .......................19 - 5.5. Using a Mixing Function to Stretch Random Bits ............20 - 5.6. Other Factors in Choosing a Mixing Function ...............20 - 6. Pseudo-random Number Generators ................................21 - 6.1. Some Bad Ideas ............................................21 - 6.1.1. The Fallacy of Complex Manipulation ................21 - 6.1.2. The Fallacy of Selection from a Large Database .....22 - 6.1.3. Traditional Pseudo-random Sequences ................23 - 6.2. Cryptographically Strong Sequences ........................24 - 6.2.1. OFB and CTR Sequences ..............................25 - 6.2.2. The Blum Blum Shub Sequence Generator ..............26 - 6.3. Entropy Pool Techniques ...................................27 - 7. Randomness Generation Examples and Standards ...................28 - 7.1. Complete Randomness Generators ............................28 - 7.1.1. US DoD Recommendations for Password Generation .....28 - 7.1.2. The /dev/random Device .............................29 - 7.1.3. Windows CryptGenRandom .............................30 - 7.2. Generators Assuming a Source of Entropy ...................31 - 7.2.1. X9.82 Pseudo-Random Number Generation ..............31 - 7.2.2. X9.17 Key Generation ...............................33 - 7.2.3. DSS Pseudo-random Number Generation ................34 - 8. Examples of Randomness Required ................................34 - 8.1. Password Generation .......................................35 - 8.2. A Very High Security Cryptographic Key ....................36 - 9. Conclusion .....................................................38 - 10. Security Considerations ........................................38 - - - -Eastlake, et al. Standards Track [Page 2] - -RFC 4086 Randomness Requirements for Security June 2005 - - - 11. Acknowledgments ................................................39 - Appendix A: Changes from RFC 1750 ..................................40 - Informative References .............................................41 - -1. Introduction and Overview - - Software cryptography is coming into wider use, although there is a - long way to go until it becomes pervasive. Systems such as SSH, - IPSEC, TLS, S/MIME, PGP, DNSSEC, and Kerberos are maturing and - becoming a part of the network landscape [SSH] [IPSEC] [TLS] [S/MIME] - [MAIL_PGP*] [DNSSEC*]. For comparison, when the previous version of - this document [RFC1750] was issued in 1994, the only Internet - cryptographic security specification in the IETF was the Privacy - Enhanced Mail protocol [MAIL_PEM*]. - - These systems provide substantial protection against snooping and - spoofing. However, there is a potential flaw. At the heart of all - cryptographic systems is the generation of secret, unguessable (i.e., - random) numbers. - - The lack of generally available facilities for generating such random - numbers (that is, the lack of general availability of truly - unpredictable sources) forms an open wound in the design of - cryptographic software. For the software developer who wants to - build a key or password generation procedure that runs on a wide - range of hardware, this is a very real problem. - - Note that the requirement is for data that an adversary has a very - low probability of guessing or determining. This can easily fail if - pseudo-random data is used that meets only traditional statistical - tests for randomness, or that is based on limited-range sources such - as clocks. Sometimes such pseudo-random quantities can be guessed by - an adversary searching through an embarrassingly small space of - possibilities. - - This Best Current Practice document describes techniques for - producing random quantities that will be resistant to attack. It - recommends that future systems include hardware random number - generation or provide access to existing hardware that can be used - for this purpose. It suggests methods for use if such hardware is - not available, and it gives some estimates of the number of random - bits required for sample applications. - - - - - - - - - -Eastlake, et al. Standards Track [Page 3] - -RFC 4086 Randomness Requirements for Security June 2005 - - -2. General Requirements - - Today, a commonly encountered randomness requirement is to pick a - user password, usually a simple character string. Obviously, a - password that can be guessed does not provide security. For re- - usable passwords, it is desirable that users be able to remember the - password. This may make it advisable to use pronounceable character - strings or phrases composed of ordinary words. But this affects only - the format of the password information, not the requirement that the - password be very hard to guess. - - Many other requirements come from the cryptographic arena. - Cryptographic techniques can be used to provide a variety of - services, including confidentiality and authentication. Such - services are based on quantities, traditionally called "keys", that - are unknown to and unguessable by an adversary. - - There are even TCP/IP protocol uses for randomness in picking initial - sequence numbers [RFC1948]. - - Generally speaking, the above examples also illustrate two different - types of random quantities that may be wanted. In the case of - human-usable passwords, the only important characteristic is that - they be unguessable. It is not important that they may be composed - of ASCII characters, so the top bit of every byte is zero, for - example. On the other hand, for fixed length keys and the like, one - normally wants quantities that appear to be truly random, that is, - quantities whose bits will pass statistical randomness tests. - - In some cases, such as the use of symmetric encryption with the one- - time pads or an algorithm like the US Advanced Encryption Standard - [AES], the parties who wish to communicate confidentially and/or with - authentication must all know the same secret key. In other cases, - where asymmetric or "public key" cryptographic techniques are used, - keys come in pairs. One key of the pair is private and must be kept - secret by one party; the other is public and can be published to the - world. It is computationally infeasible to determine the private key - from the public key, and knowledge of the public key is of no help to - an adversary [ASYMMETRIC]. See general references [SCHNEIER, - FERGUSON, KAUFMAN]. - - The frequency and volume of the requirement for random quantities - differs greatly for different cryptographic systems. With pure RSA, - random quantities are required only when a new key pair is generated; - thereafter, any number of messages can be signed without a further - need for randomness. The public key Digital Signature Algorithm - devised by the US National Institute of Standards and Technology - (NIST) requires good random numbers for each signature [DSS]. And - - - -Eastlake, et al. Standards Track [Page 4] - -RFC 4086 Randomness Requirements for Security June 2005 - - - encrypting with a one-time pad (in principle the strongest possible - encryption technique) requires randomness of equal volume to all the - messages to be processed. See general references [SCHNEIER, - FERGUSON, KAUFMAN]. - - In most of these cases, an adversary can try to determine the - "secret" key by trial and error. This is possible as long as the key - is enough smaller than the message that the correct key can be - uniquely identified. The probability of an adversary succeeding at - this must be made acceptably low, depending on the particular - application. The size of the space the adversary must search is - related to the amount of key "information" present, in an - information-theoretic sense [SHANNON]. This depends on the number of - different secret values possible and the probability of each value, - as follows: - - ----- - \ - Bits of information = \ - p * log ( p ) - / i 2 i - / - ----- - - where i counts from 1 to the number of possible secret values and p - sub i is the probability of the value numbered i. (Because p sub i - is less than one, the log will be negative, so each term in the sum - will be non-negative.) - - If there are 2^n different values of equal probability, then n bits - of information are present and an adversary would have to try, on the - average, half of the values, or 2^(n-1), before guessing the secret - quantity. If the probability of different values is unequal, then - there is less information present, and fewer guesses will, on - average, be required by an adversary. In particular, any values that - an adversary can know to be impossible or of low probability can be - initially ignored by the adversary, who will search through the more - probable values first. - - For example, consider a cryptographic system that uses 128-bit keys. - If these keys are derived using a fixed pseudo-random number - generator that is seeded with an 8-bit seed, then an adversary needs - to search through only 256 keys (by running the pseudo-random number - generator with every possible seed), not 2^128 keys as may at first - appear to be the case. Only 8 bits of "information" are in these - 128-bit keys. - - - - - - -Eastlake, et al. Standards Track [Page 5] - -RFC 4086 Randomness Requirements for Security June 2005 - - - While the above analysis is correct on average, it can be misleading - in some cases for cryptographic analysis where what is really - important is the work factor for an adversary. For example, assume - that there is a pseudo-random number generator generating 128-bit - keys, as in the previous paragraph, but that it generates zero half - of the time and a random selection from the remaining 2^128 - 1 - values the rest of the time. The Shannon equation above says that - there are 64 bits of information in one of these key values, but an - adversary, simply by trying the value zero, can break the security of - half of the uses, albeit a random half. Thus, for cryptographic - purposes, it is also useful to look at other measures, such as min- - entropy, defined as - - Min-entropy = - log ( maximum ( p ) ) - i - - where i is as above. Using this equation, we get 1 bit of min- - entropy for our new hypothetical distribution, as opposed to 64 bits - of classical Shannon entropy. - - A continuous spectrum of entropies, sometimes called Renyi entropy, - has been defined, specified by the parameter r. Here r = 1 is - Shannon entropy and r = infinity is min-entropy. When r = zero, it - is just log (n), where n is the number of non-zero probabilities. - Renyi entropy is a non-increasing function of r, so min-entropy is - always the most conservative measure of entropy and usually the best - to use for cryptographic evaluation [LUBY]. - - Statistically tested randomness in the traditional sense is NOT the - same as the unpredictability required for security use. - - For example, the use of a widely available constant sequence, such as - the random table from the CRC Standard Mathematical Tables, is very - weak against an adversary. An adversary who learns of or guesses it - can easily break all security, future and past, based on the sequence - [CRC]. As another example, using AES with a constant key to encrypt - successive integers such as 1, 2, 3, ... will produce output that - also has excellent statistical randomness properties but is - predictable. On the other hand, taking successive rolls of a six- - sided die and encoding the resulting values in ASCII would produce - statistically poor output with a substantial unpredictable component. - So note that passing or failing statistical tests doesn't reveal - whether something is unpredictable or predictable. - - - - - - - - -Eastlake, et al. Standards Track [Page 6] - -RFC 4086 Randomness Requirements for Security June 2005 - - -3. Entropy Sources - - Entropy sources tend to be very implementation dependent. Once one - has gathered sufficient entropy, it can be used as the seed to - produce the required amount of cryptographically strong pseudo- - randomness, as described in Sections 6 and 7, after being de-skewed - or mixed as necessary, as described in Sections 4 and 5. - - Is there any hope for true, strong, portable randomness in the - future? There might be. All that's needed is a physical source of - unpredictable numbers. - - Thermal noise (sometimes called Johnson noise in integrated circuits) - or a radioactive decay source and a fast, free-running oscillator - would do the trick directly [GIFFORD]. This is a trivial amount of - hardware, and it could easily be included as a standard part of a - computer system's architecture. Most audio (or video) input devices - are usable [TURBID]. Furthermore, any system with a spinning disk or - ring oscillator and a stable (crystal) time source or the like has an - adequate source of randomness ([DAVIS] and Section 3.3). All that's - needed is the common perception among computer vendors that this - small additional hardware and the software to access it is necessary - and useful. - - ANSI X9 is currently developing a standard that includes a part - devoted to entropy sources. See Part 2 of [X9.82]. - -3.1. Volume Required - - How much unpredictability is needed? Is it possible to quantify the - requirement in terms of, say, number of random bits per second? - - The answer is that not very much is needed. For AES, the key can be - 128 bits, and, as we show in an example in Section 8, even the - highest security system is unlikely to require strong keying material - of much over 200 bits. If a series of keys is needed, they can be - generated from a strong random seed (starting value) using a - cryptographically strong sequence, as explained in Section 6.2. A - few hundred random bits generated at start-up or once a day is enough - if such techniques are used. Even if the random bits are generated - as slowly as one per second and it is not possible to overlap the - generation process, it should be tolerable in most high-security - applications to wait 200 seconds occasionally. - - These numbers are trivial to achieve. It could be achieved by a - person repeatedly tossing a coin, and almost any hardware based - process is likely to be much faster. - - - - -Eastlake, et al. Standards Track [Page 7] - -RFC 4086 Randomness Requirements for Security June 2005 - - -3.2. Existing Hardware Can Be Used For Randomness - - As described below, many computers come with hardware that can, with - care, be used to generate truly random quantities. - -3.2.1. Using Existing Sound/Video Input - - Many computers are built with inputs that digitize some real-world - analog source, such as sound from a microphone or video input from a - camera. The "input" from a sound digitizer with no source plugged in - or from a camera with the lens cap on is essentially thermal noise. - If the system has enough gain to detect anything, such input can - provide reasonably high quality random bits. This method is - extremely dependent on the hardware implementation. - - For example, on some UNIX-based systems, one can read from the - /dev/audio device with nothing plugged into the microphone jack or - with the microphone receiving only low level background noise. Such - data is essentially random noise, although it should not be trusted - without some checking, in case of hardware failure, and it will have - to be de-skewed. - - Combining this approach with compression to de-skew (see Section 4), - one can generate a huge amount of medium-quality random data with the - UNIX-style command line: - - cat /dev/audio | compress - >random-bits-file - - A detailed examination of this type of randomness source appears in - [TURBID]. - -3.2.2. Using Existing Disk Drives - - Disk drives have small random fluctuations in their rotational speed - due to chaotic air turbulence [DAVIS, Jakobsson]. The addition of - low-level disk seek-time instrumentation produces a series of - measurements that contain this randomness. Such data is usually - highly correlated, so significant processing is needed, as described - in Section 5.2 below. Nevertheless, experimentation a decade ago - showed that, with such processing, even slow disk drives on the - slower computers of that day could easily produce 100 bits a minute - or more of excellent random data. - - Every increase in processor speed, which increases the resolution - with which disk motion can be timed or increases the rate of disk - seeks, increases the rate of random bit generation possible with this - technique. At the time of this paper and with modern hardware, a - more typical rate of random bit production would be in excess of - - - -Eastlake, et al. Standards Track [Page 8] - -RFC 4086 Randomness Requirements for Security June 2005 - - - 10,000 bits a second. This technique is used in random number - generators included in many operating system libraries. - - Note: the inclusion of cache memories in disk controllers has little - effect on this technique if very short seek times, which represent - cache hits, are simply ignored. - -3.3. Ring Oscillator Sources - - If an integrated circuit is being designed or field-programmed, an - odd number of gates can be connected in series to produce a free- - running ring oscillator. By sampling a point in the ring at a fixed - frequency (for example, one determined by a stable crystal - oscillator), some amount of entropy can be extracted due to - variations in the free-running oscillator timing. It is possible to - increase the rate of entropy by XOR'ing sampled values from a few - ring oscillators with relatively prime lengths. It is sometimes - recommended that an odd number of rings be used so that, even if the - rings somehow become synchronously locked to each other, there will - still be sampled bit transitions. Another possible source to sample - is the output of a noisy diode. - - Sampled bits from such sources will have to be heavily de-skewed, as - disk rotation timings must be (see Section 4). An engineering study - would be needed to determine the amount of entropy being produced - depending on the particular design. In any case, these can be good - sources whose cost is a trivial amount of hardware by modern - standards. - - As an example, IEEE 802.11i suggests the circuit below, with due - attention in the design to isolation of the rings from each other and - from clocked circuits to avoid undesired synchronization, etc., and - with extensive post processing [IEEE_802.11i]. - - - - - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 9] - -RFC 4086 Randomness Requirements for Security June 2005 - - - |\ |\ |\ - +-->| >0-->| >0-- 19 total --| >0--+-------+ - | |/ |/ |/ | | - | | | - +----------------------------------+ V - +-----+ - |\ |\ |\ | | output - +-->| >0-->| >0-- 23 total --| >0--+--->| XOR |------> - | |/ |/ |/ | | | - | | +-----+ - +----------------------------------+ ^ ^ - | | - |\ |\ |\ | | - +-->| >0-->| >0-- 29 total --| >0--+------+ | - | |/ |/ |/ | | - | | | - +----------------------------------+ | - | - Other randomness, if available ---------+ - -3.4. Problems with Clocks and Serial Numbers - - Computer clocks and similar operating system or hardware values, - provide significantly fewer real bits of unpredictability than might - appear from their specifications. - - Tests have been done on clocks on numerous systems, and it was found - that their behavior can vary widely and in unexpected ways. One - version of an operating system running on one set of hardware may - actually provide, say, microsecond resolution in a clock, while a - different configuration of the "same" system may always provide the - same lower bits and only count in the upper bits at much lower - resolution. This means that successive reads of the clock may - produce identical values even if enough time has passed that the - value "should" change based on the nominal clock resolution. There - are also cases where frequently reading a clock can produce - artificial sequential values, because of extra code that checks for - the clock being unchanged between two reads and increases it by one! - Designing portable application code to generate unpredictable numbers - based on such system clocks is particularly challenging because the - system designer does not always know the properties of the system - clock. - - Use of a hardware serial number (such as an Ethernet MAC address) may - also provide fewer bits of uniqueness than one would guess. Such - quantities are usually heavily structured, and subfields may have - only a limited range of possible values, or values may be easily - guessable based on approximate date of manufacture or other data. - - - -Eastlake, et al. Standards Track [Page 10] - -RFC 4086 Randomness Requirements for Security June 2005 - - - For example, it is likely that a company that manufactures both - computers and Ethernet adapters will, at least internally, use its - own adapters, which significantly limits the range of built-in - addresses. - - Problems such as those described above make the production of code to - generate unpredictable quantities difficult if the code is to be - ported across a variety of computer platforms and systems. - -3.5. Timing and Value of External Events - - It is possible to measure the timing and content of mouse movement, - key strokes, and similar user events. This is a reasonable source of - unguessable data, with some qualifications. On some machines, input - such as key strokes is buffered. Even though the user's inter- - keystroke timing may have sufficient variation and unpredictability, - there might not be an easy way to access that variation. Another - problem is that no standard method exists for sampling timing - details. This makes it hard to use this technique to build standard - software intended for distribution to a large range of machines. - - The amount of mouse movement and the actual key strokes are usually - easier to access than timings, but they may yield less - unpredictability because the user may provide highly repetitive - input. - - Other external events, such as network packet arrival times and - lengths, can also be used, but only with great care. In particular, - the possibility of manipulation of such network traffic measurements - by an adversary and the lack of history at system start-up must be - carefully considered. If this input is subject to manipulation, it - must not be trusted as a source of entropy. - - In principle, almost any external sensor, such as raw radio reception - or temperature sensing in appropriately equipped computers, can be - used. But in each case, careful consideration must be given to how - much this data is subject to adversarial manipulation and to how much - entropy it can actually provide. - - The above techniques are quite powerful against attackers that have - no access to the quantities being measured. For example, these - techniques would be powerful against offline attackers who had no - access to one's environment and who were trying to crack one's random - seed after the fact. In all cases, the more accurately one can - measure the timing or value of an external sensor, the more rapidly - one can generate bits. - - - - - -Eastlake, et al. Standards Track [Page 11] - -RFC 4086 Randomness Requirements for Security June 2005 - - -3.6. Non-hardware Sources of Randomness - - The best source of input entropy would be a hardware-based random - source such as ring oscillators, disk drive timing, thermal noise, or - radioactive decay. However, if none of these is available, there are - other possibilities. These include system clocks, system or - input/output buffers, user/system/hardware/network serial numbers or - addresses and timing, and user input. Unfortunately, each of these - sources can produce very limited or predictable values under some - circumstances. - - Some of the sources listed above would be quite strong on multi-user - systems, where each user of the system is in essence a source of - randomness. However, on a small single-user or embedded system, - especially at start-up, it might be possible for an adversary to - assemble a similar configuration. This could give the adversary - inputs to the mixing process that were well-enough correlated to - those used originally to make exhaustive search practical. - - The use of multiple random inputs with a strong mixing function is - recommended and can overcome weakness in any particular input. The - timing and content of requested "random" user keystrokes can yield - hundreds of random bits, but conservative assumptions need to be - made. For example, one reasonably conservative assumption would be - that an inter-keystroke interval provides at most a few bits of - randomness, but only when the interval is unique in the sequence of - intervals up to that point. A similar assumption would be that a key - code provides a few bits of randomness, but only when the code is - unique in the sequence. Thus, an interval or key code that - duplicated a previous value would be assumed to provide no additional - randomness. The results of mixing these timings with typed - characters could be further combined with clock values and other - inputs. - - This strategy may make practical portable code for producing good - random numbers for security, even if some of the inputs are very weak - on some of the target systems. However, it may still fail against a - high-grade attack on small, single-user, or embedded systems, - especially if the adversary has ever been able to observe the - generation process in the past. A hardware-based random source is - still preferable. - -4. De-skewing - - Is there any specific requirement on the shape of the distribution of - quantities gathered for the entropy to produce the random numbers? - The good news is that the distribution need not be uniform. All that - is needed to bound performance is a conservative estimate of how - - - -Eastlake, et al. Standards Track [Page 12] - -RFC 4086 Randomness Requirements for Security June 2005 - - - non-uniform it is. Simple techniques to de-skew a bit stream are - given below, and stronger cryptographic techniques are described in - Section 5.2. - -4.1. Using Stream Parity to De-Skew - - As a simple but not particularly practical example, consider taking a - sufficiently long string of bits and mapping the string to "zero" or - "one". The mapping will not yield a perfectly uniform distribution, - but it can be as close as desired. One mapping that serves the - purpose is to take the parity of the string. This has the advantages - that it is robust across all degrees of skew up to the estimated - maximum skew and that it is trivial to implement in hardware. - - The following analysis gives the number of bits that must be sampled: - - Suppose that the ratio of ones to zeros is ( 0.5 + E ) to - ( 0.5 - E ), where E is between 0 and 0.5 and is a measure of the - "eccentricity" of the distribution. Consider the distribution of the - parity function of N bit samples. The respective probabilities that - the parity will be one or zero will be the sum of the odd or even - terms in the binomial expansion of (p + q)^N, where p = 0.5 + E, the - probability of a one, and q = 0.5 - E, the probability of a zero. - - These sums can be computed easily as - - N N - 1/2 * ( ( p + q ) + ( p - q ) ) - - and - N N - 1/2 * ( ( p + q ) - ( p - q ) ). - - (Which formula corresponds to the probability that the parity will be - 1 depends on whether N is odd or even.) - - Since p + q = 1 and p - q = 2E, these expressions reduce to - - N - 1/2 * [1 + (2E) ] - - and - N - 1/2 * [1 - (2E) ]. - - Neither of these will ever be exactly 0.5 unless E is zero, but we - can bring them arbitrarily close to 0.5. If we want the - probabilities to be within some delta d of 0.5, e.g., then - - - -Eastlake, et al. Standards Track [Page 13] - -RFC 4086 Randomness Requirements for Security June 2005 - - - N - ( 0.5 + ( 0.5 * (2E) ) ) < 0.5 + d. - - Solving for N yields N > log(2d)/log(2E). (Note that 2E is less than - 1, so its log is negative. Division by a negative number reverses - the sense of an inequality.) - - The following table gives the length N of the string that must be - sampled for various degrees of skew in order to come within 0.001 of - a 50/50 distribution. - - +---------+--------+-------+ - | Prob(1) | E | N | - +---------+--------+-------+ - | 0.5 | 0.00 | 1 | - | 0.6 | 0.10 | 4 | - | 0.7 | 0.20 | 7 | - | 0.8 | 0.30 | 13 | - | 0.9 | 0.40 | 28 | - | 0.95 | 0.45 | 59 | - | 0.99 | 0.49 | 308 | - +---------+--------+-------+ - - The last entry shows that even if the distribution is skewed 99% in - favor of ones, the parity of a string of 308 samples will be within - 0.001 of a 50/50 distribution. But, as we shall see in section 5.2, - there are much stronger techniques that extract more of the available - entropy. - -4.2. Using Transition Mappings to De-Skew - - Another technique, originally due to von Neumann [VON_NEUMANN], is to - examine a bit stream as a sequence of non-overlapping pairs. One - could then discard any 00 or 11 pairs found, interpret 01 as a 0 and - 10 as a 1. Assume that the probability of a 1 is 0.5+E and that the - probability of a 0 is 0.5-E, where E is the eccentricity of the - source as described in the previous section. Then the probability of - each pair is shown in the following table: - - +------+-----------------------------------------+ - | pair | probability | - +------+-----------------------------------------+ - | 00 | (0.5 - E)^2 = 0.25 - E + E^2 | - | 01 | (0.5 - E)*(0.5 + E) = 0.25 - E^2 | - | 10 | (0.5 + E)*(0.5 - E) = 0.25 - E^2 | - | 11 | (0.5 + E)^2 = 0.25 + E + E^2 | - +------+-----------------------------------------+ - - - - -Eastlake, et al. Standards Track [Page 14] - -RFC 4086 Randomness Requirements for Security June 2005 - - - This technique will completely eliminate any bias but requires an - indeterminate number of input bits for any particular desired number - of output bits. The probability of any particular pair being - discarded is 0.5 + 2E^2, so the expected number of input bits to - produce X output bits is X/(0.25 - E^2). - - This technique assumes that the bits are from a stream where each bit - has the same probability of being a 0 or 1 as any other bit in the - stream and that bits are uncorrelated, i.e., that the bits come from - identical independent distributions. If alternate bits are from two - correlated sources, for example, the above analysis breaks down. - - The above technique also provides another illustration of how a - simple statistical analysis can mislead if one is not always on the - lookout for patterns that could be exploited by an adversary. If the - algorithm were misread slightly so that overlapping successive bits - pairs were used instead of non-overlapping pairs, the statistical - analysis given would be the same. However, instead of providing an - unbiased, uncorrelated series of random 1s and 0s, it would produce a - totally predictable sequence of exactly alternating 1s and 0s. - -4.3. Using FFT to De-Skew - - When real-world data consists of strongly correlated bits, it may - still contain useful amounts of entropy. This entropy can be - extracted through various transforms, the most powerful of which are - described in section 5.2 below. - - Using the Fourier transform of the data or its optimized variant, the - FFT, is interesting primarily for theoretical reasons. It can be - shown that this technique will discard strong correlations. If - adequate data is processed and if remaining correlations decay, - spectral lines that approach statistical independence and normally - distributed randomness can be produced [BRILLINGER]. - -4.4. Using Compression to De-Skew - - Reversible compression techniques also provide a crude method of de- - skewing a skewed bit stream. This follows directly from the - definition of reversible compression and the formula in Section 2 for - the amount of information in a sequence. Since the compression is - reversible, the same amount of information must be present in the - shorter output as was present in the longer input. By the Shannon - information equation, this is only possible if, on average, the - probabilities of the different shorter sequences are more uniformly - distributed than were the probabilities of the longer sequences. - Therefore, the shorter sequences must be de-skewed relative to the - input. - - - -Eastlake, et al. Standards Track [Page 15] - -RFC 4086 Randomness Requirements for Security June 2005 - - - However, many compression techniques add a somewhat predictable - preface to their output stream and may insert a similar sequence - periodically in their output or otherwise introduce subtle patterns - of their own. They should be considered only rough techniques - compared to those described in Section 5.2. At a minimum, the - beginning of the compressed sequence should be skipped and only later - bits should used for applications requiring roughly-random bits. - -5. Mixing - - What is the best overall strategy for obtaining unguessable random - numbers in the absence of a strong, reliable hardware entropy source? - It is to obtain input from a number of uncorrelated sources and to - mix them with a strong mixing function. Such a function will - preserve the entropy present in any of the sources, even if other - quantities being combined happen to be fixed or easily guessable (low - entropy). This approach may be advisable even with a good hardware - source, as hardware can also fail. However, this should be weighed - against a possible increase in the chance of overall failure due to - added software complexity. - - Once one has used good sources, such as some of those listed in - Section 3, and mixed them as described in this section, one has a - strong seed. This can then be used to produce large quantities of - cryptographically strong material as described in Sections 6 and 7. - - A strong mixing function is one that combines inputs and produces an - output in which each output bit is a different complex non-linear - function of all the input bits. On average, changing any input bit - will change about half the output bits. But because the relationship - is complex and non-linear, no particular output bit is guaranteed to - change when any particular input bit is changed. - - Consider the problem of converting a stream of bits that is skewed - towards 0 or 1 or which has a somewhat predictable pattern to a - shorter stream which is more random, as discussed in Section 4. This - is simply another case where a strong mixing function is desired, to - mix the input bits and produce a smaller number of output bits. The - technique given in Section 4.1, using the parity of a number of bits, - is simply the result of successively XORing them. This is examined - as a trivial mixing function, immediately below. Use of stronger - mixing functions to extract more of the randomness in a stream of - skewed bits is examined in Section 5.2. See also [NASLUND]. - - - - - - - - -Eastlake, et al. Standards Track [Page 16] - -RFC 4086 Randomness Requirements for Security June 2005 - - -5.1. A Trivial Mixing Function - - For expository purposes we describe a trivial example for single bit - inputs using the Exclusive Or (XOR) function. This function is - equivalent to addition without carry, as show in the table below. - This is a degenerate case in which the one output bit always changes - for a change in either input bit. But, despite its simplicity, it - provides a useful illustration. - - +-----------+-----------+----------+ - | input 1 | input 2 | output | - +-----------+-----------+----------+ - | 0 | 0 | 0 | - | 0 | 1 | 1 | - | 1 | 0 | 1 | - | 1 | 1 | 0 | - +-----------+-----------+----------+ - - If inputs 1 and 2 are uncorrelated and combined in this fashion, then - the output will be an even better (less skewed) random bit than the - inputs are. If we assume an "eccentricity" E as defined in Section - 4.1 above, then the output eccentricity relates to the input - eccentricity as follows: - - E = 2 * E * E - output input 1 input 2 - - Since E is never greater than 1/2, the eccentricity is always - improved, except in the case in which at least one input is a totally - skewed constant. This is illustrated in the following table, where - the top and left side values are the two input eccentricities and the - entries are the output eccentricity: - - +--------+--------+--------+--------+--------+--------+--------+ - | E | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | - +--------+--------+--------+--------+--------+--------+--------+ - | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | 0.00 | - | 0.10 | 0.00 | 0.02 | 0.04 | 0.06 | 0.08 | 0.10 | - | 0.20 | 0.00 | 0.04 | 0.08 | 0.12 | 0.16 | 0.20 | - | 0.30 | 0.00 | 0.06 | 0.12 | 0.18 | 0.24 | 0.30 | - | 0.40 | 0.00 | 0.08 | 0.16 | 0.24 | 0.32 | 0.40 | - | 0.50 | 0.00 | 0.10 | 0.20 | 0.30 | 0.40 | 0.50 | - +--------+--------+--------+--------+--------+--------+--------+ - - However, note that the above calculations assume that the inputs are - not correlated. If the inputs were, say, the parity of the number of - minutes from midnight on two clocks accurate to a few seconds, then - each might appear random if sampled at random intervals much longer - - - -Eastlake, et al. Standards Track [Page 17] - -RFC 4086 Randomness Requirements for Security June 2005 - - - than a minute. Yet if they were both sampled and combined with XOR, - the result would be zero most of the time. - -5.2. Stronger Mixing Functions - - The US Government Advanced Encryption Standard [AES] is an example of - a strong mixing function for multiple bit quantities. It takes up to - 384 bits of input (128 bits of "data" and 256 bits of "key") and - produces 128 bits of output, each of which is dependent on a complex - non-linear function of all input bits. Other encryption functions - with this characteristic, such as [DES], can also be used by - considering them to mix all of their key and data input bits. - - Another good family of mixing functions is the "message digest" or - hashing functions such as the US Government Secure Hash Standards - [SHA*] and the MD4, MD5 [MD4, MD5] series. These functions all take - a practically unlimited amount of input and produce a relatively - short fixed-length output mixing all the input bits. The MD* series - produces 128 bits of output, SHA-1 produces 160 bits, and other SHA - functions produce up to 512 bits. - - Although the message digest functions are designed for variable - amounts of input, AES and other encryption functions can also be used - to combine any number of inputs. If 128 bits of output is adequate, - the inputs can be packed into a 128-bit data quantity and successive - AES "keys", padding with zeros if needed; the quantity is then - successively encrypted by the "keys" using AES in Electronic Codebook - Mode. Alternatively, the input could be packed into one 128-bit key - and multiple data blocks and a CBC-MAC could be calculated [MODES]. - - More complex mixing should be used if more than 128 bits of output - are needed and one wants to employ AES (but note that it is - absolutely impossible to get more bits of "randomness" out than are - put in). For example, suppose that inputs are packed into three - quantities, A, B, and C. One may use AES to encrypt A with B and - then with C as keys to produce the first part of the output, then - encrypt B with C and then A for more output and, if necessary, - encrypt C with A and then B for yet more output. Still more output - can be produced by reversing the order of the keys given above. The - same can be done with the hash functions, hashing various subsets of - the input data or different copies of the input data with different - prefixes and/or suffixes to produce multiple outputs. - - For an example of using a strong mixing function, reconsider the case - of a string of 308 bits, each of which is biased 99% toward zero. - The parity technique given in Section 4.1 reduces this to one bit, - with only a 1/1000 deviance from being equally likely a zero or one. - But, applying the equation for information given in Section 2, this - - - -Eastlake, et al. Standards Track [Page 18] - -RFC 4086 Randomness Requirements for Security June 2005 - - - 308-bit skewed sequence contains over 5 bits of information. Thus, - hashing it with SHA-1 and taking the bottom 5 bits of the result - would yield 5 unbiased random bits and not the single bit given by - calculating the parity of the string. Alternatively, for some - applications, you could use the entire hash output to retain almost - all of the 5+ bits of entropy in a 160-bit quantity. - -5.3. Using S-Boxes for Mixing - - Many modern block encryption functions, including DES and AES, - incorporate modules known as S-Boxes (substitution boxes). These - produce a smaller number of outputs from a larger number of inputs - through a complex non-linear mixing function that has the effect of - concentrating limited entropy from the inputs into the output. - - S-Boxes sometimes incorporate bent Boolean functions (functions of an - even number of bits producing one output bit with maximum non- - linearity). Looking at the output for all input pairs differing in - any particular bit position, exactly half the outputs are different. - An S-Box in which each output bit is produced by a bent function such - that any linear combination of these functions is also a bent - function is called a "perfect S-Box". - - S-boxes and various repeated applications or cascades of such boxes - can be used for mixing [SBOX1, SBOX2]. - -5.4. Diffie-Hellman as a Mixing Function - - Diffie-Hellman exponential key exchange is a technique that yields a - shared secret between two parties. It can be computationally - infeasible for a third party to determine this secret even if they - can observe all the messages between the two communicating parties. - This shared secret is a mixture of initial quantities generated by - each of the parties [D-H]. - - If these initial quantities are random and uncorrelated, then the - shared secret combines their entropy but, of course, can not produce - more randomness than the size of the shared secret generated. - - Although this is true if the Diffie-Hellman computation is performed - privately, an adversary who can observe either of the public keys and - knows the modulus being used need only search through the space of - the other secret key in order to be able to calculate the shared - secret [D-H]. So, conservatively, it would be best to consider - public Diffie-Hellman to produce a quantity whose guessability - corresponds to the worse of the two inputs. Because of this and the - fact that Diffie-Hellman is computationally intensive, its use as a - mixing function is not recommended. - - - -Eastlake, et al. Standards Track [Page 19] - -RFC 4086 Randomness Requirements for Security June 2005 - - -5.5. Using a Mixing Function to Stretch Random Bits - - Although it is not necessary for a mixing function to produce the - same or fewer output bits than its inputs, mixing bits cannot - "stretch" the amount of random unpredictability present in the - inputs. Thus, four inputs of 32 bits each, in which there are 12 - bits worth of unpredictability (such as 4,096 equally probable - values) in each input, cannot produce more than 48 bits worth of - unpredictable output. The output can be expanded to hundreds or - thousands of bits by, for example, mixing with successive integers, - but the clever adversary's search space is still 2^48 possibilities. - Furthermore, mixing to fewer bits than are input will tend to - strengthen the randomness of the output. - - The last table in Section 5.1 shows that mixing a random bit with a - constant bit with Exclusive Or will produce a random bit. While this - is true, it does not provide a way to "stretch" one random bit into - more than one. If, for example, a random bit is mixed with a 0 and - then with a 1, this produces a two bit sequence but it will always be - either 01 or 10. Since there are only two possible values, there is - still only the one bit of original randomness. - -5.6. Other Factors in Choosing a Mixing Function - - For local use, AES has the advantages that it has been widely tested - for flaws, is reasonably efficient in software, and is widely - documented and implemented with hardware and software implementations - available all over the world including open source code. The SHA* - family have had a little less study and tend to require more CPU - cycles than AES but there is no reason to believe they are flawed. - Both SHA* and MD5 were derived from the earlier MD4 algorithm. They - all have source code available [SHA*, MD4, MD5]. Some signs of - weakness have been found in MD4 and MD5. In particular, MD4 has only - three rounds and there are several independent breaks of the first - two or last two rounds. And some collisions have been found in MD5 - output. - - AES was selected by a robust, public, and international process. It - and SHA* have been vouched for by the US National Security Agency - (NSA) on the basis of criteria that mostly remain secret, as was DES. - While this has been the cause of much speculation and doubt, - investigation of DES over the years has indicated that NSA - involvement in modifications to its design, which originated with - IBM, was primarily to strengthen it. There has been no announcement - of a concealed or special weakness being found in DES. It is likely - that the NSA modifications to MD4 to produce the SHA algorithms - similarly strengthened these algorithms, possibly against threats not - yet known in the public cryptographic community. - - - -Eastlake, et al. Standards Track [Page 20] - -RFC 4086 Randomness Requirements for Security June 2005 - - - Where input lengths are unpredictable, hash algorithms are more - convenient to use than block encryption algorithms since they are - generally designed to accept variable length inputs. Block - encryption algorithms generally require an additional padding - algorithm to accommodate inputs that are not an even multiple of the - block size. - - As of the time of this document, the authors know of no patent claims - to the basic AES, DES, SHA*, MD4, and MD5 algorithms other than - patents for which an irrevocable royalty free license has been - granted to the world. There may, of course, be essential patents of - which the authors are unaware or patents on implementations or uses - or other relevant patents issued or to be issued. - -6. Pseudo-random Number Generators - - When a seed has sufficient entropy, from input as described in - Section 3 and possibly de-skewed and mixed as described in Sections 4 - and 5, one can algorithmically extend that seed to produce a large - number of cryptographically-strong random quantities. Such - algorithms are platform independent and can operate in the same - fashion on any computer. For the algorithms to be secure, their - input and internal workings must be protected from adversarial - observation. - - The design of such pseudo-random number generation algorithms, like - the design of symmetric encryption algorithms, is not a task for - amateurs. Section 6.1 below lists a number of bad ideas that failed - algorithms have used. To learn what works, skip Section 6.1 and just - read the remainder of this section and Section 7, which describes and - references some standard pseudo random number generation algorithms. - See Section 7 and Part 3 of [X9.82]. - -6.1. Some Bad Ideas - - The subsections below describe a number of ideas that might seem - reasonable but that lead to insecure pseudo-random number generation. - -6.1.1. The Fallacy of Complex Manipulation - - One approach that may give a misleading appearance of - unpredictability is to take a very complex algorithm (or an excellent - traditional pseudo-random number generator with good statistical - properties) and to calculate a cryptographic key by starting with - limited data such as the computer system clock value as the seed. - Adversaries who knew roughly when the generator was started would - have a relatively small number of seed values to test, as they would - know likely values of the system clock. Large numbers of pseudo- - - - -Eastlake, et al. Standards Track [Page 21] - -RFC 4086 Randomness Requirements for Security June 2005 - - - random bits could be generated, but the search space that an - adversary would need to check could be quite small. - - Thus, very strong or complex manipulation of data will not help if - the adversary can learn what the manipulation is and if there is not - enough entropy in the starting seed value. They can usually use the - limited number of results stemming from a limited number of seed - values to defeat security. - - Another serious strategic error is to assume that a very complex - pseudo-random number generation algorithm will produce strong random - numbers, when there has been no theory behind or analysis of the - algorithm. There is a excellent example of this fallacy near the - beginning of Chapter 3 in [KNUTH], where the author describes a - complex algorithm. It was intended that the machine language program - corresponding to the algorithm would be so complicated that a person - trying to read the code without comments wouldn't know what the - program was doing. Unfortunately, actual use of this algorithm - showed that it almost immediately converged to a single repeated - value in one case and a small cycle of values in another case. - - Not only does complex manipulation not help you if you have a limited - range of seeds, but blindly-chosen complex manipulation can destroy - the entropy in a good seed! - -6.1.2. The Fallacy of Selection from a Large Database - - Another approach that can give a misleading appearance of - unpredictability is to randomly select a quantity from a database and - to assume that its strength is related to the total number of bits in - the database. For example, typical USENET servers process many - megabytes of information per day [USENET_1, USENET_2]. Assume that a - random quantity was selected by fetching 32 bytes of data from a - random starting point in this data. This does not yield 32*8 = 256 - bits worth of unguessability. Even if much of the data is human - language that contains no more than 2 or 3 bits of information per - byte, it doesn't yield 32*2 = 64 bits of unguessability. For an - adversary with access to the same Usenet database, the unguessability - rests only on the starting point of the selection. That is perhaps a - little over a couple of dozen bits of unguessability. - - The same argument applies to selecting sequences from the data on a - publicly available CD/DVD recording or any other large public - database. If the adversary has access to the same database, this - "selection from a large volume of data" step buys little. However, - if a selection can be made from data to which the adversary has no - access, such as system buffers on an active multi-user system, it may - be of help. - - - -Eastlake, et al. Standards Track [Page 22] - -RFC 4086 Randomness Requirements for Security June 2005 - - -6.1.3. Traditional Pseudo-random Sequences - - This section talks about traditional sources of deterministic or - "pseudo-random" numbers. These typically start with a "seed" - quantity and use simple numeric or logical operations to produce a - sequence of values. Note that none of the techniques discussed in - this section is suitable for cryptographic use. They are presented - for general information. - - [KNUTH] has a classic exposition on pseudo-random numbers. - Applications he mentions are simulations of natural phenomena, - sampling, numerical analysis, testing computer programs, decision - making, and games. None of these have the same characteristics as - the sorts of security uses we are talking about. Only in the last - two could there be an adversary trying to find the random quantity. - However, in these cases, the adversary normally has only a single - chance to use a guessed value. In guessing passwords or attempting - to break an encryption scheme, the adversary normally has many, - perhaps unlimited, chances at guessing the correct value. Sometimes - the adversary can store the message to be broken and repeatedly - attack it. Adversaries are also be assumed to be aided by a - computer. - - For testing the "randomness" of numbers, Knuth suggests a variety of - measures, including statistical and spectral. These tests check - things like autocorrelation between different parts of a "random" - sequence or distribution of its values. But these tests could be met - by a constant stored random sequence, such as the "random" sequence - printed in the CRC Standard Mathematical Tables [CRC]. Despite - meeting all the tests suggested by Knuth, that sequence is unsuitable - for cryptographic us, as adversaries must be assumed to have copies - of all commonly published "random" sequences and to be able to spot - the source and predict future values. - - A typical pseudo-random number generation technique is the linear - congruence pseudo-random number generator. This technique uses - modular arithmetic, where the value numbered N+1 is calculated from - the value numbered N by - - V = ( V * a + b )(Mod c) - N+1 N - - The above technique has a strong relationship to linear shift - register pseudo-random number generators, which are well understood - cryptographically [SHIFT*]. In such generators, bits are introduced - at one end of a shift register as the Exclusive Or (binary sum - without carry) of bits from selected fixed taps into the register. - For example, consider the following: - - - -Eastlake, et al. Standards Track [Page 23] - -RFC 4086 Randomness Requirements for Security June 2005 - - - +----+ +----+ +----+ +----+ - | B | <-- | B | <-- | B | <-- . . . . . . <-- | B | <-+ - | 0 | | 1 | | 2 | | n | | - +----+ +----+ +----+ +----+ | - | | | | - | | V +-----+ - | V +----------------> | | - V +-----------------------------> | XOR | - +---------------------------------------------------> | | - +-----+ - - V = ( ( V * 2 ) + B XOR B ... )(Mod 2^n) - N+1 N 0 2 - - The quality of traditional pseudo-random number generator algorithms - is measured by statistical tests on such sequences. Carefully-chosen - values a, b, c, and initial V or carefully-chosen placement of the - shift register tap in the above simple process can produce excellent - statistics. - - These sequences may be adequate in simulations (Monte Carlo - experiments) as long as the sequence is orthogonal to the structure - of the space being explored. Even there, subtle patterns may cause - problems. However, such sequences are clearly bad for use in - security applications. They are fully predictable if the initial - state is known. Depending on the form of the pseudo-random number - generator, the sequence may be determinable from observation of a - short portion of the sequence [SCHNEIER, STERN]. For example, with - the generators above, one can determine V(n+1) given knowledge of - V(n). In fact, it has been shown that with these techniques, even if - only one bit of the pseudo-random values are released, the seed can - be determined from short sequences. - - Not only have linear congruent generators been broken, but techniques - are now known for breaking all polynomial congruent generators - [KRAWCZYK]. - -6.2. Cryptographically Strong Sequences - - In cases where a series of random quantities must be generated, an - adversary may learn some values in the sequence. In general, - adversaries should not be able to predict other values from the ones - that they know. - - The correct technique is to start with a strong random seed, to take - cryptographically strong steps from that seed [FERGUSON, SCHNEIER], - and not to reveal the complete state of the generator in the sequence - elements. If each value in the sequence can be calculated in a fixed - - - -Eastlake, et al. Standards Track [Page 24] - -RFC 4086 Randomness Requirements for Security June 2005 - - - way from the previous value, then when any value is compromised, all - future values can be determined. This would be the case, for - example, if each value were a constant function of the previously - used values, even if the function were a very strong, non-invertible - message digest function. - - (Note that if a technique for generating a sequence of key values is - fast enough, it can trivially be used as the basis for a - confidentiality system. If two parties use the same sequence - generation technique and start with the same seed material, they will - generate identical sequences. These could, for example, be XOR'ed at - one end with data being sent to encrypt it, and XOR'ed with this data - as received to decrypt it, due to the reversible properties of the - XOR operation. This is commonly referred to as a simple stream - cipher.) - -6.2.1. OFB and CTR Sequences - - One way to produce a strong sequence is to take a seed value and hash - the quantities produced by concatenating the seed with successive - integers, or the like, and then to mask the values obtained so as to - limit the amount of generator state available to the adversary. - - It may also be possible to use an "encryption" algorithm with a - random key and seed value to encrypt successive integers, as in - counter (CTR) mode encryption. Alternatively, one can feedback all - of the output value from encryption into the value to be encrypted - for the next iteration. This is a particular example of output - feedback mode (OFB) [MODES]. - - An example is shown below in which shifting and masking are used to - combine part of the output feedback with part of the old input. This - type of partial feedback should be avoided for reasons described - below. - - - - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 25] - -RFC 4086 Randomness Requirements for Security June 2005 - - - +---------------+ - | V | - | | n |--+ - +--+------------+ | - | | +---------+ - shift| +---> | | +-----+ - +--+ | Encrypt | <--- | Key | - | +-------- | | +-----+ - | | +---------+ - V V - +------------+--+ - | V | | - | n+1 | - +---------------+ - - Note that if a shift of one is used, this is the same as the shift - register technique described in Section 6.1.3, but with the all- - important difference that the feedback is determined by a complex - non-linear function of all bits rather than by a simple linear or - polynomial combination of output from a few bit position taps. - - Donald W. Davies showed that this sort of shifted partial output - feedback significantly weakens an algorithm, compared to feeding all - the output bits back as input. In particular, for DES, repeatedly - encrypting a full 64-bit quantity will give an expected repeat in - about 2^63 iterations. Feeding back anything less than 64 (and more - than 0) bits will give an expected repeat in between 2^31 and 2^32 - iterations! - - To predict values of a sequence from others when the sequence was - generated by these techniques is equivalent to breaking the - cryptosystem or to inverting the "non-invertible" hashing with only - partial information available. The less information revealed in each - iteration, the harder it will be for an adversary to predict the - sequence. Thus it is best to use only one bit from each value. It - has been shown that in some cases this makes it impossible to break a - system even when the cryptographic system is invertible and could be - broken if all of each generated value were revealed. - -6.2.2. The Blum Blum Shub Sequence Generator - - Currently the generator which has the strongest public proof of - strength is called the Blum Blum Shub generator, named after its - inventors [BBS]. It is also very simple and is based on quadratic - residues. Its only disadvantage is that it is computationally - intensive compared to the traditional techniques given in Section - 6.1.3. This is not a major drawback if it is used for moderately- - infrequent purposes, such as generating session keys. - - - -Eastlake, et al. Standards Track [Page 26] - -RFC 4086 Randomness Requirements for Security June 2005 - - - Simply choose two large prime numbers (say, p and q) that each gives - a remainder of 3 when divided by 4. Let n = p * q. Then choose a - random number, x, that is relatively prime to n. The initial seed - for the generator and the method for calculating subsequent values - are then: - - 2 - s = ( x )(Mod n) - 0 - 2 - s = ( s )(Mod n) - i+1 i - - Be careful to use only a few bits from the bottom of each s. It is - always safe to use only the lowest-order bit. If one uses no more - than the: - - log ( log ( s ) ) - 2 2 i - - low-order bits, then predicting any additional bits from a sequence - generated in this manner is provably as hard as factoring n. As long - as the initial x is secret, n can be made public if desired. - - An interesting characteristic of this generator is that any of the s - values can be directly calculated. In particular, - - ( (2^i) (Mod ((p-1)*(q-1)) ) ) - s = ( s )(Mod n) - i 0 - - This means that in applications where many keys are generated in this - fashion, it is not necessary to save them all. Each key can be - effectively indexed and recovered from that small index and the - initial s and n. - -6.3. Entropy Pool Techniques - - Many modern pseudo-random number sources, such as those described in - Sections 7.1.2 and 7.1.3 utilize the technique of maintaining a - "pool" of bits and providing operations for strongly mixing input - with some randomness into the pool and extracting pseudo-random bits - from the pool. This is illustrated in the figure below. - - - - - - - - -Eastlake, et al. Standards Track [Page 27] - -RFC 4086 Randomness Requirements for Security June 2005 - - - +--------+ +------+ +---------+ - --->| Mix In |--->| POOL |--->| Extract |---> - | Bits | | | | Bits | - +--------+ +------+ +---------+ - ^ V - | | - +-----------+ - - Bits to be fed into the pool can come from any of the various - hardware, environmental, or user input sources discussed above. It - is also common to save the state of the pool on system shutdown and - to restore it on re-starting, when stable storage is available. - - Care must be taken that enough entropy has been added to the pool to - support particular output uses desired. See [RSA_BULL1] for similar - suggestions. - -7. Randomness Generation Examples and Standards - - Several public standards and widely deployed examples are now in - place for the generation of keys or other cryptographically random - quantities. Some, in section 7.1, include an entropy source. - Others, described in section 7.2, provide the pseudo-random number - strong-sequence generator but assume the input of a random seed or - input from a source of entropy. - -7.1. Complete Randomness Generators - - Three standards are described below. The two older standards use - DES, with its 64-bit block and key size limit, but any equally strong - or stronger mixing function could be substituted [DES]. The third is - a more modern and stronger standard based on SHA-1 [SHA*]. Lastly, - the widely deployed modern UNIX and Windows random number generators - are described. - -7.1.1. US DoD Recommendations for Password Generation - - The United States Department of Defense has specific recommendations - for password generation [DoD]. It suggests using the US Data - Encryption Standard [DES] in Output Feedback Mode [MODES] as follows: - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 28] - -RFC 4086 Randomness Requirements for Security June 2005 - - - Use an initialization vector determined from - the system clock, - system ID, - user ID, and - date and time; - use a key determined from - system interrupt registers, - system status registers, and - system counters; and, - as plain text, use an external randomly generated 64-bit - quantity such as the ASCII bytes for 8 characters typed - in by a system administrator. - - The password can then be calculated from the 64 bit "cipher text" - generated by DES in 64-bit Output Feedback Mode. As many bits as are - needed can be taken from these 64 bits and expanded into a - pronounceable word, phrase, or other format if a human being needs to - remember the password. - -7.1.2. The /dev/random Device - - Several versions of the UNIX operating system provide a kernel- - resident random number generator. Some of these generators use - events captured by the Kernel during normal system operation. - - For example, on some versions of Linux, the generator consists of a - random pool of 512 bytes represented as 128 words of 4 bytes each. - When an event occurs, such as a disk drive interrupt, the time of the - event is XOR'ed into the pool, and the pool is stirred via a - primitive polynomial of degree 128. The pool itself is treated as a - ring buffer, with new data being XOR'ed (after stirring with the - polynomial) across the entire pool. - - Each call that adds entropy to the pool estimates the amount of - likely true entropy the input contains. The pool itself contains a - accumulator that estimates the total over all entropy of the pool. - - Input events come from several sources, as listed below. - Unfortunately, for server machines without human operators, the first - and third are not available, and entropy may be added slowly in that - case. - - 1. Keyboard interrupts. The time of the interrupt and the scan code - are added to the pool. This in effect adds entropy from the human - operator by measuring inter-keystroke arrival times. - - 2. Disk completion and other interrupts. A system being used by a - person will likely have a hard-to-predict pattern of disk - - - -Eastlake, et al. Standards Track [Page 29] - -RFC 4086 Randomness Requirements for Security June 2005 - - - accesses. (But not all disk drivers support capturing this timing - information with sufficient accuracy to be useful.) - - 3. Mouse motion. The timing and mouse position are added in. - - When random bytes are required, the pool is hashed with SHA-1 [SHA*] - to yield the returned bytes of randomness. If more bytes are - required than the output of SHA-1 (20 bytes), then the hashed output - is stirred back into the pool and a new hash is performed to obtain - the next 20 bytes. As bytes are removed from the pool, the estimate - of entropy is correspondingly decremented. - - To ensure a reasonably random pool upon system startup, the standard - startup and shutdown scripts save the pool to a disk file at shutdown - and read this file at system startup. - - There are two user-exported interfaces. /dev/random returns bytes - from the pool but blocks when the estimated entropy drops to zero. - As entropy is added to the pool from events, more data becomes - available via /dev/random. Random data obtained from such a - /dev/random device is suitable for key generation for long term keys, - if enough random bits are in the pool or are added in a reasonable - amount of time. - - /dev/urandom works like /dev/random; however, it provides data even - when the entropy estimate for the random pool drops to zero. This - may be adequate for session keys or for other key generation tasks - for which blocking to await more random bits is not acceptable. The - risk of continuing to take data even when the pool's entropy estimate - is small in that past output may be computable from current output, - provided that an attacker can reverse SHA-1. Given that SHA-1 is - designed to be non-invertible, this is a reasonable risk. - - To obtain random numbers under Linux, Solaris, or other UNIX systems - equipped with code as described above, all an application has to do - is open either /dev/random or /dev/urandom and read the desired - number of bytes. - - (The Linux Random device was written by Theodore Ts'o. It was based - loosely on the random number generator in PGP 2.X and PGP 3.0 (aka - PGP 5.0).) - -7.1.3. Windows CryptGenRandom - - Microsoft's recommendation to users of the widely deployed Windows - operating system is generally to use the CryptGenRandom pseudo-random - number generation call with the CryptAPI cryptographic service - provider. This takes a handle to a cryptographic service provider - - - -Eastlake, et al. Standards Track [Page 30] - -RFC 4086 Randomness Requirements for Security June 2005 - - - library, a pointer to a buffer by which the caller can provide - entropy and into which the generated pseudo-randomness is returned, - and an indication of how many octets of randomness are desired. - - The Windows CryptAPI cryptographic service provider stores a seed - state variable with every user. When CryptGenRandom is called, this - is combined with any randomness provided in the call and with various - system and user data such as the process ID, thread ID, system clock, - system time, system counter, memory status, free disk clusters, and - hashed user environment block. This data is all fed to SHA-1, and - the output is used to seed an RC4 key stream. That key stream is - used to produce the pseudo-random data requested and to update the - user's seed state variable. - - Users of Windows ".NET" will probably find it easier to use the - RNGCryptoServiceProvider.GetBytes method interface. - - For further information, see [WSC]. - -7.2. Generators Assuming a Source of Entropy - - The pseudo-random number generators described in the following three - sections all assume that a seed value with sufficient entropy is - provided to them. They then generate a strong sequence (see Section - 6.2) from that seed. - -7.2.1. X9.82 Pseudo-Random Number Generation - - The ANSI X9F1 committee is in the final stages of creating a standard - for random number generation covering both true randomness generators - and pseudo-random number generators. It includes a number of - pseudo-random number generators based on hash functions, one of which - will probably be based on HMAC SHA hash constructs [RFC2104]. The - draft version of this generator is described below, omitting a number - of optional features [X9.82]. - - In the subsections below, the HMAC hash construct is simply referred - to as HMAC but, of course, a particular standard SHA function must be - selected in an particular use. Generally speaking, if the strength - of the pseudo-random values to be generated is to be N bits, the SHA - function chosen must generate N or more bits of output, and a source - of at least N bits of input entropy will be required. The same hash - function must be used throughout an instantiation of this generator. - - - - - - - - -Eastlake, et al. Standards Track [Page 31] - -RFC 4086 Randomness Requirements for Security June 2005 - - -7.2.1.1. Notation - - In the following sections, the notation give below is used: - - hash_length is the output size of the underlying hash function in - use. - - input_entropy is the input bit string that provides entropy to the - generator. - - K is a bit string of size hash_length that is part of the state of - the generator and is updated at least once each time random - bits are generated. - - V is a bit string of size hash_length and is part of the state of - the generator. It is updated each time hash_length bits of - output are generated. - - "|" represents concatenation. - -7.2.1.2. Initializing the Generator - - Set V to all zero bytes, except the low-order bit of each byte is set - to one. - - Set K to all zero bytes, then set: - - K = HMAC ( K, V | 0x00 | input_entropy ) - - V = HMAC ( K, V ) - - K = HMAC ( K, V | 0x01 | input_entropy ) - - V = HMAC ( K, V ) - - Note: All SHA algorithms produce an integral number of bytes, so the - lengths of K and V will be integral numbers of bytes. - -7.2.1.3. Generating Random Bits - - When output is called for, simply set: - - V = HMAC ( K, V ) - - and use the leading bits from V. If more bits are needed than the - length of V, set "temp" to a null bit string and then repeatedly - perform: - - - - -Eastlake, et al. Standards Track [Page 32] - -RFC 4086 Randomness Requirements for Security June 2005 - - - V = HMAC ( K, V ) - temp = temp | V - - stopping as soon as temp is equal to or longer than the number of - random bits requested. Use the requested number of leading bits from - temp. The definition of the algorithm prohibits requesting more than - 2^35 bits. - - After extracting and saving the pseudo-random output bits as - described above, before returning you must also perform two more - HMACs as follows: - - K = HMAC ( K, V | 0x00 ) - V = HMAC ( K, V ) - -7.2.2. X9.17 Key Generation - - The American National Standards Institute has specified the - following method for generating a sequence of keys [X9.17]: - - s is the initial 64 bit seed. - 0 - - g is the sequence of generated 64-bit key quantities - n - - k is a random key reserved for generating this key sequence. - - t is the time at which a key is generated, to as fine a resolution - as is available (up to 64 bits). - - DES ( K, Q ) is the DES encryption of quantity Q with key K. - - Then: - - g = DES ( k, DES ( k, t ) XOR s ) - n n - - s = DES ( k, DES ( k, t ) XOR g ) - n+1 n - - - If g sub n is to be used as a DES key, then every eighth bit should - be adjusted for parity for that use, but the entire 64 bit unmodified - g should be used in calculating the next s. - - - - - - -Eastlake, et al. Standards Track [Page 33] - -RFC 4086 Randomness Requirements for Security June 2005 - - -7.2.3. DSS Pseudo-random Number Generation - - Appendix 3 of the NIST Digital Signature Standard [DSS] provides a - method of producing a sequence of pseudo-random 160 bit quantities - for use as private keys or the like. This has been modified by - Change Notice 1 [DSS_CN1] to produce the following algorithm for - generating general-purpose pseudo-random numbers: - - t = 0x 67452301 EFCDAB89 98BADCFE 10325476 C3D2E1F0 - - XKEY = initial seed - 0 - - For j = 0 to ... - - XVAL = ( XKEY + optional user input ) (Mod 2^512) - j - - X = G( t, XVAL ) - j - - XKEY = ( 1 + XKEY + X ) (Mod 2^512) - j+1 j j - - - The quantities X thus produced are the pseudo-random sequence of - 160-bit values. Two functions can be used for "G" above. Each - produces a 160-bit value and takes two arguments, a 160-bit value and - a 512 bit value. - - The first is based on SHA-1 and works by setting the 5 linking - variables, denoted H with subscripts in the SHA-1 specification, to - the first argument divided into fifths. Then steps (a) through (e) - of section 7 of the NIST SHA-1 specification are run over the second - argument as if it were a 512-bit data block. The values of the - linking variable after those steps are then concatenated to produce - the output of G [SHA*]. - - As an alternative method, NIST also defined an alternate G function - based on multiple applications of the DES encryption function [DSS]. - -8. Examples of Randomness Required - - Below are two examples showing rough calculations of randomness - needed for security. The first is for moderate security passwords, - while the second assumes a need for a very high-security - cryptographic key. - - - - -Eastlake, et al. Standards Track [Page 34] - -RFC 4086 Randomness Requirements for Security June 2005 - - - In addition, [ORMAN] and [RSA_BULL13] provide information on the - public key lengths that should be used for exchanging symmetric keys. - -8.1. Password Generation - - Assume that user passwords change once a year and that it is desired - that the probability that an adversary could guess the password for a - particular account be less than one in a thousand. Further assume - that sending a password to the system is the only way to try a - password. Then the crucial question is how often an adversary can - try possibilities. Assume that delays have been introduced into a - system so that an adversary can make at most one password try every - six seconds. That's 600 per hour, or about 15,000 per day, or about - 5,000,000 tries in a year. Assuming any sort of monitoring, it is - unlikely that someone could actually try continuously for a year. - Even if log files are only checked monthly, 500,000 tries is more - plausible before the attack is noticed and steps are taken to change - passwords and make it harder to try more passwords. - - To have a one-in-a-thousand chance of guessing the password in - 500,000 tries implies a universe of at least 500,000,000 passwords, - or about 2^29. Thus, 29 bits of randomness are needed. This can - probably be achieved by using the US DoD-recommended inputs for - password generation, as it has 8 inputs that probably average over 5 - bits of randomness each (see section 7.1). Using a list of 1,000 - words, the password could be expressed as a three-word phrase - (1,000,000,000 possibilities). By using case-insensitive letters and - digits, six characters would suffice ((26+10)^6 = 2,176,782,336 - possibilities). - - For a higher-security password, the number of bits required goes up. - To decrease the probability by 1,000 requires increasing the universe - of passwords by the same factor, which adds about 10 bits. Thus, to - have only a one in a million chance of a password being guessed under - the above scenario would require 39 bits of randomness and a password - that was a four-word phrase from a 1,000 word list, or eight - letters/digits. To go to a one-in-10^9 chance, 49 bits of randomness - are needed, implying a five-word phrase or a ten-letter/digit - password. - - In a real system, of course, there are other factors. For example, - the larger and harder to remember passwords are, the more likely - users will bed to write them down, resulting in an additional risk of - compromise. - - - - - - - -Eastlake, et al. Standards Track [Page 35] - -RFC 4086 Randomness Requirements for Security June 2005 - - -8.2. A Very High Security Cryptographic Key - - Assume that a very high security key is needed for symmetric - encryption/decryption between two parties. Assume also that an - adversary can observe communications and knows the algorithm being - used. Within the field of random possibilities, the adversary can - try key values in hopes of finding the one in use. Assume further - that brute force trial of keys is the best the adversary can do. - -8.2.1. Effort per Key Trial - - How much effort will it take to try each key? For very high-security - applications, it is best to assume a low value of effort. Even if it - would clearly take tens of thousands of computer cycles or more to - try a single key, there may be some pattern that enables huge blocks - of key values to be tested with much less effort per key. Thus, it - is probably best to assume no more than a couple of hundred cycles - per key. (There is no clear lower bound on this, as computers - operate in parallel on a number of bits and a poor encryption - algorithm could allow many keys or even groups of keys to be tested - in parallel. However, we need to assume some value and can hope that - a reasonably strong algorithm has been chosen for our hypothetical - high-security task.) - - If the adversary can command a highly parallel processor or a large - network of work stations, 10^11 cycles per second is probably a - minimum assumption today. Looking forward a few years, there should - be at least an order of magnitude improvement. Thus, it is - reasonable to assume that 10^10 keys could be checked per second, or - 3.6*10^12 per hour or 6*10^14 per week, or 2.4*10^15 per month. This - implies a need for a minimum of 63 bits of randomness in keys, to be - sure that they cannot be found in a month. Even then it is possible - that, a few years from now, a highly determined and resourceful - adversary could break the key in 2 weeks; on average, they need try - only half the keys. - - These questions are considered in detail in "Minimal Key Lengths for - Symmetric Ciphers to Provide Adequate Commercial Security: A Report - by an Ad Hoc Group of Cryptographers and Computer Scientists" - [KeyStudy] that was sponsored by the Business Software Alliance. It - concluded that a reasonable key length in 1995 for very high security - is in the range of 75 to 90 bits and, since the cost of cryptography - does not vary much with the key size, it recommends 90 bits. To - update these recommendations, just add 2/3 of a bit per year for - Moore's law [MOORE]. This translates to a determination, in the year - 2004, a reasonable key length is in the 81- to 96-bit range. In - fact, today, it is increasingly common to use keys longer than 96 - - - - -Eastlake, et al. Standards Track [Page 36] - -RFC 4086 Randomness Requirements for Security June 2005 - - - bits, such as 128-bit (or longer) keys with AES and keys with - effective lengths of 112-bits with triple-DES. - -8.2.2. Meet-in-the-Middle Attacks - - If chosen or known plain text and the resulting encrypted text are - available, a "meet-in-the-middle" attack is possible if the structure - of the encryption algorithm allows it. (In a known plain text - attack, the adversary knows all or part (possibly some standard - header or trailer fields) of the messages being encrypted. In a - chosen plain text attack, the adversary can force some chosen plain - text to be encrypted, possibly by "leaking" an exciting text that is - sent by the adversary over an encrypted channel because the text is - so interesting. - - The following is an oversimplified explanation of the meet-in-the- - middle attack: the adversary can half-encrypt the known or chosen - plain text with all possible first half-keys, sort the output, and - then half-decrypt the encoded text with all the second half-keys. If - a match is found, the full key can be assembled from the halves and - used to decrypt other parts of the message or other messages. At its - best, this type of attack can halve the exponent of the work required - by the adversary while adding a very large but roughly constant - factor of effort. Thus, if this attack can be mounted, a doubling of - the amount of randomness in the very strong key to a minimum of 192 - bits (96*2) is required for the year 2004, based on the [KeyStudy] - analysis. - - This amount of randomness is well beyond the limit of that in the - inputs recommended by the US DoD for password generation and could - require user-typing timing, hardware random number generation, or - other sources of randomness. - - The meet-in-the-middle attack assumes that the cryptographic - algorithm can be decomposed in this way. Hopefully no modern - algorithm has this weakness, but there may be cases where we are not - sure of that or even of what algorithm a key will be used with. Even - if a basic algorithm is not subject to a meet-in-the-middle attack, - an attempt to produce a stronger algorithm by applying the basic - algorithm twice (or two different algorithms sequentially) with - different keys will gain less added security than would be expected. - Such a composite algorithm would be subject to a meet-in-the-middle - attack. - - Enormous resources may be required to mount a meet-in-the-middle - attack, but they are probably within the range of the national - security services of a major nation. Essentially all nations spy on - other nations' traffic. - - - -Eastlake, et al. Standards Track [Page 37] - -RFC 4086 Randomness Requirements for Security June 2005 - - -8.2.3. Other Considerations - - [KeyStudy] also considers the possibilities of special-purpose code- - breaking hardware and having an adequate safety margin. - - Note that key length calculations such as those above are - controversial and depend on various assumptions about the - cryptographic algorithms in use. In some cases, a professional with - a deep knowledge of algorithm-breaking techniques and of the strength - of the algorithm in use could be satisfied with less than half of the - 192 bit key size derived above. - - For further examples of conservative design principles, see - [FERGUSON]. - -9. Conclusion - - Generation of unguessable "random" secret quantities for security use - is an essential but difficult task. - - Hardware techniques for producing the needed entropy would be - relatively simple. In particular, the volume and quality would not - need to be high, and existing computer hardware, such as audio input - or disk drives, can be used. - - Widely-available computational techniques can process low-quality - random quantities from multiple sources, or a larger quantity of such - low-quality input from one source, to produce a smaller quantity of - higher-quality keying material. In the absence of hardware sources - of randomness, a variety of user and software sources can frequently, - with care, be used instead. However, most modern systems already - have hardware, such as disk drives or audio input, that could be used - to produce high-quality randomness. - - Once a sufficient quantity of high-quality seed key material (a - couple of hundred bits) is available, computational techniques are - available to produce cryptographically-strong sequences of - computationally-unpredictable quantities from this seed material. - -10. Security Considerations - - The entirety of this document concerns techniques and recommendations - for generating unguessable "random" quantities for use as passwords, - cryptographic keys, initialization vectors, sequence numbers, and - similar security applications. - - - - - - -Eastlake, et al. Standards Track [Page 38] - -RFC 4086 Randomness Requirements for Security June 2005 - - -11. Acknowledgements - - Special thanks to Paul Hoffman and John Kelsey for their extensive - comments and to Peter Gutmann, who has permitted the incorporation of - material from his paper "Software Generation of Practically Strong - Random Numbers". - - The following people (in alphabetic order) have contributed - substantially to this document: - - Steve Bellovin, Daniel Brown, Don Davis, Peter Gutmann, Tony - Hansen, Sandy Harris, Paul Hoffman, Scott Hollenback, Russ - Housley, Christian Huitema, John Kelsey, Mats Naslund, and Damir - Rajnovic. - - The following people (in alphabetic order) contributed to RFC 1750, - the predecessor of this document: - - David M. Balenson, Don T. Davis, Carl Ellison, Marc Horowitz, - Christian Huitema, Charlie Kaufman, Steve Kent, Hal Murray, Neil - Haller, Richard Pitkin, Tim Redmond, and Doug Tygar. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 39] - -RFC 4086 Randomness Requirements for Security June 2005 - - -Appendix A: Changes from RFC 1750 - - 1. Additional acknowledgements have been added. - - 2. Insertion of section 5.3 on mixing with S-boxes. - - 3. Addition of section 3.3 on Ring Oscillator randomness sources. - - 4. Addition of AES and the members of the SHA series producing more - than 160 bits. Use of AES has been emphasized and the use of DES - de-emphasized. - - 5. Addition of section 6.3 on entropy pool techniques. - - 6. Addition of section 7.2.3 on the pseudo-random number generation - techniques given in FIPS 186-2 (with Change Notice 1), 7.2.1 on - those given in X9.82, section 7.1.2 on the random number - generation techniques of the /dev/random device in Linux and other - UNIX systems, and section 7.1.3 on random number generation - techniques in the Windows operating system. - - 7. Addition of references to the "Minimal Key Lengths for Symmetric - Ciphers to Provide Adequate Commercial Security" study published - in January 1996 [KeyStudy] and to [RFC1948]. - - 8. Added caveats to using Diffie-Hellman as a mixing function and, - because of those caveats and its computationally intensive nature, - recommend against its use. - - 9. Addition of references to the X9.82 effort and the [TURBID] and - [NASLUND] papers. - - 10. Addition of discussion of min-entropy and Renyi entropy and - references to the [LUBY] book. - - 11. Major restructuring, minor wording changes, and a variety of - reference updates. - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 40] - -RFC 4086 Randomness Requirements for Security June 2005 - - -Informative References - - [AES] "Specification of the Advanced Encryption Standard - (AES)", United States of America, US National - Institute of Standards and Technology, FIPS 197, - November 2001. - - [ASYMMETRIC] Simmons, G., Ed., "Secure Communications and - Asymmetric Cryptosystems", AAAS Selected Symposium - 69, ISBN 0-86531-338-5, Westview Press, 1982. - - [BBS] Blum, L., Blum, M., and M. Shub, "A Simple - Unpredictable Pseudo-Random Number Generator", SIAM - Journal on Computing, v. 15, n. 2, 1986. - - [BRILLINGER] Brillinger, D., "Time Series: Data Analysis and - Theory", Holden-Day, 1981. - - [CRC] "C.R.C. Standard Mathematical Tables", Chemical - Rubber Publishing Company. - - [DAVIS] Davis, D., Ihaka, R., and P. Fenstermacher, - "Cryptographic Randomness from Air Turbulence in Disk - Drives", Advances in Cryptology - Crypto '94, - Springer-Verlag Lecture Notes in Computer Science - #839, 1984. - - [DES] "Data Encryption Standard", US National Institute of - Standards and Technology, FIPS 46-3, October 1999. - Also, "Data Encryption Algorithm", American National - Standards Institute, ANSI X3.92-1981. See also FIPS - 112, "Password Usage", which includes FORTRAN code - for performing DES. - - [D-H] Rescorla, E., "Diffie-Hellman Key Agreement Method", - RFC 2631, June 1999. - - [DNSSEC1] Arends, R., Austein, R., Larson, M., Massey, D., and - S. Rose, "DNS Security Introduction and - Requirements", RFC 4033, March 2005. - - [DNSSEC2] Arends, R., Austein, R., Larson, M., Massey, D., and - S. Rose, "Resource Records for the DNS Security - Extensions", RFC 4034, March 2005. - - [DNSSEC3] Arends, R., Austein, R., Larson, M., Massey, D., and - S. Rose, "Protocol Modifications for the DNS Security - Extensions", RFC 4035, March 2005. - - - -Eastlake, et al. Standards Track [Page 41] - -RFC 4086 Randomness Requirements for Security June 2005 - - - [DoD] "Password Management Guideline", United States of - America, Department of Defense, Computer Security - Center, CSC-STD-002-85, April 1885. - - (See also "Password Usage", FIPS 112, which - incorporates CSC-STD-002-85 as one of its appendices. - FIPS 112 is currently available at: - http://www.idl.nist.gov/fipspubs/fip112.htm.) - - [DSS] "Digital Signature Standard (DSS)", US National - Institute of Standards and Technology, FIPS 186-2, - January 2000. - - [DSS_CN1] "Digital Signature Standard Change Notice 1", US - National Institute of Standards and Technology, FIPS - 186-2 Change Notice 1, 5, October 2001. - - [FERGUSON] Ferguson, N. and B. Schneier, "Practical - Cryptography", Wiley Publishing Inc., ISBN - 047122894X, April 2003. - - [GIFFORD] Gifford, D., "Natural Random Number", MIT/LCS/TM-371, - September 1988. - - [IEEE_802.11i] "Amendment to Standard for Telecommunications and - Information Exchange Between Systems - LAN/MAN - Specific Requirements - Part 11: Wireless Medium - Access Control (MAC) and physical layer (PHY) - specifications: Medium Access Control (MAC) Security - Enhancements", IEEE, January 2004. - - [IPSEC] Kent, S. and R. Atkinson, "Security Architecture for - the Internet Protocol", RFC 2401, November 1998. - - [Jakobsson] Jakobsson, M., Shriver, E., Hillyer, B., and A. - Juels, "A practical secure random bit generator", - Proceedings of the Fifth ACM Conference on Computer - and Communications Security, 1998. - - [KAUFMAN] Kaufman, C., Perlman, R., and M. Speciner, "Network - Security: Private Communication in a Public World", - Prentis Hall PTR, ISBN 0-13-046019-2, 2nd Edition - 2002. - - - - - - - - -Eastlake, et al. Standards Track [Page 42] - -RFC 4086 Randomness Requirements for Security June 2005 - - - [KeyStudy] Blaze, M., Diffie, W., Riverst, R., Schneier, B. - Shimomura, T., Thompson, E., and M. Weiner, "Minimal - Key Lengths for Symmetric Ciphers to Provide Adequate - Commercial Security: A Report by an Ad Hoc Group of - Cryptographers and Computer Scientists", January - 1996. Currently available at: - http://www.crypto.com/papers/keylength.txt and - http://www.securitydocs.com/library/441. - - [KNUTH] Knuth, D., "The Art of Computer Programming", Volume - 2: Seminumerical Algorithms, Chapter 3: Random - Numbers, Addison-Wesley Publishing Company, 3rd - Edition, November 1997. - - [KRAWCZYK] Krawczyk, H., "How to Predict Congruential - Generators", Journal of Algorithms, V. 13, N. 4, - December 1992. - - [LUBY] Luby, M., "Pseudorandomness and Cryptographic - Applications", Princeton University Press, ISBN - 0691025460, 8 January 1996. - - [MAIL_PEM1] Linn, J., "Privacy Enhancement for Internet - Electronic Mail: Part I: Message Encryption and - Authentication Procedures", RFC 1421, February 1993. - - [MAIL_PEM2] Kent, S., "Privacy Enhancement for Internet - Electronic Mail: Part II: Certificate-Based Key - Management", RFC 1422, February 1993. - - [MAIL_PEM3] Balenson, D., "Privacy Enhancement for Internet - Electronic Mail: Part III: Algorithms, Modes, and - Identifiers", RFC 1423, February 1993. - - [MAIL_PEM4] Kaliski, B., "Privacy Enhancement for Internet - Electronic Mail: Part IV: Key Certification and - Related Services", RFC 1424, February 1993. - - [MAIL_PGP1] Callas, J., Donnerhacke, L., Finney, H., and R. - Thayer, "OpenPGP Message Format", RFC 2440, November - 1998. - - [MAIL_PGP2] Elkins, M., Del Torto, D., Levien, R., and T. - Roessler, "MIME Security with OpenPGP", RFC 3156, - August 2001. - - - - - - -Eastlake, et al. Standards Track [Page 43] - -RFC 4086 Randomness Requirements for Security June 2005 - - - [S/MIME] RFCs 2632 through 2634: - - Ramsdell, B., "S/MIME Version 3 Certificate - Handling", RFC 2632, June 1999. - - Ramsdell, B., "S/MIME Version 3 Message - Specification", RFC 2633, June 1999. - - Hoffman, P., "Enhanced Security Services for S/MIME", - RFC 2634, June 1999. - - [MD4] Rivest, R., "The MD4 Message-Digest Algorithm", RFC - 1320, April 1992. - - [MD5] Rivest, R., "The MD5 Message-Digest Algorithm ", RFC - 1321, April 1992. - - [MODES] "DES Modes of Operation", US National Institute of - Standards and Technology, FIPS 81, December 1980. - Also: "Data Encryption Algorithm - Modes of - Operation", American National Standards Institute, - ANSI X3.106-1983. - - [MOORE] Moore's Law: the exponential increase in the logic - density of silicon circuits. Originally formulated - by Gordon Moore in 1964 as a doubling every year - starting in 1962, in the late 1970s the rate fell to - a doubling every 18 months and has remained there - through the date of this document. See "The New - Hacker's Dictionary", Third Edition, MIT Press, ISBN - 0-262-18178-9, Eric S. Raymond, 1996. - - [NASLUND] Naslund, M. and A. Russell, "Extraction of Optimally - Unbiased Bits from a Biased Source", IEEE - Transactions on Information Theory. 46(3), May 2000. - - [ORMAN] Orman, H. and P. Hoffman, "Determining Strengths For - Public Keys Used For Exchanging Symmetric Keys", BCP - 86, RFC 3766, April 2004. - - [RFC1750] Eastlake 3rd, D., Crocker, S., and J. Schiller, - "Randomness Recommendations for Security", RFC 1750, - December 1994. - - [RFC1948] Bellovin, S., "Defending Against Sequence Number - Attacks", RFC 1948, May 1996. - - - - - -Eastlake, et al. Standards Track [Page 44] - -RFC 4086 Randomness Requirements for Security June 2005 - - - [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: - Keyed-Hashing for Message Authentication", RFC 2104, - February 1997. - - [RSA_BULL1] "Suggestions for Random Number Generation in - Software", RSA Laboratories Bulletin #1, January - 1996. - - [RSA_BULL13] Silverman, R., "A Cost-Based Security Analysis of - Symmetric and Asymmetric Key Lengths", RSA - Laboratories Bulletin #13, April 2000 (revised - November 2001). - - [SBOX1] Mister, S. and C. Adams, "Practical S-box Design", - Selected Areas in Cryptography, 1996. - - [SBOX2] Nyberg, K., "Perfect Non-linear S-boxes", Advances in - Cryptography, Eurocrypt '91 Proceedings, Springer- - Verland, 1991. - - [SCHNEIER] Schneier, B., "Applied Cryptography: Protocols, - Algorithms, and Source Code in C", 2nd Edition, John - Wiley & Sons, 1996. - - [SHANNON] Shannon, C., "The Mathematical Theory of - Communication", University of Illinois Press, 1963. - Originally from: Bell System Technical Journal, July - and October, 1948. - - [SHIFT1] Golub, S., "Shift Register Sequences", Aegean Park - Press, Revised Edition, 1982. - - [SHIFT2] Barker, W., "Cryptanalysis of Shift-Register - Generated Stream Cypher Systems", Aegean Park Press, - 1984. - - [SHA] "Secure Hash Standard", US National Institute of - Science and Technology, FIPS 180-2, 1 August 2002. - - [SHA_RFC] Eastlake 3rd, D. and P. Jones, "US Secure Hash - Algorithm 1 (SHA1)", RFC 3174, September 2001. - - [SSH] Products of the SECSH Working Group, Works in - Progress, 2005. - - [STERN] Stern, J., "Secret Linear Congruential Generators are - not Cryptographically Secure", Proc. IEEE STOC, 1987. - - - - -Eastlake, et al. Standards Track [Page 45] - -RFC 4086 Randomness Requirements for Security June 2005 - - - [TLS] Dierks, T. and C. Allen, "The TLS Protocol Version - 1.0", RFC 2246, January 1999. - - [TURBID] Denker, J., "High Entropy Symbol Generator", - <http://www.av8n.com/turbid/paper/turbid.htm>, 2003. - - [USENET_1] Kantor, B. and P. Lapsley, "Network News Transfer - Protocol", RFC 977, February 1986. - - [USENET_2] Barber, S., "Common NNTP Extensions", RFC 2980, - October 2000. - - [VON_NEUMANN] Von Nuemann, J., "Various techniques used in - connection with random digits", Von Neumann's - Collected Works, Vol. 5, Pergamon Press, 1963. - - [WSC] Howard, M. and D. LeBlanc, "Writing Secure Code, - Second Edition", Microsoft Press, ISBN 0735617228, - December 2002. - - [X9.17] "American National Standard for Financial Institution - Key Management (Wholesale)", American Bankers - Association, 1985. - - [X9.82] "Random Number Generation", American National - Standards Institute, ANSI X9F1, Work in Progress. - Part 1 - Overview and General Principles. - Part 2 - Non-Deterministic Random Bit Generators - Part 3 - Deterministic Random Bit Generators - - - - - - - - - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 46] - -RFC 4086 Randomness Requirements for Security June 2005 - - -Authors' Addresses - - Donald E. Eastlake 3rd - Motorola Laboratories - 155 Beaver Street - Milford, MA 01757 USA - - Phone: +1 508-786-7554 (w) - +1 508-634-2066 (h) - EMail: Donald.Eastlake@motorola.com - - - Jeffrey I. Schiller - MIT, Room E40-311 - 77 Massachusetts Avenue - Cambridge, MA 02139-4307 USA - - Phone: +1 617-253-0161 - EMail: jis@mit.edu - - - Steve Crocker - - EMail: steve@stevecrocker.com - - - - - - - - - - - - - - - - - - - - - - - - - - - -Eastlake, et al. Standards Track [Page 47] - -RFC 4086 Randomness Requirements for Security June 2005 - - -Full Copyright Statement - - Copyright (C) The Internet Society (2005). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET - ENGINEERING TASK FORCE DISCLAIM 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. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at ietf- - ipr@ietf.org. - -Acknowledgement - - Funding for the RFC Editor function is currently provided by the - Internet Society. - - - - - - - -Eastlake, et al. Standards Track [Page 48] - diff --git a/docs/sieve.dia b/docs/sieve.dia Binary files differdeleted file mode 100755 index a9b2c64f..00000000 --- a/docs/sieve.dia +++ /dev/null |