pam_dotfile 0.7

Copyright 2002,2003 Lennart Poettering <mzcnzqbgsvyr (at) 0pointer (dot) de>


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.


Wed Aug 27 2003:

Version 0.7 released, changes include: Fixed in conjunction with exim4, contact info updated, build system update, man page for pamtest added

Mon July 21 2003:

Version 0.6 released, changes include: Fix MD5 digest generation. This breaks compatibility with pam_dotfile <= 0.5 unless --enable-compat05 is specified at compile time. Minor other fixes (mostly related to the build system). All users should update.

Tue July 8 2003:

Version 0.5 released, changes include: Autoconf support, fixed an important bug regarding a race on child process creation. All users should update.


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


Version 0.7 is stable and feature complete.


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>

Replace <service> by the PAM service name, e.g. imapd. The user has to enter the new password twice. This will save the password to ~/.pam-<service> in a hashed way.

A complete example for the service imap (for the IMAP server dovecot in this case):


auth sufficient
auth sufficient use_first_pass no_warn
auth required

As user waldo:

[waldo@wonder] ~$ pam-dotfile-gen -a imap
Please repeat; password:quux
Password added.

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:

auth [success=done new_authtok_reqd=done authinfo_unavail=ignore default=die] no_warn
auth [success=done new_authtok_reqd=done default=die] use_first_pass

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 instead of as default authentication mechanism. Please adapt the pam.d configuration to your specific distribution.


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):

  1. ~/.pam-<service>
  2. ~/.pam/<service>
  3. ~/.pam-other
  4. ~/.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 (salt)
  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
  6. 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. (Probably a cryptoanalyst cannot either.)

The hashing function changed a little from 0.5 to 0.6. There was an ugly error in formatting the digest into a hexadecimal string. By fixing this the old hashed passwords became incompatible with newer releases of pam_dotfile. For sake of compatibility I added the option --enable-compat05 to the configure script. Passwords for 0.6 are prefixed with a + in the dot files, older passwords are not. You are encouraged to fix your passwords to comply with the new version.

pam-dotfile-gen 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.

PAM parameters


pam_dotfile was developed and tested on Debian GNU/Linux "testing" from July 2003, it should work on most other Linux distributions (and maybe Unix versions) since it uses GNU autoconf and GNU libtool for source code configuration and shared library management.

You need the PAM development headers installed (naturally...)


As this package is made with the GNU autotools you should run ./configure inside the distribution directory for configuring the source tree. After that you should run make for compilation and make install (as root) for installation of pam_dotfile.

If you upgrade from versions prior to 0.6 you should pass --enable-compat05 to configure to enable compatibility with old user dot files. If you do not specify this, old passwords are ignored, the users have to recreate their passwords with pam-dotfile-gen.

If you do a fresh install you should not pass --enable-compat05 to configure. (An alternative is to specify --enable-compat05 but to disable it afterwards by using nocompat05 on the pam configuration line.)


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

Oliver Kurth for packaging pam_dotfile for Debian

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


The newest release is available from

The current release is 0.7

You may find a mostly up to date Debian package of pam_dotfile in the Debian package repository.

Get pam_dotfile's development sources from the Subversion repository.

Lennart Poettering <mzcnzqbgsvyr (at) 0pointer (dot) de>
$Id: 25 2003-08-27 20:27:12Z lennart $