Access Control Lists
====================

Dovecot supports giving ACLs to mailboxes, although it doesn't yet support the
actual IMAP ACL extension. The code allows multiple ACL backends, but currently
Dovecot supports only virtual ACL files. See<SharedMailboxes.txt> for
information how to implement them.

ACLs can be enabled in dovecot.conf with:

---%<-------------------------------------------------------------------------
protocol imap {
..
  mail_plugins = acl
}
...
plugin {
  acl = vfile:/etc/dovecot-acls
}
---%<-------------------------------------------------------------------------

Groups are supported since v1.1+ by returning a comma-separated 'acl_groups'
<extra field> [UserDatabase.ExtraFields.txt] from userdb, which contains all
the groups the user belongs to.

The default ACLs for mailboxes is to give owner all permissions and other users
none. Mailboxes in public namespaces don't have owners, so by default no-one
can access them.

vfile backend
-------------

vfile backend supports per-mailbox ACLs and global ACLs which apply to all
users' mailbox with the same name.

Per-mailbox ACLs are stored in 'dovecot-acl' named file, exists in:

 * maildir: The maildir's root directory (eg. '~/Maildir',
   '~/Maildir/.folder/')
 * mbox: Currently in the same directory as indexes (eg.
   '~/mail/.imap/INBOX/'), but this might change
 * dbox: dbox's root directory (eg. '~/mail/INBOX/Mails/')

Global ACLs
-----------

Global ACLs are stored in the directory you gave as ACL plugin parameter
('/etc/dovecot-acls' in above example). They exist with the same name as the
mailbox. For example:

 * INBOX: '/etc/dovecot-acls/INBOX'
 * Maildir: archives.2007: '/etc/dovecot-acls/archives.2007'
 * mbox: archives/2007: '/etc/dovecot-acls/archives/2007'

The mailbox names are looked up using the real separators, not the virtual ones
that can be configured in namespaces. So even if you specify 'separator=/' with
Maildir the ACL files still use '.' separator, just as the maildir directory
names are also stored using '.'. There is no leading '.' however.

There is an extra problem with mailbox formats that use '/' as the separator
(e.g. mbox, dbox): If you have mailboxes *foo* and *foo/bar* and you wish to
give ACLs to both of them, you can't create both 'foo' as ACL file and 'foo' as
directory (for 'foo/bar' ACL file). To do this, you can use instead:

 * foo: '/etc/dovecot-acls/foo/.DEFAULT'
 * foo/bar: '/etc/dovecot-acls/foo/bar'

WARNING: With v1.0 namespace prefixes are ignored, so if you have multiple
namespaces their mailbox names could conflict. With v1.1 you must use the
namespace prefixes. For example with 'prefix=INBOX/' for mailbox *foo* use
'/etc/dovecot-acls/INBOX/foo'.

ACL files
---------

The files themselves are in format:

---%<-------------------------------------------------------------------------
<identifier> <ACLs> [:<named ACLs>]
---%<-------------------------------------------------------------------------

Where *identifier* is one of:

 * group-override=*group name*
 * owner / user=*user name*
 * group=*group name*
 * owner
 * authenticated
 * anyone / anonymous

The ACLS are processed in the order given above, so eg. if you have given
read-access to some group, you can still remove that from some specific user.

Group-override identifier allows you to override users' ACLs. Probably the most
useful reason to do this is to temporarily disable access for some users. For
example:

---%<-------------------------------------------------------------------------
user=timo rw
group-override=tempdisabled
---%<-------------------------------------------------------------------------

Now if *timo* is in *tempdisabled* group, he has no access to the mailbox. This
wouldn't be possible with a normal group identifier, because the 'user=timo'
would override it.

The currently supported ACLs and their corresponding named ACLs are: 

+---+---------------+---------------------------------------------------------+
| l | lookup        | Mailbox is visible in mailbox list. Mailbox can be      |
|   |               | subscribed to.                                          |
+---+---------------+---------------------------------------------------------+
| r | read          | Mailbox can be opened for reading.                      |
+---+---------------+---------------------------------------------------------+
| w | write         | Message flags and keywords can be changed, except \Seen |
|   |               | and \Deleted                                            |
+---+---------------+---------------------------------------------------------+
| s | write-seen    | \Seen flag can be changed                               |
+---+---------------+---------------------------------------------------------+
| t | write-deleted | \Deleted flag can be changed                            |
+---+---------------+---------------------------------------------------------+
| i | insert        | Messages can be written or copied to the mailbox        |
+---+---------------+---------------------------------------------------------+
| e | expunge       | Messages can be expunged                                |
+---+---------------+---------------------------------------------------------+
| k | create        | Mailboxes can be created under this mailbox             |
+---+---------------+---------------------------------------------------------+
| x | delete        | Mailbox can be deleted                                  |
+---+---------------+---------------------------------------------------------+
| a | admin         | Administration rights to the mailbox                    |
+---+---------------+---------------------------------------------------------+

The ACLs are compatible with RFC 4314 (IMAP ACL extension, updated version).

Unknown ACL letters are complained about, but unknown named ACLs are ignored.
Named ACLs are mostly intended for future extensions.

Example ACL file:

---%<-------------------------------------------------------------------------
owner lrwstiekxa
user=timo rl
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2009-01-07 04:42)
