<!--
   $Id: pam_filter.sgml,v 1.1.1.2 2002/09/15 20:08:29 hartmans Exp $
   
   This file was written by Andrew G. Morgan <morgan@kernel.org>
-->

<sect1>The filter module

<sect2>Synopsis

<p>
<descrip>

<tag><bf>Module Name:</bf></tag>

pam_filter

<tag><bf>Author:</bf></tag>

Andrew G. Morgan &lt;morgan@kernel.org&gt;

<tag><bf>Maintainer:</bf></tag>
	
Author.

<tag><bf>Management groups provided:</bf></tag>

account; authentication; password; session

<tag><bf>Cryptographically sensitive:</bf></tag>

Not yet.

<tag><bf>Security rating:</bf></tag>

<tag><bf>Clean code base:</bf></tag>

This module compiles cleanly on Linux based systems.

<tag><bf>System dependencies:</bf></tag>

To function it requires <em/filters/ to be installed on the system.

<tag><bf>Network aware:</bf></tag>

</descrip>

<sect2>Overview of module

<p>
This module was written to offer a plug-in alternative to programs
like ttysnoop (XXX - need a reference). Since writing a filter that
performs this function has not occurred, it is currently only a toy.
The single filter provided with the module simply transposes upper and
lower case letters in the input and output streams. (This can be very
annoying and is not kind to termcap based editors).

<sect2>Account+Authentication+Password+Session components

<p>
<descrip>

<tag><bf>Recognized arguments:</bf></tag>

<tt/debug/; <tt/new_term/; <tt/non_term/; <tt/runX/

<tag><bf>Description:</bf></tag>

Each component of the module has the potential to invoke the desired
filter.  The filter is always <tt/execv(2)/d with the privilege of the
calling application and <bf/not/ that of the user. For this reason it
cannot usually be killed by the user without closing their session.

<p>
The behavior of the module can be significantly altered by the
arguments passed to it in the <bf/Linux-PAM/ configuration file:
<itemize>
<item><tt/debug/ -

this option increases the amount of information logged to
<tt/syslog(3)/ as the module is executed.

<item><tt/new_term/ -

the default action of the filter is to set the <tt/PAM_TTY/ item to
indicate the terminal that the user is using to connect to the
application. This argument indicates that the filter should set
<tt/PAM_TTY/ to the filtered pseudo-terminal.

<item><tt/non_term/ -
don't try to set the <tt/PAM_TTY/ item.

<item><tt/runX/ -

in order that the module can invoke a filter it should know when to
invoke it. This argument is required to tell the filter when to do
this. The arguments that follow this one are respectively the full
pathname of the filter to be run and any command line arguments that
the filter might expect.

<p>
Permitted values for <tt/X/ are <tt/1/ and <tt/2/. These indicate the
precise time that the filter is to be run. To understand this concept
it will be useful to have read the Linux-PAM Module developer's
guide. Basically, for each management group there are up to two ways
of calling the module's functions.

In the case of the <em/authentication/ and <em/session/ components
there are actually two separate functions.  For the case of
authentication, these functions are <tt/_authenticate/ and
<tt/_setcred/ -- here <tt/run1/ means run the filter from the
<tt/_authenticate/ function and <tt/run2/ means run the filter from
<tt/_setcred/. In the case of the session modules, <tt/run1/ implies
that the filter is invoked at the <tt/_open_session/ stage, and
<tt/run2/ for <tt/_close_session/.

<p>
For the case of the account component. Either <tt/run1/ or <tt/run2/
may be used.

<p>
For the case of the password component, <tt/run1/ is used to indicate
that the filter is run on the first occasion <tt/_chauthtok/ is run
(the <tt/PAM_PRELIM_CHECK/ phase) and <tt/run2/ is used to indicate
that the filter is run on the second occasion (the
<tt/PAM_UPDATE_AUTHTOK/ phase).

</itemize>

<tag><bf>Examples/suggested usage:</bf></tag>

At the time of writing there is little real use to be made of this
module. For fun you might try adding the following line to your
login's configuration entries
<tscreen>
<verb>
#
# An example to see how to configure login to transpose upper and
# lower case letters once the user has logged in(!)
#
login	session	 required	pam_filter.so \
			run1 /usr/sbin/pam_filter/upperLOWER
</verb>
</tscreen>

</descrip>

<!--
End of sgml insert for this module.
-->
