From Kolab Wiki

KEP 9: Storage of configuration and application control information

Abstract

This Kolab Enhancement Proposal (KEP) ^[1] defines part of a changeset applied against Kolab XML version 1.0 of Kolab Format 2.0 to introduce a new folder-type 'configuration' as well as new object type 'configuration' for usage in all non-email folders. The purpose is to establish a mechanism that allows configuration information and application specific behaviour to be configured and coordinated across different Kolab clients to achieve more consistency in how Kolab clients represent user data. In addition, this KEP clarifies and documents some of the existing mechanisms for storing configuration and application control information.

The mechanisms defined in this KEP include

1. ANNOTATE annotations, both private and shared (new)
2. METADATA annotations, both private and public (modified, previously ANNOTATEMORE)
3. Configuration XML objects and specialised folders for their storage (new)

Mechanisms not further defined in this KEP are those relying on the Directory Service, typically based on LDAP (see RFC 4511 ^[2]). These mechanisms form part of the toolset available for storing configuration and application control information, but are so case specific that no overarching mechanisms can be usefully defined in this KEP.

All four mechanisms of

1. ANNOTATE annotations, both private and shared
2. METADATA annotations, both private and public
3. Configuration XML objects and specialised folders for their storage
4. Directory Service information

form part of the comprehensive toolset for storing configuration and application control information used by the Kolab Groupware Solution. Any configuration or application control use case is free to choose one or more of these mechanisms to define its particular scenario. It is explicitly foreseen that applications will mix these approaches as and where is appropriate and useful to achieve the most robust, flexible and comprehensive solution possible.

Configuration storage in message annotations

This is a new mechanism:

IMAP ANNOTATE RFC 5257 message annotations

The Kolab Groupware Solution currently does not make use of message annotations according to RFC 5257 ^[3], but it has been argued that in some cases such annotations would be the most efficient approach, e.g. single-message encryption and ACL scenarios of groupware items.

Scope of these provisions

The provisions set forth in this KEP MUST be followed for all annotations in the '/vendor/kolab/*' namespace.

Third party annotations in different name spaces SHOULD follow these provisions, and MUST be documented by their provider in an informational KEP in order to become eligible for inclusion in the Kolab Groupware Server.

Public and private annotations

RFC 5257 provides means for public and private annotations. Both kinds MAY be used in the Kolab Groupware Solution, but use of each annotation MUST be defined in a single KEP for all prefixes.

Values

Simple values for both private and public annotations SHOULD be stored as UTF-8 encoded string whenever possible.

Where array serialization or hashing is required because a value cannot be stored as plain text or contains illegal characters, values MUST be stored as UTF-8 encoded string according to RFC 4627^[4], the JavaScript Object Notation (JSON).

If that encoding cannot safely represent the value, Base64 encoded according to RFC 3548 ^[5] MAY be used, but its use is strongly discouraged.

Other encodings MUST NOT be used.

Background: Requirements by RFC 5257

Values MUST conform to the UTF-8 character set defined in RFC 3629^[6] as specified in RFC 5257^[3].

Configuration storage in folder annotations

This is a modificaton and clarification of an existing mechanism:

IMAP METADATA RFC 5464 folder annotations

From its inception in 2003 and up until and including Kolab Format 2.0, the Kolab Groupware Solution has been using draft version 5 of the ANNOTATEMORE proposal which has been finalized in February 2009 into the IMAP METADATA Extension defined in RFC 5464 ^[7].

With application of this changeset against the Kolab Format 2.0, all clients MUST conform to RFC 5464 only.

Usage of ANNOTATEMORE will be deprecated, unsupported and not compliant with the Kolab Format resulting from application of this changeset.

Scope of these provisions

The provisions set forth in this KEP MUST be followed for all annotations in the '/vendor/kolab/*' namespace.

Third party annotations in different name spaces SHOULD follow these provisions, and MUST be documented by their provider in an informational KEP in order to become eligible for inclusion in the Kolab Groupware Server.

Public and private annotations

RFC 5464 provides means for public and private annotations. Both kinds MAY be used in the Kolab Groupware Solution, but use of each annotation MUST be defined in a single KEP for all prefixes.

Values

Simple values for both private and public annotations SHOULD be stored as UTF-8 encoded string whenever possible.

Where array serialization or hashing is required because a value cannot be stored as plain text or contains illegal characters, values MUST be stored as UTF-8 encoded string according to RFC 4627^[4], the JavaScript Object Notation (JSON).

If that encoding cannot safely represent the value, Base64 encoded according to RFC 3548 ^[5] MAY be used, but its use is strongly discouraged.

Other encodings MUST NOT be used.

Background: Requirements by RFC 5464

RFC 5464^[7] inherits the Augmented Backus-Naur Form (ABNF, RFC 5234^[8]) including definitions from RFC 3501^[9] superseded by RFC 4466^[10].

In this notation, value is specified in RFC 5464 as

  value          =  nstring / literal8

which allows representation as string or binary value as detailed in RFC 3516^[11].

Rationale
For the rationale of defining the allowed values in a way that is more limited than what the RFC allows, please see the section 'Rationale on encoding for values of RFC 5257 and RFC 5464 annotations' below.

Configuration storage in XML objects

This is a new mechanism:

Update to the XML Format

The following changes to the Kolab Format are part of the changeset against Kolab XML version 1.0 as described by Kolab Format 2.0:

