Authentication is split into two separate parts: the authentication method,
and the password/user information backend (FIXME: is there a good name for
that? I can't think of any).

Currently supported methods:

 - 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, and 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

passwd, shadow and pam backends work only with plaintext authentication.
passwd-file can be used with both plaintext and Digest-MD5. More backends
can be easily added later.


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 README 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, the user is searched from all the realms, and first found is
used.

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.

Easiest way to generate Digest-MD5 passwords is to use perl:

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