auth.txt revision 061da1b9d309301a7e3f5e0f240d7a7e99652d63
76b43e4417bab52e913da39b5f5bc2a130d3f149Timo SirainenAuthentication is split into three parts: authentication mechanism,
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainenpassword database and user database.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenCurrently supported authentication mechanisms:
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - PLAIN: By itself it's very insecure, but through secured SSL/TLS
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen connection it should be fine.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - DIGEST-MD5: Should be quite secure by itself. It also supports
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen integrity protecting and crypting the rest of the communication, but
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainen we don't support those yet.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - ANONYMOUS: No authentication required. User will be logged in as the user
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen specified by auth_anonymous_username setting (default "anonymous"). There's
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen no special restrictions given for anonymous users so you have to make sure
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen it doesn't have access to unwanted locations.
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo SirainenCurrently supported password databases:
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - passwd: /etc/passwd or similiar, using getpwnam()
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - shadow: /etc/shadow or similiar, using getspnam()
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - pam: Pluggable Authentication Modules
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - passwd-file: /etc/passwd-like file in specified location
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - ldap: Lightweight Directory Access Protocol
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - vpopmail: External software used to handle virtual domains
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - pgsql: A PostgreSQL database.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenCurrently supported user databases:
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - passwd: /etc/passwd or similiar, using getpwnam()
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - passwd-file: /etc/passwd-like file in specified location
0e3f8c6edad565112d91f0a53568c0313d657e48Timo Sirainen - ldap: Lightweight Directory Access Protocol
0e3f8c6edad565112d91f0a53568c0313d657e48Timo Sirainen - vpopmail: External software used to handle virtual domains
0e3f8c6edad565112d91f0a53568c0313d657e48Timo Sirainen - static: Static UID and GID, home directory from given template
0e3f8c6edad565112d91f0a53568c0313d657e48Timo Sirainen - pgsql: A PostgreSQL database.
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo SirainenMost password databases support only plaintext authentication. passwd-file
d56384d5226c8860079d0d0b08b83404e8c42986Timo Sirainenand LDAP exceptions since they support multiple password schemes.
d56384d5226c8860079d0d0b08b83404e8c42986Timo SirainenPassword schemes supporting only plaintext authentication:
4b058f90f9e8a2c6b2eed275de4eb8cc5195a71dTimo Sirainen - CRYPT: Use crypt(). Usually DES, but some systems support others too
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen (eg. MD5 and SHA1)
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - MD5: MD5crypt algorithm, sometimes used in /etc/passwd and likes
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - PLAIN-MD5: Simple MD5 sum of password. Used by libpam-pwdfile
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenPassword schemes supporting plaintext authentication and more:
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - PLAIN: Although not that good idea, it enables support for all current
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen and future authentication mechanisms.
d6af1e63bc7824f1cc5b9b73a1c5f8f8789788d6Timo Sirainen - DIGEST-MD5: MD5 sum of "user:realm:password", as required by DIGEST-MD5
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenRealms (or virtual domains) are supported by appending the "@realm" after
d5cebe7f98e63d4e2822863ef2faa4971e8b3a5dTimo Sirainenthe user name. This behaviour works with all authentication mechanisms and
0f66f12eb4cdbf47670975044c88d8f388bf92dfTimo SirainenHome directory can be prefixed with "<chroot>/./" in which case <chroot>
6a9f9a5101b665fd2ef80c9e048a5eace78e01efTimo Sirainendirectory will be chrooted into. The actual home directory follows the
6a9f9a5101b665fd2ef80c9e048a5eace78e01efTimo Sirainen"/./". For example "/chroot/./home/user".
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenMost commonly used as user database. Many systems use shadow passwords
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainennowadays so it doesn't usually work as password database. BSDs are an
a3ea111cfdbfd4f32baeb0bd7f1d72568c60a023Timo Sirainenexception to this, they still set the password field even with shadow
8d80659e504ffb34bb0c6a633184fece35751b18Timo SirainenWorks at least with Linux and Solaris.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenWe should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenApplePAM (OSX). PAM doesn't provide user database, so you have to use
1f57716285d4c5bc9bf2fd5569e3c85fd496afd9Timo Sirainensomething else for that - passwd usually.
1f57716285d4c5bc9bf2fd5569e3c85fd496afd9Timo SirainenHere's an example /etc/pam.d/imap configuration file which uses
1f57716285d4c5bc9bf2fd5569e3c85fd496afd9Timo Sirainenstandard UNIX authentication:
1f57716285d4c5bc9bf2fd5569e3c85fd496afd9Timo Sirainenauth required pam_unix.so nullok
1f57716285d4c5bc9bf2fd5569e3c85fd496afd9Timo Sirainenaccount required pam_unix.so
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenThis is compatible with regular /etc/passwd, and a password file used by
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenlibpam-pwdfile. It's in the following format:
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainenuser:password:uid:gid:(gecos):home:(shell):flags:mail
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenFor password database, it's enough to have only user and password fields.
a3ea111cfdbfd4f32baeb0bd7f1d72568c60a023Timo SirainenFor user database, you need to set also uid, gid and either home or mail.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenFlags is a comma-separated list of flags, currently only recognized value
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainenis "chroot", which makes the imap process chroot into home directory, if
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainenallowed by master process.
a29a5b7520f7b8d6cdaf97e66d184b6a9e4f4ecfTimo SirainenThe password field can be in three formats:
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - password: Assume CRYPT scheme
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - password[type]: libpam-passwd file compatible format. Type is one of:
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen 13: CRYPT scheme
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainen 34: MD5 scheme
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen 56: DIGEST-MD5 scheme (Dovecot extension, deprecated)
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen - {SCHEME}password
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenSee dovecot-ldap.conf for more information. Password and user databases may
c0435c854a0e7246373b9752d163095cc4fbe985Timo Sirainenuse different configuration files to keep the information in separate
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainenlocations. If both refer to same file, they share the same LDAP connection.
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo SirainenThis is an external software intended to make handling virtual domains
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Siraineneasier. Supports Qmail and Postfix. See http://inter7.com/vpopmail.html
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainenstatic uid=<uid> gid=<gid> home=<dir template>
b09be485e9373be4288f5615bbce6ebed65a425aTimo SirainenAll users share the same UID and GID. Home directory template can use %u,
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainen%n and %d variables, see default_mail_env description in dovecot-example.conf.
b09be485e9373be4288f5615bbce6ebed65a425aTimo SirainenSee dovecot-pgsql.conf for more information. Password and user databases may
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainenuse different configuration files to keep the information in separate
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainenlocations. If both refer to same file, they share the same PostgreSQL
b09be485e9373be4288f5615bbce6ebed65a425aTimo SirainenGenerating passwords
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainen--------------------
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainen perl -e 'printf "%s\n", crypt("pass", "two-letter-salt")'
5dd05e966ffd69181ab3067f6939b03ced68ebc3Timo Sirainen mkpasswd --hash=md5
b09be485e9373be4288f5615bbce6ebed65a425aTimo Sirainen perl -e 'printf "%s\n", crypt("pass", "\$1\$6-8-letter-salt\$")'
33ca6b017b6ebbd048651b5e3d16915001dbc291Timo Sirainen perl -MDigest::MD5 -e 'printf "{PLAIN-MD5}%s\n", Digest::MD5::md5_hex("pass")'
9453e8d75cfd8fab2232cf772e9b120f308fb3eeTimo Sirainen perl -MDigest::MD5 -e 'printf "{DIGEST-MD5}%s\n", Digest::MD5::md5_hex("user:realm:pass")'