RFC 5183

Status of This Memo 📜

This is an Internet standards track protocol for the Internet community, and it's open for discussion and suggestions for improvements. For the standardization state and status, check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited.

Abstract 🦋

Okay so this doc is about the "environment" extension for the Sieve email filtering language. It lets a Sieve script look at the Sieve interpreter itself, see where it's running, and check out any transport connection that's carrying the message. Main character energy 💅

1. Introduction ✨

Sieve [RFC5228] is a language for filtering email messages at or around the time of final delivery. It's built to run on either a mail client or a mail server. It's especially good for mail servers where users aren't allowed to run arbitrary programs, like on black box Internet Message Access Protocol [RFC3501] servers, because it has no user-controlled loops and can't run external programs. Super safe 🔒

Sieve is meant to stay independent of the access protocol, mail architecture, and operating system, but sometimes scripts need to know about their execution context. The "environment" extension adds a new environment test for exactly that. You can write scripts that act differently when they move from one system to another, when messages come in from different remote sources, or when they're running in other contexts. It's giving flexibility 🧚

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 get interpreted the way [RFC2119] describes. Keep an eye on them, bestie 👀

The terms for the parts of the Sieve language come from Section 1.1 of [RFC5228].

This document uses the ABNF productions IPv4-address-literal, IPv6-address-literal, and General-address-literal, which are defined in Section 4.1.3 of [RFC2821].

The location item uses standard terms for email service components. You can find more info and background on those in [EMAIL-ARCH] 📚

3. Capability Identifiers 🎀

The capability string for the extension in this document is "environment". That's the name you'll see everywhere 💖

4. Environment Test 🔍

Usage:

Usage:   environment [COMPARATOR] [MATCH-TYPE]
                     <name: string>
                     <key-list: string-list>

Okay, the environment test grabs the item of environment information named by the name string, then matches it against the values in the key-list argument. The test succeeds if there's a match. The match type defaults to :is, and the default comparator is "i;ascii-casemap". Easy peasy 🫶

The current message isn't where the environment test gets its info. The item comes from the script's operating environment, and the key-list argument comes from the script itself. So the message isn't the source here, the environment is 🌈

The environment test MUST fail unconditionally if the specified information item doesn't exist. A script MUST NOT fail with an error if the item is missing. This lets you write scripts that handle missing items gracefully, which is so responsible 🥹 For example:

if environment :contains "item" "" { ... }

only succeeds if "item" is known to the implementation, and it always succeeds if it is.

The "relational" extension [RFC5231] adds a match type called :count. The count of an environment test is 0 if the environment information returned is the empty string, and 1 otherwise.

Environment items can be standardized or vendor-defined, and IANA keeps a registry for both kinds. Extensions meant for interoperable use SHOULD be defined in standards track or experimental RFCs. Lowkey the most important rule in this section 👑

4.1. Initial Standard Environment Items 💅

Here's the starter set of standardized environment items:

• "domain": the primary DNS domain tied to the Sieve execution context. It's usually, but not always, a proper suffix of the host name.
• "host": the fully-qualified domain name of the host where the Sieve script is running.
• "location": Sieve can be evaluated at different points as messages get processed, so this item tells you what type of service is evaluating the script. The possible values are "MTA" (a Message Transfer Agent is evaluating the Sieve), "MDA" (a Mail Delivery Agent is doing it), "MUA" (a Mail User Agent is doing it), and "MS" (a Message Store is doing it). More info and background on these terms is in [EMAIL-ARCH] 🧐
• "name": the product name of the Sieve interpreter.
• "phase": where the Sieve script is being evaluated relative to final delivery. The possible values are "pre", "during", and "post", meaning before, during, and after final delivery has happened.
• "remote-host": the host name of the remote SMTP, LMTP, or Submission client, written as a Fully Qualified Domain Name (FQDN), if that applies and is available. If it can't be obtained for the current client, you get the empty string 🫣
• "remote-ip": the IP address of the remote SMTP, LMTP, or Submission client, if that applies and is available. IPv4, IPv6, and other address types use the formats from the IPv4-address-literal, IPv6-address-literal, and General-address-literal productions in Section 4.1.3 of [RFC2821] respectively.
• "version": the product version of the Sieve interpreter. What the version string means is product-specific, so always read it alongside the product name from the "name" item 🔢

Implementations SHOULD support as many items on this starter list as they can. More standardized items can only be defined in standards-track or experimental RFCs. Let's gooo 🚀

4.2. Vendor-defined Environment Items 🌷

Item names that start with "vnd." are vendor-defined extensions. They aren't defined by Internet standards or RFCs, but they still get registered with IANA so nobody steps on anybody else's toes 🤝

4.3. IANA Registration of Environment Items 📝

IANA provides a registry of environment items. Item names can be registered on a first-come, first-served basis.