/vendor/kolab/folder-type: 'configuration'

• In addition to the existing <type>[.<subtype>] values for value.shared defined by Kolab Format 2.0, the /vendor/kolab/folder-type annotation MAY be set to 'configuration' or 'configuration.default';
• There MUST be at most a single folder of type 'configuration' with the subtype 'default' per user;
• A folder of type 'configuration' MUST only contain objects of Kolab XML object type 'configuration' (see below);
• Folders in the IMAP 'shared' namespace of type 'configuration' SHALL NOT carry the subtype 'default';

Kolab XML object type: 'configuration'

• The mimetype for 'configuration' type objects is 'application/x-vnd.kolab.configuration';
• Common fields for 'configuration' type objects are 'uid', 'creation-date', 'last-modification-date', 'type';
• The 'type' field SHALL define the type of configuration information stored in the object and the specific fields for the object;
• The individual configuration object types SHALL be defined in individual KEP proposals;

Example

An example configuration object might look as follows, assuming the changeset defined by this KEP has been incorporated in a future version 2.1 of Kolab XML:

<?xml version="1.1" encoding="UTF-8"?>
<configuration version="2.1">
  <!-- Common fields -->
  <uid>(string, no default)</uid>
  <creation-date>(datetime, no default)</creation-date>
  <last-modification-date>(datetime, no default)</last-modification-date>
  <type>(string, no default)</type>
  
  <!-- Type specific fields -->
  ... type specific fields ...
</configuration>

Client Behaviour: Parsing folder based XML configuration data

• Clients SHALL parse folders of folder-type 'configuration' starting from the least to the most significant folder, followed by parsing the applicable non-email folder for 'configuration' type objects;
• Clients SHALL only follow the most significant value for any given configuration parameter, configuration values set by less significant sources SHALL be overridden by more significant sources;
• The order of parsing beginning with the least significant category of folder SHALL be as follows:

1. Shared folder(s) with folder-type value.shared set to 'configuration';
2. Folder(s) of other users with folder-type value.shared set to 'configuration' or 'configuration.default';
3. Folder of current user with folder-type value.shared set to 'configuration.default';
4. Folder(s) of current user with folder-type value.shared set to 'configuration';
5. 'configuration' type objects for current folder NOT of folder-type 'email' or 'configuration';

• If there is more than one folder in any of categories listed above, folders shall be parsed in alphabetical order traversing through the hierarchy as they appear in the IMAP folder tree according to RFC 3501 ^[9] and its updates;
• If there is more than one configuration object in any given folder of the same type affecting the same/overlapping configuration objects/values AND there is no other policy for treating this case defined in the particular configuration object definition, objects SHALL be interpreted in the order of their 'creation-date' from the oldest to the youngest configuration object.

Upgrade Path

This KEP adds new functionality and folder types that will not be understood by older clients.

Clarification possibility
Kolab Format 2.0 is not very explicit about how clients should treating folder and object types unknown to them, so substantial differences between clients are possible.

Rationale

Overview

There have been repeated discussions about how and where to store configuration for application specific settings in the Kolab Groupware Solution. In some cases, these ended up in annotations themselves (e.g. Z-Push configuration ^[12]) in other cases they ended up in LDAP (e.g. free/busy list generation interval). Some scenarios have thus far only been theoretically examined, e.g. use of individual message annotations.

Any such choice has advantages and disadvantages, specific properties that make it well suited for one, but not another scenario, e.g. offline storage yes/no, ability to share with others, ability to be determined by admin without user influence, and so on and so forth.

So the Kolab Community has come to understand it needs a toolset of approaches to storing configuration and coordination data from which we need to choose carefully for every individual use case and issue we seek to address. Besides the approaches that are already in use, this KEP also defines a new approach that was suggested by Bernhard Reiter^[13] during the discussion on where to store Z-Push configuration data and became the basis of this KEP.

The resulting set of four clearly defined mechanisms that can be mixed, matched and applied to the various scenarios should result in an encompassing set of options while ensuring these are used consistently across scenarios to simplify the life of all participants in the community.

Rationale on encoding of values for RFC 5257 and RFC 5464 annotations

As the sections Background: Requirements by RFC 5257 and Background: Requirements by RFC 5464 demonstrate, values for these annotations have different requirements: RFC 5257 specifies UTF-8 text, RFC 5464 allows strings or binary data.

Because annotations according to RFC 5257 and RFC 5464 are conceptually very similar, we aim to unify the practical aspects of their use as much as possible. Identical rules for values to be stored is a step in that direction and the provisions in this KEP should be sufficiently wide to allow for efficient usage in all kinds of scenarios.

Explicitly choosing the JavaScript Object Notation (JSON)^[4] for encoding complex values also comes from the same background. Unlike other serializations which are often dependent upon a particular programming language, JSON encoding is equally available in a wide range of languages. Furthermore its default output is defined as UTF-8, thus matching the character range of the more limited of the two annotations, RFC 5257. The JSON specification also allows for UTF-16LE, UTF-32LE, UTF-16BE encoding in principle, but these have been excluded by an explicit selection of UTF-8 for the JSON encoding in the normative section of this KEP.

Where that encoding is insufficient for reasons unforeseeable during the drafting of this KEP, Base64 encoding is also allowed in order to wrap whatever else we might need to store. It should be noted however that at the current point in time it is not clear why Base 64 should ever be used in practice.

References

Copyright

This document has been placed in the public domain.