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