1 files changed, 80 insertions, 0 deletions
diff --git a/doc/wiki/Authentication.Mechanisms.DigestMD5.txt b/doc/wiki/Authentication.Mechanisms.DigestMD5.txt
new file mode 100644
index 0000000..eda617e
--- /dev/null
+++ b/doc/wiki/Authentication.Mechanisms.DigestMD5.txt
@@ -0,0 +1,80 @@
+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.
+
+For these and other reasons Digest-MD5 has been obsoleted
+[http://tools.ietf.org/html/rfc6331] by SCRAM
+[http://tools.ietf.org/html/rfc5802].
+
+Realms
+------
+
+Dovecot v1.0 has problems handling user@domain style usernames with Digest-MD5
+and with passwords stored in plaintext in the password database.
+
+Instead, user@realm is used. Realms are an integral part of Digest-MD5. You
+will need to specify realms you want to advertise to the client in the config
+file:
+
+---%<-------------------------------------------------------------------------
+auth_realms = example.com another.example.com foo
+---%<-------------------------------------------------------------------------
+
+The realms don't have to be domains. All listed realms are presented to the
+client and it can select to use one of them. Some clients always use the first
+realm. Some clients use your domain name, whenever given more than one realm to
+choose from. Even if this was NOT one of the choices you provided (KMail,
+others?). In both cases the user never sees the advertised realms.
+
+You can also set an 'auth_default_realm' to use when a client gives an empty
+realm. However the client is supposed to use the same realm it tells the server
+for the calculation. So when this option helps, it is only for broken clients.
+
+DIGEST-MD5 scheme
+-----------------
+
+Password must be stored in either plaintext or with DIGEST-MD5 scheme. See
+<Authentication.PasswordSchemes.txt>.
+
+The Digest is the MD5 sum of the string "user:realm:password". So for example
+if you want to log in as 'user' with password 'pass' and the realm should be
+'example.com' (usually not provided by the user, see above), create the digest
+with:
+
+---%<-------------------------------------------------------------------------
+% echo -n "user:example.com:pass" | md5sum
+c19c4c6e32f9d8026b26ba77c21fb8eb  -
+---%<-------------------------------------------------------------------------
+
+And save it as
+
+---%<-------------------------------------------------------------------------
+user@example.com:c19c4c6e32f9d8026b26ba77c21fb8eb
+---%<-------------------------------------------------------------------------
+
+Note that if you're using DIGEST-MD5 scheme to store the passwords, you can't
+change the users' names or realms in any way or the authentication will fail
+because the MD5 sums don't match. Also not that this is different from what
+Apache does with HTTP AUTH Digest. There it would be
+'user:example.com:c19c4c6e32f9d8026b26ba77c21fb8eb' and is created with
+'htdigest'.
+
+Testing
+-------
+
+You can use 'imtest' from Cyrus SASL
+[http://asg.web.cmu.edu/sasl/sasl-library.html] library to test an IMAP
+connection:
+
+---%<-------------------------------------------------------------------------
+# With realm:
+imtest -a user -r example.com
+# Without realm:
+imtest -a user@example.com
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)