This documentation is for Dovecot v1.x, see wiki2 for v2.x documentation.
Differences between revisions 1 and 34 (spanning 33 versions)
Revision 1 as of 2006-05-12 23:25:25
Size: 2126
Editor: TimoSirainen
Comment:
Revision 34 as of 2012-04-27 18:36:34
Size: 8100
Editor: bugeye
Comment: v2: doveadm pw
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
Password scheme means the format in which the password is stored in [[PasswordDatabase|password databases]]. The most commonly used password schemes are:
Line 4: Line 5:
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.  * '''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}}})
Line 6: Line 13:
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. Password databases have a default password scheme:
Line 8: Line 15:
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.  * [[AuthDatabase/SQL|SQL]]: See {{{default_pass_scheme}}} setting in {{{dovecot-sql.conf}}}
 * [[AuthDatabase/LDAP|LDAP]]: See {{{default_pass_scheme}}} setting in {{{dovecot-ldap.conf}}}
 * [[AuthDatabase/PasswdFile|PasswdFile]]: CRYPT is used by default, v1.1+ allows changing with {{{scheme}}} parameter in passdb args.
 * [[AuthDatabase/Passwd|Passwd]], [[PasswordDatabase/Shadow|Shadow]], [[AuthDatabase/VPopMail|VPopMail]]: CRYPT is used by default and can't be changed currently.
 * [[PasswordDatabase/PAM|PAM]], [[PasswordDatabase/BSDAuth|BSDAuth]], [[PasswordDatabase/CheckPassword|CheckPassword]]: Dovecot never even sees the password with these databases, so Dovecot has nothing to do with what password scheme is used.
Line 10: Line 21:
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. The password scheme can be overridden for each password by prefixing it with {SCHEME}, for example: {{{{PLAIN}pass}}}.
Line 12: Line 23:
Currently supported password schemes are: Dovecot contains a utility which can be used to easily generate passwords for a wanted scheme: in Dovecot v1, {{{dovecotpw}}}; in Dovecot v2, {{{doveadm pw}}}
Line 14: Line 25:
 * CRYPT: DES-based encryption. This is how passwords are historically stored in `/etc/passwd`.
 * LANMAN: DES-based encryption. Used sometimes with NTLM mechanism.
== 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 SSHA.
Line 17: Line 28:
 * NTLM: MD4 sum of the password stored in hex. Used with NTLM mechanism. 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.
Line 19: Line 30:
 * 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.
 * RPA: Use with RPA mechanism.
== Non-plaintext authentication mechanisms ==
See [[Authentication/Mechanisms]] 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.
Line 27: Line 33:
 * SHA: SHA1 sum of the password stored in base64.
 * SSHA: Salted SHA1 sum of the password stored in base64.
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.
Line 30: Line 35:
 * PLAIN: Password is in plaintext. In future it's possible that Dovecot could support multiple passwords in different schemes for a single user.
Line 32: Line 37:
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). == Supported schemes ==
'''PLAIN''', '''CRYPT''' and '''MD5-CRYPT''' schemes were explained above.
Line 34: Line 40:
Dovecot contains a `dovecotpw` utility which can be used to easily generate passwords for wanted scheme. 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 (v1.0.rc16 and later, for older use HMAC-MD5)
  * '''HMAC-MD5''': Deprecated name for CRAM-MD5. The password isn't really in a standard HMAC-MD5 format.
 * '''DIGEST-MD5''': Used with [[Authentication/Mechanisms/DigestMD5|DIGEST-MD5 mechanism]]. 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. {{{dovecotpw}}} 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.

== 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 dovecotpw. For example: {{{dovecotpw -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 [[http://developer.gauner.org/vboxadm/|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.

Password Schemes

Password scheme means the format in which the password is stored in password databases. 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: See default_pass_scheme setting in dovecot-sql.conf

  • LDAP: See default_pass_scheme setting in dovecot-ldap.conf

  • PasswdFile: CRYPT is used by default, v1.1+ allows changing with scheme parameter in passdb args.

  • Passwd, Shadow, VPopMail: CRYPT is used by default and can't be changed currently.

  • PAM, BSDAuth, CheckPassword: 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.

Dovecot contains a utility which can be used to easily generate passwords for a wanted scheme: in Dovecot v1, dovecotpw; in Dovecot v2, doveadm pw

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

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 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 (v1.0.rc16 and later, for older use HMAC-MD5)

    • HMAC-MD5: Deprecated name for CRAM-MD5. The password isn't really in a standard HMAC-MD5 format.

  • DIGEST-MD5: Used with DIGEST-MD5 mechanism. 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. dovecotpw 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.

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 dovecotpw. For example: dovecotpw -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 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.

None: Authentication/PasswordSchemes (last edited 2012-04-27 18:36:34 by bugeye)