Pigeonhole Project S. Bosch January 8, 2010 Sieve Email Filtering: Externally Stored Data Abstract In advanced mail filtering setups, it is often convenient to store global configuration data in an external data store for easy configuration management. The base specification of the Sieve filtering langage (RFC 5228) only allows for hardcoding configuration data in Sieve script itself, which means that the script needs to be updated each time the configuration changes. This document updates the Sieve filtering language with an extension to support retrieving string data from external sources. The extension supplies a new test so that external data can be examined. When the variables extension (RFC5229) is also active, the external data can also be directly accessed as a special variables namespace. Bosch [Page 1] Sieve Extension: Externally Stored Data January 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . . 3 3. Capability Identifier . . . . . . . . . . . . . . . . . . . . . 3 4. Naming of Data Items . . . . . . . . . . . . . . . . . . . . . 3 5. Extdata Test . . . . . . . . . . . . . . . . . . . . . . . . . 4 6. Variables Namespace extdata . . . . . . . . . . . . . . . . . . 4 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 8. Security Considerations . . . . . . . . . . . . . . . . . . . . 6 9. Normative References . . . . . . . . . . . . . . . . . . . . . 6 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 Bosch [Page 2] Sieve Extension: Externally Stored Data January 2010 1. Introduction This is an extension to the Sieve language defined by SIEVE [RFC5228]. It adds support for referencing externally stored named data. In advanced mail filtering setups, it is often convenient to store global configuration data in an external data store for easy configuration management. In the Sieve base specification such data can only be made available in a Sieve script by hardcoding it in the Sieve script itself. This extension adds a new test command to retrieve and evaluate data items stored externally. When the Sieve Variables extension [RFC5229] is also active, a special variables namespace is available through which the data items can be accessed directly for string substitution. This extension is specific to the Pigeonhole Sieve implementation for the Dovecot Secure IMAP server. It will therefore most likely not be supported by web interfaces and GUI-based ManageSieve clients. This extension is primarily meant for use in global scripts that are managed by the systems administrator. 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 RFC 2119 [RFC2119]. Conventions for notations are as in SIEVE [RFC5228] Section 1.1. 3. Capability Identifier The capability string associated with the extension defined in this document is "vnd.dovecot.extdata". 4. Naming of Data Items In the simplest case, i.e. when the implementation is restricted to only one distinct data store or when the source of the data item has no significance, the name of an external data item MAY be a simple identifier as defined in the SIEVE [RFC5228] grammar. When multiple distinct data stores are available, the item name MUST be structured hierarchically just like the variables namespace syntax defined in VARIABLES [RFC5229], with the restriction that numeric (num-variable) elements are not allowed. The first element of a hierarchical item name identifies the data store and subsequent Bosch [Page 3] Sieve Extension: Externally Stored Data January 2010 elements identify the data item within that data store. This yields the following syntax for a hierarchical data item name: item-name = data-store-name "." identifier *("." identifier) data-store-name = identifier 5. Extdata Test Usage: extdata [COMPARATOR] [MATCH-TYPE] The extdata test retrieves the data item specified by the item-name string from the external data store and matches it to the values specified in the key-list argument. The specified item-name MUST conform to the syntax defined in Section 4. The test succeeds if a match occurs. The type of match defaults to ":is" and the default comparator is "i;ascii-casemap". The extdata test MUST fail unconditionally if the specified data item cannot be retrieved, e.g. because it does not exist in the external data store or when the data store is not available. A script MUST NOT fail with an error if the item cannot be retrieved. This allows scripts to be written that handle nonexistent items gracefully. In particular, the test: if extdata :contains "item" "" { ... } only fails if the "item" does not exists in the data store or when the data store is not available, and always succeeds otherwise. The "relational" extension [RFC5231] adds a match type called ":count". The count of an extdata test is 0 if the extdata information returned is the empty string, or 1 otherwise. 6. Variables Namespace extdata This document defines the variables namespace "extdata", as specified in VARIABLES [RFC5229], Section 3. The extdata namespace provides direct access to the data items in the external data store. Example: require ["vacation", "variables", "vnd.dovecot.extdata"]; vacation :subject "${extdata.vacation_subject}" Bosch [Page 4] Sieve Extension: Externally Stored Data January 2010 "${extdata.vacation_message}"; External data items accessed via the extdata test and the extdata variables namespace MUST be one and the same. The following example scripts are equivalent: Example 1: require ["fileinto", "variables", "vnd.dovecot.extdata"]; if allof (header :is "X-Spam-Status" "Yes", extdata :is "discard_spam" "yes") { discard; } else { fileinto "Spam"; } Example 2: require ["fileinto", variables", "vnd.dovecot.extdata"]; if allof (header :is "X-Spam-Status" "Yes", string :is "${extdata.discard_spam}" "yes") { discard; } else { fileinto "Spam"; } The extdata namespace accepts any data item name. A script MUST NOT fail with an error when a data item is referenced that does not exist in the external data store or otherwise cannot be retrieved. In that case the empty string will be substituted, which is analogous to the substitution of unset normal variables. Use the extdata test to evaluate wether a data item exists and can be retrieved. This extension only concerns the retrieval of external data items and therefore it is not possible to assign values to items within the extdata variables namespace using for example the "set" action defined in VARIABLES [RFC5229]. A script MUST fail with an error when an attempt is made to assign to an item in the extdata namespace. 7. Acknowledgements Martin F. Foster provided the original idea for this extension. Bosch [Page 5] Sieve Extension: Externally Stored Data January 2010 8. Security Considerations Administrators should keep in mind that retrieving values from an external data store can reveal more data to a user than strictly allowed when the data store is not queried carefully. 9. 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. [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", RFC 5229, January 2008. [RFC5231] Segmuller, W. and B. Leiba, "Sieve Email Filtering: Relational Extension", RFC 5231, January 2008. Author's Address Stephan Bosch Enschede NL Email: stephan@rename-it.nl Bosch [Page 6]