[Dovecot] authentication documentation

[Tom Metro]

Timo Sirainen wrote:
>> 1 LOGIN tmetro at example.com password
>> 1 NO Login failed: Unsupported authentication mechanism
> 
> The error message is fine for AUTHENTICATE command I 
> think, but for LOGIN it could be something like: "Plaintext 
> authentication mechanism is disabled"

Yes, that would help clarify.


>> That got me wondering whether there were two different areas where
>> authentication terms apply - one being the password exchange in
>> the IMAP protocol, and the other being how the password is stored 
>> on the server - yet the discussion of the two seems to be mixed 
>> together in the documentation.
> 
> Where? I don't see any obvious mixes, except that DIGEST-MD5...

http://dovecot.org/doc/auth.txt says:
> Authentication is split into three parts: authentication mechanism,
> password database and user database.

Which is good, except it never defines what "authentication mechanism" 
really means, and how it is distinct from how the password is stored.

Password database is quite self explanatory, but it wouldn't hurt to 
explain the purpose of the user database here.

The information in auth.txt is of course technically correct, but the 
listing of mechanisms at the top of the file looks enough like the list 
of schemes under "Generating passwords" to cause confusion.


> ...DIGEST-MD5 is both an authentication mechanism name and password 
> scheme name (because they're supposed to be used together).

That's enough to start raising confusion. There are PLAIN-MD5 and MD5 
schemes that look similar to PLAIN and CRAM-MD5 mechanisms. When you're 
looking at something as a new user, you never know if the differences 
are significant or just inconsistencies.


> DIGEST-MD5 scheme isn't very useful unless you're using DIGEST-MD5 
> authentication.

A pretty important point that isn't made in auth.txt.


Quoting from auth.txt again:
> Most password databases support only plaintext authentication. passwd-file
> and LDAP exceptions since they support multiple password schemes.

The reasoning behind this should be explained. (Though that would be 
more obvious once "authentication mechanism" is well defined.) Also the 
wording is confusing as it is, and also out of date because it doesn't 
mention pgsql and mysql.

The point you want to make is that if the client authenticates using 
plain text in the IMAP protocol, then Dovecot can encrypt the password 
to match a variety of encryption schemes used in password databases.

If the client authenticates using a mechanism like DIGEST-MD5, which is 
a one-way hashing algorithm, Dovecot can't "translate" it to some other 
scheme, so the password databases must use a password encryption scheme 
that matches the IMAP protocol authentication mechanism.


> How about:
> 
> # Space separated list of wanted authentication mechanisms:
> #   plain digest-md5 anonymous
> #
> # All IMAP/POP3 clients support plain-authentication. Digest-MD5 is more
> # secure, but it's not widely supported by clients. Note that by default
> # plaintext authentication is disabled unless SSL is used - see
> # disable_plaintext_auth setting.
> auth_mechanisms = plain

Here too, I think it would be useful to define "authentication 
mechanisms", but you should probably first provide a better definition 
for "Authentication processes." Though the term "process" makes me think 
  that we're talking about an executable. But I guess it is defining the 
behavior of a child process - right?

Perhaps:

##
## Authentication processes
##

# An Authentication process is a child process used by Dovecot that
# handles the authentication steps. The steps cover an authentication
# mechanism (auth_mechanisms, how the client authenticates in the IMAP
# protocol), which password database should be queried (auth_passdb),
# and which user database should be queried (auth_userdb, to obtain
# UID, GID, and location of the user's mailbox/home directory).
#
# You can have multiple processes, though a typical configuration will
# have only one. Each time "auth = xx" is seen, a new process
# definition is started. The point of multiple processes is to be able
# to set stricter permissions. (See auth_user below.)
#
# Just remember that only one Authentication process is asked for the
# password, so you can't have different passwords accessible through
# different process definitions (unless they have different
# auth_mechanisms, and you're ok with having different password for
# each mechanisms).

(What is the order in which Authentication processes are chosen, if say, 
you have multiple defined for the 'plain' auth_mechanisms? Or is that 
considered a configuration error?

The above paragraph might be describing an obscure enough condition that 
it would be better moved to auth.txt. If anything, the point you might 
want to get across is that each auth mechanism should uniquely map to a 
single password database.)


And...

# Specifies how the client authenticates in the IMAP protocol.
# Space separated list of permitted authentication mechanisms:
#   anonymous plain digest-md5 cram-md5
#
# anonymous - No authentication required.
# plain - The password is sent as plain text. All IMAP/POP3 clients
#  support this, and the password can be encrypted by Dovecot to match
#  any of the encryption schemes used in password databases.
# digest-md5 and cram-md5 - both encrypt the password so it is more
#  secure in transit, but are not well supported by clients, and
#  require that the password database use a matching encryption
#  scheme.
#
# See auth.txt for more details.
#
# If you are using SSL there is less benefit to digest-md5 and
# cram-md5 as the communication is already encrypted. Note that by
# default plain text authentication is disabled unless SSL is used -
# see disable_plaintext_auth setting.
auth_mechanisms = plain

(I thought by default disable_plaintext_auth=no. Has that changed?

My assertion, "the password can be encrypted by Dovecot to match any of 
the encryption schemes used in password databases," may not be accurate. 
Your comments seem to imply that Dovecot won't translate a plain 
password to a digest-md5 storage scheme (perhaps also cram-md5), though 
it seems this should be possible.)

  -Tom