This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.
Differences between revisions 18 and 21 (spanning 3 versions)
Revision 18 as of 2006-04-25 14:27:39
Size: 10229
Revision 21 as of 2009-02-25 03:05:45
Size: 260
Editor: pool-96-240-13-138
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
Line 5: Line 4:
 1. Authentication mechanisms
 1. Password schemes
 1. Password databases
 1. User databases

= Authentication Mechanisms =

Authentication mechanism means the protocol that an IMAP or POP3 client uses to communicate with 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 commonly used 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.
 * NTLM: Mechanism created by Microsoft and supported by their clients.
 * GSSAPI: Kerberos v5 support.
 * LOGIN: Similiar to PLAIN, useful only when serving SMTP AUTH to Outlook clients (ie. pretty useless with IMAP and POP).
 * 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 non-PLAIN authentication mechanisms you either have to store the password in their special format (which is incompatible with everything else except PLAIN), or you'll have to store the passwords as plaintext.

With PLAIN mechanism it doesn't matter in which format the password is stored locally, because Dovecot will internally encrypt the sent plaintext password to match the storage scheme.

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.
 * RPA: Use with RPA 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 contains a `dovecotpw` utility which can be used to easily generate passwords for wanted scheme.

= Password Databases =

Dovecot authenticates users from password database. It needs to contain only usernames and their passwords.

Dovecot supports defining multiple password databases, so that if the 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 virtual users and also local system users in `/etc/passwd`. 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
 * sql: SQL database (PostgreSQL, MySQL, SQLite)
 * bsdauth: BSD authentication
 * vpopmail: External software used to handle virtual domains
 * checkpassword: External checkpassword program which is run

= 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 ones 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
 * sql: SQL database (PostgreSQL, MySQL, SQLite)
 * static: Static UID and GID, home directory from given template
 * vpopmail: External software used to handle virtual domains
 * prefetch: This assumes that the passdb already returned also all the required userdb information

= 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.

By giving `session=yes` parameter you can make Dovecot open a PAM session and close it immediately. Some PAM plugins, such as `pam_mkhomedir`, need this. With this parameter `/etc/dovecot.conf` might look something like this:

passdb pam {
  args = session=yes *

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

Dovecot 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 nullok
account required

On Mac OS X, the `/etc/pam.d/dovecot` file should look like this:
auth required
auth sufficient
auth sufficient
auth required
account required
password required
session required

== passwd-file ==

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


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 preferably home (see VirtualUsers).

extra_fields is a space-separated list of key=value pairs which can be used to set various settings, for example you can override default_mail_env setting by giving `mail=mbox:~/mail`.

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

Here's an example file for used by passdb:


Or for passdb and userdb:

user:{plain}pass:1000:1000::/home/user::mail=maildir:~/Maildir allow_nets=

== 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.

== SQL ==

See `doc/dovecot-sql.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> mail=<dir template>

The home and mail are both optional. The directory templates 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..
''at least openbsd''

== vpopmail ==

This is an external software intended to make handling virtual domains easier. Supports Qmail and Postfix. See []

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.
 1. [:Authentication/Mechanisms:Authentication mechanisms]
 1. [:Authentication/PasswordSchemes:Password schemes]
 1. [:PasswordDatabase:Password databases]
 1. [:UserDatabase:User databases]


Authentication is split into four parts:

  1. [:Authentication/Mechanisms:Authentication mechanisms]

  2. [:Authentication/PasswordSchemes:Password schemes]

  3. [:PasswordDatabase:Password databases]

  4. [:UserDatabase:User databases]

None: Authentication (last edited 2013-06-26 14:53:36 by TimoSirainen)