Groups of items defined in a standards track or experimental RFC MAY choose to use a common name prefix of the form "name.", where "name" is a string that identifies the group of related items. Think of it like a family name for your items 👨‍👩‍👧

Items that aren't defined in a standards track or experimental RFC MUST have a name that begins with the "vnd." prefix. That prefix gets followed by the name of the vendor or product, like "vnd.acme.rocket-sled-status". Iconic naming 🛷

4.3.1. Template for Environment Registrations 🧾

This is the template you use to register new Sieve environment item names with IANA:

   To: iana@iana.org
   Subject: Registration of new Sieve environment item

   Item name: [the string for use in the 'environment' test]
   Description:     [a brief description of the semantics of the
                     value the item returns]

   RFC number:      [for extensions published as RFCs]
   Contact address: [email and/or physical address to contact for
                     additional information]

You can put multiple items and descriptions in a single registration request, and the template works for both standardized and vendor-defined items. Bestie, that's the whole thing for part 1 🎀✨

6.1. Initial Environment Item Registrations

okay so this part is the IANA paperwork, and it's giving organized 📋✨ The RFC gives us a ready-made email template to send to IANA, and it registers the environment items from this document. Here's the template, bestie 💌

   To: iana@iana.org
   Subject: Registration of new Sieve environment items

   Capability name: domain
   Description:     The primary DNS domain associated with the Sieve
                    execution context, usually but not always a
                    proper suffix of the host name.

   Capability name: host
   Description:     The fully-qualified domain name of the host
                    where the Sieve script is executing.

   Capability name: location
   Description:     Type of service executing the Sieve script.

   Capability name: name
   Description:     The product name associated with the Sieve
                    interpreter.

   Capability name: phase
   Description:     Point relative to final delivery at which the
                    Sieve script is being evaluated.

   Capability name: remote-host
   Description:     Host name of remote SMTP client, if applicable
                    and available.

   Capability name: remote-ip
   Description:     IP address of remote SMTP client, if applicable
                    and available.

   Capability name: version
   Description:     The product version associated with the Sieve
                    interpreter.

   RFC number:      RFC 5183
   Contact address: Sieve discussion list <ietf-mta-filters@imc.org>

The eight items are domain, host, location, name, phase, remote-host, remote-ip and version, each with its own little description. Serving registry realness 🎀

---

7. References

7.1. Normative references

   [RFC2119]     Bradner, S., "Key words for use in RFCs to Indicate
                 Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC2821]     Klensin, J., "Simple Mail Transfer Protocol", RFC 2821,
                 April 2001.

   [RFC5228]     Guenther, P. and T. Showalter, "Sieve: An Email
                 Filtering Language", RFC 5228, January 2008.

   [RFC5231]     Segmuller, W. and B. Leiba, "Sieve Email Filtering:
                 Relational Extension", RFC 5231, January 2008.

These are the normative references: the stuff you need to actually read in order to implement this. RFC 2119 covers the key words, RFC 2821 is SMTP, RFC 5228 is the Sieve language itself, and RFC 5231 is the relational extension 💅

7.2. Informative references

   [EMAIL-ARCH]  Crocker, D., "Internet Mail Architecture", Work
                 in Progress, February 2008.

   [RFC3501]     Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
                 VERSION 4rev1", RFC 3501, March 2003.

And these are the informative ones: good background reading, not required to build the thing. [EMAIL-ARCH] is still a work in progress as of this writing, and [RFC3501] is IMAP version 4rev1 🦋

---

Appendix A. Acknowledgements

   Brian Carpenter, Dave Crocker, Cyrus Daboo, Philip Guenther, Kjetil
   Torgrim Homme, John Klensin, Mark Mallett, Alexey Melnikov, and
   Dilyan Palauzo provided helpful suggestions and corrections.

The people who gave helpful suggestions and corrections 🫶 Main character energy for everyone on this list, no cap.

---

Author's Address

   Ned Freed
   Sun Microsystems
   3401 Centrelake Drive, Suite 410
   Ontario, CA  92761-1205
   USA

   Phone: +1 909 457 4293
   EMail: ned.freed@mrochek.com

This is where you'd reach the author, Ned Freed, at Sun Microsystems 📮

---

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.

The legal stuff, copied word for word so nothing gets fuzzy ⚖️ The short version: the IETF Trust holds the copyright from 2008, the authors keep their rights under BCP 78, and the document comes "AS IS" with no warranties 🙈

---

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`.

Last but not least, the IPR section 🌈 The IETF doesn't claim to know who owns what, and it's not going to vouch for any patents. Procedures live in BCP 78 and BCP 79. If you spot a patent that might cover this tech, tell the IETF at ietf-ipr@ietf.org, and IPR disclosures are available at http://www.ietf.org/ipr 💜