7Network Working Group N. Freed
8Request for Comments: 5183 Sun Microsystems
9Category: Standards Track May 2008
12 Sieve Email Filtering: Environment Extension
16 This document specifies an Internet standards track protocol for the
17 Internet community, and requests discussion and suggestions for
18 improvements. Please refer to the current edition of the "Internet
19 Official Protocol Standards" (STD 1) for the standardization state
20 and status of this protocol. Distribution of this memo is unlimited.
24 This document describes the "environment" extension to the Sieve
25 email filtering language. The "environment" extension gives a Sieve
26 script access to information about the Sieve interpreter itself,
27 where it is running, and about any transport connection currently
28 involved in transferring the message.
32 Sieve [RFC5228] is a language for filtering email messages at or
33 around the time of final delivery. It is designed to be
34 implementable on either a mail client or mail server. It is suitable
35 for running on a mail server where users may not be allowed to
36 execute arbitrary programs, such as on black box Internet Message
37 Access Protocol [RFC3501] servers, as it has no user-controlled loops
38 or the ability to run external programs.
40 Although Sieve is intended to be independent of access protocol, mail
41 architecture, and operating system, in some cases it is useful to
42 allow scripts to access information about their execution context.
43 The "environment" extension provides a new environment test that can
44 be used to implement scripts that behave differently when moved from
45 one system to another, when messages arrive from different remote
46 sources or when otherwise operated in different contexts.
482. Conventions Used in This Document
50 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
51 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
52 document are to be interpreted as described in [RFC2119].
58Freed Standards Track [Page 1]
60RFC 5183 Sieve Environment Extension May 2008
63 The terms used to describe the various components of the Sieve
64 language are taken from Section 1.1 of [RFC5228].
66 This document refers to the ABNF productions IPv4-address-literal,
67 IPv6-address-literal, and General-address-literal defined in Section
70 The location item makes use of standard terms for email service
71 components. Additional information and background on these terms can
72 be found in [EMAIL-ARCH].
743. Capability Identifiers
76 The capability string associated with the extension defined in this
77 document is "environment".
81 Usage: environment [COMPARATOR] [MATCH-TYPE]
83 <key-list: string-list>
85 The environment test retrieves the item of environment information
86 specified by the name string and matches it to the values specified
87 in the key-list argument. The test succeeds if a match occurs. The
88 type of match defaults to ":is" and the default comparator is
91 The current message is not a direct source of information for the
92 environment test; the item of information specified by the name
93 string is extracted from the script's operating environment and the
94 key-list argument comes from the script.
96 The environment test MUST fail unconditionally if the specified
97 information item does not exist. A script MUST NOT fail with an
98 error if the item does not exist. This allows scripts to be written
99 that handle nonexistent items gracefully. In particular, the test:
101 if environment :contains "item" "" { ... }
103 only succeeds if "item" is known to the implementation, and always
106 The "relational" extension [RFC5231] adds a match type called
107 ":count". The count of an environment test is 0 if the environment
108 information returned is the empty string, or 1 otherwise.
114Freed Standards Track [Page 2]
116RFC 5183 Sieve Environment Extension May 2008
119 Environment items can be standardized or vendor-defined. An IANA
120 registry is defined for both types of items. Extensions designed for
121 interoperable use SHOULD be defined in standards track or
1244.1. Initial Standard Environment Items
126 The initial set of standardized environment items is as follows:
128 "domain" => The primary DNS domain associated with the Sieve
129 execution context, usually but not always a proper
130 suffix of the host name.
132 "host" => The fully-qualified domain name of the host where
133 the Sieve script is executing.
136 => Sieve evaluation can be performed at various
137 different points as messages are processed. This item
138 provides additional information about the type of
139 service that is evaluating the script. Possible values
140 are "MTA", meaning the Sieve is being evaluated by a
141 Message Transfer Agent, "MDA", meaning evaluation is
142 being performed by a Mail Delivery Agent, "MUA",
143 meaning evaluation is being performed by a Mail User
144 Agent, and "MS", meaning evaluation is being performed
145 by a Message Store. Additional information and
146 background on these terms can be found in
149 "name" => The product name associated with the Sieve interpreter.
151 "phase" => The point relative to final delivery where the
152 Sieve script is being evaluated. Possible values are
153 "pre", "during", and "post", referring respectively to
154 processing before, during, and after final delivery
158 => Host name of remote SMTP/LMTP/Submission client
159 expressed as a Fully Qualified Domain Name (FQDN),
160 if applicable and available. The empty string will be
161 returned if for some reason this information cannot be
162 obtained for the current client.
170Freed Standards Track [Page 3]
172RFC 5183 Sieve Environment Extension May 2008
176 => IP address of remote SMTP/LMTP/Submission client, if
177 applicable and available. IPv4, IPv6, and other types
178 of addresses are respectively represented in the
179 formats defined by the IPv4-address-literal,
180 IPv6-address-literal, and General-address-literal
181 productions defined in Section 4.1.3 of [RFC2821].
183 "version" => The product version associated with the Sieve
184 interpreter. The meaning of the product version string
185 is product-specific and should always be considered
186 in the context of the product name given by the
189 Implementations SHOULD support as many of the items on this initial
190 list as possible. Additional standardized items can only be defined
191 in standards-track or experimental RFCs.
1934.2. Vendor-defined Environment Items
195 Environment item names beginning with "vnd." represent vendor-defined
196 extensions. Such extensions are not defined by Internet standards or
197 RFCs, but are still registered with IANA in order to prevent
2004.3. IANA Registration of Environment Items
202 A registry of environment items is provided by IANA. Item names may
203 be registered on a first-come, first-served basis.
205 Groups of items defined in a standards track or experimental RFC MAY
206 choose to use a common name prefix of the form "name.", where "name"
207 is a string that identifies the group of related items.
209 Items not defined in a standards track or experimental RFC MUST have
210 a name that begins with the "vnd." prefix, and this prefix is
211 followed by the name of the vendor or product, such as
212 "vnd.acme.rocket-sled-status".
226Freed Standards Track [Page 4]
228RFC 5183 Sieve Environment Extension May 2008
2314.3.1. Template for Environment Registrations
233 The following template is to be used for registering new Sieve
234 environment item names with IANA.
237 Subject: Registration of new Sieve environment item
239 Item name: [the string for use in the 'environment' test]
240 Description: [a brief description of the semantics of the
241 value the item returns]
243 RFC number: [for extensions published as RFCs]
244 Contact address: [email and/or physical address to contact for
245 additional information]
247 Multiple items and descriptions MAY be specified in a single
248 registration request. Both standardized and vendor-defined items use
2515. Security Considerations
253 The environment extension may be used to obtain information about the
254 system the Sieve implementation is running on. This information in
255 turn may reveal details about service provider or enterprise
258 An implementation can use any technique to determine the remote-host
259 environment item defined in this specification, and the
260 trustworthiness of the result will vary. One common method will be
261 to perform a PTR DNS lookup on the client IP address. This
262 information may come from an untrusted source. For example, the
265 if environment :matches "remote-host" "*.example.com" { ... }
267 is not a good way to test whether the message came from "outside"
268 because anyone who can create a PTR record can create one that refers
269 to whatever domain they choose.
271 All of the security considerations given in the base Sieve
272 specification also apply to this extension.
282Freed Standards Track [Page 5]
284RFC 5183 Sieve Environment Extension May 2008
2876. IANA Considerations
289 The following template specifies the IANA registration of the Sieve
290 extension specified in this document:
293 Subject: Registration of new Sieve extension
295 Capability name: environment
296 Description: The "environment" extension provides a new
297 environment test that can be used to implement
298 scripts that behave differently when moved
299 from one system to another or otherwise
300 operated in different contexts.
302 Contact address: Sieve discussion list <ietf-mta-filters@imc.org>
304 This specification also defines a new IANA registry for Sieve
305 environment item names. The specifics of this registry are given in
306 Section 4.3. The initial contents of the registry are given in the
338Freed Standards Track [Page 6]
340RFC 5183 Sieve Environment Extension May 2008
3436.1. Initial Environment Item Registrations
345 The following template specifies the initial IANA registrations for
346 the environment items defined in this document:
349 Subject: Registration of new Sieve environment items
351 Capability name: domain
352 Description: The primary DNS domain associated with the Sieve
353 execution context, usually but not always a
354 proper suffix of the host name.
356 Capability name: host
357 Description: The fully-qualified domain name of the host
358 where the Sieve script is executing.
360 Capability name: location
361 Description: Type of service executing the Sieve script.
363 Capability name: name
364 Description: The product name associated with the Sieve
367 Capability name: phase
368 Description: Point relative to final delivery at which the
369 Sieve script is being evaluated.
371 Capability name: remote-host
372 Description: Host name of remote SMTP client, if applicable
375 Capability name: remote-ip
376 Description: IP address of remote SMTP client, if applicable
379 Capability name: version
380 Description: The product version associated with the Sieve
384 Contact address: Sieve discussion list <ietf-mta-filters@imc.org>
394Freed Standards Track [Page 7]
396RFC 5183 Sieve Environment Extension May 2008
4017.1. Normative references
403 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
404 Requirement Levels", BCP 14, RFC 2119, March 1997.
406 [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
409 [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email
410 Filtering Language", RFC 5228, January 2008.
412 [RFC5231] Segmuller, W. and B. Leiba, "Sieve Email Filtering:
413 Relational Extension", RFC 5231, January 2008.
4157.2. Informative references
417 [EMAIL-ARCH] Crocker, D., "Internet Mail Architecture", Work
418 in Progress, February 2008.
420 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
421 VERSION 4rev1", RFC 3501, March 2003.
450Freed Standards Track [Page 8]
452RFC 5183 Sieve Environment Extension May 2008
455Appendix A. Acknowledgements
457 Brian Carpenter, Dave Crocker, Cyrus Daboo, Philip Guenther, Kjetil
458 Torgrim Homme, John Klensin, Mark Mallett, Alexey Melnikov, and
459 Dilyan Palauzo provided helpful suggestions and corrections.
465 3401 Centrelake Drive, Suite 410
466 Ontario, CA 92761-1205
469 Phone: +1 909 457 4293
470 EMail: ned.freed@mrochek.com
506Freed Standards Track [Page 9]
508RFC 5183 Sieve Environment Extension May 2008
511Full Copyright Statement
513 Copyright (C) The IETF Trust (2008).
515 This document is subject to the rights, licenses and restrictions
516 contained in BCP 78, and except as set forth therein, the authors
517 retain all their rights.
519 This document and the information contained herein are provided on an
520 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
521 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
522 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
523 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
524 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
525 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
529 The IETF takes no position regarding the validity or scope of any
530 Intellectual Property Rights or other rights that might be claimed to
531 pertain to the implementation or use of the technology described in
532 this document or the extent to which any license under such rights
533 might or might not be available; nor does it represent that it has
534 made any independent effort to identify any such rights. Information
535 on the procedures with respect to rights in RFC documents can be
536 found in BCP 78 and BCP 79.
538 Copies of IPR disclosures made to the IETF Secretariat and any
539 assurances of licenses to be made available, or the result of an
540 attempt made to obtain a general license or permission for the use of
541 such proprietary rights by implementers or users of this
542 specification can be obtained from the IETF on-line IPR repository at
543 http://www.ietf.org/ipr.
545 The IETF invites any interested party to bring to its attention any
546 copyrights, patents or patent applications, or other proprietary
547 rights that may cover technology that may be required to implement
548 this standard. Please address the information to the IETF at
562Freed Standards Track [Page 10]