summaryrefslogtreecommitdiff
path: root/KEP-0009.txt
blob: 52b53840abeef6fafffa78468753fc9273a98c95 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
{{kep
 |number=9
 |ticketnumber=
 |title=Storage of configuration and application control information
 |author=Georg Greve
 |author_email=greve@kolabsys.com
 |status=approved
 |type=design
 |creation_date=
 |obsoleted_by=
 |related=
}}


== Abstract ==

This Kolab Enhancement Proposal (KEP) <ref name"kep">[[KEP:1]] Bootstrapping the KEP process</ref> 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
# ANNOTATE annotations, both private and shared (new)
# METADATA annotations, both private and public (modified, previously ANNOTATEMORE)
# 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}} <ref name="rfc4511">{{rfc|4511|title=Lightweight Directory Access Protocol (LDAP): The Protocol}}</ref>). 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
# ANNOTATE annotations, both private and shared
# METADATA annotations, both private and public
# Configuration XML objects and specialised folders for their storage
# 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}} <ref name="rfc5257">{{rfc|5257|title=Internet Message Access Protocol - ANNOTATE Extension}}</ref>, 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}}<ref name="rfc4627">{{rfc|4627|title=The application/json Media Type for JavaScript Object Notation (JSON)}}</ref>, the JavaScript Object Notation (JSON).

If that encoding cannot safely represent the value, Base64 encoded according to {{rfc|3548}} <ref name="rfc3548">{{rfc|3548|title=The Base16, Base32, and Base64 Data Encodings}}</ref> '''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}}<ref name="rfc3629">{{rfc|3629|title=UTF-8, a transformation format of ISO 10646}}</ref> as specified in RFC 5257<ref name="rfc5257" />.

== 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 [http://tools.ietf.org/html/draft-daboo-imap-annotatemore-05 draft version 5 of the ANNOTATEMORE proposal] which has been finalized in February 2009 into the IMAP METADATA Extension defined in {{rfc|5464}} <ref name="rfc5464">{{rfc|5464|title=The IMAP METADATA Extension}}</ref>. 

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}}<ref name="rfc4627">{{rfc|4627|title=The application/json Media Type for JavaScript Object Notation (JSON)}}</ref>, the JavaScript Object Notation (JSON). 

If that encoding cannot safely represent the value, Base64 encoded according to {{rfc|3548}} <ref name="rfc3548">{{rfc|3548|title=The Base16, Base32, and Base64 Data Encodings}}</ref> '''MAY''' be used, but its use is strongly discouraged.

Other encodings '''MUST NOT''' be used.

==== Background: Requirements by RFC 5464 ====

RFC 5464<ref name="rfc5464" /> inherits the Augmented Backus-Naur Form (ABNF, {{rfc|5234}}<ref name="rfc5234">{{rfc|5234|title=Augmented BNF for Syntax Specifications: ABNF}}</ref>) including definitions from {{rfc|3501}}<ref name="rfc3501">{{rfc|3501|title=INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1}}</ref> superseded by {{rfc|4466}}<ref name="rfc4466">{{rfc|4466|title=Collected Extensions to IMAP4 ABNF}}</ref>. 

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}}<ref name="rfc3516">{{rfc|3516|title=IMAP4 Binary Content Extension}}</ref>.

{{note|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|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">
   &lt;!-- Common fields --&gt;
   <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>
   
   &lt;!-- Type specific fields --&gt;
   ... 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:
# Shared folder(s) with folder-type value.shared set to 'configuration';
# Folder(s) of other users with folder-type value.shared set to 'configuration' or 'configuration.default';
# Folder of current user with folder-type value.shared set to 'configuration.default';
# Folder(s) of current user with folder-type value.shared set to 'configuration';
# '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}} <ref name="rfc3501">{{rfc|3501|title=INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1}}</ref> 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.

{{note|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 <ref name"zpc">Z-Push Configuration Details: [[Z_push:Configuration]]</ref>) 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<ref name="ber">2010-08-27: Bernhard Reiter: [http://kolab.org/pipermail/kolab-format/2010-August/000919.html Where to store different configurations]</ref> 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|Background: Requirements by RFC 5257]] and [[#Background:_Requirements_by_RFC_5464|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)<ref name="rfc4627" /> 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 ==

{{Reflist}}

== Copyright ==

This document has been placed in the public domain.