Debian Codegraph @

doc/html/_sources/imap/reference/admin/access-control/rights-reference.rst.txt

raw
1 :tocdepth: 1
2
3 .. _imap-admin-access-control-lists-rights-reference:
4
5 =====================================
6 Access Control Lists Rights Reference
7 =====================================
8
9 Access rights in Cyrus IMAP are fully compatible with :rfc:`4314`,
10 *IMAP4 Access Control List (ACL) Extension*, which has obsoleted
11 :rfc:`2086`.
12
13 Additional documentation on Access Control is available in the following
14 documents:
15
16 * :ref:`imap-admin-access-control-combining-rights`
17 * :ref:`imap-admin-access-control-defaults`
18
19 Individual 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.