Digest-MD5 Authentication Mechanism
===================================

Digest-MD5 has two things that make it special and which can cause problems:

 * Instead of using user@domain usernames, it supports *realms*.
 * User name and realm are part of the MD5 hash that's used for authentication.

Realms
------

Dovecot v1.0 has problems handling user@domain style usernames with Digest-MD5
and passwords stored in plaintext in the password database. You'll need to use
realms instead. You'll need to specify realms in the config file:

---%<-------------------------------------------------------------------------
auth_realms = example.com another.example.com
---%<-------------------------------------------------------------------------

All listed realms are presented to the client and it can select to use one of
them. However some clients always use the first realm, so keep it your primary
one.

DIGEST-MD5 scheme
-----------------

Alternative to using realms is to store the passwords using DIGEST-MD5 scheme.
It's a MD5 sum of "user:realm:password" string. So for example if you want to
log in as 'user@example.com', create the password with:

---%<-------------------------------------------------------------------------
% echo -n "user@example.com::pass"|md5sum
e5c14634647ab53ff84f189addd7c518  -
---%<-------------------------------------------------------------------------

Note that if you're using DIGEST-MD5 scheme to store the passwords, you can't
change the users' names in any way or the authentication will fail because the
MD5 sums don't match.

Testing
-------

You can use 'imtest' from Cyrus SASL
[http://asg.web.cmu.edu/sasl/sasl-library.html] library:

---%<-------------------------------------------------------------------------
# With realm:
imtest -a user -r example.com
# Without realm:
imtest -a user@example.com
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2009-10-16 04:42)