Authentication

Authentication is split into four parts:

1. Authentication mechanisms
2. Password schemes
3. Password databases
4. User databases

Authentication Mechanisms

Authentication mechanism means the protocol that IMAP or POP3 client communicates with to Dovecot to perform the authentication. The most simple one is PLAIN, in which the client simply sends the password unencrypted to Dovecot. All clients support PLAIN authentication, but obviously there's the problem that anyone listening the network can steal the password. For that reason (and some others) other mechanisms were implemented.

Non-PLAIN mechanisms have one major disadvantage however. In server side the password must be stored in a special format or in plaintext. This makes it impossible to use most mechanisms with the common DES and MD5 crypted passwords.

Today however many people use SSL, and there's no problem with sending unencrypted password inside SSL secured connection. So if you're using SSL, you probably don't need to bother worrying about anything else than PLAIN mechanism.

Other non-PLAIN mechanisms include:

• CRAM-MD5: Protects the password in transit against eavesdroppers. Somewhat good support in clients.
• DIGEST-MD5: Somewhat stronger cryptographically than CRAM-MD5, but clients rarely support it.
• APOP: This is POP3-specific authentication. Similiar to CRAM-MD5, but requires storing password in plaintext. [in 1.0-tests only]
• NTLM: Mechanism created by Microsoft and supported by their clients. [in 1.0-tests only]
• KERBEROS: Kerberos v5 support. [Currently exists only as a patch.]
• LOGIN: Similiar to PLAIN, not very useful. [in 1.0-tests only]
• ANONYMOUS: Support for logging in anonymously. This may be useful if you're intending to provide publically accessible IMAP archive.

Password Schemes

Passwords can be stored in password database in many different formats. Usually they should be stored encrypted just to make sure if an attacker gets into your computer he can't easily read everyone's passwords. With PLAIN authentication mechanism it doesn't matter in which format the password is stored locally, but with other mechanisms you either have to store them in their special format (which is incompatible with everything else except PLAIN), or you'll have to store the passwords as plaintext.

Often you already have the passwords in some specific format, so best idea is to just keep using them. Otherwise just pick one to use, for example SHA1.

Currently supported password schemes are:

• CRYPT: DES-based encryption. This is how passwords are historically stored in /etc/passwd.

• LANMAN: DES-based encryption. Used sometimes with NTLM mechanism.
• NTLM: MD4 sum of the password stored in hex. Used with NTLM mechanism.

• MD5: MD5crypt. Another format historically used in /etc/passwd.

• PLAIN-MD5: MD5 sum of the password stored in hex.
• LDAP-MD5: MD5 sum of the password stored in base64.
• SMD5: Salted MD5 sum of the password stored in base64.
• HMAC-MD5: Use with CRAM-MD5 mechanism.
• DIGEST-MD5: Use with DIGEST-MD5 mechanism.
• SHA: SHA1 sum of the password stored in base64.
• SSHA: Salted SHA1 sum of the password stored in base64.
• PLAIN: Password is in plaintext.

Default password scheme can usually be specified for password database. You can override it by prefixing password with {SCHEME}. For example "{PLAIN}password". Note that not all password databases support changing the scheme. With some you might cause incompatibilities with other software using it (eg. passwd, shadow) and with others it simply isn't possible at all because of the way they work (eg. PAM).

Dovecot 1.0-tests contain dovecotpw utility which can be used to easily generate passwords for wanted scheme.

Password Databases

Dovecot authenticates user using password database. It needs to contain only user names and their passwords.

Dovecot 1.0-tests support defining multiple password databases, so that if password doesn't match in the first database, it checks the next one. This can be useful if you want to easily support having both local system users in /etc/passwd but also virtual users. This isn't possible in 0.99 releases.

Currently supported password databases:

• passwd: /etc/passwd or similiar (using getpwnam() function)

• shadow: /etc/shadow or similiar (using getspnam() function)

• pam: Pluggable Authentication Modules

• passwd-file: /etc/passwd-like file in specified location

• ldap: Lightweight Directory Access Protocol
• mysql: MySQL database.
• pgsql: PostgreSQL database.
• bsdauth: BSD authentication
• vpopmail: External software used to handle virtual domains

User Databases

Dovecot gets user's UID, GID, home directory and mail location from user database after user is authenticated. User and password databases may be the same one or they may be different depending on your needs.

For more information about UID and GID, see UserIds. For more information about home directory and mail location see VirtualUsers.

Currently supported user databases:

• passwd: /etc/passwd or similiar (using getpwnam() function)

• passwd-file: /etc/passwd-like file in specified location

• ldap: Lightweight Directory Access Protocol
• mysql: MySQL database.
• pgsql: PostgreSQL database.
• static: Static UID and GID, home directory from given template
• vpopmail: External software used to handle virtual domains

Database Descriptions

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, but nowadays PAM is usually preferred to this.

PAM

Pluggable Authentication Modules. This is the most common way to authenticate users nowadays. The PAM configuration is usually in /etc/pam.d/ directory. By default Dovecot uses dovecot PAM service name, so the configuration is read from /etc/pam.d/dovecot file. You can change this by appending the wanted service name after auth_passdb = pam, eg. auth_passdb = pam imap would use /etc/pam.d/imap. You can also set the service to * in which case Dovecot automatically uses either imap or pop3 service depending on which one user is using to login.

PAM doesn't provide a user database, so you have to use something else for that - passwd or static usually.

We should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and ApplePAM (Mac OS X).

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 and gid and preferrably home (see VirtualUsers).

Flags are currently unused.

The password field can be in three formats:

• password: Assume CRYPT password scheme
• password[type]: libpam-passwd file compatible format. Type is one of:
  • 13: CRYPT scheme
  • 34: MD5 scheme
• {SCHEME}password

LDAP

See doc/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.

MySQL

See doc/dovecot-mysql.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 SQL connection.

PostgreSQL

See doc/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 SQL connection.

static

Static user database can be used when you want to use only single UID and GID for all users and home directory can be specified with a simple template. The syntax is:

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

The home directory template can use variables just like default_mail_env setting in config file. See [wiki:Variables Variables].

BSDauth

FIXME: I'm not actually sure who uses this. Some BSDs I guess..

vpopmail

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

Currently vpopmail works only with PLAIN mechanism. vpopmail also supports storing passwords in plaintext which would allow adding support for other mechanisms, but for now no-one has been interested.