#
# $Id: README,v 1.4 2002/03/27 02:36:25 bbraun Exp $
#
# This describes the behavior of this module with respect to the
# /etc/pam.conf file.
#
# writen by Andrew Morgan <morgan@parc.power.net>
#

This module is intended to be a platform for providing access to all
of the input/output that passes between the user and the application.
It is only suitable for tty-based and (stdin/stdout) applications. And
is only known to work on Linux based systems.

The action of the module is dictated by the arguments it is given in
the pam.conf file.

recognized flags are:

	debug			print some information to syslog(3)

	new_term		set the PAM_TTY item to the new filtered
				terminal (the default is to set it
				to be that of the users terminal)

	non_term		don't try to set the PAM_TTY item

	run1/run2		these arguments indicate that the
				module should separate the application
				from the user and insert a filter
				program between them. The pathname of
				the filter program follows the 'runN'
				argument. Arguments that follow this
				pathname are passed as arguments to
				the filter program.

				The distinction between run1 and run2
				is which of the two functions of
				the given management-type triggers the
				execution of the indicated filter.

	type:		run1			run2
	-----		----			----

	auth		pam_sm_authenticate	pam_sm_setcred

	account		[  pam_sm_acct_mgmt  (either is good)  ] 

	session		pam_sm_open_session	pam_sm_close_session

	password	pam_sm_chauthtok/PRELIM	pam_sm_chauthtok/UPDATE

Note, in the case of 'password' PRELIM/UPDATE indicates which of the
two calls to pam_sm_chauthtok from libpam (not the application) will
trigger the filter.

What a filter program should expect:
------------------------------------

Definitions for filter programs (which may be locally designed) are
contained in the <security/pam_filter.h> file.

Arguments are not passed to the filter on the command line, since this
is plainly visible when a user types 'ps -a'. Instead they are passed
as the filter's environment. Other information is passed in this way
too.

Here is a list of the environment variables that a filter should
expect:

	ARGS="filter_path_name argument list"
	SERVICE="service_name"  (as it appears in /etc/pam.conf)
	USER="username"
	TYPE="module_fn"  (the name of the function in pam_filter.so
			   that invoked the filter)

[This list is likely to grow. If you want something added, email me!]

Among other things this module is intended to provide a useful means
of logging the activity of users in as discrete a manner as possible.

Existing filters:
-----------------

Currently, there is a single supplied filter (upperLOWER).  The effect
of using this filter is to transpose upper and lower case letters
between the user and the application. This is really annoying when you
try the 'xsh' example application! ;)

TODO: provide more filters...
      Decide if providing stderr interception is really overkill.

Andrew G. Morgan <morgan@parc.power.net> 1996/5/27

