This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.
Differences between revisions 16 and 17
Revision 16 as of 2006-03-24 04:46:03
Size: 9793
Comment: fix typo
Revision 17 as of 2006-04-01 10:30:56
Size: 9861
Editor: TimoSirainen
Comment:
Deletions are marked like this. Additions are marked like this.
Line 22: Line 22:
 * 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]
 * 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).
Line 34: Line 34:
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. 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.
Line 51: Line 51:
 * RPA: Use with RPA mechanism.
Line 59: Line 60:
Dovecot 1.0-tests contain `dovecotpw` utility which can be used to easily generate passwords for wanted scheme. Dovecot contains a `dovecotpw` utility which can be used to easily generate passwords for wanted scheme.
Line 63: Line 64:
Dovecot authenticates user using password database. It needs to contain only user names and their passwords. Dovecot authenticates users from password database. It needs to contain only usernames and their passwords.
Line 65: Line 66:
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. 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.
Line 74: Line 75:
 * mysql: MySQL database.
* pgsql: PostgreSQL database.
 * sql: SQL database (PostgreSQL, MySQL, SQLite)
Line 78: Line 78:
 * checkpassword: External checkpassword program which is run
Line 81: Line 82:
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. 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.
Line 90: Line 91:
 * mysql: MySQL database.
* pgsql: PostgreSQL database.
 * sql: SQL database (PostgreSQL, MySQL, SQLite)
Line 94: Line 94:
 * prefetch: This assumes that the passdb already returned also all the required userdb information
Line 109: Line 110:
By giving -session parameter you can make Dovecot open a PAM session and close it immediately. Some PAM plugins - such as `pam_mkhomedir` - need this. [1.0-test79 and later only]. With this parameter `/etc/dovecot.conf` might look something like this: 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:
Line 113: Line 114:
args = "-session *"   args = session=yes *
Line 119: Line 120:
We should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and ApplePAM (Mac OS X). Dovecot should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and ApplePAM (Mac OS X).
Line 121: Line 122:
Here's an example /etc/pam.d/dovecot configuration file which uses standard Here's an example `/etc/pam.d/dovecot` configuration file which uses standard
Line 131: Line 132:
This is compatible with regular `/etc/passwd`, and a password file used by libpam-pwdfile. It's in the following format: This file is compatible with regular `/etc/passwd` and a password file used by libpam-pwdfile. It's in the following format:
Line 134: Line 135:
user:password:uid:gid:(gecos):home:(shell):flags:mail user:password:uid:gid:(gecos):home:(shell):extra_fields
Line 139: Line 140:
Flags are currently unused.

mail field can be used to override default_mail_env setting in configuration file.
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`.
Line 151: Line 150:
Example for CRAM-MD5 (using plaintext source passwords): Here's an example file for used by passdb:
Line 155: Line 154:
}}}

Or for passdb and userdb:

{{{
user:{plain}pass:1000:1000::/home/user::mail=maildir:~/Maildir allow_nets=192.168.0.0/24
Line 161: Line 166:
== MySQL == == SQL ==
Line 163: Line 168:
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.
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.

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 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        pam_unix.so nullok
account required        pam_unix.so

passwd-file

This file 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):extra_fields

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:

user:{PLAIN}password

Or for passdb and userdb:

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

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

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