RFC 5463

Sieve Email Filtering: Ihave Extension 💖

RFC 5463, a Standards Track document from the Network Working Group, dated March 2009. The author is Ned Freed of Sun Microsystems. The header doesn't list anything it obsoletes or updates. 🎀

---

Status of This Memo ✨

okay so this doc is an Internet standards track protocol for the Internet community, and the authors want feedback and suggestions 🫶. For the official standardization state and status, check the current "Internet Official Protocol Standards" (STD 1). Distribution is unlimited, so share it with everyone 🌸.

Copyright Notice 💅

Copyright (c) 2009 IETF Trust and the persons identified as the document authors. All rights reserved.

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents as of the publication date (http://trustee.ietf.org/license-info). Read those carefully, bestie, because they explain your rights and restrictions 📜.

Abstract 🦋

So this doc describes the "ihave" extension to the Sieve email filtering language. "ihave" lets you write scripts that use optional Sieve features but still run when those features aren't available, which is so iconic 👑. It also defines a new error control command for when no combo of available extensions can meet what the script needs 💀.

1. Introduction ✨

Sieve [RFC5228] is a language for filtering email messages at or around 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 🔒.

There are already a bunch of Sieve extensions, like [RFC5229], [RFC5230], [RFC5231], [RFC5232], [RFC5233], and [RFC5235], and honestly more are gonna show up over time 🌈. Sieve's require clause says which extensions a script needs, and if the script asks for an extension that isn't available, you get an error. That works for most situations, ngl 💅. But sometimes a script could use an extension if it's there and still function without it (maybe with a little less shine ✨). Other times a script would prefer extension A but can fall back to extension B if A isn't around 🦋.

The "ihave" extension is how you write scripts that only use extensions when they're actually available. It adds a new "ihave" test that takes a list of capability names and succeeds if and only if all of them are present 🎀. Also, putting "ihave" in the require clause turns off parse-time checking of extension use, so run-time checking has to do the job instead. This makes portable scripts possible, scripts that work in lots of different environments and use whatever extensions happen to exist, even when different places offer different sets 🧚.

"ihave" also adds a new error control command. An error stops the script and reports the message you pass as its argument 💀.

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

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

3. Capability Identifiers 🍓

The capability string for the extension in this doc is "ihave" 💜.

4. Ihave Test 🔥

Here's the usage:

Usage:   ihave <capabilities: string-list>

The "ihave" test lets Sieve scripts check whether an extension exists before they actually use it 🙈. Its capabilities argument works exactly like the similarly named argument in the require control statement. It names one or more Sieve extensions or comparators. "ihave" succeeds if all the extensions in the list are available to the script ✨.

Unlike most Sieve tests, "ihave" takes no match or comparator arguments. The match type is always ":is", and the comparator is always "i;octet" 💖.

The strings in the capabilities list are constant strings in terms of Sieve variables [RFC5229]. Passing a non-constant string as an argument to "ihave" is an error 🚫.

The Sieve base spec says every extension a script uses has to be listed in the script's initial require control statement. It's an error for a script to ask for an extension the interpreter doesn't support, or to use an extension that isn't in its require clause. "ihave" changes interpreter behavior and the underlying requirements in these ways:

1. Once an "ihave" test on an extension succeeds, you can use that extension all the way to the end of the script, even outside the block the "ihave" test wraps. Basically, after a successful "ihave", things work just as if the extension had been in the require clause 🦋. You can't use the extension before that test is evaluated, and a run-time error MUST be generated if you try. Later uses might still need their own "ihave" test to handle the case where the extension isn't supported 🫶.
2. Sieve interpreters normally get to pick whether they check extension use at parse time or at execution time. Putting "ihave" in a script's require clause changes that: Scripts MUST either defer extension checking to run time or else take the presence of "ihave" tests into account at parse time. Since "ihave" can be used inside "anyof", "allof", and "not" tests, full parse-time checking of "ihave" may be very difficult to implement 😭.
3. It makes little sense, but an extension can be listed in both the require control statement and an "ihave" test. If that happens and the extension is implemented, the extension can be used anywhere in the script, and an "ihave" test for it will always return true 💅.
4. The "ihave" test takes a list of capabilities. If any of them are unavailable, the test fails and none of the capabilities get enabled 🙅‍♀️.
5. The Sieve base spec doesn't require interpreters to evaluate arguments in any particular order or to short-circuit tests. If "ihave" is enabled, the interpreter MUST short-circuit tests, meaning it can't do more tests than needed to get the result. Also, evaluation order MUST be left to right if "ihave" is enabled 👑.

"ihave" is meant to work with other extensions that add tests, actions, comparators, or arguments. Implementations MUST NOT allow it to be used with extensions that change the underlying Sieve grammar, or with extensions like encoded-character [RFC5228] or variables [RFC5229] that change how the content of Sieve scripts gets interpreted 🚫. The test MUST fail and the extension MUST NOT be enabled if someone tries that 💀.

5. Error Control 💀

Here's the usage:

Usage:   error <message: string>

The error control stops script execution with a run-time error. The message argument is a text description of the error condition, and it SHOULD be included in any report generated about the error 📝. Section 2.10.6 of [RFC5228] explains how run-time errors get handled in Sieve 🫶.

Heads up: the message argument, like every Sieve string, uses the UTF-8 charset and can contain non-US-ASCII characters. That must be taken into consideration when reporting script errors 🌍.

The error control is part of the "ihave" extension so that it's always available to scripts using ihave 💜.

6. Security Considerations 🚨

Okay, this part is serious bestie. A possible security issue with Sieve scripts is that when a script fails to run because some extension is missing, it might fail to block dangerous email 😱. "ihave" makes scripts more portable and general, which may improve the overall security Sieve provides 🛡️.

That said, ihave is basically a more flexible version of Sieve's existing require mechanism. So it doesn't add any new capabilities to a Sieve implementation that could create security issues ✨. Of course, every security consideration in the base Sieve spec and in any extensions a script uses still applies 🔥.

7. IANA Considerations 🌈

The IANA registration for this extension uses the following template:

   To: iana@iana.org
   Subject: Registration of new Sieve extension

   Capability name: ihave
   Description:     The "ihave" extension provides a means to write
                    scripts that make use of other extensions only
                    when they are actually available.
   RFC number:      RFC 5463
   Contact address: Sieve discussion list <ietf-mta-filters@imc.org>

8. References 📚

8.1. Normative References 💖

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

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

8.2. Informative References 🦋

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

   [RFC5229]  Homme, K., "Sieve Email Filtering: Variables Extension",
              RFC 5229, January 2008.

   [RFC5230]  Showalter, T. and N. Freed, "Sieve Email Filtering:
              Vacation Extension", RFC 5230, January 2008.

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

   [RFC5232]  Melnikov, A., "Sieve Email Filtering: Imap4flags
              Extension", RFC 5232, January 2008.

   [RFC5233]  Murchison, K., "Sieve Email Filtering: Subaddress
              Extension", RFC 5233, January 2008.

   [RFC5235]  Daboo, C., "Sieve Email Filtering: Spamtest and Virustest
              Extensions", RFC 5235, January 2008.

9. Acknowledgments 🫶

Stephan Bosch, Cyrus Daboo, Arnt Gulbrandsen, Andrew McKeon, and Alexey Melnikov gave helpful suggestions and corrections. Thank you, besties 💜.

Author's Address 🎀

   Ned Freed
   Sun Microsystems
   800 Royal Oaks
   Monrovia, CA  91016-6347
   USA

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