
README

W. Michael Petullo
     _________________________________________________________________

   Table of Contents

   [1]COPYRIGHT
   [2]OVERVIEW
   [3]BUILDING
   [4]NASTY DETAILS

COPYRIGHT

   Copyright (C) 2000 Conectiva SA Elvis Pftzenreuter <epx@conectiva.com>

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
   [5]loopback encrypted filesystems.

     * Every user can access his own volumes
     * The user needs to type the password just once (at login)
     * The mouting process is transparent to the users
     * There is no need to keep the login passwords in any additional
       file
     * The volumes are unmount 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 encrypted loopback volumes, but
   this can be extended very easily. If someone has a particular need for
   a different filesystem, feel free to ask me to include it and / or
   send me patches.

BUILDING

   Procedure 1. 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 the /etc/pam.d/SERVICE config file, 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

   THIS IS A CHANGE TO THE WAY PAM_MOUNT <= 0.3.8 WAS CONFIGURED! A
   pam_mount auth entry is needed once again because Debian's PAM does
   not allow session-related functions to retreive a user's password.

   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 PAM
   applications.

   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 <program>mkehd</program> 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,
   <program>mkehd</program> will create necessary filesystem images and
   possibly encrypted filesystem keys.

   The /etc/pam_mount.conf file itself has a lot of commented lines that
   explain what every parameter means.

   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
   /etc/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
   /etc/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.

References

   1. file://localhost/tmp/xmlto.guquCn/README.proc#id5352279
   2. file://localhost/tmp/xmlto.guquCn/README.proc#id5352287
   3. file://localhost/tmp/xmlto.guquCn/README.proc#id5353702
   4. file://localhost/tmp/xmlto.guquCn/README.proc#id5353680
   5. http://www.tldp.org/HOWTO/Loopback-Encrypted-Filesystem-HOWTO.html
