This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.
Differences between revisions 6 and 29 (spanning 23 versions)
Revision 6 as of 2004-08-28 19:48:32
Size: 9223
Editor: ip213-185-36-189
Comment:
Revision 29 as of 2013-06-26 14:53:36
Size: 1477
Editor: TimoSirainen
Comment:
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
 1. [[Authentication/Mechanisms|Authentication mechanisms]]
 1. [[Authentication/PasswordSchemes|Password schemes]]
 1. [[PasswordDatabase|Password databases]]
 1. [[UserDatabase|User databases]]
Line 10: Line 9:
= Authentication Mechanisms = == Authentication mechanisms vs. password schemes ==
Authentication mechanisms and password schemes are often confused, because they have somewhat similar values. For example there is a PLAIN auth mechanism and PLAIN password scheme. But they mean completely different things.
Line 12: Line 12:
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 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.

 * 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.
 * '''Authentication mechanism is a client/server protocol'''. It's about how the client and server talk to each others in order to perform the authentication. Most people use only PLAIN authentication, which basically means that the user and password are sent without any kind of encryption to server. SSL/TLS can then be used to provide the encryption to make PLAIN authentication secure.
 * '''Password scheme is about how the password is hashed in your password database'''. If you use a PLAIN scheme, your passwords are stored in cleartext without any hashing in the password database. A popular password scheme MD5-CRYPT (also commonly used in {{{/etc/shadow}}}) where passwords looks like "$1$oDMXOrCA$plmv4yuMdGhL9xekM.q.I/".
 * Plaintext authentication mechanisms work with ALL password schemes.
 * Non-plaintext authentication mechanisms require either PLAIN password scheme or a mechanism-specific password scheme.

Authentication

Authentication is split into four parts:

  1. Authentication mechanisms

  2. Password schemes

  3. Password databases

  4. User databases

Authentication mechanisms vs. password schemes

Authentication mechanisms and password schemes are often confused, because they have somewhat similar values. For example there is a PLAIN auth mechanism and PLAIN password scheme. But they mean completely different things.

  • Authentication mechanism is a client/server protocol. It's about how the client and server talk to each others in order to perform the authentication. Most people use only PLAIN authentication, which basically means that the user and password are sent without any kind of encryption to server. SSL/TLS can then be used to provide the encryption to make PLAIN authentication secure.

  • Password scheme is about how the password is hashed in your password database. If you use a PLAIN scheme, your passwords are stored in cleartext without any hashing in the password database. A popular password scheme MD5-CRYPT (also commonly used in /etc/shadow) where passwords looks like "$1$oDMXOrCA$plmv4yuMdGhL9xekM.q.I/".

  • Plaintext authentication mechanisms work with ALL password schemes.
  • Non-plaintext authentication mechanisms require either PLAIN password scheme or a mechanism-specific password scheme.

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