| 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. |