Copyright (C) 2003 W. Michael Petullo <mike@flyn.org>

pam_mount is a PAM module that can mount volumes for a user session

= OVERVIEW ====================================================================
	
This module is aimed at environments with SMB (Samba or Windows NT) 
or NCP (Netware or Mars-NWE) servers that Unix users wish to access 
transparently. It facilitates access to private volumes of these types 
well. The module also supports mounting home directories using 
loopback encrypted filesystems.

 o Every user can access his own volumes

 o The user needs to type the password just once (at login)

 o The mouting process is transparent to the users

 o There is no need to keep the login passwords in any additional file

 o The volumes are unmounted upon logout, so it saves system resources, 
 avoiding the need of listing every every possibly useful remote 
 volume in /etc/fstab or in an automount/supermount config file. This 
 is also necessary for securing encrypted filesystems.

Pam_mount "understands" SMB, NCP, and any type of filesystem that can 
be mounted using the standard mount command. If someone has a 
particular need for a different filesystem, feel free to ask me to 
include it and send me patches.

= BUILDING ====================================================================

To build, cross your fingers and try...

 1. ./configure
 2. make
 3. make install

Read the ``INSTALL'' file for generic detailed information on installing
this program.
	
= NASTY DETAILS ===============================================================
	
You must include two entries in /etc/pam.d/SERVICE config files, as 
the following example shows:


    #%PAM-1.0
    auth      required  /lib/security/pam_securetty.so
    auth      required  /lib/security/pam_pwdb.so shadow nullok
    auth      required  /lib/security/pam_nologin.so
    account   required  /lib/security/pam_pwdb.so
    password  required  /lib/security/pam_cracklib.so
    password  required  /lib/security/pam_pwdb.so shadow nullok use_authtok
    session   required  /lib/security/pam_pwdb.so
    session   optional  /lib/security/pam_console.so
+++ session   required  /lib/security/pam_mount.so use_first_pass
+++ auth      required  /lib/security/pam_mount.so use_first_pass


If you want to support having different passwords for login and 
mounting, replace use_first_pass with try_first_pass. This depends on 
proper support of the PAM conversation mechanism by the applications 
using PAM for authentication.

Another solution is to encrypt the password to the volume you wish 
mounted using your system password as the key and store it somewhere 
on your system's local filesystem. Pam_mount supports transparently 
decrypting this filesystem key, as long as the cipher used is 
supported by openssl. Given:

sk
	system key, the key or password used to log into the system

fsk
	filesystem key, the key that allows you to use the filesystem you 
	wish pam_mount to mount for you

E and D
	an openssl supported synchronous encryption/decryption algorithm

efsk
	encrypted filesystem key, efsk = E_sk (fsk), stored somewhere on the 
	local filesystem (ie: /home/user.key)

Pam_mount will read efsk from the local filesystem, perform fsk = 
D_sk (efsk) and use fsk to mount the filesystem. If you change your 
system password, simply regenerate efsk using efsk = E_sk (fsk). If 
you want to mount this volume by hand, use something like openssl 
-d -bf-ecb -in /home/user.key | mount -p0 /home/user. More information 
about this technique is included in pam_mount.conf.

A script named mkehd is provided with pam_mount to help create 
encrypted home directories. If you have an entry for a user using 
encrypted home directories in pam_mount.conf, mkehd will create 
necessary filesystem images and possibly encrypted filesystem keys.

Pam_mount's main configuration file, pam_mount.conf, has a lot of 
commented lines that explain what every parameter means. Individual 
users may define additional volumes to mount in ~/.pam_mount.conf. The 
volume keyword is the only valid keyword in these per-user 
configuration files.

In general, you will leave all the first (general) parameters as 
provided by default. You only have to provide the user/volume list 
in the end of the file, following the examples.

To ensure that your system and, possibly, the remote server are all 
properly configured, you should try to mount all or some of the 
volumes by hand, using the same commands and mount points provided 
in pam_mount.conf. This will save you a lot of grief, since it is 
more difficult to debug the mounting process via pam_mount.

If you can mount the volumes by hand but it is not happening via 
pam_mount, you may want to enable the "debug" option in 
pam_mount.conf to see what is happening.

Verify if the user owns the mount point and has sufficient 
permissions over that. pam_mount will verify this and will refuse to 
mount the remote volume if the user does not own that directory.

If pam_mount is having trouble unmounting volumes upon logging out, 
enable the debug variable and check the lsof variable in 
pam_mount.conf. This causes pam_mount to run lsof upon logging out 
and write lsof's output to the system's logs.

Because of the way pmhelper transmits passwords to ncpmount, if you 
with to mount NCP filesystems then you will need ncpfs >= 
2.2.0.19.10. This package is available at http://platan.vc.cvut.cz/ftp/private/ncpfs/ncpfs-2.2.0.19.10.tar.gz.

