pam_dotfile 0.4
===============

Copyright 2003
Lennart Poettering <mz70616d646f7466696c65@itaparica.org>

--

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

--

pam_dotfile is a PAM module which allows users to have more than one
password for a single account, each for a different service. This is
desirable because many users have objections to using the same
password for (as an example) an IMAP4 mailbox and SSH access. The
IMAP4 password should be distinct from the SSH password because the
user wants to save the former in the configuration of his mail agent,
but not the latter. The same applies to POP3 mailboxes, FTP and
comparable services.

How does it work?
=================

The module needs be activated for the specific service in the
configuration file /etc/pam.d/<service>. The user is than able to
create a second valid password for that service by issuing the
following commands:

pam-dotfile-gen -a <service>

The user has to enter the new password now twice. This will write the
password in a hashed way to ~/.pam-<service>.

An example for the service imap (for the IMAP-server dovecot in this
case):

/etc/pam.d/imap:

<snip>
#%PAM-1.0
auth sufficient pam_unix_auth.so
auth sufficient pam_dotfile.so use_first_pass no_warn
auth required pam_deny.so
</snip>

As user waldo:

<snip>
[waldo@wonderi] ~$ pam-dotfile-gen -a imap
Password:quux
Please repeat; password:quux
Password added.
</snip>

That's it. User waldo may now access his IMAP mail store either by
using his unix password or by using quux.

If you want to deny access with the unix password when a .pam file
exists, you should install the following /etc/pam.d/imap:

<snip>
#%PAM-1.0
auth [success=done new_authtok_reqd=done authinfo_unavail=ignore default=die] pam_dotfile.so no_warn
auth [success=done new_authtok_reqd=done default=die] pam_unix.so use_first_pass
</snip>

Please note: the pam.d fragments shown above are based on Debian
GNU/Linux' default PAM installation. I know that some distributions
(i.e. Red Hat) use pam_pwdb.so instead of pam_unix.so as default
authentication mechanism. Please adapt the pam.d configuration to your
specific distribution.

Technical details
=================

For getting access to the user's files a SUID root helper utility
/sbin/pam-dotfile-helper is used.

--

The .pam files are ignored when their access mode AND 077 is non-zero,
when they are symlinks or when any parent directory is group or world
writable.

--

pam_dotfile will try to open the the following files for
authentication (in that order):

        ~/.pam-<service>
        ~/.pam/<service>
        ~/.pam-other
        ~/.pam/other

The first file in this list that exists is used for
authentication. Regardless of any of the passwords contained therein
are correct the other files are NOT evaluated.

--

The hashing is implemented in the following way: 

    1. A 16 byte random string is read from /dev/urandom
    2. It is formatted in a 32 character hexadecimal string
    3. The password is appended
    4. The MD5 hash of this string is calculated
    5. The hash is formatted in another 32 character hexadecimal string 
    5. The result is the concatenation of the two hexadecimal strings

I believe that this is somewhat secure. However, I am not a
cryptoanalyst, I cannot guarantee for this.

--

pam-dotfile-gen is may be used as a filter that reads a text stream
with unencrypted passwords and crypts them. Empty lines and those
starting with # are passed in an unmodified way to STDOUT. Thus the
user may comment the passwords in his .pam files.

--

The following PAM parameters are understood:

debug            Be very verbose to syslog(3)
use_first_pass   Don't issue a password prompt, use one supplied by a
                 previous modules
try_first_pass   Nearly the same as use_first_pass, but don't fail if no
                 password was supplied, instead query the user
use_authtok      Synonym for use_first_pass
rootok           Don't deny access for users with uid == 0
nullok           Don't deny access for null passwords
fork             Always fork before trying to open the password files via the helper tool
nofork           Never fork
no_warn          Suppress warnings to syslog(3)
stat_only_home   verifies group/world readability only inside the homedir
		 if, for instance the pam_dotfile is: /home/waldo/.pam/service
		 only /home/waldo/.pam and /home/waldo are tested.
		 This is sometimes necessairy if home-dirs are symbolic links.

Installation
============

Please adjust the Makefile to your needs (paths!) and than run "make"
to compile the package. A "make install" (as root!) will install
pam_dotfile to your machine.

--

Development was done on Debian GNU/Linux Sarge as of March 2003.

--

This software includes an implementation of the MD5 algorithm by
L. Peter Deutsch. Thanks to him for this.

Oliver Kurth wrote the manpages and created Debian packages for this
software.

Christian Loitsch provided a patch with some bugfixes and support
for stat_only_home.

--

Lennart Poettering <mz70616d646f7466696c65@itaparica.org>, May 2003
