pam_dotfile 0.2
===============

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:

( umask 077 ; pam-dotfile-gen > ~/.pam-<service> )

The user has to enter the new password now, finished by return and
^D. The tool pam-dofile-gen reads passwords from STDIN, hashes them
with MD5 (combined with a salt value) and writes that to STDOUT.

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>
( umask 077 ; pam-dotfile-gen > ~/.pam-imap )
quux
^D
</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 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)

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.

--

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