Password Schemes
================

Password scheme means the format in which the password is stored in <password
databases> [PasswordDatabase.txt]. The most commonly used password schemes are:

 * *PLAIN*: Password is in plaintext.
 * *CRYPT*: Traditional DES-crypted password in '/etc/passwd' (e.g. "pass" =
   'vpvKh.SaNbR6s')
    * Dovecot uses libc's 'crypt()' function, which means that CRYPT is usually
      able to recognize MD5-CRYPT and possibly also other password schemes. 
      Please see the notes below regarding glibc's 'crypt()' and SHA-256/512
      support.
    * The traditional DES-crypt scheme only uses the first 8 characters of the
      password, the rest are ignored.  Other schemes may have other password
      length limitations (if they limit the password length at all).
 * *MD5-CRYPT*: MD5 based salted password hash nowadays commonly used in
   '/etc/shadow'. (e.g. "pass" = '$1$ozdpg0V0$0fb643pVsPtHVPX8mCZYW/')
    * *MD5*: Alias for MD5-CRYPT. Dovecot versions earlier than v1.0.rc16 need
      to use this instead of MD5-CRYPT. This name is deprecated because
      MD5-CRYPT isn't an actual MD5 hash.
 * *PLAIN-MD5*: An actual MD5 hash of the password. (e.g. "pass" =
   '1a1dc91c907325c69271ddf0c944bc72')

Password databases have a default password scheme:

 * <SQL> [AuthDatabase.SQL.txt]: See 'default_pass_scheme' setting in
   'dovecot-sql.conf.ext'
 * <LDAP> [AuthDatabase.LDAP.txt]: See 'default_pass_scheme' setting in
   'dovecot-ldap.conf.ext'
 * <PasswdFile> [AuthDatabase.PasswdFile.txt]: CRYPT is used by default, but
   can be changed with 'scheme' parameter in passdb args.
 * <Passwd> [AuthDatabase.Passwd.txt], <Shadow> [PasswordDatabase.Shadow.txt],
   <VPopMail> [AuthDatabase.VPopMail.txt]: CRYPT is used by default and can't
   be changed currently.
 * <PAM> [PasswordDatabase.PAM.txt], <BSDAuth> [PasswordDatabase.BSDAuth.txt],
   <CheckPassword> [PasswordDatabase.CheckPassword.txt]: Dovecot never even
   sees the password with these databases, so Dovecot has nothing to do with
   what password scheme is used.

The password scheme can be overridden for each password by prefixing it with
{SCHEME}, for example:'{PLAIN}pass'.

You can generate passwords for wanted scheme easily with "doveadm pw" utility.
For example:

---%<-------------------------------------------------------------------------
doveadm pw -s ssha256
---%<-------------------------------------------------------------------------

It's not possible to easily switch from one password scheme to another. The
only practical way to do this is to wait until user logs in and change the
password during the login. <This HOWTO> [HowTo.ConvertPasswordSchemes.txt]
shows one way to do this.

What scheme to use?
-------------------

With most installations it doesn't really matter what scheme you're using. If
you already have users with existing passwords, it's easiest to just keep using
the same scheme. Otherwise just pick something strong enough, for example
SSHA256.

The main idea behind storing passwords in non-plaintext scheme is that if an
attacker gets access to your server, he can't easily just get all users'
passwords and start using them. With stronger schemes it takes more time to
crack the passwords.

Non-plaintext authentication mechanisms
---------------------------------------

See <Authentication.Mechanisms.txt> for explanation of auth mechanisms. Most
installations use only plaintext mechanisms, so you can skip this section
unless you know you want to use them.

The problem with non-plaintext auth mechanisms is that the password must be
stored either in plaintext, or using a mechanism-specific scheme that's
incompatible with all other non-plaintext mechanisms. For example if you're
going to use CRAM-MD5 authentication, the password needs to be stored in either
PLAIN or CRAM-MD5 scheme. If you want to allow both CRAM-MD5 and DIGEST-MD5,
the password must be stored in plaintext.

In future it's possible that Dovecot could support multiple passwords in
different schemes for a single user.

Supported schemes
-----------------

*PLAIN*, *CRYPT* and *MD5-CRYPT* schemes were explained above.

Non-plaintext mechanism specific schemes:

 * *LANMAN*: DES-based encryption. Used sometimes with NTLM mechanism.
 * *NTLM*: MD4 sum of the password stored in hex. Used with NTLM mechanism.
 * *RPA*: Used with RPA mechanism.
 * *CRAM-MD5*: Used with CRAM-MD5 mechanism.
 * *DIGEST-MD5*: Used with <DIGEST-MD5 mechanism>
   [Authentication.Mechanisms.DigestMD5.txt]. The username is included in the
   hash, so it's not possible to use the hash for different usernames.

