Authentication is split into three parts: authentication mechanism,
password database and user database.

Currently supported authentication mechanisms:

 - PLAIN: By itself it's very insecure, but through secured SSL/TLS
   connection it should be fine.
 - DIGEST-MD5: Should be quite secure by itself. It also supports
   integrity protecting and crypting the rest of the communication, but
   we don't support those yet.
 - CRAM-MD5: Protects the secret in transit from eavesdroppers.  Doesn't
   provide any integrity guarantees.
 - ANONYMOUS: No authentication required. User will be logged in as the user
   specified by auth_anonymous_username setting (default "anonymous"). There's
   no special restrictions given for anonymous users so you have to make sure
   it doesn't have access to unwanted locations.

Currently supported password databases:

 - passwd: /etc/passwd or similiar, using getpwnam()
 - shadow: /etc/shadow or similiar, using getspnam()
 - pam: Pluggable Authentication Modules
 - passwd-file: /etc/passwd-like file in specified location
 - ldap: Lightweight Directory Access Protocol
 - vpopmail: External software used to handle virtual domains
 - pgsql: A PostgreSQL database.

Currently supported user databases:

 - passwd: /etc/passwd or similiar, using getpwnam()
 - passwd-file: /etc/passwd-like file in specified location
 - ldap: Lightweight Directory Access Protocol
 - vpopmail: External software used to handle virtual domains
 - static: Static UID and GID, home directory from given template
 - pgsql: A PostgreSQL database.

Most password databases support only plaintext authentication. passwd-file
and LDAP exceptions since they support multiple password schemes.

Password schemes supporting only plaintext authentication:

 - CRYPT: Use crypt(). Usually DES, but some systems support others too
   (eg. MD5 and SHA1)
 - MD5: MD5crypt algorithm, sometimes used in /etc/passwd and likes
 - PLAIN-MD5: Simple MD5 sum of password. Used by libpam-pwdfile

Password schemes supporting plaintext authentication and more:

 - PLAIN: Although not that good idea, it enables support for all current
   and future authentication mechanisms.
 - HMAC-MD5: HMAC-MD5 context of password, for the CRAM-MD5 mechanism.
 - DIGEST-MD5: MD5 sum of "user:realm:password", as required by DIGEST-MD5
   mechanism.

Realms (or virtual domains) are supported by appending the "@realm" after
the user name. This behaviour works with all authentication mechanisms and
databases.

Home directory can be prefixed with "<chroot>/./" in which case <chroot>
directory will be chrooted into. The actual home directory follows the
"/./". For example "/chroot/./home/user".


passwd
------

Most commonly used as user database. Many systems use shadow passwords
nowadays so it doesn't usually work as password database. BSDs are an
exception to this, they still set the password field even with shadow
passwords.


shadow
------

Works at least with Linux and Solaris.


PAM
---

We should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and
ApplePAM (OSX). PAM doesn't provide user database, so you have to use
something else for that - passwd usually.

By default Dovecot uses "dovecot" service, ie. the PAM configuration is in
/etc/pam.d/dovecot file. You can override this by giving the wanted service
name as parameter for pam. For example "auth_passdb = pam dovecot2". If you
give "*" as service name, Dovecot uses "imap" service for IMAP connections
and "pop3" service for POP3 connections.

Here's an example /etc/pam.d/dovecot configuration file which uses standard
UNIX authentication:

auth	required	pam_unix.so nullok
account	required	pam_unix.so


passwd-file
-----------

This is compatible with regular /etc/passwd, and a password file used by
libpam-pwdfile. It's in the following format:

user:password:uid:gid:(gecos):home:(shell):flags:mail

For password database, it's enough to have only user and password fields.
For user database, you need to set also uid, gid and either home or mail.

Flags is a comma-separated list of flags, currently only recognized value
is "chroot", which makes the imap process chroot into home directory, if
allowed by master process.

The password field can be in three formats:

 - password: Assume CRYPT scheme
 - password[type]: libpam-passwd file compatible format. Type is one of:
     13: CRYPT scheme
     34: MD5 scheme
     56: DIGEST-MD5 scheme (Dovecot extension, deprecated)
 - {SCHEME}password


LDAP
----

See dovecot-ldap.conf for more information. Password and user databases may
use different configuration files to keep the information in separate
locations. If both refer to same file, they share the same LDAP connection.


vpopmail
--------

This is an external software intended to make handling virtual domains
easier. Supports Qmail and Postfix. See http://inter7.com/vpopmail.html


static
------

static uid=<uid> gid=<gid> home=<dir template>

All users share the same UID and GID. Home directory template can use %u,
%n and %d variables, see default_mail_env description in dovecot-example.conf.


PostgreSQL
----------

See dovecot-pgsql.conf for more information. Password and user databases may
use different configuration files to keep the information in separate
locations. If both refer to same file, they share the same PostgreSQL
connection.


Generating passwords
--------------------

DES:
  mkpasswd
  perl -e 'printf "%s\n", crypt("pass", "two-letter-salt")'

MD5:
  mkpasswd --hash=md5
  perl -e 'printf "%s\n", crypt("pass", "\$1\$6-8-letter-salt\$")'

PLAIN-MD5:
  perl -MDigest::MD5 -e 'printf "{PLAIN-MD5}%s\n", Digest::MD5::md5_hex("pass")'

DIGEST-MD5:
  perl -MDigest::MD5 -e 'printf "{DIGEST-MD5}%s\n", Digest::MD5::md5_hex("user:realm:pass")'