[dovecot-cvs] dovecot/doc auth.txt,1.4,1.5 configuration.txt,1.8,1.9

[cras at procontrol.fi]

Update of /home/cvs/dovecot/doc
In directory danu:/tmp/cvs-serv1665/doc

Modified Files:
	auth.txt configuration.txt 
Log Message:
updates



Index: auth.txt
===================================================================
RCS file: /home/cvs/dovecot/doc/auth.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- auth.txt	5 Jan 2003 13:11:38 -0000	1.4
+++ auth.txt	20 Feb 2003 15:04:44 -0000	1.5
@@ -1,47 +1,74 @@
-Authentication is split into two separate parts: the authentication
-mechanism, and the authentication backend.
+Authentication is split into three parts: authentication mechanism,
+password database and user database.
 
-Currently supported mechanisms:
+Currently supported authentication mechanisms:
 
- - plaintext: By itself it's very insecure, but through secured SSL/TLS
+ - PLAIN: By itself it's very insecure, but through secured SSL/TLS
    connection it should be fine.
- - Digest-MD5: Should be quite secure by itself. It also supports
-   integrity protection and crypting the rest of the communication, but
+ - DIGEST-MD5: Should be quite secure by itself. It also supports
+   integrity protecting and crypting the rest of the communication, but
    we don't support those yet.
 
-Currently supported backends:
+Currently supported password databases:
 
  - passwd: /etc/passwd or similiar, using getpwnam()
  - shadow: /etc/shadow or similiar, using getspnam()
- - pam: PAM authentication
- - passwd-file: /etc/passwd-like file
+ - pam: Pluggable Authentication Modules
+ - passwd-file: /etc/passwd-like file in specified location
+ - ldap: Lightweight Directory Access Protocol
  - vpopmail: External software used to handle virtual domains
 
-Digest-MD5 works only with passwd-file. More mechanisms and backends can be
-easily added later.
+Currently supported user databases:
+
+ - passwd: /etc/passwd or similiar, using getpwnam()
+ - passwd-file: /etc/passwd-like file in specified location
+ - ldap: Lightweight Directory Access Protocol
+ - vpopmail: External software used to handle virtual domains
+ - static: Static UID and GID, home directory from given template
+
+Most password databases support only plaintext authentication. passwd-file
+and LDAP exceptions since they support multiple password schemes.
+
+Password schemes supporting only plaintext authentication:
+
+ - CRYPT: Use crypt(). Usually DES, but some systems support others too
+   (eg. MD5 and SHA1)
+ - MD5: MD5crypt algorithm, sometimes used in /etc/passwd and likes
+ - PLAIN-MD5: Simple MD5 sum of password. Used by libpam-pwdfile
+
+Password schemes supporting plaintext authentication and more:
+
+ - PLAIN: Although not that good idea, it enables support for all current
+   and future authentication mechanisms.
+ - DIGEST-MD5: MD5 sum of "user:realm:password", as required by DIGEST-MD5
+   mechanism.
+
+Realms (or virtual domains) are supported by appending the "@realm" after
+the user name. This behaviour works with all authentication mechanisms and
+databases.
 
 
 passwd
 ------
 
-This is the most standard way to authenticate. However with shadow
-passwords some systems (Linux) don't work with this backend. At least BSDs
-still support this backend correctly.
+Most commonly used as user database. Many systems use shadow passwords
+nowadays so it doesn't usually work as password database. BSDs are an
+exception to this, they still set the password field even with shadow
+passwords.
 
 
 shadow
 ------
 
-Authenticate from /etc/shadow. Works at least with Linux and Solaris.
+Works at least with Linux and Solaris.
 
 
-pam
+PAM
 ---
 
-PAM is the preferred authentication system nowadays with Linux. PAM handles
-only password checking, for getting the user information Dovecot still
-requires the user to exist in /etc/passwd. This requirement may be removed
-later.
+We should work with Linux PAM, Solaris PAM, OpenPAM (FreeBSD) and
+ApplePAM (OSX). PAM doesn't provide user database, so you have to use
+something else for that - passwd usually.
 
 Here's an example /etc/pam.d/imap configuration file which uses
 /etc/imap.passwd:
@@ -56,56 +83,62 @@
 This is compatible with regular /etc/passwd, and a password file used by
 libpam-pwdfile. It's in the following format:
 
-user:password:uid:gid:(ignored):home:(ignored):realm:mail:flags
-
-Only user and password fields are required. If uid, gid or home fields
-aren't set, they're read from system's passwd file. If the user doesn't
-exist in system, a warning is printed to syslog and the user entry is
-ignored.
+user:password:uid:gid:(gecos):home:(shell):flags:mail
 