MD5 based schemes:

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

SHA based schemes (also see below for libc's SHA* support):

 * *SHA*: SHA1 sum of the password stored in base64.
 * *SSHA*: Salted SHA1 sum of the password stored in base64.
 * *SHA256*: SHA256 sum of the password stored in base64. (v1.1 and later).
 * *SSHA256*: Salted SHA256 sum of the password stored in base64. (v1.2 and
   later).
 * *SHA512*: SHA512 sum of the password stored in base64. (v2.0 and later).
 * *SSHA512*: Salted SHA512 sum of the password stored in base64. (v2.0 and
   later).

For some schemes (e.g. PLAIN-MD5, SHA) Dovecot is able to detect if the
password hash is base64 or hex encoded, so both can be used.'doveadm pw' anyway
generates the passwords using the encoding mentioned above.

SHA256 and SHA512 in libc
-------------------------

glibc v2.7+ supports SHA256 and SHA512 based password schemes. The passwords
look like:

 * SHA256: $5$salt$data
 * SHA512: $6$salt$data

These passwords are completely different than what Dovecot generates. They use
multiple rounds of SHA, so they're also safer against brute forcing (but also
requiring more CPU from your server). You can use these simply by using CRYPT
scheme, assuming your libc can handle these kinds of passwords.

One way to generate this type of password hash is via the mkpasswd command
included in the whois package. For example:'mkpasswd -m sha-512'

This is especially useful for sharing the same password file with other
software. It can be used with Apache's basic authentication in lieu of the much
less secure htpasswd as the check is passed through to the system's crypt(3)
library.

Encoding
--------

The base64 vs. hex encoding that is mentioned above is simply the default
encoding that is used. You can override it for any scheme by adding a ".hex",
".b64" or ".base64" suffix. For example:

 * '{SSHA.b64}986H5cS9JcDYQeJd6wKaITMho4M9CrXM' contains the password encoded
   to base64 (just like {SSHA})
 * '{SSHA.HEX}3f5ca6203f8cdaa44d9160575c1ee1d77abcf59ca5f852d1' contains the
   password encoded to hex

This can be especially useful with plaintext passwords to encode characters
that would otherwise be illegal. For example in passwd-file you couldn't use a
":" character in the password without encoding it to base64 or hex. For
example:'{PLAIN}{\}:!"' is the same as '{PLAIN.b64}e1x9OiEiCg=='.

You can also specify the encoding with doveadm pw. For example: 'doveadm pw -s
plain.b64'

Salting
-------

For most of the salted password schemes (SMD5, SSHA*) the salt is stored after
the password hash and its length can vary. When hashing the password, append
the salt after the plaintext password, e.g.: SSHA256(pass, salt) = SHA256(pass
+ salt) + salt.

For example with SSHA256 you know that the hash itself is 32 bytes (256 bits/8
bits per byte). Everything after that 32 bytes is the salt. For example if you
have a password:

---%<-------------------------------------------------------------------------
{SSHA256}SoR/78T5q0UPFng8UCXWQxOUKhzrJZlwfNtllAupAeUT+kQv
---%<-------------------------------------------------------------------------

After base64 decoding it you'll see that its length is 36 bytes, so the first
32 bytes are the hash and the following 4 bytes are the salt:

 * length: 'echo SoR/78T5q0UPFng8UCXWQxOUKhzrJZlwfNtllAupAeUT+kQv|base64 -d|wc
   -c' -> 36
 * hash: 'echo SoR/78T5q0UPFng8UCXWQxOUKhzrJZlwfNtllAupAeUT+kQv|base64 -d|dd
   bs=1 count=32|hexdump -C' -> 4a 84 7f ef c4 f9 ab 45  0f 16 78 3c 50 25 d6
   43 13 94 2a 1c eb 25 99 70  7c db 65 94 0b a9 01 e5
 * salt: 'echo SoR/78T5q0UPFng8UCXWQxOUKhzrJZlwfNtllAupAeUT+kQv|base64 -d|dd
   bs=1 skip=32|hexdump -C' -> 13 fa 44 2f

Other common hash sizes are:

 * MD5: 16 bytes
 * SHA: 20 bytes
 * SHA256: 32 bytes
 * SHA512: 64 bytes

The web management gui VBoxAdm [http://developer.gauner.org/vboxadm/] has some
code dealing with creation and verification of salted hashes in Perl. However
not all password schemes provided by dovecotpw are supported. Have a look at
the module VBoxAdm::DovecotPW for more details.

(This file was created from the wiki on 2011-11-16 14:09)