diff options
Diffstat (limited to 'doc/modules/pam_filter.sgml')
| -rw-r--r-- | doc/modules/pam_filter.sgml | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/doc/modules/pam_filter.sgml b/doc/modules/pam_filter.sgml new file mode 100644 index 00000000..598279b8 --- /dev/null +++ b/doc/modules/pam_filter.sgml @@ -0,0 +1,150 @@ +<!-- + $Id$ + + This file was written by Andrew G. Morgan <morgan@parc.power.net> +--> + +<sect1>The filter module + +<sect2>Synopsis + +<p> +<descrip> + +<tag><bf>Module Name:</bf></tag> + +pam_filter + +<tag><bf>Author:</bf></tag> + +Andrew G. Morgan <morgan@parc.power.net> + +<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 the that filter is to be run. To explain 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. +--> |