Authentication is split into two separate parts: the authentication
mechanism, and the authentication backend.

Currently supported mechanisms:

 - plaintext: 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 protection and crypting the rest of the communication, but
   we don't support those yet.

Currently supported backends:

 - passwd: /etc/passwd or similiar, using getpwnam()
 - shadow: /etc/shadow or similiar, using getspnam()
 - pam: PAM authentication
 - passwd-file: /etc/passwd-like file
 - vpopmail: External software used to handle virtual domains

Digest-MD5 works only with passwd-file. More mechanisms and backends can be
easily added later.


passwd
------

This is the most standard way to authenticate. However with shadow
passwords some systems (Linux) don't work with this backend. At least BSDs
still support this backend correctly.


shadow
------

Authenticate from /etc/shadow. Works at least with Linux and Solaris.


pam
---

PAM is the preferred authentication system nowadays with Linux. PAM handles
only password checking, for getting the user information Dovecot still
requires the user to exist in /etc/passwd. This requirement may be removed
later.

Here's an example /etc/pam.d/imap configuration file which uses
/etc/imap.passwd:

auth     required     pam_pwdfile.so pwdfile /etc/imap.passwd
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:(ignored):home:(ignored):realm:mail:flags

Only user and password fields are required. If uid, gid or home fields
aren't set, they're read from system's passwd file. If the user doesn't
exist in system, a warning is printed to syslog and the user entry is
ignored.

Either home or mail is required to exist. Home specifies the home directory
of user under which mail is located. The actual mail format and location is
automatically detected, just as if you run the imap binary directly. Other
way is to specify the mail storage parameters directly using the
mail-field, see "Detecting what to use" chapter in mail-storage.txt file
for more information about it (the MAIL environment).

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

Realm is useful only with Digest-MD5 authentication. It's possible to have
multiple users with same name but in different realms. If plaintext is used
to log in, user is expected to be in no realm.

The password field is in format: <data> "[" <type> "]", like "foo[13]".
Type can be one of the following:

 13: DES password
 34: MD5 password
 56: Digest-MD5 password - Hexadecimal MD5 sum of "user:realm:password"

If [type] isn't specified at all or it's unknown, DES is used. The 13 and
34 methods are compatible with PAM module pwdfile. Only the 56 method works
with Digest-MD5 authentication.

DES
---

Use either mkpasswd, or:

perl -e 'print crypt("pass", "two-letter-salt")."\n"'

MD5
---

perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("pass")."[34]\n"'

Digest-MD5
----------

perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("user:realm:pass")."[56]\n"'

For plaintext authentication:

perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("user::pass")."[56]\n"'