1:tocdepth: 1
2
3.. _imap-admin-access-control-lists-rights-reference:
4
5=====================================
6Access Control Lists Rights Reference
7=====================================
8
9Access rights in Cyrus IMAP are fully compatible with :rfc:`4314`,
10*IMAP4 Access Control List (ACL) Extension*, which has obsoleted
11:rfc:`2086`.
12
13Additional documentation on Access Control is available in the following
14documents:
15
16*   :ref:`imap-admin-access-control-combining-rights`
17*   :ref:`imap-admin-access-control-defaults`
18
19Individual Rights Reference
20===========================
21
22.. _imap-admin-access-control-right-l:
23
24``l``
25-----
26
27    Stands for **lookup**.
28
29    The ACI subject can lookup this folder, and see that the folder
30    exists, meaning the folder will appear in the response to a
31    ``LIST "" "*"`` command issued by a client.
32
33    Folders to which the ACI subject has no lookup rights may still be
34    subscribed to. The lookup right is only required if Cyrus IMAP has
35    been configured with the ``allowallsubscribe`` setting to ``0``.
36
37    This setting defaults to ``0``. In a Cyrus IMAP Murder, this setting
38    is typically set to ``1``.
39
40    The :ref:`imap-admin-access-control-right-l` right can be assigned
41    to a folder, without the :ref:`imap-admin-access-control-right-l`
42    right having been given out for the parent folder. Cyrus IMAP will
43    pretend the parent folder does not exist;
44
45    :rfc:`4314`, states the following example in section 4:
46
47    .. epigraph::
48
49        Note that if the user has
50        :ref:`imap-admin-access-control-right-l` right to a mailbox
51        ``A/B``, but not to its parent mailbox ``A``, the ``LIST``
52        command should behave as if the mailbox ``A`` doesn't exist, for
53        example:
54
55        .. parsed-literal::
56
57            C: A777 LIST "" *
58            S: * LIST (\\NoInferiors) "/" "A/B"
59            S: * LIST () "/" "C"
60            S: * LIST (\\NoInferiors) "/" "C/D"
61            S: A777 OK LIST completed
62
63.. _imap-admin-access-control-right-r:
64
65``r``
66-----
67
68    Stands for **read**.
69
70    The ACI subject can read the contents of this folder, meaning that
71    the ACI subject is allowed to ``SELECT`` or ``EXAMINE`` the folder,
72    query its ``STATUS``, ``FETCH`` data, ``SEARCH`` the contents, and
73    ``COPY`` contents from the folder.
74
75    The :ref:`imap-admin-access-control-right-r` right also allows the
76    user to ``GETMETADATA`` when used in conjunction with the
77    :ref:`imap-admin-access-control-right-l` right, as defined in
78    :rfc:`5464`.
79
80.. _imap-admin-access-control-right-s:
81
82``s``
83-----
84
85    Stands for **seen**.
86
87    The ACI subject is permitted to maintain the ACI subject's seen
88    state for this folder, or the shared seen state in case the
89    ``/vendor/cmu/cyrus-imapd/sharedseen`` has been set to ``1`` (see
90    :ref:`imap-reference-manpages-systemcommands-cyradm`).
91
92    Additionally, the ``\Recent`` flags are preserved for the ACI
93    subject.
94
95.. _imap-admin-access-control-right-w:
96
97``w``
98-----
99
100    Stands for **write**.
101
102    The ACI subject is permitted to write to the folder, actually
103    meaning the ACI subject is permitted to maintain flags and keywords
104    other then ``\Seen`` and ``\Deleted``, which are controlled using
105    the :ref:`imap-admin-access-control-right-s` and
106    :ref:`imap-admin-access-control-right-t` rights respectively.
107
108    The :ref:`imap-admin-access-control-right-w` right also allows the
109    user to ``SETMETADATA`` when used in conjunction with the
110    :ref:`imap-admin-access-control-right-l` and
111    :ref:`imap-admin-access-control-right-r` rights, as defined in
112    :rfc:`5464`.
113
114    .. NOTE::
115
116        IMAP clients may expect to be able to set flags other than
117        ``\Seen`` and ``\Deleted`` and attempt to set those flags
118        immediately along with a "Mark as read" action, but without the
119        ACI subject actually being permitted to set some of those flags
120        through the :ref:`imap-admin-access-control-right-w` right.
121
122        :rfc:`4314`, section 4., page 15, states that the server SHOULD
123        NOT fail, as the tagged NO response is not handled very well by
124        deployed clients.
125
126        In order to comply, we have `Bug #1375 <https://github.com/cyrusimap/cyrus-imapd/issues/1375>`__, as
127        Cyrus IMAP currently does seem to issue a tagged ``NO``
128        response.
129
130.. _imap-admin-access-control-right-i:
131
132``i``
133-----
134
135    Stands for **insert**.
136
137    The ACI subject is permitted to insert content into a folder,
138    meaning the ACI subject may ``COPY`` messages with this folder as
139    the target folder, and may ``APPEND`` messages to this folder.
140
141.. _imap-admin-access-control-right-p:
142
143``p``
144-----
145
146    Stands for **post**.
147
148    The post right currently is exclusive to Cyrus IMAP, and allows the
149    ACI subject to send email to the submission address for the mailbox.
150
151    This right differs from the :ref:`imap-admin-access-control-right-i`
152    right in that the delivery system inserts trace information into
153    submitted messages.
154
155    Example implementations using the
156    :ref:`imap-admin-access-control-right-p` right include shared
157    folders to which specific recipient addresses are delivered through
158    LMTP pre-authorized as the ``postuser``, which must then also have
159    the :ref:`imap-admin-access-control-right-p` right on the target
160    folder.
161
162.. _imap-admin-access-control-right-c:
163
164``c``
165-----
166
167    Stands for **create**.
168
169    The create right is a right introduced with :rfc:`2086`, indicating
170    the ACI subject's right to create new sub-folders in the parent
171    folder on which this right has been assigned, but also to delete the
172    same folder.
173
174    Since :rfc:`4314`, the :ref:`imap-admin-access-control-right-c`
175    right has been replaced with the
176    :ref:`imap-admin-access-control-right-k` right to allow the ACI
177    subject to ``CREATE`` folders, and the
178    :ref:`imap-admin-access-control-right-x` right to allow the ACI
179    subject to ``DELETE`` folders.
180
181    .. IMPORTANT::
182
183        The :ref:`imap-admin-access-control-right-c` right should no
184        longer be used. It will be deprecated completely in version
185        |imap_version_rfc2086_dropped|.
186
187        While Cyrus IMAP is backwards compatible when it comes to the
188        :ref:`imap-admin-access-control-right-c` right, which it
189        implements as implying as the
190        :ref:`imap-admin-access-control-right-k` right, implementations
191        should not count on the :ref:`imap-admin-access-control-right-c`
192        right backwards compatibility to be around forever, and fully
193        implement the successor rights
194        :ref:`imap-admin-access-control-right-k` and
195        :ref:`imap-admin-access-control-right-x`.
196
197.. _imap-admin-access-control-right-k:
198
199``k``
200-----
201
202    The ACI subject has the right to ``CREATE`` a new folder if the
203    :ref:`imap-admin-access-control-right-k` right exists on the parent
204    folder of the folder to be created.
205
206    The rights required for a ``RENAME`` to be successful could be
207    illustrated by describing a ``RENAME`` as a ``CREATE`` of the new
208    folder, not exactly followed by a ``COPY`` on the old folder's
209    contents, but more like a move like on a filesystem, and finally a
210    ``DELETE`` on the old folder.
211
212    As such, the :ref:`imap-admin-access-control-right-k` is the right
213    required on the parent folder of the target folder, and the
214    :ref:`imap-admin-access-control-right-x` right on the source folder.
215
216    To further illustrate, suppose the ACI subject has the
217    :ref:`imap-admin-access-control-right-k` right on folder
218    ``C/``, and the :ref:`imap-admin-access-control-right-x` right on
219    folder ``A/B``. The execution of the command ``RENAME A/B C/B``
220    would succeed.
221
222.. _imap-admin-access-control-right-a:
223
224``a``
225-----
226
227    Stands for **administer**.
228
229    The ACI subject is allowed to administer the folder, meaning the ACI
230    subject is allowed to perform administrative operations on the
231    folder.
232
233    The :ref:`imap-admin-access-control-right-a` right is needed to
234    successfully execute ``SETACL``, ``DELETEACL`` (short for
235    ``SETACL ""``) and to execute ``GETACL`` or ``LISTRIGHTS``.
236
237    .. NOTE::
238
239        IMAP clients may issue a ``GETACL`` in order to obtain the ACI
240        subject's rights on the folder, where they should be using
241        ``MYRIGHTS``, as ``GETACL`` or ``LISTRIGHTS`` return the full
242        Access Control List, including other ACI subject's identifiers.
243
244        However unless the ACI subject has the
245        :ref:`imap-admin-access-control-right-a` right on a folder,
246        issuing a ``GETACL`` or ``LISTRIGHTS`` will cause Cyrus IMAP to
247        send a tagged ``NO: Permission denied`` response if the ACI
248        subject has the :ref:`imap-admin-access-control-right-l` right
249        on the folder, and a ``NO: No Such Mailbox`` response otherwise,
250        as per section 8 of :rfc:`2086` and section 6 of :rfc:`4314` --
251        both conveniently called *Security Considerations* -- which
252        state that the IMAP server must not inadvertently admit the
253        mailbox exists.
254
255.. _imap-admin-access-control-right-x:
256
257``x``
258-----
259
260    Use the :ref:`imap-admin-access-control-right-x` right to indicate
261    the ACI subject has the right to ``DELETE`` the folder on which the
262    ACL is set, as opposed to the now obsolete
263    :ref:`imap-admin-access-control-right-c` right or
264    :ref:`imap-admin-access-control-right-d` right.
265
266.. _imap-admin-access-control-right-t:
267
268``t``
269-----
270
271    The ACI subject is allowed to delete messages from this folder,
272    meaning that the ACI subject is allowed to flag messages as
273    ``\Deleted``.
274
275    In IMAP, messages are only actually deleted (i.e. in a way that
276    makes them invisible to users of the folder) after the folder's
277    contents have been expunged.
278
279    For the corresponding ``EXPUNGE`` command however, the
280    :ref:`imap-admin-access-control-right-e` right is required.
281
282.. _imap-admin-access-control-right-n:
283
284``n``
285-----
286
287    The ACI subject is allowed to annotate individual messages in this
288    folder, in compliance with :rfc:`5257`.
289
290    .. NOTE::
291
292        The ACI subject must also have at least the
293        :ref:`imap-admin-access-control-right-r` right, as otherwise the
294        ACI subject won't know which messages are available to annotate.
295
296        This is not explicitly mentioned in the :rfc:`5257`, but
297        implied.
298
299.. _imap-admin-access-control-right-e:
300
301``e``
302-----
303
304    Stands for **expunge**.
305
306    The ACI subject is allowed to expunge messages in this folder,
307    meaning the ACI subject has the right to remove all messages that
308    have been flagged as ``\Deleted`` from all visibility.
309
310    In IMAP, expunging messages only applies to messages flagged as
311    ``\Deleted``. For the ACI subject to be able to flag messages as
312    ``\Deleted`` however, the :ref:`imap-admin-access-control-right-t`
313    right is required.
314
315    We say "remove from all visibility", because the implementation of
316    expunging messages in Cyrus IMAP is subject to the ``expunge_mode``
317    setting in :cyrusman:`imapd.conf(5)`, which when set to ``delayed``
318    only causes the reference to the expunged messages to be deleted
319    from the folder index database -- effectively removing the expunged
320    message(s) from all visibility, while the individual message files
321    remain in place on the Cyrus IMAP server filesystem.
322
323    .. seealso::
324
325        *   :ref:`imap-admin-sop-restoring-expunged-messages`
326
327    .. NOTE::
328
329        IMAP clients may expect to be able to ``EXPUNGE`` a folder
330        regardless of the availability of the
331        :ref:`imap-admin-access-control-right-e` right to the current
332        user.
333
334.. _imap-admin-access-control-right-d:
335
336``d``
337-----
338
339    Stands for **delete**.
340
341    This is the legacy :rfc:`2086` access control right for the
342    ``DELETE`` command.
343
344    In versions of Cyrus IMAP implementing only this right (prior to
345    2.3.7), ACI subjects were allowed to flag messages as
346    ``\Deleted``, and ``EXPUNGE`` and ``DELETE`` folders.
347
348    The delete right has been split in to three separate rights,
349    :ref:`imap-admin-access-control-right-t` (flag messages as
350    ``\Deleted``), :ref:`imap-admin-access-control-right-e`
351    (``EXPUNGE`` folder) and :ref:`imap-admin-access-control-right-x`
352    (``DELETE`` folder).
353
354    .. NOTE::
355
356        The ``deleteright`` setting in :cyrusman:`imapd.conf(5)`
357        controls the :rfc:`2086` right which controls whether or not the
358        ACI subject may delete a folder. However, this setting (as the
359        original specification for the delete right was considered
360        ambiguous) is ignored, and if it is set to
361        :ref:`imap-admin-access-control-right-c`, is automatically
362        converted to the :ref:`imap-admin-access-control-right-x` right.
363
364    .. IMPORTANT::
365
366        Even though Cyrus IMAP is backwards compatible when it comes to
367        the :ref:`imap-admin-access-control-right-d` right, which it
368        implements as implying as the
369        :ref:`imap-admin-access-control-right-e` and
370        :ref:`imap-admin-access-control-right-t` rights, implementations
371        should not count on the :ref:`imap-admin-access-control-right-d`
372        right backwards compatibility to be around forever, and instead
373        fully implement the successor rights
374        :ref:`imap-admin-access-control-right-e`,
375        :ref:`imap-admin-access-control-right-t` and
376        :ref:`imap-admin-access-control-right-x` rights.
377