libpam-sfs
==========

libpam-sfs is a Pluggable Authentication Module that allows for the mounting of
home directories from SFS-enabled (www.fs.net; Self-certifying File System)
servers.

libpam-sfs is Copyright (C) 2000 by Luca Filipozzi <lfilipoz@debian.org>

Please visit http://sourceforge.net/projects/libpam-sfs to get the latest
tar ball or read the latest news about libpam-sfs.

Introduction
------------
Suppose that you are the system administrator for a network where you wish to
share home directories from a central server to workstations. In the past, this
meant that you would share your passwd and group files via NIS and share /home
via NFS. Unfortunately, NFS (and NIS to a much lesser extent) is considered
insecure and you want to improve the security of your network.

There are a variety of alternatives to NFS that offer more security. For
example, you could use AFS or Coda, but both of these are not completely
end-to-end secure and they require repartitioning of your server disks to
create the AFS or Coda journalling file systems. What you really want is
something that's "just like NFS, but secure". Well, SFS is for you!

Like AFS and Coda, SFS requires that the user authenticate with the SFS
server to gain access to SFS-exported volumes. In other words, the user must
authenticate twice: once with the system in order to log on and a second time
with the SFS-server in order to gain access to SFS-exported volumes.

Now, this is all fine and good for everything except home directories. How is
the user supposed to authenticate with the SFS-server prior to being fully
logged in and having access to his/her home directory. Well, on PAM-enabled
systems, you can use this module, libpam-sfs, to solve this last dilemna!!

Configuration
-------------
In order to use libpam-sfs, you must have SFS (client-side) working on your
system. You should verify you can authenticate with the SFS server and mount
the SFS-shared volumes. DO THIS BEFORE YOU TRY USING THIS MODULE.

libpam-sfs provides the pam_sfs.so module. You must modify the files that are
in /etc/pam.d so that the corresponding PAM-enabled applications are told to
load and use pam_sfs.so.

pam_sfs.so provides 'auth' and 'session' services.

The 'auth' service in pam_sfs.so expects to be called once a password is
already available. This means that pam_sfs.so must come after pam_unix.so.

The 'session' service in pam_sfs.so should come before the pam_unix.so so that
pam_unix.so can be assured of finding the user's home directory. The 'session'
service expects PAM-enabled applications to close their sessions. Linux's login
currently does not do this by default. Fortunately, it can be told to do so.

Configure pam_sfs.so in the /etc/pam.d configuration files as follows:

- place pam_sfs.so after pam_unix.so for auth, as in this example for login:
  auth       required   pam_unix.so nullok
  auth       required   pam_sfs.so

- place pam_sfs.so before pam_unix.so for session, as in this example for ssh:
  session    required     pam_sfs.so
  session    required     pam_unix.so

- modify login.defs (Linux only?) so that CLOSE_SESSIONS is set to yes:
  CLOSE_SESSIONS yes

a Note about /etc/passwd and the SFS key that will be used
----------------------------------------------------------
pam_sfs.so reads the user's passwd file entry to determine the user's home dir.
If the home dir is in any way a symbolic link into /sfs, then pam_sfs.so goes
to the trouble of trying to authenticate the user and mount the home directory.

For example, suppose that user 'joe' has a home dir of '/home/joe'. If you, as
the system administrator, set up a symbolic link as:

  /home -> /sfs/hostname/home

then all users' home dirs will be mounted from the server named 'hostname'.
The 'key' that will be used by pam_sfs.so is 'username@hostname' and the
password will be the same as that entered for satisfaction of pam_unix.so (this
is why pam_unix.so needs to come before pam_sfs.so).

a Note about passwords
----------------------
pam_sfs.so will use the same password entered to satisfy pam_unix.so to satisfy
the PAM server. What this really means is that the user must use the same
password with both the user-authentication and SFS-authentication mechanisms.

Q: So what happens if the user changes their unix password? 
A: Things break. You have to help the user change their SFS password, too. In
   the future, pam_sfs.so will also provide the 'password' service, so password
   changing should be more integrated.