-Either home or mail is required to exist. Home specifies the home directory
-of user under which mail is located. The actual mail format and location is
-automatically detected, just as if you run the imap binary directly. Other
-way is to specify the mail storage parameters directly using the
-mail-field, see "Detecting what to use" chapter in mail-storage.txt file
-for more information about it (the MAIL environment).
+For password database, it's enough to have only user and password fields.
+For user database, you need to set also uid, gid and either home or mail.
 
 Flags is a comma-separated list of flags, currently only recognized value
 is "chroot", which makes the imap process chroot into home directory, if
-it's allowed by master process.
+allowed by master process.
 
-Realm is useful only with Digest-MD5 authentication. It's possible to have
-multiple users with same name but in different realms. If plaintext is used
-to log in, user is expected to be in no realm.
+The password field can be in three formats:
 
-The password field is in format: <data> "[" <type> "]", like "foo[13]".
-Type can be one of the following:
+ - password: Assume CRYPT scheme
+ - password[type]: libpam-passwd file compatible format. Type is one of:
+     13: CRYPT scheme
+     34: MD5 scheme
+     56: DIGEST-MD5 scheme (Dovecot extension, deprecated)
+ - {SCHEME}password
 
- 13: DES password
- 34: MD5 password
- 56: Digest-MD5 password - Hexadecimal MD5 sum of "user:realm:password"
 
-If [type] isn't specified at all or it's unknown, DES is used. The 13 and
-34 methods are compatible with PAM module pwdfile. Only the 56 method works
-with Digest-MD5 authentication.
+LDAP
+----
 
-DES
----
+See dovecot-ldap.conf for more information. Password and user databases may
+use different configuration files to keep the information in separate
+locations. If both refer to same file, they share the same LDAP connection.
 
-Use either mkpasswd, or:
 
-perl -e 'print crypt("pass", "two-letter-salt")."\n"'
+vpopmail
+--------
 
-MD5
----
+This is an external software intended to make handling virtual domains
+easier. Supports Qmail and Postfix. See http://inter7.com/vpopmail.html
 
-perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("pass")."[34]\n"'
 
-Digest-MD5
-----------
+static
+------
 
-perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("user:realm:pass")."[56]\n"'
+static uid=<uid> gid=<gid> home=<dir template>
 
-For plaintext authentication:
+All users share the same UID and GID. Home directory template can use %u,
+%n and %d variables, see default_mail_env description in dovecot-example.conf.
 
-perl -MDigest::MD5 -e 'print Digest::MD5::md5_hex("user::pass")."[56]\n"'
+
+Generating passwords
+--------------------
+
+DES:
+  mkpasswd
+  perl -e 'printf "%s\n", crypt("pass", "two-letter-salt")'
+
+MD5:
+  mkpasswd --hash=md5
+  perl -e 'printf "%s\n", crypt("pass", "\$1\$6-8-letter-salt\$")'
+
+PLAIN-MD5:
+  perl -MDigest::MD5 -e 'printf "{PLAIN-MD5}%s\n", Digest::MD5::md5_hex("pass")'
+
+DIGEST-MD5:
+  perl -MDigest::MD5 -e 'printf "{DIGEST-MD5}%s\n", Digest::MD5::md5_hex("user:realm:pass")'

Index: configuration.txt
===================================================================
RCS file: /home/cvs/dovecot/doc/configuration.txt,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- configuration.txt	21 Jan 2003 06:50:00 -0000	1.8
+++ configuration.txt	20 Feb 2003 15:04:44 -0000	1.9
@@ -1,3 +1,18 @@
+Quick setup
+-----------
+
+If you use mbox, make sure that mbox_locks is set up the same way as rest
+of your system.
+
+Check client_workarounds and enable those you think you need.
+
+If you need to create new SSL certificate, edit dovecot-openssl.cnf and
+run mkcert.sh.
+
+Going through settings in dovecot-example.conf is a good idea, they should
+be well commented.
+
+
 Authentication
 --------------
 
@@ -18,7 +33,7 @@
 With larger mailboxes it's a good idea to use a filesystem which uses
 b-tree or hash indexes for directories, for example ReiserFS, XFS or JFS.
 ext2 and ext3 have some patches to implement this but they're not in Linux
-2.4.19 yet. I'm not sure about *BSD's filesystems, FreeBSD's ufs had some
+2.4.20 yet. I'm not sure about *BSD's filesystems, FreeBSD's ufs had some
 support for hashes.
 
 mbox is just a single file where new mails are appeneded, flags are stored
@@ -47,10 +62,10 @@
 ---------
 
 Chrooting can be used for extra security hardening to prevent users from
-having full access to the system, in case some security hole was found. It
-can also be used for local users to gain root privileges if used
-incorrectly. This is possible with hardlinking setuid binaries inside the
-chroot jail. There's at least two possibilities: create your own
+having full access to the system in case some security hole was found. If
+used incorrectly, it can also allow local users to gain root privileges.
+This is possible by hardlinking setuid binaries inside the chroot jail and
+tricking them. There's at least two possibilities: create your own
 chroot/etc/passwd and run /bin/su, or create your own chroot/lib/libc.so
 and run any setuid binary.