7
Network Working Group N. Freed
8
Request for Comments: 5183 Sun Microsystems
9
Category: 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.
48
2. 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].
58
Freed Standards Track [Page 1]
60
RFC 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].
74
3. 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.
114
Freed Standards Track [Page 2]
116
RFC 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
124
4.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.
170
Freed Standards Track [Page 3]
172
RFC 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.
193
4.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
200
4.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".
226
Freed Standards Track [Page 4]
228
RFC 5183 Sieve Environment Extension May 2008
231
4.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
251
5. 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.
282
Freed Standards Track [Page 5]
284
RFC 5183 Sieve Environment Extension May 2008
287
6. 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
338
Freed Standards Track [Page 6]
340
RFC 5183 Sieve Environment Extension May 2008
343
6.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>
394
Freed Standards Track [Page 7]
396
RFC 5183 Sieve Environment Extension May 2008
401
7.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.
415
7.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.
450
Freed Standards Track [Page 8]
452
RFC 5183 Sieve Environment Extension May 2008
455
Appendix 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
506
Freed Standards Track [Page 9]
508
RFC 5183 Sieve Environment Extension May 2008
511
Full 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.
527
Intellectual Property
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
562
Freed Standards Track [Page 10]